# 배치 평가 암호화
배치 평가`kmsKeyArn`에서를 지정하면 서비스는 KMS를 사용한 S3 서버 측 암호화(SSE-KMS)를 사용하여 S3에 저장된 모든 출력 아티팩트를 암호화합니다. 여기에는 데이터 소스 구성, 세션 메타데이터 및 평가 결과가 포함됩니다.
는 생성 시를 통해 지정`kmsKeyArn`됩니다`StartBatchEvaluation`.
## 작동 방식
배치 평가 암호화는 S3 SSE-KMS를 사용합니다. 서비스가 S3에서 배치 평가 출력을 쓰거나 읽으면 S3는 서비스를 대신하여 KMS를 호출하여 데이터를 암호화하거나 해독합니다. 서비스 보안 주체(`bedrock-agentcore.amazonaws.com`)는 키 정책에 KMS 권한이 있어야 합니다.
API 시간에 서비스는 직접 실행 검사(Forward Access Sessions)를 사용하여 호출자에게 KMS 권한이 있는지 확인합니다. 이렇게 하면 배치 평가 워크플로 중에 비동기적으로 실패하지 않고 권한 문제를 즉시 포착할 수 있습니다.
또한 서비스는 자체 자격 증명`kms:GenerateDataKey`으로를 수행할 수 있는지 검증하여 키 정책이 서비스 보안 주체에게 암호화된 출력을 작성하는 데 필요한 권한을 부여하는지 확인합니다.
AgentCore Evaluations는 대칭 암호화 KMS 키만 지원합니다. KMS 키는 배치 평가와 동일한 AWS 리전에 있어야 합니다.
### 고객 관리형 KMS 키를 사용하도록 권한 구성
다음 키 정책은 배치 평가 암호화에 필요한 최소 권한을 제공합니다. 이 정책에는 3개의 문이 있습니다.
+ **AllowCallerAccess** - IAM 사용자 또는 역할이를 통해 키를 검증할 수 있도록 허용합니다`DescribeKey`.
+ **AllowCallerCryptoOps** - IAM 사용자 또는 역할이 암호화 컨텍스트에 따라 범위를 지정하여 암호화 및 복호화할 수 있습니다.
+ **AllowServicePrincipalAccess** - AgentCore 서비스 보안 주체가 소스 계정 및 소스 ARN에 따라 범위가 지정된 S3의 배치 평가 데이터를 암호화하고 해독할 수 있도록 허용합니다.
```
{
"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** - `aws:bedrock-agentcore:batchEvaluationArn` 암호화 컨텍스트에 따라 범위가 지정된 IAM 역할 `kms:GenerateDataKey` 및 `kms:Decrypt` 권한을 부여합니다. {{111122223333}}, {{MyBatchEvaluationRole}} 및 {{us-east-1}}을 값으로 바꿉니다. 계정의 모든 배치 평가에 대한 액세스를 허용하려면 `StringLike`와 함께 와일드카드를 사용합니다`arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*`.
+ **AllowServicePrincipalAccess** - AgentCore 서비스 보안 주체 `kms:GenerateDataKey` 및 S3에서 배치 평가 데이터를 암호화하고 해독할 수 있는 `kms:Decrypt` 권한을 부여합니다. 혼동된 대리자 공격을 방지하기 위해 소스 계정 및 소스 ARN(`aws:SourceArn`)별로 범위가 지정됩니다. {{us-east-1}} 및 {{111122223333}}을 리전 및 계정 ID로 바꿉니다.
### 고객 관리형 KMS 키에 대한 액세스 범위 축소
암호화 컨텍스트를 사용하여 고객 관리형 키에 대한 액세스 범위를 좁힐 수 있습니다. AgentCore 평가에는 모든 KMS 작업에 다음과 같은 암호화 컨텍스트가 포함됩니다.
```
{
"aws:bedrock-agentcore:batchEvaluationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/batch-evaluation-id"
}
```
위의 예제 키 정책의 `AllowCallerCryptoOps` 문과 같이 키 정책 조건에서이 암호화 컨텍스트를 사용하여 KMS 작업을 특정 배치 평가로 제한할 수 있습니다. 는 암호화 컨텍스트가 아닌 범위 지정`aws:SourceArn`에를 `AllowServicePrincipalAccess` 사용합니다.
## 고객 관리형 KMS 키를 사용하여 배치 평가 시작
를 호출할 때 `kmsKeyArn` 파라미터를 지정합니다`StartBatchEvaluation`.
**Example**
AgentCore CLI에서 `--kms-key` 옵션을 사용하여 배치 평가 결과를 암호화하기 위한 단일 KMS 키 ARN을 지정합니다. AgentCore CLI는 CLI의 `--kms-key` 플래그 및 boto3 `kmsKeyArn` 파라미터와 다른 AWS `--kms-key-arn` 플래그를 사용합니다.
```
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 Key Management Service 개발자 안내서*의 [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 `