本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

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

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

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

AWS 中策略的 KMS 密钥类型 AgentCore

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

AWS 自有密钥

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

客户自主管理型密钥

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

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

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

使用 AWS 带有策略的 KMS 和数据密钥 AgentCore

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

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

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

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

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

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

要在策略中使用客户管理的密钥 AgentCore，您的 AWS KMS 密钥策略必须向您的 AWS 账户授予权限。创建策略引擎时，Policy 会通过前向访问会 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 密钥所在的账户相同，则此密钥策略允许中的策略通过授予代表您发出 KMS 调用。 AgentCore 在检查 KMS 密钥的 CloudTrail 审计日志时，这些值应该是可验证的。有关全局 AWS 条件密钥的更多信息，请参阅 AWS KMS 开发人员指南中的使用 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 使用以下加密上下文，当策略中的 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 开发人员指南中的 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 密钥未处于可用状态。确认密钥已启用且未待删除。”

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

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