| copyright |
|
||
|---|---|---|---|
| lastupdated | 2026-02-25 | ||
| subcollection | cloud-databases-gen2 | ||
| keywords | bring your own key, byok, cryptoshredding, key rotation, key rotation frequency, bring your own key |
{{site.data.keyword.attribute-definition-list}}
{: #key-protect}
[Gen 2]{: tag-purple}
The data that you store in {{site.data.keyword.databases-for}} is encrypted by default by using randomly generated keys. To control the encryption keys, you can Bring Your Own Key (BYOK) through {{site.data.keyword.keymanagementservicelong_notm}} and use one of your own keys to encrypt your databases and backups.
This document covers the integration of {{site.data.keyword.keymanagementserviceshort}} with Gen 2 {{site.data.keyword.databases-for}}, which includes {{site.data.keyword.databases-for-postgresql}} and {{site.data.keyword.databases-for-mongodb}}. {: .note}
To get started, provision {{site.data.keyword.keymanagementserviceshort}} on your {{site.data.keyword.cloud_notm}} account.
{: #key-create}
Go to your instance of {{site.data.keyword.keymanagementserviceshort}} and generate or enter a key.
{: #granting-service-auth} {: ui}
Authorize {{site.data.keyword.keymanagementserviceshort}} for use with {{site.data.keyword.databases-for}} deployments:
- Open your {{site.data.keyword.cloud_notm}} dashboard.
- From the menu bar, click Manage -> Access (IAM).
- In the side navigation, click Authorizations.
- Click Create.
- In the Source service menu, select the service of the deployment. For example, {{site.data.keyword.databases-for-postgresql}} or {{site.data.keyword.databases-for-mongodb}}.
- In the Source service resources menu, select All resources.
- In the Target service menu, select {{site.data.keyword.keymanagementserviceshort}}.
- Select or retain the default value Account as the resource group for the Target Service
- In the Target service Instance ID menu, select the service instances to authorize.
- Enable the Reader role.
- To use "Bring your own key" (BYOK), Select the Enable authorizations to be delegated box in the Authorize dependent services section.
- 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 {{site.data.keyword.keymanagementserviceshort}} instance. Restrictions applied for {{site.data.keyword.keymanagementserviceshort}} key rings are currently not supported. {: .important}
{: #granting-service-auth-cli} {: cli}
- Create an authorization policy to allow the {{site.data.keyword.databases-for}} service to access the {{site.data.keyword.keymanagementserviceshort}} service instance on the CLI. For a full set of arguments, see the IAM CLI reference.
bx iam authorization-policy-create <SERVICE-NAME> 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 {{site.data.keyword.keymanagementserviceshort}} instance. Restrictions applied for {{site.data.keyword.keymanagementserviceshort}} key rings are currently not supported. {: .important}
{: #granting-service-auth-api} {: api}
- Create an authorization policy to allow the {{site.data.keyword.databases-for}} service to access the {{site.data.keyword.keymanagementserviceshort}} service instance via the IAM REST API.
For a full API reference, see the IAM Policy Management API. {: note}
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": "<SERVICE-NAME>"
}
]
}
],
"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 {{site.data.keyword.keymanagementserviceshort}} instance. Restrictions applied for {{site.data.keyword.keymanagementserviceshort}} key rings are currently not supported. {: .important}
{: #key-using}
After you grant your {{site.data.keyword.databases-for}} deployments permission to use your keys, you supply the key name or CRN when you provision a deployment. The deployment uses your encryption key to encrypt your data.
{: #key-using-ui} {: ui}
If provisioning from the catalog page, select the {{site.data.keyword.keymanagementserviceshort}} instance and key from the dropdown menu.
{: #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.
ibmcloud resource service-instance-create <INSTANCE-NAME> <SERVICE-NAME> <PLAN-NAME> REGION -p '{"dataservices":{"encryption":{"disk":"KMS_KEY_CRN"}}}'{: codeblock}
The {{site.data.keyword.keymanagementserviceshort}} key needs to be identified by its full CRN, not just its ID. A {{site.data.keyword.keymanagementserviceshort}} CRN is in the format crn:v1:<...>:key:<id>.
{: .tip}
{: #key-using-api} {: api}
In the API, use the dataservices.encryption.disk parameter in the body of the request.
curl -X POST https://resource-controller.cloud.ibm.com/v2/resource_instances -H "Authorization: Bearer <IAM token>" -H 'Content-Type: application/json' -d '{
"name": "<INSTANCE-NAME>",
"target": "ca-mon",
"resource_group": "<A RESOURCE GROUP GUID>",
"resource_plan_id": "<A PLAN ID>",
"parameters": {
"dataservices": {
"encryption": {
"disk": "KMS_KEY_CRN"
}
}
}{: codeblock}
The {{site.data.keyword.keymanagementserviceshort}} key needs to be identified by its full CRN, not just its ID. A {{site.data.keyword.keymanagementserviceshort}} CRN is in the format crn:v1:<...>:key:<id>.
{: .tip}
{: #keyrotation}
{{site.data.keyword.keymanagementserviceshort}} offers manual and automatic key rotation and key rotation is supported by {{site.data.keyword.databases-for}} 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 {{site.data.keyword.keymanagementserviceshort}} and {{site.data.keyword.databases-for}} events are sent to Activity Tracker.
For more information, see Rotating manually or automatically.
{: #key-protect-deleting-deployment}
If you delete a deployment that is protected with a {{site.data.keyword.keymanagementserviceshort}} 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 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.
{: #crypto-shredding}
Cryptoshredding is a destructive action. When the key is deleted, your data is unrecoverable. {: .important}
{{site.data.keyword.keymanagementserviceshort}} allows you to initiate a force delete of a key that is in use by {{site.data.keyword.cloud}} services, including your Gen 2 {{site.data.keyword.databases-for}} 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 {{site.data.keyword.atracker_short}} as kms.secrets.delete.
{: #key-byok}
If you use {{site.data.keyword.keymanagementserviceshort}}, when you provision a database you can also designate a key to encrypt the {{site.data.keyword.block_storage_is_full}} disk that holds your deployment's backups.
BYOK for backups is available only in select regions. {: .note}
Only keys in the select regions are durable to region failures. To ensure that your backups are available even if a region failure occurs, you must use a key from these select regions, regardless of your deployment's location. {: .important}
{: #grant-auth}
To enable your deployment to use the {{site.data.keyword.keymanagementserviceshort}} key, you need to Enable authorization to be delegated 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 | <cloud-databases> Service |
{{site.data.keyword.keymanagementserviceshort}} Service | User defined |
| {: caption="Example delegator {{site.data.keyword.keymanagementserviceshort}} Authorization " caption-side="bottom"} |
And one for the {{site.data.keyword.block_storage_is_short}} volume for the service instance and its backups (if present), where the deployment is the initiator.
| Role | Source | Target | Type |
|---|---|---|---|
| Reader | {{site.data.keyword.block_storage_is_short}} service | {{site.data.keyword.keymanagementserviceshort}} Service | Created by <cloud-databases-crn> |
| {: caption="Example {{site.data.keyword.keymanagementserviceshort}} authorization for Cloud Object Storage from {{site.data.keyword.databases-for}} " caption-side="bottom"} |
{: #key-remove}
IAM/{{site.data.keyword.keymanagementserviceshort}} does not stop you from removing the policy between the key and {{site.data.keyword.block_storage_is_short}} (the second example), but doing so can make your topics/partitions unrestorable.
{: #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. {{site.data.keyword.block_storage_is_short}} 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 {{site.data.keyword.block_storage_is_short}} 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}