Customer Managed Encryption Keys (CMEK)

ClickHouse Cloud enables customers to protect their services hosted on AWS by leveraging their own AWS KMS key. We utilize the ClickHouse's built-in Virtual File System for Data Encryption feature to encrypt and protect your data. The data encryption key used by ClickHouse service is then encrypted and protected using customer's provided AWS KMS key in a process known as envelope encryption. All the service needs for this to work is access to your AWS KMS key to decrypt & encrypt the data encryption key at runtime.

note

To enable this feature for ClickHouse Cloud Production services in AWS please contact support. Customer managed encryption keys must be specified at the time the service is created. Existing services cannot use this option at this time.

Step 1. Creating an AWS KMS Key

You can create the AWS KMS key via the AWS Console, CloudFormation stack, or using a Terraform provider. We walk through the steps for each below.

Option 1. Manually create a KMS key via the AWS Console

Note: If you already have a KMS key you want to use, you can move on to the next step.

1. Login to your AWS Account and navigate to the Key Management Service.
2. Select Customer managed keys on the left.
3. Click Create key on the upper right.
4. Choose Key type "Symmetric" and Key usage "Encrypt and decrypt" and click Next.
5. Enter an alias (display name) for your key and click Next.
6. Choose your key administrator(s) and click Next.
7. (Optional) Choose your key user(s) and click Next.
8. Add the following code snippet at the bottom of the Key policy.

   {
               "Sid": "Allow ClickHouse Access",
               "Effect": "Allow",
               "Principal": {
                   "AWS": "arn:aws:iam::576599896960:role/prod-kms-request-role"
               },
               "Action": ["kms:GetPublicKey",
                       "kms:Decrypt",
                       "kms:GenerateDataKeyPair",
                       "kms:Encrypt",
                       "kms:GetKeyRotationStatus",
                       "kms:GenerateDataKey",
                       "kms:DescribeKey"],
               "Resource": "*"
           }
   
9. Click Finish.
10. Click the alias of the key you just created.
11. Use the copy button to copy the ARN.

Option 2. Configure or Create a KMS key using a CloudFormation stack

ClickHouse provides a simple Cloud Formation stack to deploy the AWS Policy for your key. This method supports both existing KMS keys and creation of new KMS keys for ClickHouse Cloud integration.

Use an existing KMS key

1. Login to your AWS account.
2. Visit this link to prepare the CloudFormation template.
3. Enter the ARNs of the KMS key(s) you want to use (comma separated with no spaces in between).
4. Accept "I acknowledge that AWS CloudFormation might create IAM resources with custom names." and click Create stack.
5. Make note of the RoleArn and the KeyArn in the stack output as you will need these for the next step.

Create a new KMS key

1. Login to your AWS account.
2. Visit this link to prepare the CloudFormation template.
3. Accept "I acknowledge that AWS CloudFormation might create IAM resources with custom names." and click Create stack.
4. Make note of the KeyArn in the stack output as you will need this for the next step.

Option 3. Create a KMS key via Terraform

For users who want to deploy the key via Terraform, check out the AWS provider documentation here.

Step 2. Starting a ClickHouse service with Customer Managed Encryption Keys

1. Log into your ClickHouse Cloud account.
2. Go to the Services screen if you are not already there.
3. Click New Service.
4. Select your Cloud provider, Region and name your service.
5. Click Set up encryption key (CMEK).
6. Paste your AWS ARN in the field on the right side of the window.
7. The system will check to ensure the encryption key is accessible.
8. Once you see the Valid message above the AWS ARN box click Create Service.
9. A key icon will show in the upper right corner of the service tile on the Services screen to let you know it is encrypted.

Note: Backups will be encrypted using the same key as the service to which they are associated. If you need to restore an encrypted backup, please contact support.

KMS Key Poller

When using envelope encryption, we need to periodically confirm the AWS KMS key is still valid. We check the access for the AWS KMS Key every 10 minutes, when the access is not valid anymore we stop the ClickHouse service. To resume service, please reinstate access by following the steps on this guide and then start you service.

Note: Deleting the AWS KMS Key will cause your ClickHouse service to be stopped and the data will be unretrievable.