Key Protect Integration

The data that you store in IBM 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 and use one of your own keys to encrypt your databases and backups.

This document covers the integration of Key Protect with Cloud Databases, which includes Databases for DataStax, Databases for Elasticsearch, Databases for EnterpriseDB, Databases for etcd, Databases for MongoDB, Databases for PostgreSQL, Databases for Redis, Messages for RabbitMQ, IBM Cloud® Databases for MySQL, and IBM Cloud® Databases for MySQL.

To get started, you need Key Protect provisioned on your IBM Cloud account.

Creating or adding a key in Key Protect

Go to your instance of Key Protect and generate or enter a key.

Granting service authorization in the UI

Authorize Key Protect for use with Cloud Databases deployments:

Open your IBM Cloud 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, Databases for PostgreSQL or Messages for RabbitMQ
In the Source service instance menu, select All instances.
In the Target service menu, select Key Protect.
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) for backups, 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.

Using the Key Protect Key

After you grant your Cloud Databases 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.

Using the Key Protect Key in the UI

If provisioning from the catalog page, select the Key Protect instance and key from the dropdown menus.

Using the Key Protect Key in the CLI

In the CLI, use the disk_encryption_key_crn parameter in the parameters JSON object.

ibmcloud resource service-instance-create example-database <service-name> standard us-south \
-p \ '{
  "disk_encryption_key_crn": "crn:v1:<...>:key:<id>"
}'

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:<id>.

Using the Key Protect Key in the API

In the API, use the disk_encryption_key parameter in the body of the request.

curl -X POST \
  https://resource-controller.cloud.ibm.com/v2/resource_instances \
  -H 'Authorization: Bearer <>' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "my-instance",
    "target": "blue-us-south",
    "resource_group": "5g9f447903254bb58972a2f3f5a4c711",
    "resource_plan_id": "databases-for-x-standard",
    "disk_encryption_key_crn": "crn:v1:<...>:key:<id>"
  }'

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:<id>.

Key Rotation

Key Protect offers manual and automatic key rotation 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.

Deleting the 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 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.

Cryptoshredding

Cryptoshredding is a destructive action. When the key is deleted, your data is unrecoverable.

Key Protect allows you to initiate a force delete of a key that is in use by IBM Cloud® services, including your 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 as kms.secrets.delete.

Bring your own key for backups

If you use Key Protect, when you provision a database you can also designate a key to encrypt the Cloud Object Storage disk that holds your deployment's backups.

BYOK for backups is available only in US regions us-south and us-east, and eu-de.

Only keys in the us-south and eu-de are durable to region failures. To ensure that your backups are available even if a region failure occurs, you must use a key from us-south or eu-de, regardless of your deployment's location.

Granting the delegation authorization

To enable your deployment to use the Key Protect 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.

Using the Key at Provision in the CLI

After the appropriate authorization and delegation is granted, you supply the key name or CRN when you provision a deployment.

In the CLI, use the backup_encryption_key_crn parameter in the parameters JSON object.

ibmcloud resource service-instance-create example-database <service-name> standard us-south \
-p \ '{
  "backup_encryption_key_crn": "crn:v1:<...>:key:<id>"
}'

Using the Key at Provision in the API

In the API, use the backup_encryption_key_crn parameter in the body of the request.

curl -X POST \
  https://resource-controller.cloud.ibm.com/v2/resource_instances \
  -H 'Authorization: Bearer <>' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "my-instance",
    "target": "blue-us-south",
    "resource_group": "5g9f447903254bb58972a2f3f5a4c711",
    "resource_plan_id": "databases-for-x-standard",
    "backup_encryption_key_crn": "crn:v1:<...>:key:<id>"
  }'

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".

Table 1. Example delegator Key Protect Authorization
Role	Source	Target	Type
AuthorizationDelegator, Reader	`<cloud-databases>` Service	Key Protect Service	User defined

And one for the Cloud Object Storage bucket for its backups, where the deployment is the initiator.

Table 2. Example Key Protect Authorization for Cloud Object Storage from Cloud Databases
Role	Source	Target	Type
Reader	Cloud Object Storage service	Key Protect Service	Created by `<cloud-databases-crn>`

Removing Keys

IAM/Key Protect does not stop you from removing the policy between the key and Cloud Object Storage (the second example), but doing so can make your backups unrestorable. To prevent this, if you delete the Cloud Object Storage policy that governs the ability of Cloud Databases to use the key for Cloud Object Storage, the policy is re-created to continue backing up your deployment.

Be careful when removing keys and authorizations. If you have multiple deployments that use the same keys, it is possible to inadvertently destroy backups to all of those deployments by revoking the delegation authorization. If possible, do not use the same key for multiple deployment's backups.

If you want to shred the backups, you can delete the key. Cloud Object Storage ensures that the storage is unreadable and unwriteable. However, any other deployments that use that same key for backups encounter subsequent backup failures.

If you do require that the same key to be used for multiple deployment's backups, removing keys and authorizations can have the following side effects.

If you delete just the Cloud Object Storage authorization (as seen in Table 2), then not only is the deployment that is shown as the creator affected, but any deployments that also use the same key are also affected. Those deployments can encounter temporary backup failures until the policy is automatically re-created. There should be no lasting effects, except for missing backups.
If you delete just Cloud Databases delegator authorization, which is created by you (as seen in Table 1), nothing immediately breaks because the second authorization is still in place. However, if the Cloud Object Storage authorization is ever removed, it cannot be re-created, and can lead to multiple deployments that use the same key losing the ability to back up.
If you delete both the Cloud Object Storage authorization AND the Cloud Databases delegator authorization, all deployments that use the same key will immediately not have the ability to back up and the correct authorizations will not be able to be re-created, effectively destroying the backups for all deployments that use that key.

Use caution if you reuse keys.