Skip to content

Commit

Permalink
Improve the UI capability of CMEK to make it GA
Browse files Browse the repository at this point in the history 
Signed-off-by: longjun <[email protected]>
  • Loading branch information
@ljun0712
ljun0712 committed Jul 8, 2023
1 parent 477577a commit 510d6f6
Showing 1 changed file with 69 additions and 45 deletions.
114 changes: 69 additions & 45 deletions tidb-cloud/tidb-cloud-encrypt-cmek.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ summary: Learn about how to use Customer-Managed Encryption Key (CMEK) in TiDB C

# Encryption at Rest Using Customer-Managed Encryption Keys

Customer-Managed Encryption Key (CMEK) lets you protect your static data in a TiDB Dedicated cluster using a cryptographic key that is completely controlled by you. This key is known as the CMEK key.
Customer-Managed Encryption Key (CMEK) allows you to secure your static data in a TiDB Dedicated cluster by utilizing a cryptographic key that is under your complete control. This key is referred to as the CMEK key.

After you enable CMEK for a project, all clusters created within this project encrypt their static data using this CMEK key, and any backup data produced by these clusters is also encrypted using the same key. If you do not enable CMEK, TiDB Cloud uses an escrow key to encrypt all data in your cluster at rest.
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:**
>
Expand All @@ -24,13 +24,76 @@ After you enable CMEK for a project, all clusters created within this project en

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

### Step 1. Provision KMS and IAM in your cloud provider
### Step 1. Create a CMEK-enabled project

1. Create your CMEK Key on the AWS Key Management Service (KMS) console. Copy the KMS Key ARN. To learn how to create a key, see [Creating Keys](http://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk) in the AWS documentation.
> **Note:**
>
> You can complete this step through [Create a CMEK-enabled project](https://docs.pingcap.com/tidbcloud/api/v1beta#tag/Project/operation/CreateProject) endpoint of TiDB Cloud API. Make sure the `aws_cmek_enabled` field is set to `true`.
You need to create a CMEK-enabled project, take the following steps:

1. Click <MDSvgIcon name="icon-top-organization" /> in the lower-left corner of the TiDB Cloud console.
2. Click **Organization Settings**. You can enter your organization management page.
3. Click **Create New Project** to enter the project creation page.
4. Fill in a project name
5. Choose to enable the CMEK capability of the Project.
6. Click **Confirm** to complete the project creation.

> **Note:**
>
> After creating a CMEK-enabled project, you will be redirected to the Encryption Access page so that you can complete the CMEK configuration.
### Step 2. Complete the CMEK configuration of the project

> **Note:**
>
> You can complete this step through the "Configure AWS CMEK" endpoint of the TiDB Cloud API.
You need to complete the CMEK configuration of the project, take the following steps:
1. Click <MDSvgIcon name="icon-left-projects" /> in the lower-left corner, switch to the target project if you have multiple projects, and then click **Admin**.
2. Click **Encryption Access** to enter the encryption management page of the project.
3. Click **Create Encryption Key** to enter the key creation page.
4. The key provider only supports AWS KMS. You can choose the region where the encryption key is used.
5. Copy and save JSON file as ROLE-TRUST-POLICY.JSON，This file describes the trust relationship. Please add this trust relationship to the key policy of AWS KMS. Please refer to [Key policies in AWS KMS](https://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/key-policies.html).
6. Fill in the Key ARN obtained from AWS KMS.
7. Click **Create** to complete the creation of the key.

> **Note:**
>
> - this feature is in the development stage and the policy requirement could be subject to change as future features might require more permissions.
> - For projects that do not have CMEK enabled, you can view the Encryption Access page, but you are not allowed to click Create New Key.
### Step 3. Create a cluster

[Create a TiDB Dedicated Cluster](https://docs.pingcap.com/tidbcloud/create-tidb-cluster) hosted on AWS under the project created in Step 1. 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

2. Create an IAM role and configure the role's access policy to CMEK.
You can configure [automatic CMEK rotation](http://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) on AWS KMS. With this rotation enabled, you do not need to update the Encryption at Rest project settings in TiDB Cloud, including the CMEK ID.

To make the TiDB cluster function as expected, you need to grant certain permissions to the TiDB account for accessing KMS. Note that this feature is in the development stage and the policy requirement could be subject to change as future features might require more permissions. Here’re the required permissions for supported features at present:
## Revoke and restore CMEK

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

1. On the AWS KMS console, revoke the corresponding permissions and update the KMS Key policy.
2. 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:

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

## Appendix

If you need to configure CMEK through TiDB Cloud API, You need to use the "Configure AWS CMEK" endpoint of the TiDB Cloud API. Before calling the API, you need to configure the key policy on AWS KMS, please add the following information to In the key policy:

```json
{
Expand Down Expand Up @@ -85,42 +148,3 @@ If you want to encrypt your data using the KMS owned by your account, take the f
> - For EBS-related policy in the preceding block, refer to [AWS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/conditions-kms.html#conditions-kms-caller-account).
> - For S3-related policy in the preceding block, refer to [AWS blog](https://repost.aws/knowledge-center/s3-bucket-access-default-encryption).
### Step 2. Create a new project and enable CMEK

> **Note:**
>
> Currently, the CMEK configuration is not available on the TiDB Cloud console. You can only configure the project using TiDB Cloud API.

1. Create a new project and enable AWS CMEK using the [Create a project](https://docs.pingcap.com/tidbcloud/api/v1beta#tag/Project/operation/CreateProject) endpoint of TiDB Cloud API.

Make sure the `aws_cmek_enabled` field is set to `true`.

2. Configure the KMS Key ARN for the specified region (for example, us-east-1) under this project using the [Configure AWS CMEK](https://docs.pingcap.com/tidbcloud/api/v1beta#tag/Cluster/operation/CreateAwsCmek) endpoint of TiDB Cloud API.

### Step 3. Create a cluster

Create a TiDB Dedicated cluster hosted on AWS under the project created in Step 1. 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](http://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) on AWS KMS. With this rotation enabled, you do not need to update the Encryption at Rest 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:

1. On the AWS KMS console, revoke the corresponding permissions and update the KMS Key policy.
2. 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:

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

0 comments on commit 510d6f6

Please sign in to comment.