Manage Customer-Managed Encryption Keys (CMEK) for CockroachDB Dedicated

On this page Carat arrow pointing down

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

This page shows how to enable Customer-Managed Encryption Keys (CMEK) for a CockroachDB Dedicated cluster.

To follow this procedure requires admin access to your CockroachDB Dedicated organization, and the ability to create and manage identity and access management (IAM) and key management (KMS) services in your organization's cloud, i.e., your Google Cloud Platform (GCP) project or Amazon Web Services (AWS) account.

See also:

Before you begin

  • A new CockroachDB Dedicated private cluster] is required. CMEK is not supported on CockroachDB Serverless. An existing cluster cannot be migrated to a private cluster. Refer to Create Private Clusters.
  • A service account with admin privilege on clusters in your organization is required. Refer to Service Accounts.

Overview of CMEK management procedures

This section gives a high level overview of the operations involved with implementing CMEK with your CockroachDB Dedicated cluster.

  • Enabling CMEK for a CockroachDB Dedicated requires several steps:

    • Provision an encryption key with your cloud provider's key management service (KMS).
    • Grant CockroachDB Cloud access to use the new encryption key.
    • Switch your cluster to use the new encryption key for CMEK.

  • Check CMEK status allows you to inspect the CMEK state of your cluster with a call to the Cluster API.

  • Rotate a CMEK key allows you to begin using a new CMEK key for one or more cluster regions.

  • Revoke CMEK for a cluster by revoking CockroachDB Dedicated's access to your CMEK at the IAM/KMS level.

  • Restore CMEK following a revocation event by reauthorizing CockroachDB Cloud to use your key, and coordinating with our support team to assist in recovering your Organization.

Enable CMEK

Step 1. Prepare your CockroachDB Dedicated Organization

  1. Create a CockroachDB Cloud service account.
  2. Create an API key for the service account to use.

Step 2. Provision your cluster

Create a new private cluster on CockroachDB Dedicated. To create a private cluster, you must use CockroachDB Cloud API or CockroachDB's Terraform provider. An existing cluster cannot be migrated to be a private cluster.

Step 3. Provision IAM and KMS in your Cloud

Next, you must provision the required resources in your cloud provider's KMS platform, whether this is AWS or GCP:

  1. The key itself.
  2. The principal that is authorized to encrypt and decrypt using the key, which is an IAM role in AWS or a cross-tenant service account in GCP.

Follow the instructions that correspond to your cluster's deployment environment:

Step 4. Activate CMEK for your CockroachDB Dedicated Cluster

Follow the steps in this section to activate CMEK with a call to the cluster's /cmek endpoint, using the cloud-specific CMEK configuration manifest you built in Step 3. Provision IAM and KMS in your Cloud.

Refer to the API specification.

  1. Create a new file named cmek_config.json. This file will contain a JSON array of region_spec objects, each of which includes the name of a CockroachDB Cloud region and a key_spec that is specific to the target KMS platform and specifies the URI of the CMEK key and the principal that is authorized to encrypt and decrypt using the key.

    Start from the example for your KMS platform and replace the placeholder values. Each of these examples includes region_spec objects for two CockroachDB Cloud regions; when enabling CMEK, you must include a region_spec for each region in the cluster.

    • AWS:

      icon/buttons/copy 
      {
  "region_specs": [
    {
      "region": "{COCKROACHDB_CLOUD_REGION}",
      "key_spec": {
        "type": "AWS_KMS",
        "uri": "{YOUR_AWS_KMS_KEY_ARN}",
        "auth_principal": "{YOUR_AWS_IAM_ROLE_ARN}"
      }
    },
    {
      "region": "{COCKROACHDB_CLOUD_REGION}",
      "key_spec": {
        "type": "AWS_KMS",
        "uri": "{YOUR_AWS_KMS_KEY_ARN}",
        "auth_principal": "{YOUR_AWS_IAM_ROLE_ARN}"
      }
    }
  ]
}

    • GCP:

      icon/buttons/copy 
      {
  "region_specs": [
    {
      "region": "{COCKROACHDB_CLOUD_REGION}",
      "key_spec": {
        "type": "GCP_CLOUD_KMS",
        "uri": "{YOUR_GCP_KMS_KEY_RESOURCE_ID_EXCLUDING_VERSION}",
        "auth_principal": "{YOUR_GCP_SERVICE_ACCOUNT_ID}"
      }
    },
    {
      "region": "{COCKROACHDB_CLOUD_REGION}",
      "key_spec": {
        "type": "GCP_CLOUD_KMS",
        "uri": "{YOUR_GCP_KMS_KEY_RESOURCE_ID_EXCLUDING_VERSION}",
        "auth_principal": "{YOUR_GCP_SERVICE_ACCOUNT_ID}"
      }
    }
  ]
}
    Note:

    When enabling CMEK on a multi-region cluster, your region_spec must include an entry for each of the cluster's regions. Otherwise, an error occurs and CMEK is not enabled.

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

    icon/buttons/copy 
    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

An API call displays information about your cluster's use of CMEK:

See the API specification.

icon/buttons/copy 
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 Dedicated 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.

The API to rotate a CMEK key is nearly identical to the API to activate CMEK on a cluster, with one notable exception. When you activate CMEK, you use a POST request that includes a CMEK key for each of the cluster's regions. When you rotate a CMEK key, you use a PUT request that includes a CMEK key for each region you intend to rotate.

See the API specification.

To rotate the CMEK keys for one or more cluster regions:

  1. Create a new file named cmek_config.json. This file will contain a JSON array of region_spec objects, each of which includes the name of a CockroachDB Cloud region and a key_spec that is specific to the target KMS platform and specifies the URI of the CMEK key and the principal that is authorized to encrypt and decrypt using the key.

    Start from the example for your KMS platform and replace the placeholder values. Each of these examples includes region_spec objects for two CockroachDB Cloud regions; you need only include regions for which you want to rotate the CMEK key.

    • AWS:

      icon/buttons/copy 
      {
"region_specs": [
  {
    "region": "{COCKROACHDB_CLOUD_REGION}",
    "key_spec": {
      "type": "AWS_KMS",
      "uri": "{YOUR_AWS_KMS_KEY_ARN}",
      "auth_principal": "{YOUR_AWS_IAM_ROLE_ARN}"
    }
  },
  {
    "region": "{COCKROACHDB_CLOUD_REGION}",
    "key_spec": {
      "type": "AWS_KMS",
      "uri": "{YOUR_AWS_KMS_KEY_ARN}",
      "auth_principal": "{YOUR_AWS_IAM_ROLE_ARN}"
    }
  }
]
}

    • GCP:

      icon/buttons/copy 
      {
"region_specs": [
  {
    "region": "{COCKROACHDB_CLOUD_REGION}",
    "key_spec": {
      "type": "GCP_CLOUD_KMS",
      "uri": "{YOUR_GCP_KMS_KEY_RESOURCE_ID_EXCLUDING_VERSION}",
      "auth_principal": "{YOUR_GCP_SERVICE_ACCOUNT_ID}"
    }
  },
  {
    "region": "{COCKROACHDB_CLOUD_REGION}",
    "key_spec": {
      "type": "GCP_CLOUD_KMS",
      "uri": "{YOUR_GCP_KMS_KEY_RESOURCE_ID_EXCLUDING_VERSION}",
      "auth_principal": "{YOUR_GCP_SERVICE_ACCOUNT_ID}"
    }
  }
]
}

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

    icon/buttons/copy 
    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, update your cluster's region definitions using the CockroachDB Cloud API Update Cluster endpoint.

  1. Construct the data payload JSON to update you region definitions.

    The payload format depends on which cloud provider you use:

    • AWS:

      icon/buttons/copy 

      # cmek_aws_config.json
{
    "dedicated": {
        "region_nodes": {
            "us-west-1": 3,
            "us-central-1": 5
        },
        "cmek_region_specs": [
            {
                "region": "us-west-1",
                "key_spec": {
                    "type": "AWS_KMS",
                    "uri": "{id-of-key}",
                    "auth_principal": "{role-with-kms-access}"
                }
            },
            {
                "region": "us-central-1",
                "key_spec": {
                    "type": "AWS_KMS",
                    "uri": "{id-of-another-key}",
                    "auth_principal": "{another-role-with-kms-access}"
                }
            }
        ],
        "hardware": {
            "machine_type": "n2-standard-8"
        }
    }
}

    • GCP:

      icon/buttons/copy 

      # cmek_gcp_config.json
{
    "dedicated": {
        "region_nodes": {
            "us-west1": 3,
            "us-central1": 5
        },
        "cmek_region_specs": [
            {
                "region": "us-west1",
                "key_spec": {
                    "type": "GCP_CLOUD_KMS",
                    "uri": "{id-of-key}",
                    "auth_principal": "{service-account-with-kms-access}"
                }
            },
            {
                "region": "us-central1",
                "key_spec": {
                    "type": "GCP_CLOUD_KMS",
                    "uri": "{id-of-another-key}",
                    "auth_principal": "{another-service-account-with-kms-access}"
                }
            }
        ],
        "hardware": {
            "machine_type": "n2-standard-8"
        }
    }
}

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

    icon/buttons/copy 
    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

Revoking access to the CMEK means disabling all encryption/decryption of data in your cluster, which means preventing reading and writing any data from or to your cluster. This likely implies a shutdown of your service, with significant business implications. This is a disaster mitigation tactic to be used only in a scenario involving a severe, business critical security breach.

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

Step 1. Revoke IAM access

Warning:

Do not delete the CMEK key. Deleting the CMEK key will permanently prevent decryption of your data, preventing all possible access and rendering the data inaccessible.

First, revoke CockroachDB Dedicated's access to your key at the IAM level in your cloud provider's KMS platform.

You can do this two ways:

  • Remove the authorization granted to CockroachDB Dedicated cluster with your cross-account IAM role.
  • Remove the KMS key permissions from the IAM policy attached to your cross-account IAM role.

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.

Step 2. Update your cluster to stop using the CMEK key for encryption

Your cluster will continue to operate with the encryption keys it has provisioned with your CMEK key until you update it to revoke CMEK.

  1. Update your cluster with the the Cloud API as follows:

    See the API specification.

    icon/buttons/copy 
    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.

Step 3. Assess and resolve the situation

Once you have resolved the security incident, re-authorize CMEK for your cluster to return to normal operations.

Restore CMEK following a revocation event

To restore CMEK after the incident has been resolved, contact your account team, or create a support ticket.


Yes No
On this page

Yes No

Product

Resources

Learn

Support Channels

Company

Get developer news