使用客户管理的 KMS 密钥加密您的 AgentCore 策略引擎

中的策略默认 AgentCore 提供加密，以使用 AWS 自有的加密密钥保护敏感的静态客户数据。作为额外的保护层，中的策略 AgentCore 允许您使用密 AWS 钥管理服务 (AWS KMS) 客户托管密钥 (CMK) 对策略引擎进行加密。此功能可确保通过静态加密保护敏感数据，从而帮助您：

以下各节说明如何为新的策略引擎配置加密以及如何管理您的加密密钥。

AWS 中策略的 KMS 密钥类型 AgentCore

中的策略与 AWS KMS AgentCore 集成，用于管理用于加密和解密客户数据的加密密钥。要了解有关密钥类型和状态的更多信息，请参阅 AWS KMS 开发人员指南中的密AWS 钥管理服务概念。创建新的策略引擎时，您可以从以下 AWS KMS 密钥类型中进行选择来加密您的数据：

AWS 拥有的密钥

默认加密类型。中的策略 AgentCore 拥有密钥，您无需支付任何额外费用，并在创建时对静态资源数据进行加密。使用中 Policy 拥有的密钥加密或解密数据，无需在代码或应用程序中进行额外配置。 AgentCore您无需查看、管理、使用或审核这些密钥。有关更多信息，请参阅 AWS KMS 开发人员指南中的AWS 自有密钥。

客户自主管理型密钥

您在 AWS 账户中创建、拥有和管理密钥。您可以完全控制 KMS 密钥。 AWS KMS 费用适用于客户托管的密钥。有关更多信息，请参阅 AWS KMS 定价页面。有关密钥类型的更多信息，请参阅 AWS KMS 开发人员指南中的客户托管密钥。

当您为策略引擎的加密指定客户托管密钥时，中的策略会使用该密钥 AgentCore 加密策略引擎及其所有子资源（策略、策略生成）。要使用客户托管密钥加密策略引擎，您需要在密钥策略 AgentCore 中授予对策略的访问权限。密钥策略是一种基于资源的策略，您可以将其附加到客户托管密钥上，以控制对密钥的访问权限。有关更多详细信息，请参阅策略中的 AgentCore授权使用您的 AWS KMS 密钥。

此外，要使用客户托管密钥创建加密策略引擎，或者要对由客户托管密钥加密的策略引擎进行 API 调用，进行调用的 IAM 用户或角色也必须有权访问该密钥。如果 AgentCore Policy in 无法访问该密钥，则任何涉及由该密钥加密的资源的授权决策都将被拒绝。当您无权访问密钥时，您将无法读取、更新或删除由该密钥加密的资源，并且任何使用该密钥进行加密的创建调用都将失败。

使用 AWS KMS 和包含策略的数据密钥 AgentCore

静 AgentCore 态加密策略功能使用 KMS 密钥和数据密钥层次结构来保护您的资源数据。

中的策略 AgentCore 使用基于授权的模型来访问您的客户托管密钥。当您使用客户托管密钥创建策略引擎时，中的策略将 AgentCore 执行以下步骤：

这两笔补助金的用途不同：

两种授权都受使用密钥的加密上下文的限制aws:bedrock-agentcore-policy:policy-engine-arn，该密钥将授权绑定到特定的策略引擎资源。

当您删除带有客户托管密钥的策略引擎时，中的策略 AgentCore 会自动停用这两个授权。

授权使用您的 AWS 中策略的 KMS 密钥 AgentCore

要使用包含策略的客户托管密钥 AgentCore，您的 AWS KMS 密钥策略必须向您的 AWS 账户授予权限。创建策略引擎时，通过转发访问会 AgentCore 话 (FAS) kms:CreateGrant 使用您的身份进行通话策略。因此，密钥策略必须向您的账户委托人（而不是服务委托人）授予kms:CreateGrant和其他必需的权限，并使用kms:ViaService条件来确保仅通过中的策略使用密钥 AgentCore。

中的策略至少 AgentCore 需要对客户托管密钥具有以下权限：

了解源上下文

源上下文提供有关试图对给定密钥进行 AWS KMS 操作的源调用者的信息。这通过将上下文绑定到数据源来防止加密数据的混淆或滥用。

当中的策略代表您通过授权 AgentCore 执行 AWS KMS 操作时，源上下文会在发起请求的 AgentCore 资源中标识策略。您可以在密钥策略中使用源上下文作为基于授权的操作的附加条件，将密钥的使用限制在来自特定账户或资源的请求上。

例如，您可以在密钥策略中的 KMS 操作和验证语句中添加aws:SourceAccount和aws:SourceArn条件，以确保只有在请求来自您的账户和策略引擎资源时，这些操作才会成功：

{
  "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 密钥所在的账户相同，则此密钥策略允许 Policy in 通过授权代表您拨打 KMS 呼叫。 AgentCore 在检查 KMS 密钥的 CloudTrail 审计日志时，这些值应该是可验证的。有关全局 AWS 条件密钥的更多信息，请参阅 AWS KM S 开发人员指南中的使用 aws: SourceArn 或 aws: SourceAccount 条件密钥。

了解 kms：ViaService

kms:ViaService条件密钥将 KMS 密钥的使用限制为来自指定 AWS 服务的请求。此条件密钥适用于转发访问会话 (FAS)。有关的更多信息kms:ViaService，请参阅 KM AWS S 开发人员指南ViaService中的 kms:。

在密钥策略中，kms:ViaService值遵循以下格式bedrock-agentcore.REGION.amazonaws.com，其中REGION是创建策略引擎的 AWS 区域（例如bedrock-agentcore.us-east-1.amazonaws.com）。

了解加密上下文

加密上下文是一组键值对，其中包含用于加密完整性检查的其他经过身份验证的数据。当您在加密数据的请求中包含加密上下文时， AWS KMS 会以加密方式将加密上下文绑定到加密数据。要解密数据，必须传递相同的加密上下文。有关更多信息，请参阅 AWS KMS 开发人员指南中的加密上下文。

中的策略在所有 AWS KMS 加密操作中 AgentCore 使用以下加密上下文，当策略中的策略代表您调用 AWS KMS AgentCore 进行加密和解密过程时，可以在 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 开发人员指南中的 AWS KMS 密钥访问和权限。

创建加密策略引擎

在创建加密策略引擎之前，请确保您正在使用的客户托管密钥已为策略设置了正确的密钥策略声明， AgentCore 以便使用该密钥进行加密和解密。有关所需权限，请参阅策略中的 AgentCore授权使用您的 AWS KMS 密钥。

要使用 AWS CLI 加密您的策略引擎，请在发送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 策略或 KMS 密 AWS 钥策略中缺少所需的 kms: * 操作权限，或者被引用的密钥不存在或已不存在。

要解决此问题，请执行以下操作：

验证异常： AWS KMS 密钥配置

错误：“指定的 KMS 密钥未处于可用状态。确认密钥已启用且未等待删除。”

这意味着，由于其当前配置，所引用的密钥不能用于客户托管密钥加密。可能的原因包括：

要解决此问题，请验证密钥是否满足加密策略引擎的先决条件中描述的先决条件。