Setting up custom secrets in Key Protect

IBM Cloud® Data Engine is deprecated. As of 18 February 2024 you can't create new instances, and access to free instances will be removed. Existing Standard plan instances are supported until 18 January 2025. Any instances that still exist on that date will be deleted.

IBM® Key Protect for IBM Cloud® is the service for storing and managing secrets in IBM Cloud. You can upload custom secrets and Key Protect manages them for you. Key Protect ensures that only those users and services whom you explicitly granted permission are able to access and use secrets. Data Engine uses Key Protect as its secure and trusted credential broker for custom access secrets to data resources as the following diagram shows.

Make sure that you provisioned or received access to an instance of Key Protect in IBM Cloud. The following description uses the command-line interface to set up a new custom key. Alternatively, you can also use the IBM Cloud console.

1. Log on to IBM Cloud with ibmcloud login --sso.
2. Install the Key Protect CLI plug-in, if it is not already installed: ibmcloud plugin install key-protect -r 'IBM Cloud'. For more information, see the Key Protect CLI documentation.
3. List your Key Protect service instances and identify the ID and region of the instance where you want to store the secret: ibmcloud resource service-instances --long --service-name kms. The instance ID is in output column "GUID", the region in column "Location".
4. Select the appropriate target region with ibmcloud kp region-set <region>.
5. Optionally review the existing keys in the instance with following command: ibmcloud kp list -c -i <kp instance id>.
6. Key Protect accepts only base64 encoded secret data. Issue the following command to add a custom secret as properly encoded content to Key Protect: ibmcloud kp create "<key name>" -i <kp instance id> -s -k `echo -ne "<your custom secret>" | base64` . The key name that you provide is for your reference only and can be an arbitrary string.
7. List the keys again (as in step 5) to retrieve the key ID and CRN for the new key that you created. Use the key CRN in an access secret clause of an SQL query.

You can verify the correct setup and function of your IBM Cloud CLI by downloading and running this script in your command line. It performs some tests for creating and verifying a test key in one of your Key Protect instances.

You cannot use the CLI or web console to review actual key content after it is uploaded. However, you can use the REST API directly to review existing custom key content by issuing the following command:

curl -X GET "https://us-south.kms.cloud.ibm.com/api/v2/keys/<key id>" \
  -H "accept: application/vnd.ibm.collection+json" \
  -H "authorization: <Bearer token>" \
  -H "bluemix-instance: <kp instance id>" \
| jq -r '.resources[].payload' | base64 --decode

Replace us-south in the REST API URL with the appropriate region. The <key id> is the one you obtained in step 7. The required <Bearer token> can be retrieved with ibmcloud iam oauth-tokens. For more information, see to the Key Protect CLI documentation.