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

# 配置包加密
<a name="configuration-bundles-encryption"></a>

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

## 工作原理
<a name="configuration-bundles-encryption-how-it-works"></a>

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

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

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

### 配置使用客户管理的 KMS 密钥的权限
<a name="configuration-bundles-encryption-key-policy"></a>

以下密钥策略提供了配置包加密所需的最低权限。该策略包含两条语句：
+  **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*`权限。将{{111122223333}}{{MyConfigBundleRole}}、和{{us-east-1}}替换为您的值。要允许访问您账户中的所有配置包，请使用通配`StringLike`符和:。`arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/*`

### 缩小对客户管理的 KMS 密钥的访问权限
<a name="configuration-bundles-encryption-scoping"></a>

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

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

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

### 使用客户管理的 KMS 密钥创建配置包
<a name="configuration-bundles-encryption-creating"></a>

要加密配置包，请在调用时指定`kmsKeyArn`参数[CreateConfigurationBundle](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_CreateConfigurationBundle.html)。

**Example**  

```
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"
      }
    }
  }'
```

```
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']}")
```

### 更改现有捆绑包的加密配置
<a name="configuration-bundles-encryption-changing"></a>

您可以使用以下方法更改现有捆绑包的加密配置 [ UpdateConfigurationBundle](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_UpdateConfigurationBundle.html)：
+  **添加加密 **-在没有加密的情况下创建的捆绑包`kmsKeyArn`上指定。该服务生成新的 DEK 并对组件配置进行加密。
+  **旋转密钥 **-指定不同的密钥`kmsKeyArn`。该服务使用将现有 DEK 从旧密钥重新打包到新密钥。`kms:ReEncrypt`调用者必须对两个密钥都有权限。如果旧密钥不可用（禁用、删除或缺少权限），更新将失败。

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

## 监控配置包的 KMS 使用情况
<a name="configuration-bundles-encryption-monitoring"></a>

配置包 KMS 操作会显示以下 CloudTrail 事件名称：
+  `GenerateDataKey`— 使用客户管理的密钥创建捆绑包或向现有捆绑包添加加密时。该`encryptionContext`字段包含`aws:bedrock-agentcore:configurationBundleArn`。
+  `Decrypt`— 检索捆绑包内容 (GetConfigurationBundle、 GetConfigurationBundleVersion) 或更新加密包时。
+  `ReEncrypt`— 通过 UpdateConfigurationBundle. 在现有捆绑包上轮换 KMS 密钥时
+  `DescribeKey`— 在捆绑包创建或更新时验证密钥时。

## 密钥不可用时的行为
<a name="configuration-bundles-encryption-unavailable"></a>

如果您禁用或删除配置包使用的客户管理的 KMS 密钥：
+  **CreateConfigurationBundle**— 使用进行验证时失败`ValidationException`。
+  **UpdateConfigurationBundle**— 失败，因为该服务无法解密现有 DEK 以重新加密新组件。密钥轮换也失败，因为旧密钥无法重新打包。
+  **GetConfigurationBundle / GetConfigurationBundleVersion**— 由于服务无法解密 DEK 或组件配置而失败。
+  **ListConfigurationBundles / ListConfigurationBundleVersions**— 之所以成功，是因为清单仅返回元数据，不需要 KMS 操作。
+  **DeleteConfigurationBundle**— 成功是因为删除不需要解密捆绑数据。

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