Configuring Key Management Service

Configure Key Management Service (KMS) to encrypt data at rest and in transit.

Install the IBM Cloud Private 3.2.1 Key Management HSM package key-management-hsm-amd64.tar.gz by following the steps in Installing IBM software onto the IBM Cloud Private platform.

Set up an HSM device

Use the KMS to provision and manage encrypted keys for your applications and services. You must set up a Hardware Security Module (HSM) device that is partitioned for use by KMS. IBM® Cloud Private version 3.2.1 supports SafeNet Luna Network HSM 6.2 and nCipher nShield Connect HSM 12.40.2.

• Configuring SafeNet Luna Network HSM 6.2
• Configuring nCipher nShield Connect HSM 12.40.2
• Configuring SoftHSM
• Generating keys
• Clearing HSM Application Data
• Onboarding a service to use KMS

Configuring SafeNet Luna Network HSM 6.2

Complete these steps to configure the HSM device:

1. Set up Helm CLI. For more information, see Installing the Helm CLI (helm).

2. Add the mgmt-charts repository to your cluster.

   helm repo add mgmt-charts https://<CLUSTER_NAME>.icp:8443/mgmt-repo/charts --ca-file ~/.helm/ca.pem --cert-file ~/.helm/cert.pem --key-file ~/.helm/key.pem
   

3. Update Helm repositories.

   helm repo update
   

4. Create a hsm-Secret.yaml file with the following content:

   apiVersion: v1
   kind: Secret
   type: Opaque
   metadata:
     name: hsm-secret
     namespace: kube-system
   data:
     hsm-pass: <BASE64 ENCODED PASSWORD OF HSM>
     ServerCAFile: <BASE64 ENCODED CONTENTS OF LUNA SERVER CERTIFICATE>
     <MANAGEMENT_NODE_IP>: <BASE64 ENCODED CONTENTS OF LUNA CLIENT CERTIFICATE>
     <MANAGEMENT_NODE_IP>-key: <BASE64 ENCODED CONTENTS OF LUNA CLIENT KEY>
   

5. Import the hsm-Secret.yaml file into the cluster.

   kubectl apply -f hsm-Secret.yaml -n kube-system
   

6. Verify the creation of your secret.

   kubectl get secret hsm-secret -n kube-system -o yaml
   

7. Create a overrides_hsm.yaml file with the following content:

   hsm:
     hsm_model: gemalto
     hsm_ip: <HSM IP ADDRESS>
   oss:
     image:
       repository: <CLUSTER_NAME>.icp:8500/ibmcom/kms-oss
       tag: <ICP_version>
   storage:
     image:
       repository: <CLUSTER_NAME>.icp:8500/ibmcom/kms-onboarding
       tag: <ICP_version>
   gemalto:
     image:
       repository: <CLUSTER_NAME>.icp:8500/ibmcom/kms-gemaltov6
       tag: <ICP_version>
   watcher:
     image:
       repository: <CLUSTER_NAME>.icp:8500/ibmcom/kms-oss-watcher
       tag: <ICP_version>
   

   Note: For IBM Cloud Private with OpenShift, the repository for all images must start with docker- registry.default.svc:5000. For example: docker-registry.default.svc:5000/ibmcom/kms-oss-watcher.

   Under the client_certs parameter, you must list the certificate and key pair for all management nodes. All certificates and keys must be base64 encoded.

   Note: As the overrides_hsm.yaml file contains sensitive information, you must encrypt it or delete it when the file is not in use.

8. Run the following command:

   helm install mgmt-charts/key-management-hsm --tls --namespace kube-system --name key-management-hsm -f path/to/overrides_hsm.yaml
   

Configuring nCipher nShield Connect HSM 12.40.2

Complete these steps to configure the HSM device:

1. Set up Helm CLI. For more information, see Installing the Helm CLI (helm).

2. Add the mgmt-charts repository to your cluster.

   helm repo add mgmt-charts https://<CLUSTER_NAME>.icp:8443/mgmt-repo/charts --ca-file ~/.helm/ca.pem --cert-file ~/.helm/cert.pem --key-file ~/.helm/key.pem
   

3. Update Helm repositories.

   helm repo update
   

4. Create a hsm-Secret.yaml file with the following content:

   apiVersion: v1
   kind: Secret
   type: Opaque
   metadata:
     name: hsm-secret
   namespace: kube-system
   data:
     hsm-pass: <BASE64 ENCODED PASSWORD OF HSM>
   

5. Import the hsm-Secret.yaml file into the cluster.

   kubectl apply -f hsm-Secret.yaml -n kube-system
   

6. Verify the creation of your secret.

   kubectl get secret hsm-secret -n kube-system -o yaml
   

7. Create a overrides_hsm.yaml file with the following content:

    hsm:
      hsm_model: thales
      hsm_ip: <HSM IP ADDRESS>
      rfs_ip: <RFS IP ADDRESS>
      slotId: <HSM slot ID string, i.e. "492971158">
    oss:
      image:
        repository: <CLUSTER_NAME>.icp:8500/ibmcom/kms-oss
        tag: <ICP_version>
    storage:
      image:
        repository: <CLUSTER_NAME>.icp:8500/ibmcom/kms-onboarding
        tag: <ICP_version>
    thales:
      image:
        repository: <CLUSTER_NAME>.icp:8500/ibmcom/kms-thalesv12
        tag: <ICP_version>
    watcher:
      image:
        repository: <CLUSTER_NAME>.icp:8500/ibmcom/kms-oss-watcher
        tag: <ICP_version>
   

   Note: For IBM Cloud Private with OpenShift, the repository for all images must start with docker- registry.default.svc:5000. For example: docker-registry.default.svc:5000/ibmcom/kms-oss-watcher.

   Under the client_certs parameter, you must list the certificate and key pair for all management nodes. All certificates and keys must be base64 encoded.

   Note: As the overrides_hsm.yaml file contains sensitive information, you must encrypt it or delete it when the file is not in use.

8. Run the following command:

    helm install mgmt-charts/key-management-hsm --tls --namespace kube-system --name key-management-hsm -f path/to/overrides_hsm.yaml
   

Configuring SoftHSM

SoftHSM is a virtualized HSM that displays the functions of the key management system that is available. SoftHSM can be used only for demonstration purpose. You can test the APIs in a non-production environment to understand what might be possible with a real hardware security module.

Limitations

• You cannot import root keys.
• If a pod is restarted, the KMS becomes invalid.

Complete these steps to install SoftHSM:

1. Set up Helm CLI. For more information, see Installing the Helm CLI (helm).

2. Add the mgmt-charts repository to your cluster.

   helm repo add mgmt-charts https://<CLUSTER_NAME>.icp:8443/mgmt-repo/charts --ca-file ~/.helm/ca.pem --cert-file ~/.helm/cert.pem --key-file ~/.helm/key.pem
   

3. Update Helm repositories.

   helm repo update
   

4. Create a hsm-Secret.yaml file with the following content:

   apiVersion: v1
   kind: Secret
   metadata:
     name: hsm-secret
     namespace: kube-system
   data:
     hsm-pass: <ANY BASE64 ENCODED string, i.e. cGFzc3dvcmQ=>
   

5. Import the hsm-Secret.yaml file into the cluster.

   kubectl apply -f hsm-Secret.yaml -n kube-system
   

6. Verify the creation of your secret.

   kubectl get secret hsm-secret -n kube-system -o yaml
   

7. Create a overrides_hsm.yaml file with the following content:

   hsm:
     hsm_model: softhsm
   oss:
     image:
       repository: <CLUSTER_NAME>.icp:8500/ibmcom/kms-oss
       tag: <ICP_version>
   storage:
     image:
       repository: <CLUSTER_NAME>.icp:8500/ibmcom/kms-onboarding
       tag: <ICP_version>
   softhsm:
     image:
       repository: <CLUSTER_NAME>.icp:8500/ibmcom/kms-softhsm
       tag: <ICP_version>
   watcher:
     image:
       repository: <CLUSTER_NAME>.icp:8500/ibmcom/kms-oss-watcher
       tag: <ICP_version>
   

   Note: For IBM Cloud Private with OpenShift, the repository for all images must start with docker- registry.default.svc:5000. For example: docker-registry.default.svc:5000/ibmcom/kms-oss-watcher.

   Under the client_certs parameter, you must list the certificate and key pair for all management nodes. All certificates and keys must be base64 encoded.

   Note: As the overrides_hsm.yaml file contains sensitive information, you must encrypt it or delete it when the file is not in use.

8. Run the following command:

   helm install mgmt-charts/key-management-hsm --tls --namespace kube-system --name key-management-hsm -f path/to/overrides_hsm.yaml
   

Clearing HSM Application Data

If you are switching over to a new HSM model, HSM Application Data can be cleared by adding clear_data: true into the overrides.yaml configuration file under hsm. This value is by default set to false. For example:

hsm:
  hsm_model: <HSM MODEL>
  clear_data: true
  hsm_ip: <HSM IP ADDRESS>
  hsm_pw: <HSM PARTITION PASSWORD>

Generating keys

KMS uses two types of keys.

• Root keys: Root keys are symmetric key-wrapping keys that you completely manage. You can use a root key to protect other cryptographic keys with advanced encryption.
• Standard keys: Standard keys are symmetric keys that are used for cryptography. You can use a standard key to directly encrypt and decrypt data.

You can create or import an existing key by using the following APIs:

• Create a key. See Generate a key
• Import a key. See Import a key

Onboarding a service to use KMS

To use KMS for your service, complete the following tasks:

1. Set up the Kubernetes CLI. For more information, see Installing the Kubernetes CLI (kubectl).

2. Provision your KMS instance. For more information, see Setting up an instance.

3. Create a service ID for your service. You can use the management console or the APIs to generate a service ID.

   • To use the management console, see Creating a service ID by using the IBM Cloud Private Web console.
   • To use the API, see Create a service ID.

4. Assign an access policy for the service ID to interact with the service. You can use the management console or the APIs to assign an access policy.

   • To use the management console, see Creating a service ID by using the IBM Cloud Private Web console.
   • To use the API, see Create an access policy for a service ID.

   Following is a sample request for assigning an access policy:

   {
        "resources": [
          {
              "namespaceId": "kube-system",
              "serviceName": "kms",
              "serviceInstance": "<INSTANCE_ID>,
              "resource": "<KEY_ID>",
              "resourceType": "key"
          }
      ],
      "roles": [
          {
              "id": "crn:v1:icp:private:iam::::role:<ROLE>"
          }
      ]
   }