管理加密金鑰

為 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 使用您的加密金鑰，您必須授予 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\": [ \"00000000-0000-0000-0000-000000000000\", \"<compartment-uuid>\" ] } } }, { \"Sid\": \"AllowAnthropicCMEKDescribe\", \"Effect\": \"Allow\", \"Principal\": {\"AWS\": \"arn:aws:iam::915198916910:role/anthropic-cmek-client-us\"}, \"Action\": \"kms:DescribeKey\", \"Resource\": \"*\" } ] }"
從輸出中擷取 KeyMetadata.Arn。您在下一步向 Anthropic 註冊金鑰時會需要它。
EncryptionContext 條件是建議但非必要的。Anthropic 始終會在加密上下文中包含您工作區的區隔（compartment）ID，因此無論如何，密文在密碼學上都會繫結到該區隔。新增此條件可在 IAM 層提供深度防禦。若要先不使用它，請從 AllowAnthropicCMEKCrypto 陳述式中省略 Condition 區塊，之後再使用 kms:PutKeyPolicy 新增。
尋找您的區隔 ID： 區隔 ID 的位置在 Claude Platform 和 Claude Enterprise 之間有所不同。請參閱向 Anthropic 註冊金鑰下的 Claude Platform 和 Claude Enterprise 分頁。
您也可以從 AWS Console 建立金鑰。選擇具有加密和解密金鑰用途的對稱金鑰、單一區域金鑰，以及 KMS 金鑰材料來源。Create-key 精靈會在其**檢閱（Review）步驟提交金鑰政策：如果您在該處的金鑰使用權限下新增 Anthropic 的帳戶 ID 915198916910，產生的政策會授予整個 Anthropic 帳戶更廣泛的動作（例如 kms:ReEncrypt* 和 kms:GenerateDataKey*），且沒有 EncryptionContext 條件，而驗證仍會成功通過。為避免留下權限過大的金鑰，請僅以管理權限完成精靈，然後開啟金鑰的金鑰政策（Key policy）**分頁，將 JSON 替換為先前顯示的角色範圍政策（範圍限定於 anthropic-cmek-client-us 角色的三個陳述式，並帶有 EncryptionContext 條件）。
設定金鑰（Configure key）：對稱（symmetric）、加密與解密（encrypt and decrypt）、單一區域金鑰（single-region key）。
為金鑰新增別名（alias）和描述（description）。
定義金鑰管理權限（key administrative permissions）（選用）。您的帳戶保留完整的管理控制權。
請勿在此處新增 Anthropic 的帳戶 ID。此精靈步驟會產生權限過大的政策。請將使用權限（usage permissions）留空，並在建立後編輯 Key policy JSON（請參閱前述的金鑰政策）。

向 Anthropic 註冊金鑰

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

尋找您的區隔 ID： 每個工作區都有一個區隔 ID，用於界定其 CMEK 資料的範圍。您可以在 Claude Console 的 Workspace > Security > Encryption keys（Compartment ID 欄位）中找到它，或讀取 Get Workspace 端點回傳的 compartment_id 欄位。將該值替換到前述金鑰政策中的 <compartment-uuid>。

金鑰驗證始終會傳送全零的區隔 UUID（00000000-0000-0000-0000-000000000000）作為加密上下文，因為驗證是在金鑰附加到任何工作區之前執行的。即時流量則會傳送每個已附加工作區的區隔 ID。

任何 EncryptionContext 條件都必須允許全零值，以及金鑰所附加的每個工作區的區隔 ID。每當重新執行金鑰設定時，驗證也會再次執行，因此請永久保留全零項目。

若要將金鑰附加到其他工作區，請在附加之前使用 kms:PutKeyPolicy 將該工作區的區隔 ID 新增到條件中。

向 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 }
如果驗證失敗，常見原因包括：
- 加密上下文不符： 當 kms:EncryptionContext:anthropic:compartment_uuid 條件僅允許 Anthropic 傳送的兩個值之一時，驗證會失敗但資料流量正常（或相反），並出現不透明的 AccessDeniedException。驗證傳送全零 UUID（00000000-0000-0000-0000-000000000000）；即時流量傳送已附加工作區的區隔 ID。請確認條件同時列出兩者。若要完全排除條件的影響，請暫時從 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 提供者的 aws_kms_key 和 aws_kms_alias 資源。

Was this page helpful?

Anthropic 的 Amazon Resource Name（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\": [ \"00000000-0000-0000-0000-000000000000\", \"<compartment-uuid>\" ] } } }, { \"Sid\": \"AllowAnthropicCMEKDescribe\", \"Effect\": \"Allow\", \"Principal\": {\"AWS\": \"arn:aws:iam::915198916910:role/anthropic-cmek-client-us\"}, \"Action\": \"kms:DescribeKey\", \"Resource\": \"*\" } ] }"
從輸出中擷取 KeyMetadata.Arn。您在下一步向 Anthropic 註冊金鑰時會需要它。
EncryptionContext 條件是建議但非必要的。Anthropic 始終會在加密上下文中包含您工作區的區隔（compartment）ID，因此無論如何，密文在密碼學上都會繫結到該區隔。新增此條件可在 IAM 層提供深度防禦。若要先不使用它，請從 AllowAnthropicCMEKCrypto 陳述式中省略 Condition 區塊，之後再使用 kms:PutKeyPolicy 新增。
尋找您的區隔 ID： 區隔 ID 的位置在 Claude Platform 和 Claude Enterprise 之間有所不同。請參閱向 Anthropic 註冊金鑰下的 Claude Platform 和 Claude Enterprise 分頁。
您也可以從 AWS Console 建立金鑰。選擇具有加密和解密金鑰用途的對稱金鑰、單一區域金鑰，以及 KMS 金鑰材料來源。Create-key 精靈會在其**檢閱（Review）步驟提交金鑰政策：如果您在該處的金鑰使用權限下新增 Anthropic 的帳戶 ID 915198916910，產生的政策會授予整個 Anthropic 帳戶更廣泛的動作（例如 kms:ReEncrypt* 和 kms:GenerateDataKey*），且沒有 EncryptionContext 條件，而驗證仍會成功通過。為避免留下權限過大的金鑰，請僅以管理權限完成精靈，然後開啟金鑰的金鑰政策（Key policy）**分頁，將 JSON 替換為先前顯示的角色範圍政策（範圍限定於 anthropic-cmek-client-us 角色的三個陳述式，並帶有 EncryptionContext 條件）。
設定金鑰（Configure key）：對稱（symmetric）、加密與解密（encrypt and decrypt）、單一區域金鑰（single-region key）。
為金鑰新增別名（alias）和描述（description）。
定義金鑰管理權限（key administrative permissions）（選用）。您的帳戶保留完整的管理控制權。
請勿在此處新增 Anthropic 的帳戶 ID。此精靈步驟會產生權限過大的政策。請將使用權限（usage permissions）留空，並在建立後編輯 Key policy JSON（請參閱前述的金鑰政策）。

向 Anthropic 註冊金鑰

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

若要將金鑰附加到其他工作區，請在附加之前使用 kms:PutKeyPolicy 將該工作區的區隔 ID 新增到條件中。

向 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 }
如果驗證失敗，常見原因包括：
- 加密上下文不符： 當 kms:EncryptionContext:anthropic:compartment_uuid 條件僅允許 Anthropic 傳送的兩個值之一時，驗證會失敗但資料流量正常（或相反），並出現不透明的 AccessDeniedException。驗證傳送全零 UUID（00000000-0000-0000-0000-000000000000）；即時流量傳送已附加工作區的區隔 ID。請確認條件同時列出兩者。若要完全排除條件的影響，請暫時從 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