自定义策略引擎的加密

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

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

Amazon 中策略的 KMS 密钥类型 AgentCore

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

Amazon 拥有的密钥

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

客户自主管理型密钥

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

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

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

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

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

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

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

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

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

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

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

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

了解源代码上下文

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

当中的策略代表您通过授权 AgentCore 执行 Amazon 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/*"
    }
  }
}

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

了解 kms：ViaService

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

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

了解加密上下文

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

中的策略在所有 Amazon KMS 加密操作中 AgentCore 使用以下加密上下文，当策略中的策略代表您调用 Amazon KMS AgentCore 进行加密和解密过程时，可以在 CloudTrail 日志中进行验证：

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

您可以在密钥策略条件中使用此加密上下文来限制哪些策略引擎可以使用该密钥。例如，下一节中的密钥策略使用一个kms:EncryptionContext条件来允许该密钥仅用于策略引擎资源。

完成 Amazon 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 开发人员指南中的 Amazon KMS 密钥访问和权限。

创建加密策略引擎

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

要加密您的策略引擎，请在创建策略引擎时提供密钥 ARN：

响应包括策略引擎 ARN 和状态：

{
  "policyEngineId": "MyPolicyEngine-abc123defg",
  "name": "MyPolicyEngine",
  "description": "Policy engine with customer-managed encryption",
  "policyEngineArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/MyPolicyEngine-abc123defg",
  "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 并提供了解决这些错误的故障排除步骤。

访问被拒绝： Amazon KMS 权限问题

错误：“拒绝访问指定的 KMS 密钥。验证密钥策略是否授予了所需的权限。”

这可能意味着调用者在其 IAM 策略或 KMS 密 Amazon 钥策略中缺少所需的 kms: * 操作权限，或者被引用的密钥不存在或已不存在。

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

验证异常： Amazon KMS 密钥配置

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

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

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

密钥不可用：您无法列出或阅读您的政策

如果客户管理的密钥变得不可用（已删除、已禁用、待删除，或者授权或密钥政策已撤销），则返回加密内容的操作将停止运行。 ListPolicyEngines、GetPolicyEngine、ListPolicies、和GetPolicy都在返回之前验证密钥并解密，因此当密钥不可用时，每一个都失败。这是设计使然：没有密钥就无法阅读策略定义。

实际问题是恢复。这些是您通常用来找出存在的内容的操作，因此丢失密钥可能会使您无法枚举需要清理的资源。

要解决此问题，请使用摘要操作。它们仅返回标识符和状态，不包含加密内容，因此它们既不验证密钥，也不解密，当密钥不进行解密时，它们会继续工作。

首先，列出账户中的策略引擎，包括每个引擎使用的密钥。然后列出受影响引擎内部的策略。

引擎摘要给出了每个引擎的policyEngineIdname、status、和encryptionKeyArn。encryptionKeyArn用于确认哪些引擎依赖于受影响的密钥。策略摘要给出了每个策略的policyId、namestatusenforcementMode、和，但没有给出其 definition ——该语句是加密部分，省略了。汇总操作为您提供完整的清单。但是，删除找到的内容取决于密钥。

Policy engine still contains 3 policies and cannot be deleted

恢复密钥。对于持有策略的引擎来说，这是唯一的前进方向。

密钥再次起作用后，读取操作将返回策略定义，删除操作将正常运行 — 按 ID 删除策略，然后删除引擎：

当引擎仍与网关关联时，无论密钥的状态如何，都无法将其删除。请先将其解除关联；请参阅使用策略引擎更新现有网关。