View a markdown version of this page

配置包加密 - Amazon Bedrock 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— 授予 IAM 角色kms:GenerateDataKey和kms:ReEncrypt*权限，其范围由aws:bedrock-agentcore:configurationBundleArn加密上下文决定。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— 通过轮换现有捆绑包上的 KMS 密钥时 UpdateConfigurationBundle。

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

密钥不可用时的行为

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

  • CreateConfigurationBundle— 使用验证失败ValidationException。

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

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

  • ListConfigurationBundles / ListConfigurationBundleVersions-成功，因为列出仅返回元数据且不需要 KMS 操作。

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

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