管理加密金鑰

為 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 Resource Name (ARN)

若要讓 Anthropic 使用您的加密金鑰，您必須提供一個 KMS 金鑰給 Anthropic 的 IAM 角色，以用於加密資料。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 一律會在加密上下文中包含您工作區的 compartment ID，因此無論如何，密文都會以密碼學方式繫結至該 compartment。新增此條件可在 IAM 層提供縱深防禦。若要在一開始不使用此條件，請從 AllowAnthropicCMEKCrypto 陳述式中省略 Condition 區塊，之後再使用 kms:PutKeyPolicy 新增。
尋找您的 compartment ID： 每個工作區都有一個 compartment ID，用於限定其 CMEK 資料的範圍。您可以在 Claude Console 的 Workspace > Security > Encryption keys（Compartment ID 欄位）中找到它，或讀取 Get Workspace 端點傳回的 compartment_id 欄位。將該值替換上方金鑰政策中的 <compartment-uuid>。Anthropic 在驗證金鑰時也會將其作為加密上下文傳送，因此條件值必須相符，驗證才能成功。
您也可以從 AWS Console 建立金鑰。選擇對稱金鑰、加密與解密的金鑰用途、單一區域金鑰，以及 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（定義金鑰管理權限，選用）。您的帳戶保留完整的管理控制權。
Define key usage permissions（定義金鑰使用權限）：請勿在此處新增 Anthropic 的帳戶 ID。此精靈步驟會產生權限過寬的政策。請將使用權限留空，並在建立後編輯 Key policy JSON（請參閱上文）。

向 Anthropic 註冊金鑰

註冊金鑰的方式取決於您使用的產品。

向 Anthropic 註冊金鑰

透過 Admin API 建立外部金鑰設定。

對於使用 Claude Platform on AWS 的組織，外部金鑰端點尚未提供。請改為在 Claude Console 中註冊、驗證及附加您的金鑰。

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-create-key-step>",
      "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> 替換為您工作區的實際 compartment ID（請參閱「加密金鑰設定」下的「建立 KMS 金鑰」步驟）。錯誤或未替換的值會使 KMS 傳回不透明的 AccessDeniedException。若要排除此原因，請暫時從 AllowAnthropicCMEKCrypto 陳述式中移除 Condition 區塊，然後重新驗證。
- 資源控制政策（RCP）： 如果您的 AWS 組織有一個 RCP，會在 aws:PrincipalOrgID 與您的組織不符時拒絕 KMS 操作，則會封鎖 Anthropic 的跨帳戶角色。該 RCP 需要針對此金鑰或 Anthropic 的角色 ARN 設定例外。服務控制政策在此不適用，因為它們不會針對透過資源型政策呼叫的外部主體進行評估。
- 透過 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 provider 的 aws_kms_key 和 aws_kms_alias 資源。

Was this page helpful?

Anthropic 的 Amazon Resource Name (ARN)

若要讓 Anthropic 使用您的加密金鑰，您必須提供一個 KMS 金鑰給 Anthropic 的 IAM 角色，以用於加密資料。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 一律會在加密上下文中包含您工作區的 compartment ID，因此無論如何，密文都會以密碼學方式繫結至該 compartment。新增此條件可在 IAM 層提供縱深防禦。若要在一開始不使用此條件，請從 AllowAnthropicCMEKCrypto 陳述式中省略 Condition 區塊，之後再使用 kms:PutKeyPolicy 新增。
尋找您的 compartment ID： 每個工作區都有一個 compartment ID，用於限定其 CMEK 資料的範圍。您可以在 Claude Console 的 Workspace > Security > Encryption keys（Compartment ID 欄位）中找到它，或讀取 Get Workspace 端點傳回的 compartment_id 欄位。將該值替換上方金鑰政策中的 <compartment-uuid>。Anthropic 在驗證金鑰時也會將其作為加密上下文傳送，因此條件值必須相符，驗證才能成功。
您也可以從 AWS Console 建立金鑰。選擇對稱金鑰、加密與解密的金鑰用途、單一區域金鑰，以及 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（定義金鑰管理權限，選用）。您的帳戶保留完整的管理控制權。
Define key usage permissions（定義金鑰使用權限）：請勿在此處新增 Anthropic 的帳戶 ID。此精靈步驟會產生權限過寬的政策。請將使用權限留空，並在建立後編輯 Key policy JSON（請參閱上文）。

向 Anthropic 註冊金鑰

註冊金鑰的方式取決於您使用的產品。

向 Anthropic 註冊金鑰

透過 Admin API 建立外部金鑰設定。

對於使用 Claude Platform on AWS 的組織，外部金鑰端點尚未提供。請改為在 Claude Console 中註冊、驗證及附加您的金鑰。

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-create-key-step>",
      "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> 替換為您工作區的實際 compartment ID（請參閱「加密金鑰設定」下的「建立 KMS 金鑰」步驟）。錯誤或未替換的值會使 KMS 傳回不透明的 AccessDeniedException。若要排除此原因，請暫時從 AllowAnthropicCMEKCrypto 陳述式中移除 Condition 區塊，然後重新驗證。
- 資源控制政策（RCP）： 如果您的 AWS 組織有一個 RCP，會在 aws:PrincipalOrgID 與您的組織不符時拒絕 KMS 操作，則會封鎖 Anthropic 的跨帳戶角色。該 RCP 需要針對此金鑰或 Anthropic 的角色 ARN 設定例外。服務控制政策在此不適用，因為它們不會針對透過資源型政策呼叫的外部主體進行評估。
- 透過 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>"
  }'

先決條件

Anthropic 的 Amazon Resource Name (ARN)

加密金鑰設定

向 Anthropic 註冊金鑰

Terraform

先決條件

Anthropic 的 Amazon Resource Name (ARN)

加密金鑰設定

向 Anthropic 註冊金鑰

Terraform

先決條件

Anthropic 的 Amazon Resource Name (ARN)

加密金鑰設定

向 Anthropic 註冊金鑰

Terraform

先決條件

Anthropic 的 Amazon Resource Name (ARN)

加密金鑰設定

向 Anthropic 註冊金鑰

Terraform