From f6a54f3fbbb83982a870a7dbc3ebef0a51b66890 Mon Sep 17 00:00:00 2001 From: glorv Date: Fri, 23 Feb 2024 17:27:37 +0800 Subject: [PATCH 01/14] add kms doc for gcp --- encryption-at-rest.md | 94 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 79 insertions(+), 15 deletions(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index 197f6e0bf291..998b104e6097 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -65,9 +65,31 @@ TiKV 当前支持的加密算法包括 AES128-CTR、AES192-CTR、AES256-CTR 和 无论用户配置了哪种数据加密方法，数据密钥都使用 AES256-GCM 算法进行加密，以方便对主密钥进行验证。所以当使用文件而不是 KMS 方式指定主密钥时，主密钥必须为 256 位（32 字节）。 -### 创建密钥 +### 配置加密 + +要启用加密，你可以在 TiKV 和 PD 的配置文件中添加加密部分： + +``` +[security.encryption] +data-encryption-method = "aes128-ctr" +data-key-rotation-period = "168h" # 7 days +``` + +`data-encryption-method` 的可选值为 `"aes128-ctr"`、`"aes192-ctr"`、`"aes256-ctr"`、`"sm4-ctr"` (仅 v6.3.0 及之后版本) 和 `"plaintext"`。默认值为 `"plaintext"`，即默认不开启加密功能。`data-key-rotation-period` 指定 TiKV 轮换密钥的频率。可以为新 TiKV 集群或现有 TiKV 集群开启加密，但只有启用后写入的数据才保证被加密。要禁用加密，请在配置文件中删除 `data-encryption-method`，或将该参数值为 `"plaintext"`，然后重启 TiKV。若要替换加密算法，则将 `data-encryption-method` 替换成已支持的加密算法，然后重启 TiKV。替换加密算法后，旧加密算法生成的加密文件会随着新数据的写入逐渐被重写成新加密算法所生成的加密文件。 + +如果启用了加密（即 `data-encryption-method` 的值不是 `"plaintext"`），则必须指定主密钥。TiKV 支持 KMS 和文件两种方式指定密钥。 + +#### 配置 KMS 密钥 + +TiKV 支持 AWS、Azure 和 GCP 3 个平台的 KMS 加密，根据服务部署的平台，使用不同的方式配置 KMS 加密。 -如需在 AWS 上创建一个密钥，请执行以下步骤： + + +
+ +##### 创建密钥 + +在 AWS 上创建一个密钥，请执行以下步骤： 1. 进入 AWS 控制台的 [AWS KMS](https://console.aws.amazon.com/kms)。 2. 确保在控制台的右上角选择正确的区域。 @@ -83,19 +105,9 @@ aws --region us-west-2 kms create-alias --alias-name "alias/tidb-tde" --target-k 需要在第二条命令中输入的 `--target-key-id` 是第一条命令的结果。 -### 配置加密 - -要启用加密，你可以在 TiKV 和 PD 的配置文件中添加加密部分： - -``` -[security.encryption] -data-encryption-method = "aes128-ctr" -data-key-rotation-period = "168h" # 7 days -``` - -`data-encryption-method` 的可选值为 `"aes128-ctr"`、`"aes192-ctr"`、`"aes256-ctr"`、`"sm4-ctr"` (仅 v6.3.0 及之后版本) 和 `"plaintext"`。默认值为 `"plaintext"`，即默认不开启加密功能。`data-key-rotation-period` 指定 TiKV 轮换密钥的频率。可以为新 TiKV 集群或现有 TiKV 集群开启加密，但只有启用后写入的数据才保证被加密。要禁用加密，请在配置文件中删除 `data-encryption-method`，或将该参数值为 `"plaintext"`，然后重启 TiKV。若要替换加密算法，则将 `data-encryption-method` 替换成已支持的加密算法，然后重启 TiKV。替换加密算法后，旧加密算法生成的加密文件会随着新数据的写入逐渐被重写成新加密算法所生成的加密文件。 +##### 配置密钥 -如果启用了加密（即 `data-encryption-method` 的值不是 `"plaintext"`），则必须指定主密钥。要使用 AWS KMS 方式指定为主密钥，请在 `[security.encryption]` 部分之后添加 `[security.encryption.master-key]` 部分： +使用 AWS KMS 方式指定为主密钥，请在 `[security.encryption]` 部分之后添加 `[security.encryption.master-key]` 部分： ``` [security.encryption.master-key] @@ -109,6 +121,58 @@ endpoint = "https://kms.us-west-2.amazonaws.com" 你也可以使用 AWS [多区域键](https://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/multi-region-keys-overview.html)。为此，你需要在一个特定的区域设置一个主键，并在需要的区域中添加副本密钥。 +
+ + +
+ +##### 创建密钥 + +在 GCP 平台上创建一个密钥，请执行以下步骤： + +1. 进入 GCP 控制台的 [密钥管理](https://console.cloud.google.com/security/kms/keyrings)。 +2. 点击**创建密钥环**，创建密钥环，注意密钥环所在的位置需要覆盖 TiDB 集群部署的区域。 +3. 选择上一步创建的密钥环，在密钥环详情页面点击**创建密钥**，注意密钥的**保护级别**选择**软件**或 **HSM**，**密钥材料**选择**生成的密钥**，**用途**选择 **Symmetric encrypt/decrypt**。 + +你也可以使用 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" +``` + +请将上述命令中的 "key-ring-name"、"key-name"、"global"、"30d" 等字段替换为实际密钥对应的名称和配置。 + +##### 配置密钥 + +使用 GCP KMS 方式指定为主密钥，请在 `[security.encryption]` 部分之后添加 `[security.encryption.master-key]` 部分： + +``` +[security.encryption.master-key] +type = "kms" +key-id = 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` 指定 KMS CMK 的密钥 ID, `credential-file-path` 指向验证凭据配置文件的路径，目前支持 Serivce Account 和 Authentition User 两种凭据。如果 TiKV 的运行环境已配置 [应用默认凭据](https://cloud.google.com/docs/authentication/application-default-credentials?hl=zh-cn)，则无须此配置项。 + + +
+ +
+ +TBD.. + +
+ + + + +#### 配置文件密钥 + 若要使用文件方式指定主密钥，主密钥配置应如下所示： ``` @@ -129,7 +193,7 @@ path = "/path/to/key/file" TiKV 当前不支持在线轮换主密钥，因此你需要重启 TiKV 进行主密钥轮换。建议对运行中的、提供在线查询的 TiKV 集群进行滚动重启。 -轮换 KMS CMK 的配置示例如下： +轮换 AWS KMS CMK 的配置示例如下： ``` [security.encryption.master-key] From 4270c2fed2715b4de2a43b48ede821dcd4265630 Mon Sep 17 00:00:00 2001 From: glorv Date: Fri, 1 Mar 2024 18:20:16 +0800 Subject: [PATCH 02/14] add azure --- encryption-at-rest.md | 45 ++++++++++++++++++++++++++++++++----------- 1 file changed, 34 insertions(+), 11 deletions(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index 998b104e6097..ea7955375130 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -81,13 +81,13 @@ data-key-rotation-period = "168h" # 7 days #### 配置 KMS 密钥 -TiKV 支持 AWS、Azure 和 GCP 3 个平台的 KMS 加密，根据服务部署的平台，使用不同的方式配置 KMS 加密。 +TiKV 支持 AWS、GCP 和 Azure 3 个平台的 KMS 加密，根据服务部署的平台，使用不同的方式配置 KMS 加密。
-##### 创建密钥 +创建密钥 在 AWS 上创建一个密钥，请执行以下步骤： @@ -105,7 +105,7 @@ aws --region us-west-2 kms create-alias --alias-name "alias/tidb-tde" --target-k 需要在第二条命令中输入的 `--target-key-id` 是第一条命令的结果。 -##### 配置密钥 +配置密钥 使用 AWS KMS 方式指定为主密钥，请在 `[security.encryption]` 部分之后添加 `[security.encryption.master-key]` 部分： @@ -120,13 +120,11 @@ endpoint = "https://kms.us-west-2.amazonaws.com" `key-id` 指定 KMS CMK 的密钥 ID。`region` 为 KMS CMK 的 AWS 区域名。`endpoint` 通常无需指定，除非你在使用非 AWS 提供的 AWS KMS 兼容服务或需要使用 [KMS VPC endpoint](https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html)。 你也可以使用 AWS [多区域键](https://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/multi-region-keys-overview.html)。为此，你需要在一个特定的区域设置一个主键，并在需要的区域中添加副本密钥。 -
-
-##### 创建密钥 +创建密钥 在 GCP 平台上创建一个密钥，请执行以下步骤： @@ -143,7 +141,7 @@ gcloud kms keys create "key-name" --keyring "key-ring-name" --location "global" 请将上述命令中的 "key-ring-name"、"key-name"、"global"、"30d" 等字段替换为实际密钥对应的名称和配置。 -##### 配置密钥 +配置密钥 使用 GCP KMS 方式指定为主密钥，请在 `[security.encryption]` 部分之后添加 `[security.encryption.master-key]` 部分： @@ -158,16 +156,41 @@ credential-file-path = "/path/to/credential.json" ``` `key-id` 指定 KMS CMK 的密钥 ID, `credential-file-path` 指向验证凭据配置文件的路径，目前支持 Serivce Account 和 Authentition User 两种凭据。如果 TiKV 的运行环境已配置 [应用默认凭据](https://cloud.google.com/docs/authentication/application-default-credentials?hl=zh-cn)，则无须此配置项。 +
+
-
+创建密钥 -
+在 Azure 平台创建密钥，请参考文档 [使用 Azure 门户在 Azure Key Vault 中设置和检索密钥](https://learn.microsoft.com/zh-cn/azure/key-vault/keys/quick-create-portal)。 -TBD.. +配置密钥 -
+要使用 Azure KMS 方式指定为主密钥，请在 `[security.encryption]` 部分之后添加 `[security.encryption.master-key]` 部分： +``` +[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' +# 如下 4 个参数为可选字段，用于设置 client 认证的凭证，请根据实际的使用场景进行设置 +client_certificate = "" +client_certificate_path = "" +client_certificate_password = "" +client_secret = "" +``` + +请将上述配置中除 "vendor" 之外的其他字段设置为实际需要使用的密钥对应的配置。 + From 7c27628b70ced79a44e2f58033437e7874a74c75 Mon Sep 17 00:00:00 2001 From: glorv Date: Mon, 4 Mar 2024 14:30:31 +0800 Subject: [PATCH 03/14] fix --- 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 ea7955375130..813639e9a5a6 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -148,7 +148,7 @@ gcloud kms keys create "key-name" --keyring "key-ring-name" --location "global" ``` [security.encryption.master-key] type = "kms" -key-id = key-id = "projects/project-name/locations/global/keyRings/key-ring-name/cryptoKeys/key-name" +key-id = "projects/project-name/locations/global/keyRings/key-ring-name/cryptoKeys/key-name" vendor = "gcp" [security.encryption.master-key.gcp] From 149b9e423ed08c0eca309512647e6716ee21c328 Mon Sep 17 00:00:00 2001 From: glorv Date: Tue, 5 Mar 2024 11:56:21 +0800 Subject: [PATCH 04/14] apply comment --- 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 813639e9a5a6..ab3842757c22 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -57,7 +57,7 @@ TiKV 当前支持的加密算法包括 AES128-CTR、AES192-CTR、AES256-CTR 和 * 主密钥 (master key)：主密钥由用户提供，用于加密 TiKV 生成的数据密钥。用户在 TiKV 外部进行主密钥的管理。 * 数据密钥 (data key)：数据密钥由 TiKV 生成，是实际用于加密的密钥。 -多个 TiKV 实例可共用一个主密钥。在生产环境中，推荐通过 AWS KMS 提供主密钥。首先通过 AWS KMS 创建用户主密钥 (CMK)，然后在配置文件中将 CMK 密钥的 ID 提供给 TiKV。TiKV 进程在运行时可以通过 [IAM 角色](https://aws.amazon.com/iam/)访问 KMS CMK。如果 TiKV 无法访问 KMS CMK，TiKV 就无法启动或重新启动。详情参阅 AWS 文档中的 [KMS](https://docs.aws.amazon.com/zh_cn/kms/index.html) and [IAM](https://docs.aws.amazon.com/zh_cn/IAM/latest/UserGuide/introduction.html)。 +多个 TiKV 实例可共用一个主密钥。在生产环境中，推荐通过 KMS 提供主密钥。目前 TiKV 支持 [AWS](https://docs.aws.amazon.com/zh_cn/kms/index.html)、[Google Cloud](https://cloud.google.com/security/products/security-key-management?hl=zh-CN) 和 [Azure](https://learn.microsoft.com/en-us/azure/key-vault/) 等平台的 KMS 加密。要开启 KMS 加密，首先通过 KMS 创建用户主密钥 (CMK)，然后在配置文件中将 CMK 密钥的 ID 提供给 TiKV。如果 TiKV 无法访问 KMS CMK，TiKV 就无法启动或重新启动。 用户也可以通过文件形式提供主密钥。该文件须包含一个用十六进制字符串编码的 256 位（32 字节）密钥，并以换行符结尾（即 `\n`），且不包含其他任何内容。将密钥存储在磁盘上会泄漏密钥，因此密钥文件仅适合存储在 RAM 内存的 `tempfs` 中。 From 34d4170e23e5db1e296b8e87cb2d89c9a49c401a Mon Sep 17 00:00:00 2001 From: glorv Date: Tue, 5 Mar 2024 16:16:49 +0800 Subject: [PATCH 05/14] apply comments --- encryption-at-rest.md | 52 +++++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 22 deletions(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index ab3842757c22..dc5e5f1aa8d8 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -77,19 +77,22 @@ data-key-rotation-period = "168h" # 7 days `data-encryption-method` 的可选值为 `"aes128-ctr"`、`"aes192-ctr"`、`"aes256-ctr"`、`"sm4-ctr"` (仅 v6.3.0 及之后版本) 和 `"plaintext"`。默认值为 `"plaintext"`，即默认不开启加密功能。`data-key-rotation-period` 指定 TiKV 轮换密钥的频率。可以为新 TiKV 集群或现有 TiKV 集群开启加密，但只有启用后写入的数据才保证被加密。要禁用加密，请在配置文件中删除 `data-encryption-method`，或将该参数值为 `"plaintext"`，然后重启 TiKV。若要替换加密算法，则将 `data-encryption-method` 替换成已支持的加密算法，然后重启 TiKV。替换加密算法后，旧加密算法生成的加密文件会随着新数据的写入逐渐被重写成新加密算法所生成的加密文件。 -如果启用了加密（即 `data-encryption-method` 的值不是 `"plaintext"`），则必须指定主密钥。TiKV 支持 KMS 和文件两种方式指定密钥。 +如果启用了加密（即 `data-encryption-method` 的值不是 `"plaintext"`），则必须指定主密钥。你可以通过以下方式之一来指定主密钥。 -#### 配置 KMS 密钥 +- [通过 KMS 指定主密钥](#通过-KMS-指定主密钥) +- [通过文件指定主密钥](#通过文件指定主密钥) -TiKV 支持 AWS、GCP 和 Azure 3 个平台的 KMS 加密，根据服务部署的平台，使用不同的方式配置 KMS 加密。 +#### 通过 KMS 指定主密钥 + +TiKV 支持 AWS、Google Cloud 和 Azure 这三个平台的 KMS 加密。你可以根据服务部署的平台，你可以选择其中之一配置 KMS 加密。
-创建密钥 +**第 1 步：创建主密钥** -在 AWS 上创建一个密钥，请执行以下步骤： +在 AWS 上创建一个密钥，请进行以下操作： 1. 进入 AWS 控制台的 [AWS KMS](https://console.aws.amazon.com/kms)。 2. 确保在控制台的右上角选择正确的区域。 @@ -105,9 +108,9 @@ aws --region us-west-2 kms create-alias --alias-name "alias/tidb-tde" --target-k 需要在第二条命令中输入的 `--target-key-id` 是第一条命令的结果。 -配置密钥 +**第 2 步：配置主密钥** -使用 AWS KMS 方式指定为主密钥，请在 `[security.encryption]` 部分之后添加 `[security.encryption.master-key]` 部分： +使用 AWS KMS 方式指定主密钥，请在 TiKV 的配置文件中 `[security.encryption]` 部分之后添加 `[security.encryption.master-key]` 配置： ``` [security.encryption.master-key] @@ -122,15 +125,20 @@ endpoint = "https://kms.us-west-2.amazonaws.com" 你也可以使用 AWS [多区域键](https://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/multi-region-keys-overview.html)。为此，你需要在一个特定的区域设置一个主键，并在需要的区域中添加副本密钥。
-
+
+ +**第 1 步：创建主密钥** -创建密钥 +要在 Google Cloud 平台上创建一个密钥，请执行以下步骤： -在 GCP 平台上创建一个密钥，请执行以下步骤： +1. 进入 Google Cloud 控制台的 [密钥管理](https://console.cloud.google.com/security/kms/keyrings)。 +2. 点击**创建密钥环**。输入密钥环的名称，选择密钥环的位置，然后点击**创建**。注意密钥环的位置需要覆盖 TiDB 集群部署的区域。 +3. 选择上一步创建的密钥环，在密钥环详情页面点击**创建密钥**。 +4. 输入密钥的名称，设置密钥的信息如下，然后点击**创建**。 -1. 进入 GCP 控制台的 [密钥管理](https://console.cloud.google.com/security/kms/keyrings)。 -2. 点击**创建密钥环**，创建密钥环，注意密钥环所在的位置需要覆盖 TiDB 集群部署的区域。 -3. 选择上一步创建的密钥环，在密钥环详情页面点击**创建密钥**，注意密钥的**保护级别**选择**软件**或 **HSM**，**密钥材料**选择**生成的密钥**，**用途**选择 **Symmetric encrypt/decrypt**。 + - **保护级别**：**软件**或 **HSM** + - **密钥材料**：**生成的密钥** + - **用途**：**Symmetric encrypt/decrypt** 你也可以使用 gcloud CLI 执行该操作： @@ -139,11 +147,11 @@ 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" ``` -请将上述命令中的 "key-ring-name"、"key-name"、"global"、"30d" 等字段替换为实际密钥对应的名称和配置。 +请将上述命令中的 "key-ring-name"、"key-name"、"global"、"30d" 等字段的值替换为实际密钥对应的名称和配置。 -配置密钥 +**第 2 步：配置主密钥** -使用 GCP KMS 方式指定为主密钥，请在 `[security.encryption]` 部分之后添加 `[security.encryption.master-key]` 部分： +要使用 Google Cloud KMS 方式指定主密钥，请在 `[security.encryption]` 部分之后添加 `[security.encryption.master-key]` 配置： ``` [security.encryption.master-key] @@ -155,18 +163,18 @@ vendor = "gcp" credential-file-path = "/path/to/credential.json" ``` -`key-id` 指定 KMS CMK 的密钥 ID, `credential-file-path` 指向验证凭据配置文件的路径，目前支持 Serivce Account 和 Authentition User 两种凭据。如果 TiKV 的运行环境已配置 [应用默认凭据](https://cloud.google.com/docs/authentication/application-default-credentials?hl=zh-cn)，则无须此配置项。 +`key-id` 指定 KMS CMK 的密钥 ID, `credential-file-path` 指向验证凭据配置文件的路径，目前支持 Service Account 和 Authentication User 两种凭据。如果 TiKV 的运行环境已配置 [应用默认凭据](https://cloud.google.com/docs/authentication/application-default-credentials?hl=zh-cn)，则无须此配置项。
-创建密钥 +**第 1 步：创建主密钥** 在 Azure 平台创建密钥，请参考文档 [使用 Azure 门户在 Azure Key Vault 中设置和检索密钥](https://learn.microsoft.com/zh-cn/azure/key-vault/keys/quick-create-portal)。 -配置密钥 +**第 2 步：配置主密钥** -要使用 Azure KMS 方式指定为主密钥，请在 `[security.encryption]` 部分之后添加 `[security.encryption.master-key]` 部分： +要使用 Azure KMS 方式指定主密钥，请在 TiKV 的配置文件中 `[security.encryption]` 部分之后添加 `[security.encryption.master-key]` 配置： ``` [security.encryption.master-key] @@ -189,12 +197,12 @@ client_certificate_password = "" client_secret = "" ``` -请将上述配置中除 "vendor" 之外的其他字段设置为实际需要使用的密钥对应的配置。 +请将上述配置中除 `vendor` 之外的其他字段值修改为密钥实际的对应配置。
-#### 配置文件密钥 +#### 通过文件指定主密钥 若要使用文件方式指定主密钥，主密钥配置应如下所示： From f954073671924fe5b10a846afcea60a416830725 Mon Sep 17 00:00:00 2001 From: glorv Date: Tue, 5 Mar 2024 16:28:46 +0800 Subject: [PATCH 06/14] fix anchor --- 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 dc5e5f1aa8d8..cd5f93afd3c6 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -79,7 +79,7 @@ data-key-rotation-period = "168h" # 7 days 如果启用了加密（即 `data-encryption-method` 的值不是 `"plaintext"`），则必须指定主密钥。你可以通过以下方式之一来指定主密钥。 -- [通过 KMS 指定主密钥](#通过-KMS-指定主密钥) +- [通过 KMS 指定主密钥](#通过-kms-指定主密钥) - [通过文件指定主密钥](#通过文件指定主密钥) #### 通过 KMS 指定主密钥 From d8c7347dbda3131b402a125f7ebf8f4c29fe8732 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 7 Mar 2024 14:29:35 +0800 Subject: [PATCH 07/14] minor wording updates --- encryption-at-rest.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index cd5f93afd3c6..f51535abefe5 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -110,7 +110,7 @@ aws --region us-west-2 kms create-alias --alias-name "alias/tidb-tde" --target-k **第 2 步：配置主密钥** -使用 AWS KMS 方式指定主密钥，请在 TiKV 的配置文件中 `[security.encryption]` 部分之后添加 `[security.encryption.master-key]` 配置： +要使用 AWS KMS 方式指定主密钥，请在 TiKV 的配置文件中 `[security.encryption]` 部分之后添加 `[security.encryption.master-key]` 配置： ``` [security.encryption.master-key] @@ -129,7 +129,7 @@ endpoint = "https://kms.us-west-2.amazonaws.com" **第 1 步：创建主密钥** -要在 Google Cloud 平台上创建一个密钥，请执行以下步骤： +要在 Google Cloud 平台上创建一个密钥，请进行以下操作： 1. 进入 Google Cloud 控制台的 [密钥管理](https://console.cloud.google.com/security/kms/keyrings)。 2. 点击**创建密钥环**。输入密钥环的名称，选择密钥环的位置，然后点击**创建**。注意密钥环的位置需要覆盖 TiDB 集群部署的区域。 @@ -147,7 +147,7 @@ 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" ``` -请将上述命令中的 "key-ring-name"、"key-name"、"global"、"30d" 等字段的值替换为实际密钥对应的名称和配置。 +请将上述命令中的 `"key-ring-name"`、`"key-name"`、`"global"`、`"30d"` 等字段的值替换为实际密钥对应的名称和配置。 **第 2 步：配置主密钥** @@ -163,14 +163,14 @@ vendor = "gcp" credential-file-path = "/path/to/credential.json" ``` -`key-id` 指定 KMS CMK 的密钥 ID, `credential-file-path` 指向验证凭据配置文件的路径，目前支持 Service Account 和 Authentication User 两种凭据。如果 TiKV 的运行环境已配置 [应用默认凭据](https://cloud.google.com/docs/authentication/application-default-credentials?hl=zh-cn)，则无须此配置项。 +`key-id` 指定 KMS CMK 的密钥 ID。`credential-file-path` 指向验证凭据配置文件的路径，目前支持 Service Account 和 Authentication User 这两种凭据。如果 TiKV 的运行环境已配置[应用默认凭据](https://cloud.google.com/docs/authentication/application-default-credentials?hl=zh-cn)，则无须此配置 `credential-file-path`。
**第 1 步：创建主密钥** -在 Azure 平台创建密钥，请参考文档 [使用 Azure 门户在 Azure Key Vault 中设置和检索密钥](https://learn.microsoft.com/zh-cn/azure/key-vault/keys/quick-create-portal)。 +在 Azure 平台创建密钥，请参考文档[使用 Azure 门户在 Azure Key Vault 中设置和检索密钥](https://learn.microsoft.com/zh-cn/azure/key-vault/keys/quick-create-portal)。 **第 2 步：配置主密钥** From d450e5423dc30d5cf6d13d0b22fcfba031c1b91a Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 7 Mar 2024 15:05:23 +0800 Subject: [PATCH 08/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 f51535abefe5..2eb06f1616b4 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -163,7 +163,7 @@ vendor = "gcp" credential-file-path = "/path/to/credential.json" ``` -`key-id` 指定 KMS CMK 的密钥 ID。`credential-file-path` 指向验证凭据配置文件的路径，目前支持 Service Account 和 Authentication User 这两种凭据。如果 TiKV 的运行环境已配置[应用默认凭据](https://cloud.google.com/docs/authentication/application-default-credentials?hl=zh-cn)，则无须此配置 `credential-file-path`。 +`key-id` 指定 KMS CMK 的密钥 ID。`credential-file-path` 指向验证凭据配置文件的路径，目前支持 Service Account 和 Authentication User 这两种凭据。如果 TiKV 的运行环境已配置[应用默认凭据](https://cloud.google.com/docs/authentication/application-default-credentials?hl=zh-cn)，则无需配置 `credential-file-path`。
From 59371790f3f582a8e3e86132e463a7d5678418f1 Mon Sep 17 00:00:00 2001 From: glorv Date: Fri, 8 Mar 2024 13:02:31 +0800 Subject: [PATCH 09/14] Apply suggestions from code review Co-authored-by: Grace Cai --- encryption-at-rest.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index 2eb06f1616b4..b10b78318481 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -57,7 +57,7 @@ TiKV 当前支持的加密算法包括 AES128-CTR、AES192-CTR、AES256-CTR 和 * 主密钥 (master key)：主密钥由用户提供，用于加密 TiKV 生成的数据密钥。用户在 TiKV 外部进行主密钥的管理。 * 数据密钥 (data key)：数据密钥由 TiKV 生成，是实际用于加密的密钥。 -多个 TiKV 实例可共用一个主密钥。在生产环境中，推荐通过 KMS 提供主密钥。目前 TiKV 支持 [AWS](https://docs.aws.amazon.com/zh_cn/kms/index.html)、[Google Cloud](https://cloud.google.com/security/products/security-key-management?hl=zh-CN) 和 [Azure](https://learn.microsoft.com/en-us/azure/key-vault/) 等平台的 KMS 加密。要开启 KMS 加密，首先通过 KMS 创建用户主密钥 (CMK)，然后在配置文件中将 CMK 密钥的 ID 提供给 TiKV。如果 TiKV 无法访问 KMS CMK，TiKV 就无法启动或重新启动。 +多个 TiKV 实例可共用一个主密钥。在生产环境中，推荐通过 KMS 提供主密钥。目前 TiKV 支持 [AWS](https://docs.aws.amazon.com/zh_cn/kms/index.html)、[Google Cloud](https://cloud.google.com/security/products/security-key-management?hl=zh-CN) 和 [Azure](https://learn.microsoft.com/en-us/azure/key-vault/) 平台的 KMS 加密。要开启 KMS 加密，首先通过 KMS 创建用户主密钥 (CMK)，然后在配置文件中将 CMK 密钥的 ID 提供给 TiKV。如果 TiKV 无法访问 KMS CMK，TiKV 就无法启动或重新启动。 用户也可以通过文件形式提供主密钥。该文件须包含一个用十六进制字符串编码的 256 位（32 字节）密钥，并以换行符结尾（即 `\n`），且不包含其他任何内容。将密钥存储在磁盘上会泄漏密钥，因此密钥文件仅适合存储在 RAM 内存的 `tempfs` 中。 @@ -75,7 +75,13 @@ data-encryption-method = "aes128-ctr" data-key-rotation-period = "168h" # 7 days ``` -`data-encryption-method` 的可选值为 `"aes128-ctr"`、`"aes192-ctr"`、`"aes256-ctr"`、`"sm4-ctr"` (仅 v6.3.0 及之后版本) 和 `"plaintext"`。默认值为 `"plaintext"`，即默认不开启加密功能。`data-key-rotation-period` 指定 TiKV 轮换密钥的频率。可以为新 TiKV 集群或现有 TiKV 集群开启加密，但只有启用后写入的数据才保证被加密。要禁用加密，请在配置文件中删除 `data-encryption-method`，或将该参数值为 `"plaintext"`，然后重启 TiKV。若要替换加密算法，则将 `data-encryption-method` 替换成已支持的加密算法，然后重启 TiKV。替换加密算法后，旧加密算法生成的加密文件会随着新数据的写入逐渐被重写成新加密算法所生成的加密文件。 +- `data-encryption-method` 用于指定加密算法，可选值为 `"aes128-ctr"`、`"aes192-ctr"`、`"aes256-ctr"`、`"sm4-ctr"` (仅 v6.3.0 及之后版本)、`"plaintext"`。默认值为 `"plaintext"`，即默认不开启加密功能。 + + - 对于新 TiKV 集群或现有 TiKV 集群，只有启用加密功能后写入的数据才保证被加密。 + - 开启加密功能后，如需禁用加密，请在配置文件中删除 `data-encryption-method`，或将该参数值设置为 `"plaintext"`，然后重启 TiKV。 + - 若要替换加密算法，请将 `data-encryption-method` 替换成已支持的加密算法，然后重启 TiKV。替换加密算法后，旧加密算法生成的加密文件会随着新数据的写入逐渐被重写成新加密算法所生成的加密文件。 + +- `data-key-rotation-period` 用于指定 TiKV 轮换密钥的频率。 如果启用了加密（即 `data-encryption-method` 的值不是 `"plaintext"`），则必须指定主密钥。你可以通过以下方式之一来指定主密钥。 From cb9a3b62dda7b961680aa2422952dfe339cb35d1 Mon Sep 17 00:00:00 2001 From: glorv Date: Mon, 11 Mar 2024 10:36:10 +0800 Subject: [PATCH 10/14] fix --- 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 b10b78318481..ab74faeacc15 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -22,7 +22,7 @@ aliases: ['/docs-cn/dev/encryption-at-rest/'] TiKV 支持静态加密，即在 [CTR](https://zh.wikipedia.org/wiki/分组密码工作模式) 模式下使用 [AES](https://zh.wikipedia.org/wiki/高级加密标准) 或 [SM4](https://zh.wikipedia.org/wiki/SM4) 对数据文件进行透明加密。要启用静态加密，用户需提供一个加密密钥，即主密钥。TiKV 自动轮换 (rotate) 用于加密实际数据文件的密钥，主密钥则可以由用户手动轮换。请注意，静态加密仅加密静态数据（即磁盘上的数据），而不加密网络传输中的数据。建议 TLS 与静态加密一起使用。 -可以选择将 AWS KMS (Key Management Service) 用于云上部署或本地部署，也可以指定将密钥以明文形式存储在文件中。 +可以选择将 KMS (Key Management Service) 用于云上部署或本地部署，也可以指定将密钥以明文形式存储在文件中。 TiKV 当前不从核心转储 (core dumps) 中排除加密密钥和用户数据。建议在使用静态加密时禁用 TiKV 进程的核心转储，该功能目前无法由 TiKV 独立处理。 From 5af119ab9102883b1d26ce08855305f6061aa1cb Mon Sep 17 00:00:00 2001 From: glorv Date: Tue, 12 Mar 2024 10:53:22 +0800 Subject: [PATCH 11/14] Update encryption-at-rest.md Co-authored-by: lucasliang --- 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 ab74faeacc15..f0dda20d2987 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -57,7 +57,7 @@ TiKV 当前支持的加密算法包括 AES128-CTR、AES192-CTR、AES256-CTR 和 * 主密钥 (master key)：主密钥由用户提供，用于加密 TiKV 生成的数据密钥。用户在 TiKV 外部进行主密钥的管理。 * 数据密钥 (data key)：数据密钥由 TiKV 生成，是实际用于加密的密钥。 -多个 TiKV 实例可共用一个主密钥。在生产环境中，推荐通过 KMS 提供主密钥。目前 TiKV 支持 [AWS](https://docs.aws.amazon.com/zh_cn/kms/index.html)、[Google Cloud](https://cloud.google.com/security/products/security-key-management?hl=zh-CN) 和 [Azure](https://learn.microsoft.com/en-us/azure/key-vault/) 平台的 KMS 加密。要开启 KMS 加密，首先通过 KMS 创建用户主密钥 (CMK)，然后在配置文件中将 CMK 密钥的 ID 提供给 TiKV。如果 TiKV 无法访问 KMS CMK，TiKV 就无法启动或重新启动。 +多个 TiKV 实例可共用一个主密钥。在生产环境中，推荐通过 KMS 提供主密钥。目前 TiKV 支持 [AWS](https://docs.aws.amazon.com/zh_cn/kms/index.html)、[Google Cloud](https://cloud.google.com/security/products/security-key-management?hl=zh-CN) 和 [Azure](https://learn.microsoft.com/zh-cn/azure/key-vault/) 平台的 KMS 加密。要开启 KMS 加密，首先通过 KMS 创建用户主密钥 (CMK)，然后在配置文件中将 CMK 密钥的 ID 提供给 TiKV。如果 TiKV 无法访问 KMS CMK，TiKV 就无法启动或重新启动。 用户也可以通过文件形式提供主密钥。该文件须包含一个用十六进制字符串编码的 256 位（32 字节）密钥，并以换行符结尾（即 `\n`），且不包含其他任何内容。将密钥存储在磁盘上会泄漏密钥，因此密钥文件仅适合存储在 RAM 内存的 `tempfs` 中。 From 872b7ebe00da8089c3c88e1cdc05321eb3e12703 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 14 Mar 2024 16:40:04 +0800 Subject: [PATCH 12/14] Apply suggestions from code review Co-authored-by: Lilian Lee --- encryption-at-rest.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index f0dda20d2987..349c64303cdd 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -75,7 +75,7 @@ data-encryption-method = "aes128-ctr" data-key-rotation-period = "168h" # 7 days ``` -- `data-encryption-method` 用于指定加密算法，可选值为 `"aes128-ctr"`、`"aes192-ctr"`、`"aes256-ctr"`、`"sm4-ctr"` (仅 v6.3.0 及之后版本)、`"plaintext"`。默认值为 `"plaintext"`，即默认不开启加密功能。 +- `data-encryption-method` 用于指定加密算法，可选值为 `"aes128-ctr"`、`"aes192-ctr"`、`"aes256-ctr"`、`"sm4-ctr"`（仅 v6.3.0 及之后版本）、`"plaintext"`。默认值为 `"plaintext"`，即默认不开启加密功能。 - 对于新 TiKV 集群或现有 TiKV 集群，只有启用加密功能后写入的数据才保证被加密。 - 开启加密功能后，如需禁用加密，请在配置文件中删除 `data-encryption-method`，或将该参数值设置为 `"plaintext"`，然后重启 TiKV。 @@ -83,14 +83,14 @@ data-key-rotation-period = "168h" # 7 days - `data-key-rotation-period` 用于指定 TiKV 轮换密钥的频率。 -如果启用了加密（即 `data-encryption-method` 的值不是 `"plaintext"`），则必须指定主密钥。你可以通过以下方式之一来指定主密钥。 +如果启用了加密（即 `data-encryption-method` 的值不是 `"plaintext"`），则必须指定主密钥。你可以通过以下方式之一来指定主密钥： - [通过 KMS 指定主密钥](#通过-kms-指定主密钥) - [通过文件指定主密钥](#通过文件指定主密钥) #### 通过 KMS 指定主密钥 -TiKV 支持 AWS、Google Cloud 和 Azure 这三个平台的 KMS 加密。你可以根据服务部署的平台，你可以选择其中之一配置 KMS 加密。 +TiKV 支持 AWS、Google Cloud 和 Azure 这三个平台的 KMS 加密。你可以根据服务部署的平台，选择其中之一配置 KMS 加密。 @@ -137,7 +137,7 @@ endpoint = "https://kms.us-west-2.amazonaws.com" 要在 Google Cloud 平台上创建一个密钥，请进行以下操作： -1. 进入 Google Cloud 控制台的 [密钥管理](https://console.cloud.google.com/security/kms/keyrings)。 +1. 进入 Google Cloud 控制台的[密钥管理](https://console.cloud.google.com/security/kms/keyrings)。 2. 点击**创建密钥环**。输入密钥环的名称，选择密钥环的位置，然后点击**创建**。注意密钥环的位置需要覆盖 TiDB 集群部署的区域。 3. 选择上一步创建的密钥环，在密钥环详情页面点击**创建密钥**。 4. 输入密钥的名称，设置密钥的信息如下，然后点击**创建**。 @@ -153,7 +153,7 @@ 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" ``` -请将上述命令中的 `"key-ring-name"`、`"key-name"`、`"global"`、`"30d"` 等字段的值替换为实际密钥对应的名称和配置。 +请将上述命令中的 `"key-ring-name"`、`"key-name"`、`"global"`、`"30d"` 字段的值替换为实际密钥对应的名称和配置。 **第 2 步：配置主密钥** @@ -169,7 +169,8 @@ vendor = "gcp" credential-file-path = "/path/to/credential.json" ``` -`key-id` 指定 KMS CMK 的密钥 ID。`credential-file-path` 指向验证凭据配置文件的路径，目前支持 Service Account 和 Authentication User 这两种凭据。如果 TiKV 的运行环境已配置[应用默认凭据](https://cloud.google.com/docs/authentication/application-default-credentials?hl=zh-cn)，则无需配置 `credential-file-path`。 +- `key-id` 指定 KMS CMK 的密钥 ID。 +- `credential-file-path` 指向验证凭据配置文件的路径，目前支持 Service Account 和 Authentication User 这两种凭据。如果 TiKV 的运行环境已配置[应用默认凭据](https://cloud.google.com/docs/authentication/application-default-credentials?hl=zh-cn)，则无需配置 `credential-file-path`。
From 532b625fbd587645caa07c5e7340044a0422b74d Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 18 Mar 2024 15:31:23 +0800 Subject: [PATCH 13/14] fix building errors --- encryption-at-rest.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/encryption-at-rest.md b/encryption-at-rest.md index 349c64303cdd..5babf3508b63 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -129,8 +129,8 @@ endpoint = "https://kms.us-west-2.amazonaws.com" `key-id` 指定 KMS CMK 的密钥 ID。`region` 为 KMS CMK 的 AWS 区域名。`endpoint` 通常无需指定，除非你在使用非 AWS 提供的 AWS KMS 兼容服务或需要使用 [KMS VPC endpoint](https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html)。 你也可以使用 AWS [多区域键](https://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/multi-region-keys-overview.html)。为此，你需要在一个特定的区域设置一个主键，并在需要的区域中添加副本密钥。 -
+
**第 1 步：创建主密钥** @@ -171,8 +171,8 @@ credential-file-path = "/path/to/credential.json" - `key-id` 指定 KMS CMK 的密钥 ID。 - `credential-file-path` 指向验证凭据配置文件的路径，目前支持 Service Account 和 Authentication User 这两种凭据。如果 TiKV 的运行环境已配置[应用默认凭据](https://cloud.google.com/docs/authentication/application-default-credentials?hl=zh-cn)，则无需配置 `credential-file-path`。 -
+
**第 1 步：创建主密钥** @@ -205,8 +205,8 @@ client_secret = "" ``` 请将上述配置中除 `vendor` 之外的其他字段值修改为密钥实际的对应配置。 -
+ #### 通过文件指定主密钥 From 3330c959f33a458bc62aad4d803f817bf9cdd39e Mon Sep 17 00:00:00 2001 From: Lilian Lee Date: Tue, 19 Mar 2024 15:11:45 +0800 Subject: [PATCH 14/14] Update format --- 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 5babf3508b63..576c13e3a0cf 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -52,7 +52,7 @@ TiKV，TiDB 和 PD 信息日志中可能包含用于调试的用户数据。信 ## TiKV 静态加密 -TiKV 当前支持的加密算法包括 AES128-CTR、AES192-CTR、AES256-CTR 和 SM4-CTR (仅 v6.3.0 及之后版本)。TiKV 使用信封加密 (envelop encryption)，所以启用加密后，TiKV 使用以下两种类型的密钥： +TiKV 当前支持的加密算法包括 AES128-CTR、AES192-CTR、AES256-CTR 和 SM4-CTR（仅 v6.3.0 及之后版本）。TiKV 使用信封加密 (envelop encryption)，所以启用加密后，TiKV 使用以下两种类型的密钥： * 主密钥 (master key)：主密钥由用户提供，用于加密 TiKV 生成的数据密钥。用户在 TiKV 外部进行主密钥的管理。 * 数据密钥 (data key)：数据密钥由 TiKV 生成，是实际用于加密的密钥。 @@ -150,7 +150,7 @@ endpoint = "https://kms.us-west-2.amazonaws.com" ```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" ``` 请将上述命令中的 `"key-ring-name"`、`"key-name"`、`"global"`、`"30d"` 字段的值替换为实际密钥对应的名称和配置。