Encryption at Rest Using Customer-Managed Encryption Keys

Customer-Managed Encryption Key (CMEK) allows you to secure your static data in a TiDB Dedicated cluster by utilizing a symmetric encryption key that is under your complete control. This key is referred to as the CMEK key.

Once CMEK is enabled for a project, all clusters created within that project encrypt their static data using the CMEK key. Additionally, any backup data generated by these clusters is encrypted using the same key. If CMEK is not enabled, TiDB Cloud employs an escrow key to encrypt all data in your cluster when it is at rest.

Note

Currently, this feature is only available upon request. If you need to try out this feature, contact support.

Restrictions

Currently, TiDB Cloud only supports using AWS KMS to provide CMEK.
To use CMEK, you need to enable CMEK when creating a project and complete CMEK-related configurations before creating a cluster. You cannot enable CMEK for existing projects.
Currently, in CMEK-enabled projects, you can only create TiDB Dedicated clusters hosted on AWS. TiDB Dedicated clusters hosted on Google Cloud and TiDB Serverless clusters are not supported.
Currently, for a specific project, you can only enable CMEK for one AWS region. Once you have configured it, you cannot create clusters in other regions within the same project.

Enable CMEK

If you want to encrypt your data using the KMS owned by your account, take the following steps.

Step 1. Create a CMEK-enabled project

If you are in the Organization Owner role of your organization, you can create a CMEK-enabled project using either the TiDB Cloud console or API.

Use Console
Use API

To create a CMEK-enabled project, take the following steps:

Click in the lower-left corner of the TiDB Cloud console.
Click Organization Settings, and then click the Projects tab in the left navigation pane. The Projects tab is displayed.
Click Create New Project to open the project creation dialog.
Fill in a project name.
Choose to enable the CMEK capability of the project.
Click Confirm to complete the project creation.

You can complete this step using TiDB Cloud API through the Create a CMEK-enabled project endpoint. Make sure that the aws_cmek_enabled field is set to true.

Currently, TiDB Cloud API is still in beta. For more information, see TiDB Cloud API Documentation.

Step 2. Complete the CMEK configuration of the project

You can complete the CMEK configuration of the project using either the TiDB Cloud console or API.

Note

Make sure that the policy of the key meets the requirements and is free from errors such as insufficient permissions or account issues. These errors can cause clusters to be incorrectly created using this key.

Use Console
Use API

To complete the CMEK configuration of the project, take the following steps:

Click in the lower-left corner, switch to the target project if you have multiple projects, and then click Project Settings.
Click Encryption Access to enter the encryption management page of the project.
Click Create Encryption Key to enter the key creation page.
The key provider only supports AWS KMS. You can choose the region where the encryption key can be used.
Copy and save the JSON file as ROLE-TRUST-POLICY.JSON. This file describes the trust relationship.
Add this trust relationship to the key policy of AWS KMS. For more information, refer to Key policies in AWS KMS.
In the TiDB Cloud console, scroll to the bottom of the key creation page, and then fill in the KMS Key ARN obtained from AWS KMS.
Click Create to create the key.

Configure the key policy on AWS KMS, and add the following information to the key policy:

{
    "Version": "2012-10-17",
    "Id": "cmek-policy",
    "Statement": [
        // EBS-related policy
        {
            "Sid": "Allow access through EBS for all principals in the account that are authorized to use EBS",
            "Effect": "Allow",
            "Principal": {
                "AWS": "*"
            },
            "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:ReEncrypt*",
                "kms:GenerateDataKey*",
                "kms:CreateGrant",
                "kms:DescribeKey"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "kms:CallerAccount": "<pingcap-account>",
                    "kms:ViaService": "ec2.<region>.amazonaws.com"
                }
            }
        },
        // S3-related policy
        {
            "Sid": "Allow TiDB cloud role to use KMS to store encrypted backup to S3",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<pingcap-account>:root"
            },
            "Action": [
                "kms:Decrypt",
                "kms:GenerateDataKey"
            ],
            "Resource": "*"
        },
        ... // user's own admin access to KMS
    ]
}

<pingcap-account> is the account where your clusters run in. If you do not know the account, contact TiDB Cloud Support.
<region> is the region where you want to create your cluster, for example, us-west-2. If you do not want to specify a region, replace <region> with a wildcard *, and put it in a StringLike block.
For EBS-related policy in the preceding block, refer to AWS documentation.
For S3-related policy in the preceding block, refer to AWS blog.

Call the Configure AWS CMEK endpoint of TiDB Cloud API.
Currently, TiDB Cloud API is still in beta. For more information, see TiDB Cloud API Documentation.

Note

This feature will be further enhanced in the future, and upcoming features might require additional permissions. Therefore, this policy requirement is subject to change.

Step 3. Create a cluster

Under the project created in Step 1, create a TiDB Dedicated cluster hosted on AWS. For detailed steps, refer to this document. Ensure that the region where the cluster is located is the same as that in Step 2.

Note

When CMEK is enabled, the EBS volumes used by the nodes of the cluster and the S3 used for the cluster backups are encrypted using CMEK.

Rotate CMEK

You can configure automatic CMEK rotation on AWS KMS. With this rotation enabled, you do not need to update Encryption Access in project settings in TiDB Cloud, including the CMEK ID.

Revoke and restore CMEK

If you need to temporarily revoke TiDB Cloud's access to CMEK, follow these steps:

On the AWS KMS console, revoke the corresponding permissions and update the KMS Key policy.
On the TiDB Cloud console, pause all the clusters in the project.

Note

After you revoke CMEK on AWS KMS, your running clusters are not affected. However, when you pause a cluster and then restore the cluster, the cluster will not be able to restore normally because it cannot access CMEK.

After revoking TiDB Cloud's access to CMEK, if you need to restore the access, follow these steps:

On the AWS KMS console, restore the CMEK access policy.
On the TiDB Cloud console, restore all clusters in the project.

Encryption at Rest Using Customer-Managed Encryption Keys

Restrictions

Enable CMEK

Step 1. Create a CMEK-enabled project

Step 2. Complete the CMEK configuration of the project

Step 3. Create a cluster

Rotate CMEK

Revoke and restore CMEK

Was this page helpful?