View a markdown version of this page

配置包加密 - 亚马逊基岩 AgentCore
工作原理监控配置包的 KMS 使用情况密钥不可用时的行为

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

配置包加密

当您在配置包kmsKeyArn上指定时，该服务使用信封加密对组件配置（系统提示、工具描述和其他配置内容）进行加密。所有其他捆绑包元数据（名称、描述、版本 ID、时间戳）仍使用 AWS 自有密钥进行加密。

工作原理

配置包加密使用带有呼叫者凭据的信封加密。当您使用创建或更新包时kmsKeyArn，该服务使用您的证书（通过转发访问会话）从 KMS 生成数据加密密钥 (DEK)。该服务使用该 DEK 在本地加密组件配置，然后将加密的 DEK AES-GCM 与捆绑包一起存储。当您检索捆绑包时，该服务使用您的证书解密 DEK 并解密组件。

调用者必须对密钥拥有kms:GenerateDataKeykms:Decryptkms:DescribeKey、和kms:ReEncrypt*权限。

AgentCore 优化仅支持对称加密 KMS 密钥。KMS 密钥必须与配置包位于同一 AWS 区域。

配置使用客户管理的 KMS 密钥的权限

以下密钥策略提供了配置包加密所需的最低权限。该策略包含两条语句：

  • AllowCallerAccess— 允许 IAM 用户或角色通过验证密钥DescribeKey。

  • AllowCallerCryptoOps— 允许 IAM 用户或角色根据加密上下文生成数据密钥、解密和重新加密（用于密钥轮换）。

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCallerAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyConfigBundleRole"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*"
    },
    {
      "Sid": "AllowCallerCryptoOps",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyConfigBundleRole"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt",
        "kms:ReEncrypt*"
      ],
      "Resource": "*",
      "Condition": {
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore:configurationBundleArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/*"
        }
      }
    }
  ]
}

该政策包含以下声明：

  • AllowCallerAccess— 授予 IAM 角色在包创建或更新时进行密钥验证的kms:DescribeKey权限。111122223333替换为您的账户 ID MyConfigBundleRole 以及管理配置包的 IAM 角色或用户。

  • AllowCallerCryptoOps— 授予受aws:bedrock-agentcore:configurationBundleArn加密上下文限制的 IAM 角色kms:GenerateDataKey和kms:ReEncrypt*权限。kms:Decrypt密钥轮换（更改现有捆绑包上的 KMS 密钥）需要该kms:ReEncrypt*权限。将111122223333MyConfigBundleRole、和us-east-1替换为您的值。要允许访问您账户中的所有配置包，请使用通配StringLike符和:。arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/*

缩小对客户管理的 KMS 密钥的访问权限

您可以使用加密上下文来缩小对客户管理密钥的访问范围。 AgentCore 优化在所有 KMS 操作中包括以下加密上下文：

{
  "aws:bedrock-agentcore:configurationBundleArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/bundle-id"
}

您可以在密钥策略条件下使用此加密上下文将 KMS 操作限制在特定的配置包中，如上面示例密钥策略中的AllowCallerCryptoOps语句所示。

使用客户管理的 KMS 密钥创建配置包

要加密配置包，请在调用时指定kmsKeyArn参数CreateConfigurationBundle。

例
AWS CLI
aws bedrock-agentcore-control create-configuration-bundle \
  --bundle-name "MyEncryptedBundle" \
  --kms-key-arn "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
  --components '{
    "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/my-agent": {
      "configuration": {
        "systemPrompt": "You are a helpful assistant.",
        "modelId": "anthropic.claude-3-sonnet"
      }
    }
  }'
Python (Boto3)
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.create_configuration_bundle(
    bundleName='MyEncryptedBundle',
    kmsKeyArn='arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
    components={
        'arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/my-agent': {
            'configuration': {
                'systemPrompt': 'You are a helpful assistant.',
                'modelId': 'anthropic.claude-3-sonnet'
            }
        }
    }
)

print(f"Bundle ID: {response['bundleId']}")

更改现有捆绑包的加密配置

您可以使用以下方法更改现有捆绑包的加密配置 UpdateConfigurationBundle：

  • 添加加密 -在没有加密的情况下创建的捆绑包kmsKeyArn上指定。该服务生成新的 DEK 并对组件配置进行加密。

  • 旋转密钥 -指定不同的密钥kmsKeyArn。该服务使用将现有 DEK 从旧密钥重新打包到新密钥。kms:ReEncrypt调用者必须对两个密钥都有权限。如果旧密钥不可用（禁用、删除或缺少权限），更新将失败。

注意

一旦添加了客户管理的密钥加密，就无法将其从配置包中删除。

监控配置包的 KMS 使用情况

配置包 KMS 操作会显示以下 CloudTrail 事件名称：

  • GenerateDataKey— 使用客户管理的密钥创建捆绑包或向现有捆绑包添加加密时。该encryptionContext字段包含aws:bedrock-agentcore:configurationBundleArn。

  • Decrypt— 检索捆绑包内容 (GetConfigurationBundle、 GetConfigurationBundleVersion) 或更新加密包时。

  • ReEncrypt— 通过 UpdateConfigurationBundle. 在现有捆绑包上轮换 KMS 密钥时

  • DescribeKey— 在捆绑包创建或更新时验证密钥时。

密钥不可用时的行为

如果您禁用或删除配置包使用的客户管理的 KMS 密钥：

  • CreateConfigurationBundle— 使用进行验证时失败ValidationException。

  • UpdateConfigurationBundle— 失败，因为该服务无法解密现有 DEK 以重新加密新组件。密钥轮换也失败，因为旧密钥无法重新打包。

  • GetConfigurationBundle / GetConfigurationBundleVersion— 由于服务无法解密 DEK 或组件配置而失败。

  • ListConfigurationBundles / ListConfigurationBundleVersions— 之所以成功，是因为清单仅返回元数据，不需要 KMS 操作。

  • DeleteConfigurationBundle— 成功是因为删除不需要解密捆绑数据。

要恢复访问权限，请重新启用密钥或更新密钥策略以授予所需的权限。