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

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

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

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

呼叫者必须对密钥具有`kms:GenerateDataKey``kms:Decrypt``kms:DescribeKey`、、和`kms:ReEncrypt*`权限。

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

### 配置使用客户托管 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**— 授予 IAM 角色`kms:GenerateDataKey`和`kms:ReEncrypt*`权限，其范围由`aws:bedrock-agentcore:configurationBundleArn`加密上下文决定。`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.aws.amazon.com/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.aws.amazon.com/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`— 通过轮换现有捆绑包上的 KMS 密钥时 UpdateConfigurationBundle。
+  `DescribeKey`— 在创建或更新捆绑包时验证密钥时。

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

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

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