# Criptografia de avaliação em lote
Quando você especifica uma avaliação `kmsKeyArn` em lote, o serviço criptografa todos os artefatos de saída armazenados no S3 usando a criptografia do lado do servidor do S3 com KMS (). SSE-KMS Isso inclui a configuração da fonte de dados, os metadados da sessão e os resultados da avaliação.
O `kmsKeyArn` é especificado no momento da criação via`StartBatchEvaluation`.
## Como funciona
A criptografia de avaliação em lote usa S3 SSE-KMS. Quando o serviço grava ou lê a saída de avaliação em lote no S3, o S3 chama o KMS em nome do serviço para criptografar ou descriptografar os dados. O responsável pelo serviço (`bedrock-agentcore.amazonaws.com`) deve ter permissões KMS na política de chaves.
No momento da API, o serviço valida se o chamador tem permissões KMS usando uma verificação de execução a seco (sessões de acesso direto). Isso detecta problemas de permissão imediatamente, em vez de falhar de forma assíncrona durante o fluxo de trabalho de avaliação em lote.
O serviço também valida que pode funcionar `kms:GenerateDataKey` com suas próprias credenciais para garantir que a política de chaves conceda ao responsável pelo serviço as permissões necessárias para gravar a saída criptografada.
AgentCore As avaliações oferecem suporte somente a chaves KMS de criptografia simétrica. A chave KMS deve estar na mesma AWS região da avaliação do lote.
### Configurando permissões para usar uma chave KMS gerenciada pelo cliente
A política de chaves a seguir fornece as permissões mínimas necessárias para a criptografia de avaliação em lote. A política tem três instruções:
+ **AllowCallerAccess**— Permite que o usuário ou a função do IAM valide a chave por meio `DescribeKey` de.
+ **AllowCallerCryptoOps**— Permite que o usuário ou a função do IAM criptografe e descriptografe, de acordo com o contexto de criptografia.
+ **AllowServicePrincipalAccess**— Permite que o responsável pelo AgentCore serviço criptografe e descriptografe dados de avaliação em lote no S3, com o escopo da conta de origem e do ARN de origem.
```
{
"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/*"
}
}
}
]
}
```
A política contém as seguintes declarações:
+ **AllowCallerAccess**— Concede `kms:DescribeKey` permissão à função do IAM para a validação da chave no momento da criação da avaliação em lote. {{111122223333}}Substitua pelo ID da sua conta e {{MyBatchEvaluationRole}} pela função ou usuário do IAM que inicia as avaliações em lote.
+ **AllowCallerCryptoOps**— Concede a função `kms:GenerateDataKey` e `kms:Decrypt` as permissões do IAM, de acordo com o contexto de `aws:bedrock-agentcore:batchEvaluationArn` criptografia. Substitua {{111122223333}}{{MyBatchEvaluationRole}},, e {{us-east-1}} por seus valores. Para permitir o acesso a todas as avaliações em lote em sua conta, use um curinga com`StringLike`:. `arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*`
+ **AllowServicePrincipalAccess**— Concede ao diretor do AgentCore serviço `kms:GenerateDataKey` e `kms:Decrypt` permissões para criptografar e descriptografar dados de avaliação em lote no S3. Definido por conta de origem e ARN de origem `aws:SourceArn` () para evitar ataques confusos de deputados. Substitua {{us-east-1}} e {{111122223333}} por sua região e ID da conta.
### Definindo o escopo do acesso à chave KMS gerenciada pelo cliente
Você pode usar o contexto de criptografia para reduzir o acesso à chave gerenciada pelo cliente. AgentCore As avaliações incluem o seguinte contexto de criptografia em todas as operações do KMS:
```
{
"aws:bedrock-agentcore:batchEvaluationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/batch-evaluation-id"
}
```
Você pode usar esse contexto de criptografia nas principais condições de política para restringir as operações do KMS a avaliações específicas de lotes, conforme mostrado na `AllowCallerCryptoOps` declaração no exemplo de política de chaves acima. Observe que `AllowServicePrincipalAccess` usa `aws:SourceArn` para escopo em vez de contexto de criptografia.
## Iniciando uma avaliação em lote com uma chave KMS gerenciada pelo cliente
Especifique o `kmsKeyArn` parâmetro ao chamar`StartBatchEvaluation`:
**Example**
Com a AgentCore CLI, use a `--kms-key` opção para especificar um único ARN de chave KMS para criptografar os resultados da avaliação em lote. A AgentCore CLI usa a `--kms-key` bandeira, que difere da bandeira da AWS CLI e do parâmetro `--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']}")
```
## Monitorando o uso do KMS para avaliações em lote
Os seguintes nomes de CloudTrail eventos aparecem para operações KMS de avaliação em lote:
+ `GenerateDataKey`— Ao gravar uma saída de avaliação em lote criptografada no S3 (configuração da fonte de dados, metadados da sessão, resultados da avaliação). O `encryptionContext` campo contém`aws:bedrock-agentcore:batchEvaluationArn`.
+ `Decrypt`— Ao ler a saída de avaliação de lote criptografada do S3.
+ `DescribeKey`— Ao validar a chave no momento da criação da avaliação do lote.
Para obter mais informações sobre o monitoramento do uso do KMS, consulte [Registrar chamadas da API AWS KMS AWS CloudTrail](https://docs.aws.amazon.com/kms/latest/developerguide/logging-using-cloudtrail.html) no Guia do *desenvolvedor do AWS Key Management Service*.
## Comportamento quando uma chave fica indisponível
Se você desativar ou excluir a chave KMS gerenciada pelo cliente usada por uma avaliação em lote:
+ **StartBatchEvaluation**— Falha na validação com`ValidationException`.
+ **GetBatchEvaluation**— Retorna metadados (nome, status, registros de data e hora), mas os resultados da avaliação armazenados em objetos criptografados do S3 não podem ser lidos pelo serviço.
+ **ListBatchEvaluations**— É bem-sucedido porque a listagem retorna somente metadados e não exige operações KMS.
+ **StopBatchEvaluation**— É bem-sucedido porque a interrupção não exige a descriptografia de dados.
+ **DeleteBatchEvaluation**— É bem-sucedido porque a exclusão de objetos do S3 não exige a descriptografia do KMS.
Para restaurar o acesso, reative a chave ou atualize a política de chaves para conceder as permissões necessárias.
As operações do ciclo de vida da avaliação em lote descritas acima são mapeadas para os comandos da CLI AgentCore . Os `archive` comandos `stop` e direcionam o trabalho por meio da `-i, --id ` opção. O `view batch-evaluation` comando usa o ID como argumento posicional:
+ **StartBatchEvaluation**— `agentcore run batch-evaluation --kms-key ` (uso `-r/--runtime` e`-e/--evaluator`)
+ **GetBatchEvaluation** — `agentcore view batch-evaluation `
+ **ListBatchEvaluations**— `agentcore view batch-evaluation` ou `agentcore batch-evaluations history`
+ **StopBatchEvaluation** — `agentcore stop batch-evaluation -i `
+ **DeleteBatchEvaluation** — `agentcore archive batch-evaluation -i `