# Batch 评估加密
当您指定批量评估时，该服务会使用 S3 服务器端加密和 KMS () SSE-KMS 对存储在 S3 中的所有输出项目进行加密。`kmsKeyArn`这包括数据源配置、会话元数据和评估结果。
`kmsKeyArn`是在创建时通过指定的`StartBatchEvaluation`。
## 工作原理
Batch 评估加密使用 S3 SSE-KMS。当服务在 S3 中写入或读取批量评估输出时，S3 会代表该服务调用 KMS 来加密或解密数据。服务委托人 (`bedrock-agentcore.amazonaws.com`) 在密钥策略中必须具有 KMS 权限。
在 API 时，该服务使用试运行检查（转发访问会话）来验证呼叫者是否具有 KMS 权限。这样可以立即发现权限问题，而不是在批量评估工作流程中异步失败。
该服务还会验证它是否可以使用自己的`kms:GenerateDataKey`凭据执行任务，以确保密钥策略向服务主体授予写入加密输出所需的权限。
AgentCore 评估仅支持对称加密 KMS 密钥。KMS 密钥必须与批量评估位于同一 AWS 区域。
### 配置使用客户托管 KMS 密钥的权限
以下密钥策略提供了批量评估加密所需的最低权限。该策略包含三条语句：
+ **AllowCallerAccess**— 允许 IAM 用户或角色通过验证密钥`DescribeKey`。
+ **AllowCallerCryptoOps**— 允许 IAM 用户或角色根据加密上下文进行加密和解密。
+ **AllowServicePrincipalAccess**— 允许 AgentCore 服务主体加密和解密 S3 中的批量评估数据，范围由源账户和源 ARN 确定。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowCallerAccess",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/MyBatchEvaluationRole"
},
"Action": "kms:DescribeKey",
"Resource": "*"
},
{
"Sid": "AllowCallerCryptoOps",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/MyBatchEvaluationRole"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "*",
"Condition": {
"StringLike": {
"kms:EncryptionContext:aws:bedrock-agentcore:batchEvaluationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*"
}
}
},
{
"Sid": "AllowServicePrincipalAccess",
"Effect": "Allow",
"Principal": {
"Service": "bedrock-agentcore.amazonaws.com"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*"
}
}
}
]
}
```
该政策包含以下声明：
+ **AllowCallerAccess**— 授予 IAM 角色在创建批量评估时进行密钥验证的`kms:DescribeKey`权限。{{111122223333}}替换为您的账户 ID 和{{MyBatchEvaluationRole}}开始批量评估的 IAM 角色或用户。
+ **AllowCallerCryptoOps**— 授予 IAM 角色`kms:GenerateDataKey`和`kms:Decrypt`权限，范围由`aws:bedrock-agentcore:batchEvaluationArn`加密上下文决定。用您的值替换{{111122223333}}{{MyBatchEvaluationRole}}、和{{us-east-1}}。要允许访问您账户中的所有批量评估，请使用带有`StringLike`:`arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*`的通配符。
+ **AllowServicePrincipalAccess**— 授予在 S3 中加密`kms:GenerateDataKey`和解密批量评估数据的 AgentCore 服务主体和`kms:Decrypt`权限。按来源账户和来源 ARN `aws:SourceArn` () 划分范围，以防止混淆副手攻击。{{111122223333}}用您的地区{{us-east-1}}和账户 ID 替换和。
### 缩小对客户托管的 KMS 密钥的访问权限
您可以使用加密上下文来缩小对客户托管密钥的访问范围。 AgentCore 评估包括所有 KMS 操作中的以下加密上下文：
```
{
"aws:bedrock-agentcore:batchEvaluationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/batch-evaluation-id"
}
```
您可以在密钥策略条件中使用此加密上下文将 KMS 操作限制为特定的批量评估，如上面示例密钥策略中的`AllowCallerCryptoOps`语句所示。请注意，`AllowServicePrincipalAccess`它`aws:SourceArn`用于范围界定而不是加密上下文。
## 使用客户托管的 KMS 密钥开始批量评估
调用时指定`kmsKeyArn`参数`StartBatchEvaluation`：
**Example**
在 AgentCore CLI 中，使用`--kms-key`选项指定用于加密批量评估结果的单个 KMS 密钥 ARN。 AgentCore CLI 使用`--kms-key`标志，该标志不同于 AWS CLI 的`--kms-key-arn`标志和 boto3 参数`kmsKeyArn`。
```
agentcore run batch-evaluation \
-r MyAgent \
-e Builtin.Correctness \
--kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
```
aws bedrock-agentcore start-batch-evaluation \
--batch-evaluation-name "MyEncryptedBatchEval" \
--kms-key-arn "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
--evaluators '[{"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness"}]' \
--data-source-config '{
"cloudwatchLogs": {
"logGroupNames": ["/aws/bedrock-agentcore/sessions/my-agent"],
"serviceNames": ["my-agent.DEFAULT"],
"filterConfig": {
"timeRange": {
"startTime": "2025-01-01T00:00:00Z",
"endTime": "2025-01-02T00:00:00Z"
}
}
}
}'
```
```
import boto3
client = boto3.client('bedrock-agentcore')
response = client.start_batch_evaluation(
batchEvaluationName='MyEncryptedBatchEval',
kmsKeyArn='arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
evaluators=[{'evaluatorArn': 'arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness'}],
dataSourceConfig={
'cloudwatchLogs': {
'logGroupNames': ['/aws/bedrock-agentcore/sessions/my-agent'],
'serviceNames': ['my-agent.DEFAULT'],
'filterConfig': {
'timeRange': {
'startTime': '2025-01-01T00:00:00Z',
'endTime': '2025-01-02T00:00:00Z'
}
}
}
}
)
print(f"Batch Evaluation ID: {response['batchEvaluationId']}")
```
## 监控 KMS 使用情况以进行批量评估
批量评估 KMS 操作会出现以下 CloudTrail 事件名称：
+ `GenerateDataKey`— 将加密的批量评估输出写入 S3（数据源配置、会话元数据、评估结果）时。该`encryptionContext`字段包含`aws:bedrock-agentcore:batchEvaluationArn`。
+ `Decrypt`— 读取 S3 中的加密批处理评估输出时。
+ `DescribeKey`— 在创建批量评估时验证密钥时。
有关监控 KMS 使用情况的更多信息，请参阅密* AWS 钥管理服务开发人员指南 AWS CloudTrail*中的[使用记录 AWS KMS API 调用](https://docs.aws.amazon.com/kms/latest/developerguide/logging-using-cloudtrail.html)。
## 密钥不可用时的行为
如果您禁用或删除批量评估使用的客户托管 KMS 密钥：
+ **StartBatchEvaluation**— 使用验证失败`ValidationException`。
+ **GetBatchEvaluation**— 返回元数据（名称、状态、时间戳），但服务无法读取存储在加密 S3 对象中的评估结果。
+ **ListBatchEvaluations**— 之所以成功，是因为列出仅返回元数据且不需要 KMS 操作。
+ **StopBatchEvaluation**— 成功是因为停止不需要解密数据。
+ **DeleteBatchEvaluation**— 之所以成功，是因为删除 S3 对象不需要 KMS 解密。
要恢复访问权限，请重新启用密钥或更新密钥策略以授予所需权限。
上面描述的批量评估生命周期操作映射到 AgentCore CLI 命令。`stop`和`archive`命令通过`-i, --id `选项瞄准作业。该`view batch-evaluation`命令将 ID 作为位置参数：
+ **StartBatchEvaluation**—`agentcore run batch-evaluation --kms-key `（使用`-r/--runtime`和`-e/--evaluator`）
+ **GetBatchEvaluation** — `agentcore view batch-evaluation `
+ **ListBatchEvaluations**— `agentcore view batch-evaluation` 或 `agentcore batch-evaluations history`
+ **StopBatchEvaluation** — `agentcore stop batch-evaluation -i `
+ **DeleteBatchEvaluation** — `agentcore archive batch-evaluation -i `