Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Use Customer Managed Encryption Keys (CMEK) at Rest

  • how-to
    +
    Capella encrypts database volumes at rest. You can move control of the keys from Couchbase to your own key management system (KMS).

    By default, all databases in Couchbase Capella use your database’s cloud provider KMS to encrypt database volumes at rest. Instead of using this Couchbase-managed solution, you can create your own encryption keys for data at rest using customer-managed encryption keys (CMEK). By managing your encryption keys, you control their configuration, rotation cycles, geographic storage location, and can directly revoke them.

    Customer-managed encryption keys for backups are not available at this time. To manage your encryption keys for backups, you can run your backup outside of Capella.

    Key Management Provider Support

    Capella supports the following customer key management providers for encryption at rest:

    Couchbase recommends using one key per database and not sharing keys across databases.

    Customer-managed encryption keys are available to databases using the Enterprise plan.

    Configure Capella to use Customer Key Management

    To add and manage customer-managed encryption keys, you must use the Management API. Through the Management API, you can:

    • Add a customer-managed encryption key.

    • Get the details of a key based on its ID.

    • Get a list of keys created in an organization.

    • Rotate a key to replace an existing key with a new one.

    • Delete an existing key.

    • Associate a key with a database to enable encryption.

    • Disassociate a key with a database.

    For the details and requirements of each call, see the Management API v4.0 Reference. If you’re new to the Management API, see Get Started with the Management API v4.0

    Prerequisites

    • You must have the Organization Owner role to create, rotate, and delete customer-managed encryption keys. The Project Owner and Organizations Owner roles can associate a key with a database. All organization members can retrieve the list of keys in an organization and view the details of a key.

    • You have a Management API key.

    • You have deployed a database.

    AWS Requirements

    • A symmetric encryption key in AWS KMS that’s in the same region as your database.

    • The unique Capella AWS account ID that’s associated with your organization. Get this account ID by making a GET - Get Cloud Accounts call to the Couchbase Capella Management API.

      Use this account ID when adding CMEK to other AWS databases in your organization.

    • A key policy with the following permissions:

      • DescribeKey

      • GenerateDataKeyWithoutPlainText

      • Decrypt

      • ReEncrypt*

      • CreateGrant with the kms:GrantIsForAWSResource condition set to the Capella AWS account ID associated with your organization.

      • The principal set to the Capella AWS account ID that’s associated with your organization.

        Example
        {
            "Sid": "Allow use of the key",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<capella-account-id>:root"
            },
            "Action": [
                "kms:DescribeKey",
                "kms:GenerateDataKeyWithoutPlainText",
                "kms:Decrypt",
                "kms:ReEncrypt*"
            ],
            "Resource": "*"
        },
        {
            "Sid": "Allow attachment of persistent resources",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<capella-account-id>:root"
            },
            "Action": "kms:CreateGrant",
            "Resource": "*",
            "Condition": {
                "Bool": {
                    "kms:GrantIsForAWSResource": "true"
                }
            }
        }
        For more information about cross-account KMS encryption key access, see Creating KMS keys that other accounts can use

    • The Amazon Resource Name (ARN) of your KMS encryption key.

    GCP Requirements

    • A symmetric encryption key in GCP KMS.

    • The Key Version Resource ID of your GCP KMS encryption key.

    • The unique Capella Google service account ID that’s associated with your organization. Get this account ID by making a GET - Get Cloud Accounts call to the Couchbase Capella Management API.

      Use this service account ID when adding CMEK to other GCP databases in your organization.

    • A service account on the key with the following permissions:

    Add a Customer-Managed Encryption Key

    This example uses AWS KMS, but the process for GCP is similar with resourceName used instead of arn in the payload.

    To add a customer-managed encryption key to your organization, make a POST - Create Key Metadata call to the Capella Management API. For example:

    • $BASEURL is the base URL for the API call.

    • $ORGID is the organization ID.

    • $TOKEN is the API key token.

    • $ARN is the Amazon Resource Name (ARN) of the KMS encryption key.

    • $CMEKID is the Capella ID of the customer-managed encryption key.

    HTTP Request
    curl --request POST \
  --url "$BASEURL/v4/organizations/$ORGID/cmek" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Key name",
  "description": "Description of the key",
  "config": {
	  "arn": "$ARN"
	  }
  }'
    HTTP Response
    {
    "id": "$CMEKID"
}

    Create a Database Using a Customer-Managed Encryption Key

    After adding a customer-managed encryption key, you can use this key when creating new databases with the Management API. Do this by adding the cmekId field with the Capella ID of the customer-managed encryption key to the payload when creating a database.

    For more information, see POST - Create Cluster

    Apply a Customer-Managed Encryption Key to an Existing Database

    To apply a customer-managed encryption key to an existing database, make a POST - Associate Key with Cluster call to the Capella Management API. This call needs the ID of the database you want to apply the encryption to and the CMEK ID—​the Capella ID of the customer-managed encryption key you’re using.

    The CMEK ID is in the response when you add a new key, and you can retrieve it by making a GET - List Key Metadata call to the Capella Management API.

    When the POST - Associate Key with Cluster call is successful, the database rebalances to encrypt the existing data with the customer-provided key. Rebalancing does not cause any downtime.

    You can confirm that your database is using the encryption key by making a GET - Get Cluster call and finding cmekId in the response.

    Key Validation

    Every 30 minutes, Capella completes a validation check to verify the permissions of the key and that it’s accessible.

    Databases using an unavailable customer-managed encryption key experience availability issues and data loss. When the cause of a key validation failure is a deleted encryption key in your KMS, restoring the key can resolve the issue. Refer to your key management provider’s documentation for more information about key restoration:

    Key Rotation

    Do not use key rotation in the cloud service provider. KMS encryption key expiry is not supported. Only rotate keys out of Capella and remove them from your key management provider once your database has a new KMS encryption key. If a customer-managed encryption key becomes unavailable, the related database experiences availability issues and data loss.

    Capella cannot rotate customer-managed encryption keys. You must do this using the Capella Management API.

    To rotate your customer-managed encryption keys:

    1. Create a new KMS encryption key in your cloud service provider.

    2. Make a PUT - Rotate Key call to the Capella Management API with the resource name of your new KMS encryption key.

      After associating a new key with your database, Capella rebalances all nodes in that database. Rebalancing does not cause any downtime. Only remove the old key from your key management provider once your database is using the new KMS encryption key.

    You can rotate customer-managed encryption keys once every 30 days. Contact Couchbase Support if you need to rotate keys earlier.

    See Also