From 13dea9095793d2f06d9d7c2a05f969c34fe9bf3d Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 13 Mar 2024 16:37:37 +0800 Subject: [PATCH 01/14] Add temp.md --- temp.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 temp.md diff --git a/temp.md b/temp.md new file mode 100644 index 0000000000000..af27ff4986a7b --- /dev/null +++ b/temp.md @@ -0,0 +1 @@ +This is a test file. \ No newline at end of file From 29b4b60938faefc862cf85eea0b9f34f440126fa Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 13 Mar 2024 16:37:42 +0800 Subject: [PATCH 02/14] Delete temp.md --- temp.md | 1 - 1 file changed, 1 deletion(-) delete mode 100644 temp.md diff --git a/temp.md b/temp.md deleted file mode 100644 index af27ff4986a7b..0000000000000 --- a/temp.md +++ /dev/null @@ -1 +0,0 @@ -This is a test file. \ No newline at end of file From b61b9ac1787ee8c9fdd4435792cd0df63a4fc15f Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 13 Mar 2024 17:35:30 +0800 Subject: [PATCH 03/14] Update encryption-at-rest.md --- encryption-at-rest.md | 134 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 119 insertions(+), 15 deletions(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index 14ec3d239083e..bd1f4f19baa1c 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -22,7 +22,7 @@ When a TiDB cluster is deployed, the majority of user data is stored on TiKV and TiKV supports encryption at rest. This feature allows TiKV to transparently encrypt data files using [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) or [SM4](https://en.wikipedia.org/wiki/SM4_(cipher)) in [CTR](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation) mode. To enable encryption at rest, an encryption key must be provided by the user and this key is called master key. TiKV automatically rotates data keys that it used to encrypt actual data files. Manually rotating the master key can be done occasionally. Note that encryption at rest only encrypts data at rest (namely, on disk) and not while data is transferred over network. It is advised to use TLS together with encryption at rest. -Optionally, you can use AWS KMS for both cloud and self-hosted deployments. You can also supply the plaintext master key in a file. +Optionally, you can use KMS for both cloud and self-hosted deployments. You can also supply the plaintext master key in a file. TiKV currently does not exclude encryption keys and user data from core dumps. It is advised to disable core dumps for the TiKV process when using encryption at rest. This is not currently handled by TiKV itself. @@ -59,7 +59,7 @@ TiKV currently supports encrypting data using AES128, AES192, AES256, or SM4 (on * Master key. The master key is provided by user and is used to encrypt the data keys TiKV generates. Management of master key is external to TiKV. * Data key. The data key is generated by TiKV and is the key actually used to encrypt data. -The same master key can be shared by multiple instances of TiKV. The recommended way to provide a master key in production is via AWS KMS. Create a customer master key (CMK) through AWS KMS, and then provide the CMK key ID to TiKV in the configuration file. The TiKV process needs access to the KMS CMK while it is running, which can be done by using an [IAM role](https://aws.amazon.com/iam/). If TiKV fails to get access to the KMS CMK, it will fail to start or restart. Refer to AWS documentation for [KMS](https://docs.aws.amazon.com/kms/index.html) and [IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) usage. +The same master key can be shared by multiple instances of TiKV. The recommended way to provide a master key in production is via KMS. Currently, TiKV supports KMS encryption on [AWS](https://docs.aws.amazon.com/zh_cn/kms/index.html), [Google Cloud](https://cloud.google.com/security/products/security-), and [Azure](https://docs.aws.amazon.com/zh_cn/kms/index.html). To enable KMS encryption, you need to create a customer master key (CMK) through KMS, and then provide the CMK key ID to TiKV using the configuration file. If TiKV fails to get access to the KMS CMK, it will fail to start or restart. Alternatively, if using custom key is desired, supplying the master key via file is also supported. The file must contain a 256 bits (or 32 bytes) key encoded as hex string, end with a newline (namely, `\n`), and contain nothing else. Persisting the key on disk, however, leaks the key, so the key file is only suitable to be stored on the `tempfs` in RAM. @@ -67,7 +67,38 @@ Data keys are passed to the underlying storage engine (namely, RocksDB). All fil Regardless of data encryption method, data keys are encrypted using AES256 in GCM mode for additional authentication. This required the master key to be 256 bits (32 bytes), when passing from file instead of KMS. -### Key creation +### Configure encryption + +To enable encryption, you can add the encryption section in the configuration files of TiKV and PD: + +``` +[security.encryption] +data-encryption-method = "aes128-ctr" +data-key-rotation-period = "168h" # 7 days +``` + +- `data-encryption-method` is used to specify the encryption algorithm. The possible values are `"aes128-ctr"`, `"aes192-ctr"`, `"aes256-ctr"`, `"sm4-ctr"` (only for v6.3.0 and later versions), and `"plaintext"`. The default value is `"plaintext"`, which means that encryption is disabled by default. + + - For a new TiKV cluster or an existing TiKV cluster, only data written after encryption is enabled is guaranteed to be encrypted. + - To disable encryption after it is enabled, remove `data-encryption-method` from the configuration file or set its value to `"plaintext"`, and then restart TiKV. + - To change the encryption algorithm, replace `data-encryption-method` with a supported encryption algorithm, and then restart TiKV. after replacing the encryption algorithm, the encrypted file generated by the old encryption algorithm will be gradually rewritten to the encrypted file generated by the new encryption algorithm as new data is written. + +- `data-key-rotation-period` is used to specify how often TiKV rotates keys. + +If encryption is enabled (that is, the value of `data-encryption-method` is not `"plaintext"`), you must specify a master key in either of the following ways: + +- [Specify a master key via KMS](#specify-the-master-key-via-kms) +- [Specify a master key via a file](#specify-the-master-key-via-file) + +#### Specify a master key via KMS + +TiKV supports KMS encryption for three platforms: AWS, Google Cloud, and Azure. Depending on the platform where your service is deployed, you can choose one of them to configure KMS encryption. + + + +**Step 1: Creating a master key** To create a key on AWS, follow these steps: @@ -85,19 +116,9 @@ aws --region us-west-2 kms create-alias --alias-name "alias/tidb-tde" --target-k The `--target-key-id` to enter in the second command is in the output of the first command. -### Configure encryption - -To enable encryption, you can add the encryption section in the configuration files of TiKV and PD: - -``` -[security.encryption] -data-encryption-method = "aes128-ctr" -data-key-rotation-period = "168h" # 7 days -``` - -Possible values for `data-encryption-method` are "aes128-ctr", "aes192-ctr", "aes256-ctr", "sm4-ctr" (only in v6.3.0 and later versions) and "plaintext". The default value is "plaintext", which means encryption is not turned on. `data-key-rotation-period` defines how often TiKV rotates the data key. Encryption can be turned on for a fresh TiKV cluster, or an existing TiKV cluster, though only data written after encryption is enabled is guaranteed to be encrypted. To disable encryption, remove `data-encryption-method` in the configuration file, or reset it to "plaintext", and restart TiKV. To change encryption method, update `data-encryption-method` in the configuration file and restart TiKV. To change the encryption algorithm, replace `data-encryption-method` with a supported encryption algorithm and then restart TiKV. After the replacement, as new data is written in, the encryption file generated by the previous encryption algorithm is gradually rewritten to a file generated by the new encryption algorithm. +**Step 2: Configure the master key** -The master key has to be specified if encryption is enabled (that is,`data-encryption-method` is not "plaintext"). To specify a AWS KMS CMK as master key, add the `encryption.master-key` section after the `encryption` section: +To specify the master key using AWS KMS, add the `[security.encryption.master-key]` configuration after the `[security.encryption]` section in the TiKV configuration file: ``` [security.encryption.master-key] @@ -110,6 +131,89 @@ endpoint = "https://kms.us-west-2.amazonaws.com" The `key-id` specifies the key ID for the KMS CMK. The `region` is the AWS region name for the KMS CMK. The `endpoint` is optional and you do not need to specify it normally unless you are using an AWS KMS-compatible service from a non-AWS vendor or need to use a [VPC endpoint for KMS](https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html). You can also use [multi-Region keys](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) in AWS. For this, you need to set up a primary key in a specific region and add replica keys in the regions you require. + + +
+ +**Step 1: Create a master key** + +To create a key on Google Cloud, take the following steps: + +1. Go to [Key Management](https://console.cloud.google.com/security/kms/keyrings) in the Google Cloud Console. +2. Click **Create Key Ring**. Enter a name for the key ring, select the location of the key ring, and then click **Create**. Note that the location of the key ring needs to cover the region where the TiDB cluster is deployed. +3. Select the key ring you created in the previous step, and then click **Create Key** on the key ring details page. +4. Enter a name for the key, set the information for the key as follows, and then click **Create**. + + - **Protection Level**: **Software** or **HSM** + - **Key Material**: **Generated key** + - **Purpose**: **Symmetric encrypt/decrypt** + +You can also perform this operation using the gcloud CLI: + +```shell +gcloud kms keyrings create "key-ring-name" --location "global" +gcloud kms keys create "key-name" --keyring "key-ring-name" --location "global" --purpose "encryption" --rotation-period "30d" +``` + +Make sure to replace the values of `"key-ring-name"`, `"key-name"`, `"global"`, and `"30d"` in the preceding command with the names and configurations corresponding to your actual key. + +**Step 2: Configure the master key** + +To specify the master key using Google Cloud KMS, add the `[security.encryption.master-key]` configuration after the `[security.encryption]` section: + +``` +[security.encryption.master-key] +type = "kms" +key-id = "projects/project-name/locations/global/keyRings/key-ring-name/cryptoKeys/key-name" +vendor = "gcp" + +[security.encryption.master-key.gcp] +credential-file-path = "/path/to/credential.json" +``` + +- `key-id` specifies the key ID of the KMS CMK. +- `credential-file-path` specifies the path of the authentication credentials file, which currently supports two types of credentials: Service Account and Authentication User. If the TiKV environment is already configured with [application default credentials](https://cloud.google.com/docs/authentication/application-default-credentials), there is no need to configure the `credential-file-path`. + +
+ +
+ +**Step 1: Create a master key** + +To create a key on Azure, refer to the instructions in [Set and retrieve keys in Azure Key Vault using Azure portal](https://learn.microsoft.com/zh-cn/azure/key-vault/keys/quick-create-portal). + +**Step 2: Configure the master key** + +To specify the master key using Azure KMS, add the `[security.encryption.master-key]` configuration after the `[security.encryption]` section in the TiKV configuration file: + + +``` +[security.encryption.master-key] +type = 'kms' +key-id = 'your-kms-key-id' +region = 'region-name' +endpoint = 'endpoint' +vendor = 'azure' + +[security.encryption.master-key.azure] +tenant-id = 'tenant_id' +client-id = 'client_id' +keyvault-url = 'keyvault_url' +hsm-name = 'hsm_name' +hsm-url = 'hsm_url' +# The following four fields are optional, used to set client authentication credentials. You can configure them according to the requirements of your scenario. +client_certificate = "" +client_certificate_path = "" +client_certificate_password = "" +client_secret = "" +``` + +Except `vendor`, you need to modify the values of other fields in the preceding configuration to the corresponding configuration of the actual key. +
+ + + +#### Specify the master key via a file To specify a master key that's stored in a file, the master key configuration would look like the following: From 67b34b5e2638e25ca5acce027f9092111b9518a9 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 13 Mar 2024 17:37:09 +0800 Subject: [PATCH 04/14] Update encryption-at-rest.md --- encryption-at-rest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index bd1f4f19baa1c..164c93390c43f 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -213,7 +213,7 @@ Except `vendor`, you need to modify the values of other fields in the preceding -#### Specify the master key via a file +#### Specify a master key via a file To specify a master key that's stored in a file, the master key configuration would look like the following: From 992c066a529bf3805c48d273a5474ecfb3c03e97 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 13 Mar 2024 19:03:34 +0800 Subject: [PATCH 05/14] Update encryption-at-rest.md --- encryption-at-rest.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index 164c93390c43f..97bcdd9acc790 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -59,7 +59,7 @@ TiKV currently supports encrypting data using AES128, AES192, AES256, or SM4 (on * Master key. The master key is provided by user and is used to encrypt the data keys TiKV generates. Management of master key is external to TiKV. * Data key. The data key is generated by TiKV and is the key actually used to encrypt data. -The same master key can be shared by multiple instances of TiKV. The recommended way to provide a master key in production is via KMS. Currently, TiKV supports KMS encryption on [AWS](https://docs.aws.amazon.com/zh_cn/kms/index.html), [Google Cloud](https://cloud.google.com/security/products/security-), and [Azure](https://docs.aws.amazon.com/zh_cn/kms/index.html). To enable KMS encryption, you need to create a customer master key (CMK) through KMS, and then provide the CMK key ID to TiKV using the configuration file. If TiKV fails to get access to the KMS CMK, it will fail to start or restart. +The same master key can be shared by multiple instances of TiKV. The recommended way to provide a master key in production is via KMS. Currently, TiKV supports KMS encryption on [AWS](https://docs.aws.amazon.com/kms/index.html), [Google Cloud](https://cloud.google.com/security/products/security-key-management?hl=en), and [Azure](https://learn.microsoft.com/en-us/azure/key-vault/). To enable KMS encryption, you need to create a customer master key (CMK) through KMS, and then provide the CMK key ID to TiKV using the configuration file. If TiKV fails to get access to the KMS CMK, it will fail to start or restart. Alternatively, if using custom key is desired, supplying the master key via file is also supported. The file must contain a 256 bits (or 32 bytes) key encoded as hex string, end with a newline (namely, `\n`), and contain nothing else. Persisting the key on disk, however, leaks the key, so the key file is only suitable to be stored on the `tempfs` in RAM. @@ -139,12 +139,12 @@ You can also use [multi-Region keys](https://docs.aws.amazon.com/kms/latest/deve To create a key on Google Cloud, take the following steps: -1. Go to [Key Management](https://console.cloud.google.com/security/kms/keyrings) in the Google Cloud Console. -2. Click **Create Key Ring**. Enter a name for the key ring, select the location of the key ring, and then click **Create**. Note that the location of the key ring needs to cover the region where the TiDB cluster is deployed. +1. Go to the [Key Management](https://console.cloud.google.com/security/kms/keyrings) page in the Google Cloud console. +2. Click **Create key ring**. Enter a name for the key ring, select a location of the key ring, and then click **Create**. Note that the location of the key ring needs to cover the region where the TiDB cluster is deployed. 3. Select the key ring you created in the previous step, and then click **Create Key** on the key ring details page. 4. Enter a name for the key, set the information for the key as follows, and then click **Create**. - - **Protection Level**: **Software** or **HSM** + - **Protection level**: **Software** or **HSM** - **Key Material**: **Generated key** - **Purpose**: **Symmetric encrypt/decrypt** @@ -152,7 +152,7 @@ You can also perform this operation using the gcloud CLI: ```shell gcloud kms keyrings create "key-ring-name" --location "global" -gcloud kms keys create "key-name" --keyring "key-ring-name" --location "global" --purpose "encryption" --rotation-period "30d" +gcloud kms keys create "key-name" --keyring "key-ring-name" --location "global" --purpose "encryption" --rotation-period "30d" ``` Make sure to replace the values of `"key-ring-name"`, `"key-name"`, `"global"`, and `"30d"` in the preceding command with the names and configurations corresponding to your actual key. @@ -180,7 +180,7 @@ credential-file-path = "/path/to/credential.json" **Step 1: Create a master key** -To create a key on Azure, refer to the instructions in [Set and retrieve keys in Azure Key Vault using Azure portal](https://learn.microsoft.com/zh-cn/azure/key-vault/keys/quick-create-portal). +To create a key on Azure, refer to the instructions in [Set and retrieve keys in Azure Key Vault using Azure portal](https://learn.microsoft.com/en-us/azure/key-vault/keys/quick-create-portal). **Step 2: Configure the master key** From 78b8e431fd6512feca60c030867112cc3c1addc8 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 13 Mar 2024 19:05:50 +0800 Subject: [PATCH 06/14] Update encryption-at-rest.md --- encryption-at-rest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index 97bcdd9acc790..7b773c6cbcd65 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -81,7 +81,7 @@ data-key-rotation-period = "168h" # 7 days - For a new TiKV cluster or an existing TiKV cluster, only data written after encryption is enabled is guaranteed to be encrypted. - To disable encryption after it is enabled, remove `data-encryption-method` from the configuration file or set its value to `"plaintext"`, and then restart TiKV. - - To change the encryption algorithm, replace `data-encryption-method` with a supported encryption algorithm, and then restart TiKV. after replacing the encryption algorithm, the encrypted file generated by the old encryption algorithm will be gradually rewritten to the encrypted file generated by the new encryption algorithm as new data is written. + - To change the encryption algorithm, replace `data-encryption-method` with a supported encryption algorithm, and then restart TiKV. After the replacement, as new data is written in, the encryption file generated by the previous encryption algorithm is gradually rewritten to a file generated by the new encryption algorithm. - `data-key-rotation-period` is used to specify how often TiKV rotates keys. From 91c3e86bb8fff94cca4c47c4313060ca889bfb2f Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 13 Mar 2024 19:07:09 +0800 Subject: [PATCH 07/14] Update encryption-at-rest.md --- encryption-at-rest.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index 97bcdd9acc790..25aae54abd693 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -77,13 +77,13 @@ data-encryption-method = "aes128-ctr" data-key-rotation-period = "168h" # 7 days ``` -- `data-encryption-method` is used to specify the encryption algorithm. The possible values are `"aes128-ctr"`, `"aes192-ctr"`, `"aes256-ctr"`, `"sm4-ctr"` (only for v6.3.0 and later versions), and `"plaintext"`. The default value is `"plaintext"`, which means that encryption is disabled by default. +- `data-encryption-method` specifies the encryption algorithm. The possible values are `"aes128-ctr"`, `"aes192-ctr"`, `"aes256-ctr"`, `"sm4-ctr"` (only for v6.3.0 and later versions), and `"plaintext"`. The default value is `"plaintext"`, which means that encryption is disabled by default. - For a new TiKV cluster or an existing TiKV cluster, only data written after encryption is enabled is guaranteed to be encrypted. - To disable encryption after it is enabled, remove `data-encryption-method` from the configuration file or set its value to `"plaintext"`, and then restart TiKV. - To change the encryption algorithm, replace `data-encryption-method` with a supported encryption algorithm, and then restart TiKV. after replacing the encryption algorithm, the encrypted file generated by the old encryption algorithm will be gradually rewritten to the encrypted file generated by the new encryption algorithm as new data is written. -- `data-key-rotation-period` is used to specify how often TiKV rotates keys. +- `data-key-rotation-period` specifies how often TiKV rotates keys. If encryption is enabled (that is, the value of `data-encryption-method` is not `"plaintext"`), you must specify a master key in either of the following ways: From 02e50bffdde122426f10769b36602cb6dc79ebf4 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 18 Mar 2024 11:29:45 +0800 Subject: [PATCH 08/14] Apply suggestions from code review --- encryption-at-rest.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index 6e81854e6f30f..905829405d676 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -22,7 +22,7 @@ When a TiDB cluster is deployed, the majority of user data is stored on TiKV and TiKV supports encryption at rest. This feature allows TiKV to transparently encrypt data files using [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) or [SM4](https://en.wikipedia.org/wiki/SM4_(cipher)) in [CTR](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation) mode. To enable encryption at rest, an encryption key must be provided by the user and this key is called master key. TiKV automatically rotates data keys that it used to encrypt actual data files. Manually rotating the master key can be done occasionally. Note that encryption at rest only encrypts data at rest (namely, on disk) and not while data is transferred over network. It is advised to use TLS together with encryption at rest. -Optionally, you can use KMS for both cloud and self-hosted deployments. You can also supply the plaintext master key in a file. +You can use Key Management Service (KMS) for both cloud and self-hosted deployments or supply the plaintext master key in a file. TiKV currently does not exclude encryption keys and user data from core dumps. It is advised to disable core dumps for the TiKV process when using encryption at rest. This is not currently handled by TiKV itself. @@ -79,9 +79,9 @@ data-key-rotation-period = "168h" # 7 days - `data-encryption-method` specifies the encryption algorithm. The possible values are `"aes128-ctr"`, `"aes192-ctr"`, `"aes256-ctr"`, `"sm4-ctr"` (only for v6.3.0 and later versions), and `"plaintext"`. The default value is `"plaintext"`, which means that encryption is disabled by default. - - For a new TiKV cluster or an existing TiKV cluster, only data written after encryption is enabled is guaranteed to be encrypted. + - For a new TiKV cluster or an existing TiKV cluster, only data written after encryption has been enabled is guaranteed to be encrypted. - To disable encryption after it is enabled, remove `data-encryption-method` from the configuration file or set its value to `"plaintext"`, and then restart TiKV. - - To change the encryption algorithm, replace `data-encryption-method` with a supported encryption algorithm, and then restart TiKV. After the replacement, as new data is written in, the encryption file generated by the previous encryption algorithm is gradually rewritten to a file generated by the new encryption algorithm. + - To change the encryption algorithm, replace `data-encryption-method` with a supported encryption algorithm, and then restart TiKV. After the replacement, as new data is written in, the encryption files generated by the previous encryption algorithm are gradually rewritten to files generated by the new encryption algorithm. - `data-key-rotation-period` specifies how often TiKV rotates keys. @@ -94,11 +94,11 @@ If encryption is enabled (that is, the value of `data-encryption-method` is not TiKV supports KMS encryption for three platforms: AWS, Google Cloud, and Azure. Depending on the platform where your service is deployed, you can choose one of them to configure KMS encryption. -
-**Step 1: Creating a master key** +**Step 1: Create a master key** To create a key on AWS, follow these steps: @@ -142,7 +142,7 @@ To create a key on Google Cloud, take the following steps: 1. Go to the [Key Management](https://console.cloud.google.com/security/kms/keyrings) page in the Google Cloud console. 2. Click **Create key ring**. Enter a name for the key ring, select a location of the key ring, and then click **Create**. Note that the location of the key ring needs to cover the region where the TiDB cluster is deployed. 3. Select the key ring you created in the previous step, and then click **Create Key** on the key ring details page. -4. Enter a name for the key, set the information for the key as follows, and then click **Create**. +4. Enter a name for the key, set the key information as follows, and then click **Create**. - **Protection level**: **Software** or **HSM** - **Key Material**: **Generated key** @@ -172,7 +172,7 @@ credential-file-path = "/path/to/credential.json" ``` - `key-id` specifies the key ID of the KMS CMK. -- `credential-file-path` specifies the path of the authentication credentials file, which currently supports two types of credentials: Service Account and Authentication User. If the TiKV environment is already configured with [application default credentials](https://cloud.google.com/docs/authentication/application-default-credentials), there is no need to configure the `credential-file-path`. +- `credential-file-path` specifies the path of the authentication credentials file, which currently supports two types of credentials: Service Account and Authentication User. If the TiKV environment is already configured with [application default credentials](https://cloud.google.com/docs/authentication/application-default-credentials), there is no need to configure `credential-file-path`.
@@ -180,7 +180,7 @@ credential-file-path = "/path/to/credential.json" **Step 1: Create a master key** -To create a key on Azure, refer to the instructions in [Set and retrieve keys in Azure Key Vault using Azure portal](https://learn.microsoft.com/en-us/azure/key-vault/keys/quick-create-portal). +To create a key on Azure, refer to the instructions in [Set and retrieve a key from Azure Key Vault using the Azure portal](https://learn.microsoft.com/en-us/azure/key-vault/keys/quick-create-portal). **Step 2: Configure the master key** From 3796231ed5403b7bdfe1197cc138c85d573cdb2e Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 18 Mar 2024 11:32:34 +0800 Subject: [PATCH 09/14] Update encryption-at-rest.md --- encryption-at-rest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index 905829405d676..03b4b8ffe47ca 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -100,7 +100,7 @@ TiKV supports KMS encryption for three platforms: AWS, Google Cloud, and Azure. **Step 1: Create a master key** -To create a key on AWS, follow these steps: +To create a key on AWS, take the following steps: 1. Go to the [AWS KMS](https://console.aws.amazon.com/kms) on the AWS console. 2. Make sure that you have selected the correct region on the top right corner of your console. From 47a2f63d1b2060263078f5c38746312acd23986d Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 18 Mar 2024 15:28:24 +0800 Subject: [PATCH 10/14] fix broken links --- encryption-at-rest.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index 03b4b8ffe47ca..df94e9fdbc23d 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -87,8 +87,8 @@ data-key-rotation-period = "168h" # 7 days If encryption is enabled (that is, the value of `data-encryption-method` is not `"plaintext"`), you must specify a master key in either of the following ways: -- [Specify a master key via KMS](#specify-the-master-key-via-kms) -- [Specify a master key via a file](#specify-the-master-key-via-file) +- [Specify a master key via KMS](#specify-a-master-key-via-kms) +- [Specify a master key via a file](#specify-a-master-key-via-file) #### Specify a master key via KMS @@ -186,7 +186,6 @@ To create a key on Azure, refer to the instructions in [Set and retrieve a key f To specify the master key using Azure KMS, add the `[security.encryption.master-key]` configuration after the `[security.encryption]` section in the TiKV configuration file: - ``` [security.encryption.master-key] type = 'kms' From 6587a751355db94d3003739402db6b68069be3c8 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 18 Mar 2024 15:33:06 +0800 Subject: [PATCH 11/14] fix building errors --- encryption-at-rest.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index df94e9fdbc23d..62091449ebaf0 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -131,8 +131,8 @@ endpoint = "https://kms.us-west-2.amazonaws.com" The `key-id` specifies the key ID for the KMS CMK. The `region` is the AWS region name for the KMS CMK. The `endpoint` is optional and you do not need to specify it normally unless you are using an AWS KMS-compatible service from a non-AWS vendor or need to use a [VPC endpoint for KMS](https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html). You can also use [multi-Region keys](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) in AWS. For this, you need to set up a primary key in a specific region and add replica keys in the regions you require. - +
**Step 1: Create a master key** @@ -175,7 +175,6 @@ credential-file-path = "/path/to/credential.json" - `credential-file-path` specifies the path of the authentication credentials file, which currently supports two types of credentials: Service Account and Authentication User. If the TiKV environment is already configured with [application default credentials](https://cloud.google.com/docs/authentication/application-default-credentials), there is no need to configure `credential-file-path`.
-
**Step 1: Create a master key** @@ -208,8 +207,8 @@ client_secret = "" ``` Except `vendor`, you need to modify the values of other fields in the preceding configuration to the corresponding configuration of the actual key. -
+ #### Specify a master key via a file From dd1c8ca6d07ddd316412857f6028bedda8ef094a Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 18 Mar 2024 16:57:25 +0800 Subject: [PATCH 12/14] Apply suggestions from code review --- encryption-at-rest.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index 62091449ebaf0..28d489575e370 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -98,7 +98,7 @@ TiKV supports KMS encryption for three platforms: AWS, Google Cloud, and Azure.
-**Step 1: Create a master key** +**Step 1. Create a master key** To create a key on AWS, take the following steps: @@ -116,7 +116,7 @@ aws --region us-west-2 kms create-alias --alias-name "alias/tidb-tde" --target-k The `--target-key-id` to enter in the second command is in the output of the first command. -**Step 2: Configure the master key** +**Step 2. Configure the master key** To specify the master key using AWS KMS, add the `[security.encryption.master-key]` configuration after the `[security.encryption]` section in the TiKV configuration file: @@ -135,7 +135,7 @@ You can also use [multi-Region keys](https://docs.aws.amazon.com/kms/latest/deve
-**Step 1: Create a master key** +**Step 1. Create a master key** To create a key on Google Cloud, take the following steps: @@ -157,7 +157,7 @@ gcloud kms keys create "key-name" --keyring "key-ring-name" --location "global" Make sure to replace the values of `"key-ring-name"`, `"key-name"`, `"global"`, and `"30d"` in the preceding command with the names and configurations corresponding to your actual key. -**Step 2: Configure the master key** +**Step 2. Configure the master key** To specify the master key using Google Cloud KMS, add the `[security.encryption.master-key]` configuration after the `[security.encryption]` section: @@ -177,11 +177,11 @@ credential-file-path = "/path/to/credential.json"
-**Step 1: Create a master key** +**Step 1. Create a master key** To create a key on Azure, refer to the instructions in [Set and retrieve a key from Azure Key Vault using the Azure portal](https://learn.microsoft.com/en-us/azure/key-vault/keys/quick-create-portal). -**Step 2: Configure the master key** +**Step 2. Configure the master key** To specify the master key using Azure KMS, add the `[security.encryption.master-key]` configuration after the `[security.encryption]` section in the TiKV configuration file: From 4649e79ccca851f24fe20c1e26500a2531ad0204 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 20 Mar 2024 15:15:01 +0800 Subject: [PATCH 13/14] Update encryption-at-rest.md Co-authored-by: Lilian Lee --- encryption-at-rest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index 28d489575e370..d0a1f8bdbe4af 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -81,7 +81,7 @@ data-key-rotation-period = "168h" # 7 days - For a new TiKV cluster or an existing TiKV cluster, only data written after encryption has been enabled is guaranteed to be encrypted. - To disable encryption after it is enabled, remove `data-encryption-method` from the configuration file or set its value to `"plaintext"`, and then restart TiKV. - - To change the encryption algorithm, replace `data-encryption-method` with a supported encryption algorithm, and then restart TiKV. After the replacement, as new data is written in, the encryption files generated by the previous encryption algorithm are gradually rewritten to files generated by the new encryption algorithm. + - To change the encryption algorithm, replace the value of `data-encryption-method` with a supported encryption algorithm, and then restart TiKV. After the replacement, as new data is written in, the encryption files generated by the previous encryption algorithm are gradually rewritten to files generated by the new encryption algorithm. - `data-key-rotation-period` specifies how often TiKV rotates keys. From 3f537b5f5eadb8418bf053b33c05709b97ff9a2f Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 20 Mar 2024 15:24:26 +0800 Subject: [PATCH 14/14] fix broken links --- encryption-at-rest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index d0a1f8bdbe4af..feefd9066b94c 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -88,7 +88,7 @@ data-key-rotation-period = "168h" # 7 days If encryption is enabled (that is, the value of `data-encryption-method` is not `"plaintext"`), you must specify a master key in either of the following ways: - [Specify a master key via KMS](#specify-a-master-key-via-kms) -- [Specify a master key via a file](#specify-a-master-key-via-file) +- [Specify a master key via a file](#specify-a-master-key-via-a-file) #### Specify a master key via KMS