管理加密密钥

为 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

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

网域限定共享： 如果您的项目所属的 Google Cloud 组织强制执行 constraints/iam.allowedPolicyMemberDomains，则下方的 IAM 绑定将被拒绝，因为 Anthropic 服务账号不属于您的组织。您需要为该约束设置项目级例外，或将 Anthropic 的 Cloud Identity 客户 ID（格式为 C0xxxxxxxx）添加到允许列表中。如需获取客户 ID，请联系 Anthropic。

加密密钥设置

创建或选择密钥环
如果您已有可复用的密钥环，请跳过此步骤。密钥环是区域性的。请选择与您正在配置的 Anthropic 地理位置相匹配的美国单区域位置，例如 us-east5。不支持 us 和 global 等多区域位置。
gcloud kms keyrings create <your-keyring-name> \ --project=<your-project-id> \ --location=<region>
创建加密密钥
创建一个用途为 ENCRYPT_DECRYPT 的对称密钥。强烈建议使用 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 创建密钥。打开密钥环，点击 Create key（创建密钥），选择 Generated key（生成的密钥），将用途和算法设置为对称加密/解密，并在保护级别下选择 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
查看者权限，用于 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 中，打开密钥的详情页面，然后点击 Copy resource name（复制资源名称）。
从操作菜单中复制密钥的完整资源名称。

向 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 }

将密钥附加到工作区

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

对于基础设施即代码部署，上述步骤对应于 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 的对称密钥。强烈建议使用 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 创建密钥。打开密钥环，点击 Create key（创建密钥），选择 Generated key（生成的密钥），将用途和算法设置为对称加密/解密，并在保护级别下选择 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
查看者权限，用于 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 中，打开密钥的详情页面，然后点击 Copy resource name（复制资源名称）。
从操作菜单中复制密钥的完整资源名称。

向 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 }

将密钥附加到工作区

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>"
  }'