管理加密密钥

为 CMEK 配置 AWS KMS

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

Configure with the /claude-api skill in Claude Code

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

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

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

前提条件

一个具有创建 KMS 密钥和设置密钥策略权限（kms:CreateKey 和 kms:PutKeyPolicy）的 AWS 账户。
您组织的 Anthropic Admin API 密钥。
已安装并完成身份验证的 AWS CLI。

Anthropic 的 Amazon 资源名称（ARN）

为了让 Anthropic 使用您的加密密钥，您必须为 Anthropic 的 IAM 角色提供一个可用于加密数据的 KMS 密钥。Anthropic CMEK 的 ARN 为：

arn:aws:iam::915198916910:role/anthropic-cmek-client-us

请仅使用此已发布的 ARN。切勿信任通过电子邮件、聊天或任何入门引导渠道提供的标识符。

加密密钥设置

使用跨账户密钥策略创建 KMS 密钥
密钥策略授予 Anthropic 的 IAM 角色跨账户访问权限。需要三个语句：
1. **账户根管理员：**标准的 KMS 模式。您的账户保留完全的管理控制权。
2. Anthropic 加密和解密：kms:Encrypt 和 kms:Decrypt 操作，Anthropic 使用这些操作来加密和解密保护您工作区数据的数据密钥（信封加密）。
3. **Anthropic 描述：**Anthropic 在启动时执行的元数据读取。此权限单独授予，因为 DescribeKey 没有 EncryptionContext 参数，因此对此操作应用 EncryptionContext 条件将始终导致拒绝。
export YOUR_ACCOUNT=$(aws sts get-caller-identity --query Account --output text) aws kms create-key \ --region <region> \ --description "Anthropic CMEK" \ --key-usage ENCRYPT_DECRYPT \ --policy "{ \"Version\": \"2012-10-17\", \"Statement\": [ { \"Sid\": \"AccountRootAdmin\", \"Effect\": \"Allow\", \"Principal\": {\"AWS\": \"arn:aws:iam::${YOUR_ACCOUNT}:root\"}, \"Action\": \"kms:*\", \"Resource\": \"*\" }, { \"Sid\": \"AllowAnthropicCMEKCrypto\", \"Effect\": \"Allow\", \"Principal\": {\"AWS\": \"arn:aws:iam::915198916910:role/anthropic-cmek-client-us\"}, \"Action\": [\"kms:Encrypt\", \"kms:Decrypt\"], \"Resource\": \"*\", \"Condition\": { \"StringEquals\": { \"kms:EncryptionContext:anthropic:compartment_uuid\": \"<compartment-uuid>\" } } }, { \"Sid\": \"AllowAnthropicCMEKDescribe\", \"Effect\": \"Allow\", \"Principal\": {\"AWS\": \"arn:aws:iam::915198916910:role/anthropic-cmek-client-us\"}, \"Action\": \"kms:DescribeKey\", \"Resource\": \"*\" } ] }"
从输出中获取 KeyMetadata.Arn。您在下一步注册密钥时需要用到它。
EncryptionContext 条件是推荐的，但并非必需。Anthropic 始终会在加密上下文中包含您工作区的隔离区 ID（compartment ID），因此无论如何，密文都会以加密方式绑定到该隔离区。添加此条件可在 IAM 层提供纵深防御。如果您希望在开始时不使用该条件，可从 AllowAnthropicCMEKCrypto 语句中省略 Condition 块，稍后再通过 kms:PutKeyPolicy 添加。
**查找您的隔离区 ID：**每个工作区都有一个隔离区 ID，用于限定其 CMEK 数据的范围。您可以在 Claude Console 的 Workspace > Security > Encryption keys（工作区 > 安全 > 加密密钥）下找到它（Compartment ID 字段），或读取 Get Workspace 端点返回的 compartment_id 字段。将该值替换到上述密钥策略中的 <compartment-uuid> 处。Anthropic 在验证密钥时也会将其作为加密上下文发送，因此条件值必须匹配才能验证成功。
您也可以从 AWS 控制台创建密钥。选择对称密钥、加密和解密密钥用途、单区域密钥以及 KMS 密钥材料来源。创建密钥向导会在其 Review（审核）步骤提交密钥策略：如果您在该步骤的密钥使用权限下添加 Anthropic 的账户 ID 915198916910，生成的策略会向整个 Anthropic 账户授予更广泛的操作权限（例如 kms:ReEncrypt* 和 kms:GenerateDataKey*），且不带 EncryptionContext 条件，而验证仍然会通过。为避免留下权限过宽的密钥，请仅使用管理权限完成向导，然后打开密钥的 Key policy（密钥策略）选项卡，将 JSON 替换为上面所示的限定角色范围的策略（即限定到 anthropic-cmek-client-us 角色的三个语句，并带有 EncryptionContext 条件）。
Configure key（配置密钥）：对称、加密和解密、单区域密钥。
Add labels（添加标签）：为密钥添加别名和描述。
Define key administrative permissions（定义密钥管理权限，可选）。您的账户保留完全的管理控制权。
请勿在此处添加 Anthropic 的账户 ID。此向导步骤会生成权限过宽的策略。请将使用权限留空，并在创建后编辑 Key policy JSON（参见上文）。

向 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": "aws",
      "kms_arn": "<key-arn-from-step-1>",
      "role_arn": "arn:aws:iam::915198916910:role/anthropic-cmek-client-us"
    }
  }'

响应中包含外部密钥 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 }
如果验证失败，常见原因包括：
- **加密上下文不匹配：**如果您在密钥策略中保留了 EncryptionContext 条件，请确认您已将 <compartment-uuid> 替换为您工作区的实际隔离区 ID（参见步骤 1）。错误或未替换的值会导致 KMS 返回不透明的 AccessDeniedException。要排除此原因，可暂时从 AllowAnthropicCMEKCrypto 语句中移除 Condition 块并重新验证。
- **资源控制策略（RCP）：**如果您的 AWS 组织有一个 RCP，在 aws:PrincipalOrgID 与您的组织不匹配时拒绝 KMS 操作，它会阻止 Anthropic 的跨账户角色。该 RCP 需要为此密钥或 Anthropic 的角色 ARN 设置例外。服务控制策略（SCP）在此不适用，因为它们不会对通过基于资源的策略进行调用的外部主体进行评估。
- **通过 IAM 而非密钥策略授予访问权限：**跨账户 KMS 访问权限必须在密钥策略本身中授予，而不是通过您账户中的 IAM 策略。请使用 aws kms get-key-policy --key-id <id> --policy-name default 进行检查。
- **区域不匹配：**确认密钥所在的区域是 Anthropic 为您配置的地理层级所运营的区域之一。

将密钥附加到工作区

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）部署，上述相同步骤可映射到 aws 提供程序，使用 aws_kms_key 和 aws_kms_alias 资源。

Was this page helpful?

Anthropic 的 Amazon 资源名称（ARN）

为了让 Anthropic 使用您的加密密钥，您必须为 Anthropic 的 IAM 角色提供一个可用于加密数据的 KMS 密钥。Anthropic CMEK 的 ARN 为：

arn:aws:iam::915198916910:role/anthropic-cmek-client-us

请仅使用此已发布的 ARN。切勿信任通过电子邮件、聊天或任何入门引导渠道提供的标识符。

加密密钥设置

使用跨账户密钥策略创建 KMS 密钥
密钥策略授予 Anthropic 的 IAM 角色跨账户访问权限。需要三个语句：
1. **账户根管理员：**标准的 KMS 模式。您的账户保留完全的管理控制权。
2. Anthropic 加密和解密：kms:Encrypt 和 kms:Decrypt 操作，Anthropic 使用这些操作来加密和解密保护您工作区数据的数据密钥（信封加密）。
3. **Anthropic 描述：**Anthropic 在启动时执行的元数据读取。此权限单独授予，因为 DescribeKey 没有 EncryptionContext 参数，因此对此操作应用 EncryptionContext 条件将始终导致拒绝。
export YOUR_ACCOUNT=$(aws sts get-caller-identity --query Account --output text) aws kms create-key \ --region <region> \ --description "Anthropic CMEK" \ --key-usage ENCRYPT_DECRYPT \ --policy "{ \"Version\": \"2012-10-17\", \"Statement\": [ { \"Sid\": \"AccountRootAdmin\", \"Effect\": \"Allow\", \"Principal\": {\"AWS\": \"arn:aws:iam::${YOUR_ACCOUNT}:root\"}, \"Action\": \"kms:*\", \"Resource\": \"*\" }, { \"Sid\": \"AllowAnthropicCMEKCrypto\", \"Effect\": \"Allow\", \"Principal\": {\"AWS\": \"arn:aws:iam::915198916910:role/anthropic-cmek-client-us\"}, \"Action\": [\"kms:Encrypt\", \"kms:Decrypt\"], \"Resource\": \"*\", \"Condition\": { \"StringEquals\": { \"kms:EncryptionContext:anthropic:compartment_uuid\": \"<compartment-uuid>\" } } }, { \"Sid\": \"AllowAnthropicCMEKDescribe\", \"Effect\": \"Allow\", \"Principal\": {\"AWS\": \"arn:aws:iam::915198916910:role/anthropic-cmek-client-us\"}, \"Action\": \"kms:DescribeKey\", \"Resource\": \"*\" } ] }"
从输出中获取 KeyMetadata.Arn。您在下一步注册密钥时需要用到它。
EncryptionContext 条件是推荐的，但并非必需。Anthropic 始终会在加密上下文中包含您工作区的隔离区 ID（compartment ID），因此无论如何，密文都会以加密方式绑定到该隔离区。添加此条件可在 IAM 层提供纵深防御。如果您希望在开始时不使用该条件，可从 AllowAnthropicCMEKCrypto 语句中省略 Condition 块，稍后再通过 kms:PutKeyPolicy 添加。
**查找您的隔离区 ID：**每个工作区都有一个隔离区 ID，用于限定其 CMEK 数据的范围。您可以在 Claude Console 的 Workspace > Security > Encryption keys（工作区 > 安全 > 加密密钥）下找到它（Compartment ID 字段），或读取 Get Workspace 端点返回的 compartment_id 字段。将该值替换到上述密钥策略中的 <compartment-uuid> 处。Anthropic 在验证密钥时也会将其作为加密上下文发送，因此条件值必须匹配才能验证成功。
您也可以从 AWS 控制台创建密钥。选择对称密钥、加密和解密密钥用途、单区域密钥以及 KMS 密钥材料来源。创建密钥向导会在其 Review（审核）步骤提交密钥策略：如果您在该步骤的密钥使用权限下添加 Anthropic 的账户 ID 915198916910，生成的策略会向整个 Anthropic 账户授予更广泛的操作权限（例如 kms:ReEncrypt* 和 kms:GenerateDataKey*），且不带 EncryptionContext 条件，而验证仍然会通过。为避免留下权限过宽的密钥，请仅使用管理权限完成向导，然后打开密钥的 Key policy（密钥策略）选项卡，将 JSON 替换为上面所示的限定角色范围的策略（即限定到 anthropic-cmek-client-us 角色的三个语句，并带有 EncryptionContext 条件）。
Configure key（配置密钥）：对称、加密和解密、单区域密钥。
Add labels（添加标签）：为密钥添加别名和描述。
Define key administrative permissions（定义密钥管理权限，可选）。您的账户保留完全的管理控制权。
请勿在此处添加 Anthropic 的账户 ID。此向导步骤会生成权限过宽的策略。请将使用权限留空，并在创建后编辑 Key policy JSON（参见上文）。

向 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": "aws",
      "kms_arn": "<key-arn-from-step-1>",
      "role_arn": "arn:aws:iam::915198916910:role/anthropic-cmek-client-us"
    }
  }'

响应中包含外部密钥 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 }
如果验证失败，常见原因包括：
- **加密上下文不匹配：**如果您在密钥策略中保留了 EncryptionContext 条件，请确认您已将 <compartment-uuid> 替换为您工作区的实际隔离区 ID（参见步骤 1）。错误或未替换的值会导致 KMS 返回不透明的 AccessDeniedException。要排除此原因，可暂时从 AllowAnthropicCMEKCrypto 语句中移除 Condition 块并重新验证。
- **资源控制策略（RCP）：**如果您的 AWS 组织有一个 RCP，在 aws:PrincipalOrgID 与您的组织不匹配时拒绝 KMS 操作，它会阻止 Anthropic 的跨账户角色。该 RCP 需要为此密钥或 Anthropic 的角色 ARN 设置例外。服务控制策略（SCP）在此不适用，因为它们不会对通过基于资源的策略进行调用的外部主体进行评估。
- **通过 IAM 而非密钥策略授予访问权限：**跨账户 KMS 访问权限必须在密钥策略本身中授予，而不是通过您账户中的 IAM 策略。请使用 aws kms get-key-policy --key-id <id> --policy-name default 进行检查。
- **区域不匹配：**确认密钥所在的区域是 Anthropic 为您配置的地理层级所运营的区域之一。

将密钥附加到工作区

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