Provision AWS for CMEK

On this page

This page covers the procedures required to provision Customer-Managed Encryption Keys (CMEK) for your CockroachDB Dedicated cluster with Amazon Web Services (AWS).

This is part of the larger process of Enabling CMEK for a CockroachDB Dedicated cluster.

Overview

• In Step 1. Provision the cross-account IAM role, we will create an IAM role that will be used by CockroachDB Dedicated to access the CMEK key.
• In Step 2. Create the CMEK key, we will explore two ways of creating the required key:
  • Directly in the AWS key management service (KMS) console
  • By setting up a Vault KMS secrets engine with access to AWS KMS, in order to leverage the security advantages of Vault's additional layer of abstraction.

Step 1. Provision the cross-account IAM role

Here we will create a cross-account IAM role. This is a role in your AWS account that can be temporarily assumed by users in another account, in this case, the CockroachDB Dedicated account. This role will have permissions to use the key.

1. Find your CockroachDB Dedicated organization ID in the CockroachDB Cloud organization settings page.

2. Find your CockroachDB Dedicated cluster ID:

   1. Visit the CockroachDB Cloud console cluster page.
   2. Click on the name of your cluster.
   3. Find your cluster ID in the URL of the single cluster overview page: https://cockroachlabs.cloud/cluster/{YOUR_CLUSTER_ID}/overview.

3. Find your CockroachDB Dedicated cluster's associated AWS Account ID.

   You must find the Account ID of the AWS account that CockroachDB Dedicated will use for this purpose. To find the ID of the AWS account associated with your cluster, query the clusters endpoint of the CockroachDB Cloud API. The value is under the account_id field:

   curl --request GET \
     --url https://cockroachlabs.cloud/api/v1/clusters/{YOUR_CLUSTER_ID} \
     --header 'Authorization: Bearer {YOUR_API_KEY}' | jq .account_id
   

4. Create a cross-account IAM role in your AWS account:

   1. In the AWS console, visit the IAM page.
   2. Select Roles and click Create role.
   3. For Trusted entity type, select AWS account.
   4. Choose Another AWS account.
      1. For Account ID, provide the CockroachDB Dedicated AWS Account ID that you found previously by querying your cluster's Cloud API.
      2. Select the option to Require external ID, and for the value of External ID, provide your CockroachDB Dedicated Organization ID.
   5. Finish creating the IAM role with a suitable name. You do not need to add any permissions.
   Note:

   You will need the Amazon Resource Name (ARN) for your cross-account IAM role in the next step.

Step 2. Create the CMEK key

You can create the CMEK key two ways:

• Directly in the AWS console
• By setting up a Vault AWS-KMS secrets engine with access to AWS KMS, in order to leverage the security advantages of Vault's additional layer of abstraction.
  Note:

  Learn more about CockroachDB - HashiCorp Vault integrations.

Option A: Use the AWS Console to create the CMEK key

1. In the AWS console, visit the KMS page.
2. Choose Customer managed keys and click the Create Key button.
3. For Key type, specify Symmetric Key.
4. For Key usage, specify Encrypt and decrypt.
5. Under Advanced options, choose KMS for Key material.
6. Select single region or a multi-region key.
7. Give the key a suitable name, or alias. Note that this cannot be changed.
8. Set the permissions for your key with the crdb-cmek-kms IAM policy provided in the Appendix.
9. Finish creating the key.

After you have provisioned the cross-account IAM role and CMEK key for your CockroachDB cluster's CMEK, return to Enabling CMEK for a CockroachDB Dedicated cluster.

Option B: Use the Vault AWS-KMS secrets engine to create the CMEK key

Before you begin

• You must have a Vault enterprise license.
• You must have Vault enterprise edition installed locally.

1. Initialize your shell for Vault:

    export VAULT_ADDR={YOUR_VAULT_TARGET}
    export VAULT_TOKEN={YOUR_VAULT_TOKEN}
    export VAULT_NAMESPACE="admin"
   

2. Enable the KMS secrets engine:

   vault secrets enable keymgmt
   

   Success! Enabled the keymgmt secrets engine at: keymgmt/
   

3. Connect Vault to your AWS account by creating a KMS provider entry:

   vault write keymgmt/kms/awskms \
   provider="awskms" \
   key_collection="us-east-1" \
   credentials=access_key="{your access key}" \
   credentials=secret_key="{your secret key}"
   

   Success! Data written to: keymgmt/kms/awskms
   

4. Create an encryption key in Vault.

   This will generate the encryption key and store it in Vault. Note that at this point the key has not been imported into your AWS account's KMS service.

   vault write keymgmt/key/crdb-cmek-vault type="aes256-gcm96"
   

   Success! Data written to: keymgmt/key/aes256-gcm96
   

5. Propagate the key to your KMS service

   vault write keymgmt/kms/awskms/key/crdb-cmek-vault \
       purpose="encrypt,decrypt" \
       protection="hsm"
   

   Success! Data written to: keymgmt/kms/awskms/key/crdb-cmek-vault
   

6. In the AWS console, visit the KMS page.

7. Choose Customer managed keys.

8. Select your key, which will be named crdb-cmek-vault-{RANDOM_SUFFIX} where RANDOM_SUFFIX is a string of random numbers.

9. Set the permissions policy for your key with the crdb-cmek-kms IAM policy provided in the Appendix.

10. Save.

After you have provisioned the IAM role and KMS key in AWS, return to Enabling CMEK for a CockroachDB Dedicated cluster.

Appendix: IAM policy for the CMEK key

This IAM policy is to be attached to the CMEK key. It grants the required KMS permissions to the cross-account IAM role to be used by CockroachDB Dedicated.

Note that this IAM policy refers to the ARN for the cross-account IAM role you created at the end of Step 1. Provision the cross-account IAM role.

{
    "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?