管理加密密钥

为 CMEK 配置 Google Cloud KMS

使用 Google Cloud KMS 为您的组织提供加密密钥。

Configure with the /claude-api skill in Claude Code

claude "/claude-api help me configure a customer-managed encryption key with Google Cloud KMS"

本指南将引导您配置 Google Cloud KMS 密钥，作为您的 Anthropic 组织的"customer-managed encryption key"（客户管理的加密密钥），即 CMEK。

启用 CMEK 是永久性的。如果您的 KMS 密钥被删除或禁用，Anthropic 将无法恢复使用该密钥加密的数据。在开始之前，请查看警告和限制。

前提条件

一个已启用结算功能的 Google Cloud 项目。
已启用 Cloud KMS API（cloudkms.googleapis.com）。
拥有创建 KMS 密钥环和密钥以及在其上设置 IAM 策略的权限（roles/cloudkms.admin 或同等权限）。
您组织的 Anthropic Admin API 密钥。
已安装并完成身份验证的 gcloud CLI。
已为该项目启用 Cloud KMS 数据访问审计日志（IAM 和管理 > 审计日志 > Cloud Key Management Service，包含 DATA_READ 和 DATA_WRITE）。这些默认是关闭的；如果不启用，Anthropic 的加密和解密操作不会在 Cloud Logging 中产生任何条目。

Anthropic 服务账号电子邮件

要让 Anthropic 使用您的加密密钥，您必须向 Anthropic 的服务账号提供一个可用于加密数据的密钥。Anthropic CMEK 的服务账号电子邮件为：

anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com

仅使用此处公布的服务账号电子邮件。切勿信任通过电子邮件、聊天或任何入驻渠道提供的标识符。

域限制共享： 如果您的项目隶属于强制执行 constraints/iam.allowedPolicyMemberDomains 的 Google Cloud 组织，则以下 IAM 绑定会被拒绝，因为 Anthropic 服务账号位于您的组织之外。您需要对该约束进行项目级别的豁免，或者将 Anthropic 的 Cloud Identity 客户 ID（格式为 C0xxxxxxxx）添加到允许列表中。如有需要，请联系 Anthropic 获取客户 ID。

加密密钥设置

创建或选择密钥环
如果您已有可复用的密钥环，请跳过此步骤。密钥环是区域性的。请选择与您正在配置的 Anthropic 地理区域相匹配的美国单区域位置，例如 us-east5。不支持 us 和 global 等多区域位置。
gcloud kms keyrings create <your-keyring-name> \ --project=<your-project-id> \ --location=<region>
创建加密密钥
创建一个用途为 ENCRYPT_DECRYPT 的对称密钥。Anthropic 强烈建议使用 HSM 保护：Cloud KMS HSM 密钥已通过 FIPS 140-2 Level 3 验证，且相对于软件密钥的成本差异很小。
gcloud kms keys create <your-key-name> \ --project=<your-project-id> \ --location=<region> \ --keyring=<your-keyring-name> \ --purpose=encryption \ --protection-level=hsm
如需改用软件保护，请省略 --protection-level=hsm。本指南中的其他内容均无需更改。
您也可以从 Google Cloud Console 创建密钥。打开密钥环，点击创建密钥，选择生成的密钥，将用途和算法设置为对称加密和解密，并在保护级别下选择 HSM。
创建受 HSM 保护的对称加密/解密密钥。
授予 Anthropic 的服务账号对密钥的访问权限
需要两个密钥级别的 IAM 绑定。两者的作用域都限定在单个加密密钥上，而不是整个项目或整个密钥环。
加密和解密，Anthropic 使用它来加密和解密保护您工作区数据的数据密钥（信封加密）：
gcloud kms keys add-iam-policy-binding <your-key-name> \ --project=<your-project-id> \ --location=<region> \ --keyring=<your-keyring-name> \ --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \ --role=roles/cloudkms.cryptoKeyEncrypterDecrypter
Viewer，用于 Anthropic 在启动时执行的元数据读取（cryptoKeys.get），以验证密钥的用途和算法：
gcloud kms keys add-iam-policy-binding <your-key-name> \ --project=<your-project-id> \ --location=<region> \ --keyring=<your-keyring-name> \ --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \ --role=roles/cloudkms.viewer
在 Console 中，选择该密钥，打开权限面板，点击授予访问权限，并为服务账号添加 Cloud KMS CryptoKey Encrypter/Decrypter 和 Cloud KMS Viewer 两个角色。请确保您位于该密钥的权限页面，而不是密钥环或项目的权限页面，以便授权的作用域仅限于此密钥。
授予 Anthropic 服务账号这两个角色，作用域限定在该密钥上。

记录完整的密钥资源名称

在注册密钥时，您需要将其传递给 Anthropic。格式为：

projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>

使用以下命令获取：

gcloud kms keys describe <your-key-name> \
  --project=<your-project-id> \
  --location=<region> \
  --keyring=<your-keyring-name> \
  --format="value(name)"

在 Console 中，打开密钥的详情页面并点击复制资源名称。

Google Cloud key ring details with the Copy resource name action highlighted in the key's actions menu. — 从操作菜单中复制密钥的完整资源名称。

向 Anthropic 注册密钥

注册密钥的方式取决于您使用的产品。

向 Anthropic 注册密钥

通过 Admin API 创建外部密钥配置，使用"加密密钥设置"下"记录完整的密钥资源名称"步骤中获取的资源名称。

curl -sS https://api.anthropic.com/v1/organizations/external_keys \
  -H "x-api-key: <anthropic-admin-api-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "display_name": "<friendly-name>",
    "geo": "us",
    "provider_config": {
      "type": "gcp",
      "key_name": "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"
    }
  }'

响应中包含外部密钥 ID：

{
  "type": "external_key",
  "id": "ekey_<id>",
  "display_name": "<friendly-name>"
}

验证密钥
针对您的密钥触发一次加密和解密往返测试。
curl -sS -X POST https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate \ -H "x-api-key: <anthropic-admin-api-key>" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{}'
成功的响应如下所示：
{ "type": "external_key_validation", "status": "success", "error": null }
如果验证失败，常见原因包括：
- VPC Service Controls： 如果服务边界保护了您项目中的 Cloud KMS，请将 Anthropic 添加到该边界的访问级别中（或将密钥所在的项目排除在外），以便 Anthropic 能够访问该密钥。
- 域限制共享： constraints/iam.allowedPolicyMemberDomains 组织策略可能会移除 Anthropic 服务账号绑定（参见前面的说明）。使用 gcloud kms keys get-iam-policy <your-key-name> --project=<your-project-id> --location=<region> --keyring=<your-keyring-name> 确认绑定是否存在。
- 密钥版本已禁用或已销毁： 确认密钥的主版本已启用，且未被禁用、未计划销毁或未被销毁。

将密钥附加到工作区

curl -sS -X POST https://api.anthropic.com/v1/organizations/workspaces/<workspace-id> \
  -H "x-api-key: <anthropic-admin-api-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "external_key_id": "ekey_<id>"
  }'

Terraform

对于基础设施即代码（infrastructure-as-code）部署，相同的步骤对应于 google 提供程序中的 google_kms_key_ring、google_kms_crypto_key 和 google_kms_crypto_key_iam_member 资源。

Was this page helpful?

前提条件

一个已启用结算功能的 Google Cloud 项目。

已启用 Cloud KMS API（cloudkms.googleapis.com）。

拥有创建 KMS 密钥环和密钥以及在其上设置 IAM 策略的权限（roles/cloudkms.admin 或同等权限）。

您组织的 Anthropic Admin API 密钥。

已安装并完成身份验证的 gcloud CLI。

已为该项目启用 Cloud KMS 数据访问审计日志（IAM 和管理 > 审计日志 > Cloud Key Management Service，包含 DATA_READ 和 DATA_WRITE）。这些默认是关闭的；如果不启用，Anthropic 的加密和解密操作不会在 Cloud Logging 中产生任何条目。

Anthropic 服务账号电子邮件

要让 Anthropic 使用您的加密密钥，您必须向 Anthropic 的服务账号提供一个可用于加密数据的密钥。Anthropic CMEK 的服务账号电子邮件为：

anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com

仅使用此处公布的服务账号电子邮件。切勿信任通过电子邮件、聊天或任何入驻渠道提供的标识符。

加密密钥设置

创建或选择密钥环
如果您已有可复用的密钥环，请跳过此步骤。密钥环是区域性的。请选择与您正在配置的 Anthropic 地理区域相匹配的美国单区域位置，例如 us-east5。不支持 us 和 global 等多区域位置。
gcloud kms keyrings create <your-keyring-name> \ --project=<your-project-id> \ --location=<region>
创建加密密钥
创建一个用途为 ENCRYPT_DECRYPT 的对称密钥。Anthropic 强烈建议使用 HSM 保护：Cloud KMS HSM 密钥已通过 FIPS 140-2 Level 3 验证，且相对于软件密钥的成本差异很小。
gcloud kms keys create <your-key-name> \ --project=<your-project-id> \ --location=<region> \ --keyring=<your-keyring-name> \ --purpose=encryption \ --protection-level=hsm
如需改用软件保护，请省略 --protection-level=hsm。本指南中的其他内容均无需更改。
您也可以从 Google Cloud Console 创建密钥。打开密钥环，点击创建密钥，选择生成的密钥，将用途和算法设置为对称加密和解密，并在保护级别下选择 HSM。
创建受 HSM 保护的对称加密/解密密钥。
授予 Anthropic 的服务账号对密钥的访问权限
需要两个密钥级别的 IAM 绑定。两者的作用域都限定在单个加密密钥上，而不是整个项目或整个密钥环。
加密和解密，Anthropic 使用它来加密和解密保护您工作区数据的数据密钥（信封加密）：
gcloud kms keys add-iam-policy-binding <your-key-name> \ --project=<your-project-id> \ --location=<region> \ --keyring=<your-keyring-name> \ --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \ --role=roles/cloudkms.cryptoKeyEncrypterDecrypter
Viewer，用于 Anthropic 在启动时执行的元数据读取（cryptoKeys.get），以验证密钥的用途和算法：
gcloud kms keys add-iam-policy-binding <your-key-name> \ --project=<your-project-id> \ --location=<region> \ --keyring=<your-keyring-name> \ --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \ --role=roles/cloudkms.viewer
在 Console 中，选择该密钥，打开权限面板，点击授予访问权限，并为服务账号添加 Cloud KMS CryptoKey Encrypter/Decrypter 和 Cloud KMS Viewer 两个角色。请确保您位于该密钥的权限页面，而不是密钥环或项目的权限页面，以便授权的作用域仅限于此密钥。
授予 Anthropic 服务账号这两个角色，作用域限定在该密钥上。

记录完整的密钥资源名称

在注册密钥时，您需要将其传递给 Anthropic。格式为：

projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>

使用以下命令获取：

gcloud kms keys describe <your-key-name> \
  --project=<your-project-id> \
  --location=<region> \
  --keyring=<your-keyring-name> \
  --format="value(name)"

在 Console 中，打开密钥的详情页面并点击复制资源名称。

向 Anthropic 注册密钥

注册密钥的方式取决于您使用的产品。

向 Anthropic 注册密钥

通过 Admin API 创建外部密钥配置，使用"加密密钥设置"下"记录完整的密钥资源名称"步骤中获取的资源名称。

curl -sS https://api.anthropic.com/v1/organizations/external_keys \
  -H "x-api-key: <anthropic-admin-api-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "display_name": "<friendly-name>",
    "geo": "us",
    "provider_config": {
      "type": "gcp",
      "key_name": "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"
    }
  }'

响应中包含外部密钥 ID：

{
  "type": "external_key",
  "id": "ekey_<id>",
  "display_name": "<friendly-name>"
}

验证密钥
针对您的密钥触发一次加密和解密往返测试。
curl -sS -X POST https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate \ -H "x-api-key: <anthropic-admin-api-key>" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{}'
成功的响应如下所示：
{ "type": "external_key_validation", "status": "success", "error": null }
如果验证失败，常见原因包括：
- VPC Service Controls： 如果服务边界保护了您项目中的 Cloud KMS，请将 Anthropic 添加到该边界的访问级别中（或将密钥所在的项目排除在外），以便 Anthropic 能够访问该密钥。
- 域限制共享： constraints/iam.allowedPolicyMemberDomains 组织策略可能会移除 Anthropic 服务账号绑定（参见前面的说明）。使用 gcloud kms keys get-iam-policy <your-key-name> --project=<your-project-id> --location=<region> --keyring=<your-keyring-name> 确认绑定是否存在。
- 密钥版本已禁用或已销毁： 确认密钥的主版本已启用，且未被禁用、未计划销毁或未被销毁。

将密钥附加到工作区

curl -sS -X POST https://api.anthropic.com/v1/organizations/workspaces/<workspace-id> \
  -H "x-api-key: <anthropic-admin-api-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "external_key_id": "ekey_<id>"
  }'

前提条件

Anthropic 服务账号电子邮件

加密密钥设置

向 Anthropic 注册密钥

Terraform

前提条件

Anthropic 服务账号电子邮件

加密密钥设置

向 Anthropic 注册密钥

Terraform

前提条件

Anthropic 服务账号电子邮件

加密密钥设置

向 Anthropic 注册密钥

Terraform

前提条件

Anthropic 服务账号电子邮件

加密密钥设置

向 Anthropic 注册密钥

Terraform