Manage CMEK for CockroachDB Advanced

On this page

Customer-Managed Encryption Keys (CMEK) for CockroachDB Dedicated advanced allows the customer to delegate responsibility for the work of encrypting their cluster data to CockroachDB Cloud, while maintaining the ability to completely revoke CockroachDB Cloud's access.

This page shows how to enable Customer-Managed Encryption Keys (CMEK) for CockroachDB Advanced advanced.

Before you begin

To enable CMEK for a cluster, you need:

• An IAM role in your AWS account or a cross-tenant service account in your GCP project. CockroachDB Cloud will use this identity to encrypt and decrypt using the CMEK. This page shows how to provision a new identity, but you can use an existing identity instead. CMEK is not yet available for CockroachDB Advanced on Azure.
• A CMEK key for your cluster stored in AWS KMS or GCP KMS. CockroachDB Cloud never has access to the CMEK itself. This page shows how to provision a new CMEK directly in your KMS or using Hashicorp Vault, but you can use an existing key instead.
• A new CockroachDB Advanced private cluster with advanced security features enabled. A private cluster's nodes communicate only over private Cloud infrastructure, avoiding public networks.
  
  Advanced security features can be enabled only during cluster creation. If necessary, create a new CockroachDB Advanced private cluster and enable advanced security features. Complete the steps in this page before inserting data into the cluster.
• A CockroachDB Cloud service account and a CockroachDB Cloud API key for the service account. You will use the service account to authenticate to the CockroachDB Cloud API and configure CMEK on your cluster.

Enable CMEK

This section shows how to enable CMEK on a CockroachDB Advanced cluster.

Step 2. Create the CMEK key

If you intend to use an existing key as the CMEK, skip this step.

Step 3. Build your CMEK configuration manifest

Compile the information about the service account and key we've just created into a manifest, which you will use to activate CMEK on your cluster with the CockroachDB Cloud API.

1. Use the shell utility JQ to inspect JSON payload:

   Note:

   On a Mac, install JQ with brew install jq

   cat cmek_config.json | jq
   

After you have built your CMEK configuration manifest with the details of your cluster and provisioned the service account and KMS key in GCP, return to Enabling CMEK for a CockroachDB Dedicated cluster.

Step 4. Activate CMEK

Using the CockroachDB Cloud API, send a POST request with the contents of cmek_config.json to the cluster's cmek endpoint.

CLUSTER_ID= #{ your cluster ID }
API_KEY= #{ your API key }
curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters/${CLUSTER_ID}/cmek \
  --header "Authorization: Bearer ${API_KEY}" \
  --header 'content-type: application/json' \
  --data "@cmek_config.json"

Check CMEK status

To view your cluster's CMEK status, send a GET request:

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/cmek \
  --header "Authorization: Bearer ${API_KEY}"

Rotate a CMEK key

You can rotate a CMEK key for a CockroachDB Advanced cluster either by creating a new version of the existing CMEK key or by creating a new CMEK key. At a high level:

To begin using a new version of an existing CMEK key:

1. In your KMS platform, you can either configure automatic rotation for the CMEK key, or you can perform a manual rotation.
2. CockroachDB Cloud does not automatically re-encrypt the store key using the new CMEK key version. For each region you want to update, you must also perform a rotation using the CockroachDB Cloud API without modifying the CMEK key URI. CockroachDB Cloud re-encrypts the store key using the new CMEK key version.

To begin using an entirely new CMEK key:

1. Within your KMS platform, you create a new CMEK key.
2. Next, you perform a rotation using the CockroachDB Cloud API and provide the new CMEK key URI.

To rotate a CMEK key:

1. Edit or recreate the cluster's cmek_config.json to update the region_spec objects, each of which includes the name of a CockroachDB Cloud region and a key_spec that specifies the URI of the CMEK key and the principal that is authorized to encrypt and decrypt using the key.

2. Using the CockroachDB Cloud API, send a PUT request with the contents of cmek_config.json to the cluster's cmek endpoint:

   CLUSTER_ID= #{ your cluster ID }
   API_KEY= #{ your API key }
   curl --request PUT \
     --url https://cockroachlabs.cloud/api/v1/clusters/${CLUSTER_ID}/cmek \
     --header "Authorization: Bearer ${API_KEY}" \
     --header 'content-type: application/json' \
     --data "@cmek_config.json"
   

Add a region to a CMEK-enabled cluster

To add a region to a cluster that already has CMEK enabled:

1. Edit or recreate the cluster's cmek_config.json to update the region_spec objects, each of which includes the name of a CockroachDB Cloud region and a key_spec that specifies the URI of the CMEK key and the principal that is authorized to encrypt and decrypt using the key.

2. Send the payload as a PATCH request to the cluster endpoint:

   CLUSTER_ID= #{ your cluster ID }
   API_KEY= #{ your API key }
   curl --request PATCH \
     --url "https://cockroachlabs.cloud/api/v1/clusters/${CLUSTER_ID}" \
     --header "Authorization: Bearer ${API_KEY}" \
     --header 'content-type: application/json' \
     --data "@cmek_config.json"
   

Revoke CMEK for a cluster

When you revoke access to the CMEK in your KMS, CockroachDB Cloud can no longer encrypt or decrypt your cluster's data. All access to the cluster's data will be prevented until you you restore access. In general, revoke access to the CMEK only when you are permanently decommissioning the cluster or to mitigate a critical security breach or at the request of Cockroach Labs support.

Within your KMS platform, you can revoke access to the CMEK temporarily or permanently.

1. In your cloud provider's KMS platform, revoke CockroachDB Cloud's access to your CMEK key at the IAM level, either by removing the authorization the cross-account IAM role or by removing the cross-account IAM role's permission to access the key.

This will not immediately stop your cluster from encrypting and decrypting data, which does not take effect until you update your cluster in the next step. That is because CockroachDB does not use your CMEK key to encrypt/decrypt your cluster data itself. CockroachDB Dedicated accesses your CMEK key to encrypt/decrypt a key encryption key (KEK). This KEK is used to encrypt a data encryption key (DEK), which is used to encrypt/decrypt your application data. Your cluster will continue to use the already-provisioned DEK until you make the Cloud API call to revoke CMEK.

1. Your cluster will continue to operate with the CMEK until you update it to revoke CMEK. To revoke access:

   curl --request PATCH \
     --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/cmek \
     --header "Authorization: Bearer ${API_KEY}" \
     --header 'content-type: application/json' \
     --data '{"action":"REVOKE"}'
   

2. Check your CMEK status to confirm the revocation has taken effect.

3. Once you have resolved the security incident, re-authorize CMEK for your cluster to return to normal operations. Contact your account team, or create a support ticket.

{
    "Version": "2012-10-17",
    "Id": "crdb-cmek-kms",
    "Statement": [
        {
            "Sid": "Allow use of the key for CMEK",
            "Effect": "Allow",
            "Principal": {
                "AWS": "{ARN_OF_CROSS_ACCOUNT_IAM_ROLE}"
            },
            "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:GenerateDataKey*",
                "kms:DescribeKey",
                "kms:ReEncrypt*"
            ],
            "Resource": "*"
        },
        {
            {OTHER_POLICY_STATEMENT_FOR_ADMINISTRATING_KEY}
        }
    ]
}

Was this helpful?