使用客戶管理的 KMS 金鑰加密您的 AgentCore 政策引擎

AgentCore 中的政策預設提供加密，以使用 AWS 擁有的加密金鑰保護靜態敏感客戶資料。AgentCore 中的政策提供額外的保護，可讓您使用 AWS Key Management Service (AWS KMS) 客戶受管金鑰 (CMK) 加密政策引擎。此功能可確保透過靜態加密保護敏感資料，這可協助您：

下列各節說明如何設定新政策引擎的加密，並管理您的加密金鑰。

AWS AgentCore 中政策的 KMS 金鑰類型

AgentCore 中的政策與 AWS KMS 整合，以管理用於加密和解密客戶資料的加密金鑰。若要進一步了解金鑰類型和狀態，請參閱《 AWS KMS 開發人員指南》中的AWS 金鑰管理服務概念。當您建立新的政策引擎時，您可以選擇下列 AWS KMS 金鑰類型來加密您的資料：

AWS 擁有的金鑰

預設加密類型。AgentCore 中的政策會免費擁有金鑰，並在建立時加密靜態資源資料。您的程式碼或應用程式中不需要額外的組態，即可使用 AgentCore 中政策所擁有的金鑰來加密或解密您的資料。您不需要檢視、管理、使用或稽核這些金鑰。如需詳細資訊，請參閱《 AWS KMS 開發人員指南》中的AWS 擁有的金鑰。

客戶自管金鑰

您可以在 AWS 帳戶中建立、擁有和管理金鑰。您可以完全控制 KMS 金鑰。 AWS KMS 費用適用於客戶受管金鑰。如需詳細資訊，請參閱 AWS KMS 定價頁面。如需金鑰類型的詳細資訊，請參閱《 AWS KMS 開發人員指南》中的客戶受管金鑰。

當您指定客戶受管金鑰來加密政策引擎時，AgentCore 中的政策會使用該金鑰來加密政策引擎及其所有子資源 （政策、政策產生）。若要使用客戶受管金鑰加密政策引擎，您需要在金鑰政策中授予 AgentCore 中政策的存取權。金鑰政策是您連接到客戶受管金鑰以控制其存取的資源型政策。如需詳細資訊，請參閱授權使用 AgentCore 中政策的 AWS KMS 金鑰。

此外，若要使用客戶受管金鑰建立加密的政策引擎，或對由客戶受管金鑰加密的政策引擎進行 API 呼叫，進行呼叫的 IAM 使用者或角色也必須能夠存取金鑰。如果 AgentCore 中的政策無法存取金鑰，則涉及該金鑰加密資源的任何授權決策都將被拒絕。當您無法存取金鑰時，您將無法讀取、更新或刪除該金鑰加密的資源，而且任何使用金鑰進行加密的建立呼叫都會失敗。

在 AgentCore 中使用 AWS KMS 和資料金鑰搭配 政策

AgentCore 靜態加密功能中的政策使用 KMS 金鑰和資料金鑰階層來保護您的資源資料。

AgentCore 中的政策使用以授予為基礎的模型來存取您的客戶受管金鑰。當您使用客戶受管金鑰建立政策引擎時，AgentCore 中的政策會執行下列步驟：

這兩個授與有不同的用途：

這兩個授予都受到使用金鑰 aws:bedrock-agentcore-policy:policy-engine-arn 的加密內容限制，這會將授予繫結至特定政策引擎資源。

當您刪除具有客戶受管金鑰的政策引擎時，AgentCore 中的政策會自動淘汰這兩個授予。

授權在 AgentCore 中將您的 AWS KMS 金鑰用於 政策

若要在 AgentCore 中使用客戶受管金鑰搭配政策，您的 AWS KMS 金鑰政策必須將許可授予 AWS 您的帳戶。建立政策引擎時，AgentCore 中的政策會透過轉送存取工作階段 (FAS) kms:CreateGrant使用您的身分呼叫 。因此，金鑰政策必須將 kms:CreateGrant和其他必要的許可授予您的帳戶委託人 （而非服務委託人），並使用 kms:ViaService條件來確保金鑰只能透過 AgentCore 中的政策使用。

AgentCore 中的政策至少需要客戶受管金鑰的下列許可：

了解來源內容

來源內容提供來源發起人嘗試對指定金鑰進行 AWS KMS 動作的相關資訊。這可透過將內容繫結至資料來源，來防止加密資料的混淆或濫用。

當 AgentCore 中的政策代表您透過授予執行 AWS KMS 操作時，來源內容會識別在 AgentCore 資源中啟動請求的政策。您可以使用來源內容做為金鑰政策中授予型操作的其他條件，將金鑰用量限制為來自特定帳戶或資源的請求。

例如，您可以將 aws:SourceAccount和 aws:SourceArn條件新增至金鑰政策中的 KMS 操作和驗證陳述式，以確保這些操作只有在請求來自您的 帳戶以及您的政策引擎資源時才會成功：

{
  "Sid": "Allow Policy for KMS operations with source context",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::111122223333:root"
  },
  "Action": [
    "kms:Decrypt",
    "kms:GenerateDataKey"
  ],
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "kms:ViaService": "bedrock-agentcore.us-east-1.amazonaws.com",
      "aws:SourceAccount": "111122223333"
    },
    "StringLike": {
      "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:policy-engine/*",
      "kms:EncryptionContext:aws:bedrock-agentcore-policy:policy-engine-arn": "arn:aws*:bedrock-agentcore:*:*:policy-engine/*"
    }
  }
}

如果來源帳戶與此 AWS KMS 金鑰所在的帳戶相同，則此金鑰政策允許 AgentCore 中的政策透過授與代表您進行 KMS 呼叫。檢查 KMS 金鑰的 CloudTrail 稽核日誌時，應可驗證這些值。如需全域 AWS 條件金鑰的詳細資訊，請參閱《 AWS KMS 開發人員指南》中的使用 aws：SourceArn 或 aws：SourceAccount 條件金鑰。

了解 kms:ViaService

kms:ViaService 條件金鑰會將 KMS 金鑰的使用限制為來自指定 AWS 服務的請求。此條件金鑰適用於轉送存取工作階段 (FAS)。如需 kms:ViaService 的詳細資訊，請參閱《 AWS KMS 開發人員指南》中的 kms:ViaService。

在金鑰政策中， kms:ViaService值遵循格式 bedrock-agentcore.REGION.amazonaws.com ，其中 REGION 是建立政策引擎 AWS 的區域 （例如 bedrock-agentcore.us-east-1.amazonaws.com )。

了解加密內容

加密內容是一組金鑰值對，其中包含用於加密完整性檢查的其他已驗證資料。當您在加密資料的請求中包含加密內容時， AWS KMS 會以密碼編譯方式將加密內容繫結至加密的資料。若要解密資料，您必須傳遞相同的加密內容。如需詳細資訊，請參閱《 AWS KMS 開發人員指南》中的加密內容。

AgentCore 中的政策會在所有 AWS KMS 密碼編譯操作中使用下列加密內容，當 AgentCore 中的政策代表您進行 AWS KMS 呼叫以進行加密和解密程序時，可以在 CloudTrail 日誌中驗證：

{
  "aws:bedrock-agentcore-policy:policy-engine-arn": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:policy-engine/POLICY_ENGINE_ID"
}

您可以在金鑰政策條件中使用此加密內容，以限制哪些政策引擎可以使用金鑰。例如，下節中的金鑰政策使用 kms:EncryptionContext條件來允許金鑰僅用於政策引擎資源。

完成 AWS KMS 金鑰政策

根據先前章節中的概念，下列範例金鑰政策提供加密政策引擎並使用加密政策引擎的必要許可。政策包含符合安全最佳實務的條件金鑰。

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Allow Policy to create grants",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/ExampleRole"
      },
      "Action": "kms:CreateGrant",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "bedrock-agentcore.us-east-1.amazonaws.com",
          "kms:GrantConstraintType": "EncryptionContextSubset"
        },
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore-policy:policy-engine-arn": "arn:aws*:bedrock-agentcore:*:*:policy-engine/*"
        },
        "ForAllValues:StringEquals": {
          "kms:GrantOperations": [
            "Encrypt",
            "Decrypt",
            "GenerateDataKey",
            "GenerateDataKeyWithoutPlaintext",
            "ReEncryptFrom",
            "ReEncryptTo"
          ]
        }
      }
    },
    {
      "Sid": "Allow Policy for KMS operations",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/ExampleRole"
      },
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "bedrock-agentcore.us-east-1.amazonaws.com"
        },
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore-policy:policy-engine-arn": "arn:aws*:bedrock-agentcore:*:*:policy-engine/*"
        }
      }
    },
    {
      "Sid": "Allow Policy for KMS validation",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/ExampleRole"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "bedrock-agentcore.us-east-1.amazonaws.com"
        }
      }
    }
  ]
}

此政策包含下列陳述式：

加密政策引擎的先決條件

在加密您的政策引擎之前，請確定您已滿足下列先決條件：

如需控制 KMS 金鑰的 IAM 許可的詳細資訊，請參閱《KMS 開發人員指南》中的 KMS 金鑰存取和許可。 AWS

建立加密的政策引擎

在建立加密政策引擎之前，請確定您使用的客戶受管金鑰已為 AgentCore 中的政策設定適當的金鑰政策陳述式，以使用金鑰進行加密和解密。如需所需許可，請參閱在 AgentCore 中授權使用政策的 AWS KMS 金鑰。

若要使用 CLI AWS 加密您的政策引擎，請在傳送create-policy-engine請求時包含 --encryption-key-arn 參數：

aws bedrock-agentcore-control create-policy-engine \
  --name "MyPolicyEngine" \
  --description "Policy engine with customer-managed encryption" \
  --encryption-key-arn "arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"

回應包含政策引擎 ARN 和狀態：

{
  "policyEngineId": "MyPolicyEngine-abc123",
  "name": "MyPolicyEngine",
  "description": "Policy engine with customer-managed encryption",
  "policyEngineArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/MyPolicyEngine-abc123",
  "status": "CREATING",
  "statusReasons": [],
  "encryptionKeyArn": "arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
  "createdAt": "2026-02-24T12:00:00Z",
  "updatedAt": "2026-02-24T12:00:00Z"
}

限制

下列限制適用於政策引擎的客戶受管金鑰加密：

疑難排解

本節說明在 AgentCore 中使用政策時可能遇到的常見客戶受管金鑰相關錯誤，並提供故障診斷步驟來解決這些錯誤。

存取遭拒： AWS KMS 許可問題

錯誤：「拒絕存取指定的 KMS 金鑰。驗證金鑰政策是否授予必要的許可。」

這可能表示發起人在其 IAM 政策或 AWS KMS 金鑰政策中缺少必要的 kms:* 動作許可，或參考的金鑰不存在或不再存在。

若要解決此問題：

驗證例外狀況： AWS KMS 金鑰組態

錯誤：「指定的 KMS 金鑰未處於可用狀態。確認金鑰已啟用，而非待刪除。」

這表示參考的金鑰無法用於客戶受管金鑰加密，因為其目前的組態。可能的原因包括：

若要解決此問題：請確認金鑰符合加密政策引擎的先決條件中所述的先決條件。