diff --git a/docs/design/proposals/encryped-with-keyprotect.md b/docs/design/proposals/encryped-with-keyprotect.md new file mode 100644 index 000000000000..74bb17651af7 --- /dev/null +++ b/docs/design/proposals/encryped-with-keyprotect.md @@ -0,0 +1,67 @@ +# Encrypted volumes with IBM HPCS or Key Protect + +IBM Cloud™ Hyper Protect Crypto Services is a key management and cloud hardware +security module (HSM). It is designed to enable a user to take control of their +cloud data encryption keys and cloud hardware security models. To support this +KMS integration in Ceph CSI and thus enable the HPCS users to make use of the +same in RBD volume encrypted operations, below things are considered. + +## Connection to IBM HPCS/key Protect service + +Below parameters/values can be used to establish the connection to the HPCS +service from the CSI driver and to make use of the encryption operations: + +```console +* KMS_SERVICE_NAME=[kms_service_name] +A unique name for the key management service within the project. + +* SERVICE_INSTANCE_ID=[service_instance_id] +The Instance ID of the IBM HPCS service, ex: crn:v1:bluemix:public:hs-crypto:us-south:a/5d19cf8b82874c2dab37e397426fbc42:e2ae65ff-954b-453f-b0d7-fc5064c203ce:: + +* SERVICE_API_KEY=[service_api_key] +Ex: 06x6DbTkVQ-qCRmq9cK-p9xOQpU2UwJMcdjnIDdr0g2R + +* CUSTOMER_ROOT_KEY=[customer_root_key] +Ex: c7a9aa91-5cb5-48da-a821-e85c27b99d92 + +* KP_REGION = [region of the key protect service] +Ex: us-south-2 +``` + +### Values provided in the connection secret + +Considering `SERVICE_API_KEY` and `CUSTOMER_ROOT_KEY` are sensitive information, +those will be provided as a kubernetes secret to the CSI driver. The Ceph CSI +KMS plugin interface for the key protect will read the secret name from the kms +configmap and fetch these values. `SESSION_TOKEN and CRK_ARN` values can also be +provided by the user as part of the secret if needed. However these values are +considered to be optional. + +### Values provided in the config map + +`SERVICE_INSTANCE_ID` is part of the kms configmap and there could be an +optional value provided in the configmap for `REGION` too. + +### Storage class values or configuration + +As like other KMS enablement, the storage class has to be enabled for encryption +and `encryptionKMSID` has to be provided which is the matching value in the kms +config map to `KMS_SERVICE_NAME`. + +## Volume Encrypt or Decrypt Operation + +The IBM Key protect server's `wrap` and `unwrap` functionalities will be used by +the Ceph CSI driver to achieve encryption and decryption of RBD volumes. The DEK +can be wrapped with the help of Customer Root Key (CRK) and can be used for LUKS +operation. The wrapped cipher blob will be stored inside the RBD image +metadata ( as in other KMS integration, ex: AWS). At time of decrypt the DEK +will be unwrapped with the help of cipher blob and Key Protect server + +## Integration APIS + +https://github.com/IBM/keyprotect-go-client provide the client SDK to interact +with the Key Protect server and perform key protect operations. + +## Additional Reference# + +https://cloud.ibm.com/docs/key-protect \ No newline at end of file