--- name: cloud-databases-gen2-reference-key-protect title: Key Protect integration description: '[Gen 2]' last-updated: 2026-08-21 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/cloud-databases-gen2?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Key Protect integration {: #key-protect} [Gen 2]{: tag-purple} The data that you store in Cloud Databases is encrypted by default by using randomly generated keys. To control the encryption keys, you can Bring Your Own Key (BYOK) through [IBM Key Protect](https://cloud.ibm.com/docs/key-protect?topic=key-protect-integrate-services&format=markdown) and use one of your own keys to encrypt your databases and backups. To get started, provision [Key Protect](https://cloud.ibm.com/catalog/services/key-protect) on your IBM Cloud account. ## Creating or adding a key in Key Protect {: #key-create} Go to your instance of Key Protect and [generate or enter a key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-getting-started-tutorial&format=markdown). ## Granting service authorization in the UI {: #granting-service-auth} {: ui} Authorize Key Protect for use with Cloud Databases deployments: 1. Open your IBM Cloud dashboard. 2. From the menu bar, click **Manage** -> **Access (IAM)**. 3. In the side navigation, click **Authorizations**. 4. Click **Create**. 5. In the **Source service** menu, select the service of the deployment. For example, **Databases for PostgreSQL** or **Databases for MongoDB**. 6. In the **Source service resources** menu, select **All resources**. 7. In the **Target service** menu, select **Key Protect**. 8. Select or retain the default value **Account** as the resource group for the **Target Service** 9. In the Target service **Instance ID** menu, select the service instances to authorize. 10. Enable the **Reader** role. 11. To use "Bring your own key" (BYOK), Select the **Enable authorizations to be delegated** box in the **Authorize dependent services** section. 12. Click **Authorize**. If the service authorization is not present before provisioning your deployment with a key, the provision fails. If you want to set up a more restrictive authorization policy, configure your policy for an explicit root key CRN or for a specific Key Protect instance. Restrictions applied for Key Protect key rings are currently not supported. {: .important} ## Granting service authorization in the CLI {: #granting-service-auth-cli} {: cli} 1. Create an authorization policy to allow the Cloud Databases service to access the Key Protect service instance on the CLI. For a full set of arguments, see the [IAM CLI reference](https://cloud.ibm.com/docs/cli?topic=cli-ibmcloud_commands_iam&format=markdown#ibmcloud_iam_authorization_policy_create). ```bash ibmcloud iam authorization-policy-create kms "Reader,AuthorizationDelegator" ``` {: codeblock} If the service authorization is not present before provisioning your deployment with a key, the provision fails. If you want to set up a more restrictive authorization policy, configure your policy for an explicit root key CRN or for a specific Key Protect instance. Restrictions applied for Key Protect key rings are currently not supported. {: .important} ## Granting service authorization via the REST API {: #granting-service-auth-api} {: api} 1. Create an authorization policy to allow the Cloud Databases service to access the Key Protect service instance via the IAM REST API. For a full API reference, see the [IAM Policy Management API](https://cloud.ibm.com/apidocs/iam-policy-management#create-policy). {: note} ```bash curl -X POST 'https://iam.cloud.ibm.com/v1/policies' -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{ "type": "authorization", "subjects": [ { "attributes": [ { "name": "accountId", "value": "CUSTOMER_ACCOUNT_ID" }, { "name": "serviceName", "value": "" } ] } ], "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::serviceRole:Reader" }, { "role_id": "crn:v1:bluemix:public:iam::::role:AuthorizationDelegator" } ], "resources": [ { "attributes": [ { "name": "accountId", "operator": "stringEquals", "value": "CUSTOMER_ACCOUNT_ID" }, { "name": "serviceName", "operator": "stringEquals", "value": "kms" } ] } ] }' ``` {: codeblock} If the service authorization is not present before provisioning your deployment with a key, the provision fails. If you want to set up a more restrictive authorization policy, configure your policy for an explicit root key CRN or for a specific Key Protect instance. Restrictions applied for Key Protect key rings are currently not supported. {: .important} ## Using the Key Protect key {: #key-using} After you grant your Cloud Databases deployments permission to use your keys, you supply the [key name or CRN](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-keys&format=markdown) when you provision a deployment. The deployment uses your encryption key to encrypt your data. ## Using the Key Protect key in the UI at provision {: #key-using-ui} {: ui} If provisioning from the catalog page, select the Key Protect instance and key from the dropdown menu. ## Using the Key Protect key in the CLI at provision {: #key-using-cli} {: cli} In the CLI, use the `dataservices.encryption.disk` parameter in the parameters JSON object to assign a root key CRN to your service instance. ```bash ibmcloud resource service-instance-create REGION -p '{"dataservices":{"encryption":{"disk":"KMS_KEY_CRN"}}}' ``` {: codeblock} The Key Protect key needs to be identified by its full CRN, not just its ID. A Key Protect CRN is in the format `crn:v1:<...>:key:`. {: .tip} ## Using the Key Protect key in the API at provision {: #key-using-api} {: api} In the API, use the `dataservices.encryption.disk` parameter in the body of the request. ```sh curl -X POST https://resource-controller.cloud.ibm.com/v2/resource_instances -H "Authorization: Bearer " -H 'Content-Type: application/json' -d '{ "name": "", "target": "ca-mon", "resource_group": "", "resource_plan_id": "", "parameters": { "dataservices": { "encryption": { "disk": "KMS_KEY_CRN" } } } ``` {: codeblock} The Key Protect key needs to be identified by its full CRN, not just its ID. A Key Protect CRN is in the format `crn:v1:<...>:key:`. {: .tip} ## Key rotation {: #keyrotation} Key Protect offers manual and automatic [key rotation](https://cloud.ibm.com/docs/key-protect?topic=key-protect-rotate-keys&format=markdown) and key rotation is supported by Cloud Databases deployments. When you rotate a key, the process initiates a _syncing KMS state_ task, and your deployment is reencrypted with the new key. The task is displayed on the _Tasks_ page on your deployment's _Overview_ and the associated Key Protect and Cloud Databases events are sent to Activity Tracker. For more information, see [Rotating manually or automatically](https://cloud.ibm.com/docs/key-protect?topic=key-protect-key-rotation&format=markdown#compare-key-rotation-options). ## Deleting the deployment {: #key-protect-deleting-deployment} If you delete a deployment that is protected with a Key Protect key, the deployment remains registered against the key during the soft-deletion period (up to 9 days). To delete the key in the soft-deletion period, [force delete](https://cloud.ibm.com/docs/key-protect?topic=key-protect-delete-keys&format=markdown) the key. After the soft-deletion period, the key can be deleted without the force. To determine when you can delete the key, check the [association between the key and your deployment](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-protected-resources&format=markdown). ## Cryptoshredding {: #crypto-shredding} Cryptoshredding is a destructive action. When the key is deleted, your data is unrecoverable. {: .important} Key Protect allows you to [initiate a force delete](https://cloud.ibm.com/docs/key-protect?topic=key-protect-delete-keys&format=markdown) of a key that is in use by IBM Cloud® services, including your Gen 2 Cloud Databases deployments. This action is called cryptoshredding. Deleting a key that is in use on your deployment locks the disks that contain your data and disables your deployment. You are still able to access the UI and some metadata such as security settings in the UI, CLI, and API but you are not able to access any of the databases or data that is contained within them. Key deletion is [sent to the Activity Tracker Event Routing](https://cloud.ibm.com/docs/key-protect?topic=key-protect-at-events&format=markdown) as `kms.secrets.delete`. ## Bring your own key for backups {: #key-byok} If you use Key Protect, when you provision a database you can also designate a key to encrypt the IBM® Cloud Block Storage for Virtual Private Cloud disk that holds your deployment's backups. The backup inherits the same encryption key as the database. A different encryption key cannot be provided while creating the backup from the database. {: .note} ### Granting the delegation authorization {: #grant-auth} To enable your deployment to use the Key Protect key, you need to [Enable authorization to be delegated](https://cloud.ibm.com/docs/iam?topic=iam-serviceauth&interface=ui&format=markdown){: external} when granting the service authorizations. If the delegation authorization is not present before provisioning your deployment with a key, the provision fails. After you enable delegation and provisioned your deployment, two entries appear in your _Authorizations_ in IAM. One is the entry for the deployment that lists its status as delegator. It is "User Created". | Role | Source | Target | Type | | -----|-----|-----|----- | | AuthorizationDelegator, Reader | `` Service | Key Protect Service | User defined | {: caption="Example delegator Key Protect Authorization " caption-side="bottom"} And one for the Block Storage for VPC volume for the service instance and its backups (if present), where the deployment is the initiator. | Role | Source | Target | Type | | -----|-----|-----|----- | | Reader | Block Storage for VPC service | Key Protect Service | Created by `` | {: caption="Example Key Protect authorization for Cloud Object Storage from Cloud Databases " caption-side="bottom"} ### Removing keys {: #key-remove} IAM/Key Protect does not stop you from removing the policy between the key and Block Storage for VPC (the second example), but doing so can make your topics/partitions unrestorable. ### Common pitfalls {: #common-pitfalls} Be careful when removing keys and authorizations. If you have multiple deployments that use the same keys, it is possible to inadvertently destroy data to **all** of those deployments by revoking the delegation authorization. If possible, do not use the same key for multiple deployments. If you want to shred the data associated with your instance, you can delete the key. Block Storage for VPC ensures that the storage is unreadable and unwriteable. However, any other deployments (or their backups) that use that same key will encounter subsequent failures. If you do require that the same key to be used for multiple deployments and/or backups, removing keys and authorizations can have the following side effects. If you delete the Block Storage for VPC volume authorization (as seen in Table 2), not only the deployment that is shown as the creator is affected, but any deployments that also use the same key are affected as well. Those deployments will encounter failures until you open a support ticket and request the policy to be re-created. Use caution if you reuse keys. {: .important}