Skip to content

Latest commit

 

History

History
188 lines (146 loc) · 8.42 KB

cmek-ops-aws.md

File metadata and controls

188 lines (146 loc) · 8.42 KB
title summary toc docs_area
Provisioning AWS KMS Keys and IAM Roles for CMEK
Tutorial for provisioning CMEK in AWS, covering initial set-up, revocation, and recovery scenarios.
true
manage.security

This page covers the procedures required to provision Customer-Managed Encryption Keys (CMEK) for your {{ site.data.products.dedicated }} cluster with Amazon Web Services (AWS).

This is part of the larger process of Enabling CMEK for a {{ site.data.products.dedicated }} cluster.

Overview

  • In Step 1. Provision the cross-account IAM role, we will create an IAM role that will be used by {{ site.data.products.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.

{{site.data.alerts.callout_info}} For multi-region clusters, you must provide a key and IAM role combination per region. You can provide the same key for all your cluster regions, a different key per region, or any mapping of keys to regions you may choose. It does not matter if the key is a single- or multi-region key. {{site.data.alerts.end}}

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 {{ site.data.products.dedicated }} account. This role will have permissions to use the key.

  1. Find your {{ site.data.products.dedicated }} organization ID in the {{ site.data.products.db }} organization settings page.

  2. Find your {{ site.data.products.dedicated }} cluster ID:

    1. Visit the {{ site.data.products.db }} 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 {{ site.data.products.dedicated }} cluster's associated AWS Account ID.

    You must find the Account ID of the AWS account that {{ site.data.products.dedicated }} will use for this purpose. To find the ID of the AWS account associated with your cluster, query the clusters endpoint of the {{ site.data.products.db }} API. The value is under the account_id field:

    {% include_cached copy-clipboard.html %}

    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 {{ site.data.products.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 {{ site.data.products.dedicated }} Organization ID.
    5. Finish creating the IAM role with a suitable name. You do not need to add any permissions.

    {{site.data.alerts.callout_info}} You will need the Amazon Resource Name (ARN) for your cross-account IAM role in the next step. {{site.data.alerts.end}}

Step 2. Create the CMEK key

You can create the CMEK key two ways:

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 {{ site.data.products.dedicated }} cluster.

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

Prerequisites

  1. Initialize your shell for Vault: {% include_cached copy-clipboard.html %}

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

  2. Enable the KMS secrets engine: {% include_cached copy-clipboard.html %}

    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:

    {% include_cached copy-clipboard.html %}

    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.

    {% include_cached copy-clipboard.html %}

    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

    {% include_cached copy-clipboard.html %}

    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 for your CockroachDB cluster's CMEK, return to Enabling CMEK for a {{ site.data.products.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 {{ site.data.products.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.

{% include_cached copy-clipboard.html %}

{
	"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}
	    }
	]
}