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

# 数据集加密
<a name="datasets-encryption"></a>

当您在数据集`kmsKeyArn`上指定时，该服务会使用 S3 服务器端加密和 KMS () SSE-KMS 对所有存储的示例进行加密。这包括草稿和所有已发布版本中的示例。

数据集创建后`kmsKeyArn`不可变——您无法对其进行更改或移除。

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

数据集加密使用 S3 SSE-KMS。当服务在 S3 中写入或读取数据集内容时，S3 会代表服务调用 KMS 来加密或解密数据。服务委托人 (`bedrock-agentcore.amazonaws.com`) 在密钥策略中必须具有 KMS 权限。

在 API 时，该服务使用试运行检查（转发访问会话）来验证呼叫者是否具有 KMS 权限。这样可以立即捕获权限问题，而不是在摄取过程中异步失败。

AgentCore 评估仅支持对称加密 KMS 密钥。KMS 密钥必须与数据集位于同一 Amazon 区域。

## 必需的密钥策略
<a name="datasets-encryption-key-policy"></a>

以下密钥策略授予数据集加密所需的最低权限。它包括两个语句：
+  **AllowCallerAccess**— 向调用密钥的 IAM 用户或角色`CreateDataset`授予验证和使用密钥的权限。该服务在 API 时执行试运行检查，以验证呼叫者是否具有 KMS 访问权限。{{111122223333}}替换为您的账户 ID 以及{{MyDatasetRole}}管理数据集的 IAM 角色或用户。
+  **AllowAgentCoreDatasetAccess**— 向 AgentCore 服务主体授予在 S3 中加密和解密数据集内容的权限。

```
{
"Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "AllowCallerAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyDatasetRole"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt",
        "kms:DescribeKey"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AllowAgentCoreDatasetAccess",
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt",
        "kms:DescribeKey"
      ],
      "Resource": "*"
    }
  ]
}
```

**注意**  
这是最低限度的政策。有关推荐的安全条件，请参阅[缩小访问范围](#datasets-encryption-scoping)。

## 缩小访问范围
<a name="datasets-encryption-scoping"></a>

您可以添加条件来限制何时可以使用密钥。对于数据集，该服务通过 KMS 写入操作 (`GenerateDataKey`) 发送以下上下文：
+  `aws:SourceAccount`-拥有数据集的 Amazon 账户 ID。
+  `aws:SourceArn`— 正在加密的数据集的 ARN。
+  `kms:EncryptionContext:aws:bedrock-agentcore:datasetArn`— 数据集 ARN 作为加密上下文。

以下策略将权限分为写入（有条件）和读取（无条件）：

```
{
"Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "AllowCallerAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyDatasetRole"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt",
        "kms:DescribeKey"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AllowAgentCoreDatasetWrite",
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "kms:GenerateDataKey",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "111122223333"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:dataset/*"
        },
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore:datasetArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:dataset/*"
        }
      }
    },
    {
      "Sid": "AllowAgentCoreDatasetRead",
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": [
        "kms:Decrypt",
        "kms:DescribeKey"
      ],
      "Resource": "*"
    }
  ]
}
```

**重要**  
不要在 read 语句中添加`aws:SourceAccount`或`aws:SourceArn`条件 (`Decrypt`,`DescribeKey`)。数据集下载使用预签名的 S3 URL，下载客户端不发送源上下文标头。将这些条件添加到读取操作会导致下载失败。

{{111122223333}}替换为您的账户 ID 和{{us-east-1}}您所在 Amazon 的地区。要将范围限定为特定的数据集，请将通配符替换为数据集 ID: `arn:aws:bedrock-agentcore:us-east-1:111122223333:dataset/my-dataset-id`。

## 使用客户托管的 KMS 密钥创建数据集
<a name="datasets-encryption-creating"></a>

调用时指定`kmsKeyArn`参数`CreateDataset`：

**Example**  

1. 

   要创建加密数据集，请在添加数据集`--kms-key-arn`时通过，然后运行`agentcore deploy`。将 KMS 密钥 ARN 替换为您自己的密钥 ARN。

   ```
   agentcore add dataset --name encrypted_dataset \
       --schema-type AGENTCORE_EVALUATION_PREDEFINED_V1 \
       --kms-key-arn "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
   
   # Add your scenarios to agentcore/datasets/encrypted_dataset.jsonl, then run agentcore deploy.
   agentcore deploy
   ```

1. 

   ```
   from bedrock_agentcore.evaluation import DatasetClient
   
   client = DatasetClient(region_name="us-east-1")
   
   ds = client.create_dataset_and_wait(
       datasetName="encrypted_dataset",
       schemaType="AGENTCORE_EVALUATION_PREDEFINED_V1",
       kmsKeyArn="arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
       source={
           "inlineExamples": {
               "examples": [
                   {"scenario_id": "TC-01", "turns": [{"input": "Hello"}]}
               ]
           }
       },
   )
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   response = client.create_dataset(
       datasetName='encrypted_dataset',
       schemaType='AGENTCORE_EVALUATION_PREDEFINED_V1',
       kmsKeyArn='arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
       source={
           'inlineExamples': {
               'examples': [
                   {'scenario_id': 'TC-01', 'turns': [{'input': 'Hello'}]}
               ]
           }
       }
   )
   ```

1. 

   ```
   aws bedrock-agentcore-control create-dataset \
       --dataset-name "encrypted_dataset" \
       --schema-type AGENTCORE_EVALUATION_PREDEFINED_V1 \
       --kms-key-arn "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
       --source '{"inlineExamples": {"examples": [{"scenario_id": "TC-01", "turns": [{"input": "Hello"}]}]}}'
   ```

## 监控数据集的 KMS 使用情况
<a name="datasets-encryption-monitoring"></a>

数据集 KMS 操作会出现以下 CloudTrail 事件名称：
+  `GenerateDataKey`— 创建数据集、添加示例、更新示例或发布版本时。该`encryptionContext`字段包含`aws:bedrock-agentcore:datasetArn`。
+  `Decrypt`— 读取数据集内容 (GetDataset、 ListDatasetExamples) 或在预签名 URL 下载期间。
+  `DescribeKey`— 在创建数据集时验证密钥时。

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

如果您禁用或删除数据集使用的客户托管 KMS 密钥：
+  **CreateDataset**— 使用验证失败`ValidationException`。
+  **AddDatasetExamples, UpdateDatasetExamples, CreateDatasetVersion** — `ValidationException` 在 API 时失败。
+  **GetDataset**— 失败，`ValidationException`指示 KMS 密钥已禁用或删除。
+  **ListDatasetExamples**— 失败，`ValidationException`指示 KMS 密钥已禁用或删除。
+  **DeleteDataset**— 之所以成功，是因为删除 S3 对象不需要 KMS 解密。