Configuring Key Management Service

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

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.1.2 supports SafeNet Luna Network HSM 6.2.

Configuring SafeNet Luna Network HSM 6.2

Complete these steps to configure the HSM device:

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

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

Update Helm repositories.
```
helm repo update
```

Create a overrides_hsm.yaml file with the following content:

hsm:
 hsm_model: gemalto
 hsm_ip: <HSM IP ADDRESS>
 hsm_pw: <HSM PARTITION PASSWORD>
 server_ca: <BASE64 ENCODED CONTENTS OF LUNA SERVER CERTIFICATE>
 client_certs:
   <MANAGEMENT_NODE_IP>: <BASE64 ENCODED CONTENTS OF LUNA CLIENT CERTIFICATE>
   <MANAGEMENT_NODE_IP>-key: <BASE64 ENCODED CONTENTS OF LUNA CLIENT KEY>
oss:
 image:
   repository: <CLUSTER_NAME>.icp:8500/ibmcom/kms-oss
   tag: latest
storage:
 image:
   repository: <CLUSTER_NAME>.icp:8500/ibmcom/kms-onboarding
   tag: latest
gemalto:
 image:
   repository: <CLUSTER_NAME>.icp:8500/ibmcom/kms-gemaltov6
   tag: latest

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 not in use.

Run the following command:

helm install mgmt-charts/key-management-hsm --tls --namespace kube-system --name kms-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:

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

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

Update Helm repositories.
```
helm repo update
```

Create a overrides_softhsm.yaml file with the following content:

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

Run the following command:

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

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:

Set up the Kubernetes CLI. For more information, see Installing the Kubernetes CLI (kubectl).
Get the instance ID of your KMS. Your installation of the KMS has a unique instance ID. It is associated with a service ID that is created at the time of installation. To retrieve this instance identifier, run the following command:
```
kubectl get secret key-management-secret -o yaml --namespace kube-system
```
Following is a sample service ID:
```
kms-service-id: aWFtLVNlcnZpY2VJZC01MDI2N2U2Mi00Y2MyLTQ2YzUtOTJjYy00NDRmNWJiMjIyOTI=
```
To retrieve the instance ID, run the following command to decode UUID portion of the service ID.
```
echo <service ID> | base64 --decode
```
Following is an example command and output:
```
echo aWFtLVNlcnZpY2VJZC01MDI2N2U2Mi00Y2MyLTQ2YzUtOTJjYy00NDRmNWJiMjIyOTI= | base64 --decode

50267e62-4cc2-46c5-92cc-444f5bb22292
```
In the sample ID, 50267e62-4cc2-46c5-92cc-444f5bb22292 is the instance ID.
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.
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>"
       }
   ]
}
```