# Criptografia de recomendação
Quando você especifica um `kmsKeyArn` em uma recomendação, o serviço criptografa a **configuração da recomendação** e o **resultado da recomendação** usando criptografia de envelope com o SDK de AWS criptografia. Todos os outros metadados de recomendação (nome, tipo, status) permanecem criptografados com a chave AWS própria.
O `kmsKeyArn` é especificado no momento da criação por meio de`StartRecommendation`.
## Como funciona
A criptografia de recomendação usa o SDK de AWS criptografia para criptografia de envelopes. Quando o serviço grava ou lê dados de recomendação, ele chama o KMS para gerar ou descriptografar chaves de dados. O resultado da recomendação também é armazenado no S3 SSE-KMS usando a mesma chave gerenciada pelo cliente.
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 recomendação.
Quando o fluxo de trabalho de recomendação é executado de forma assíncrona, o principal do serviço (`bedrock-agentcore.amazonaws.com`) descriptografa a configuração e criptografa o resultado. O responsável pelo serviço deve ter uma `kms:GenerateDataKey` `kms:Decrypt` permissão na política de chaves.
AgentCore as otimizações oferecem suporte somente a chaves KMS de criptografia simétrica. A chave KMS deve estar na mesma AWS região da recomendação.
### 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 recomendada. 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 recomendação durante o fluxo de trabalho de recomendação assíncrona, com escopo definido pela conta de origem e pelo ARN de origem.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowCallerAccess",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/MyRecommendationRole"
},
"Action": "kms:DescribeKey",
"Resource": "*"
},
{
"Sid": "AllowCallerCryptoOps",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/MyRecommendationRole"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "*",
"Condition": {
"StringLike": {
"kms:EncryptionContext:aws:bedrock-agentcore:recommendationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/*"
}
}
},
{
"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:recommendation/*"
}
}
}
]
}
```
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 recomendação. {{111122223333}}Substitua pelo ID da sua conta e {{MyRecommendationRole}} pela função ou usuário do IAM que inicia as recomendações.
+ **AllowCallerCryptoOps**— Concede a função `kms:GenerateDataKey` e `kms:Decrypt` as permissões do IAM, de acordo com o contexto de `aws:bedrock-agentcore:recommendationArn` criptografia. Substitua {{111122223333}}{{MyRecommendationRole}},, e {{us-east-1}} por seus valores. Para permitir o acesso a todas as recomendações em sua conta, use um curinga com`StringLike`:`arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/*`.
+ **AllowServicePrincipalAccess**— concede ao diretor do AgentCore serviço `kms:GenerateDataKey` e `kms:Decrypt` permissões para criptografar e descriptografar dados de recomendação durante o fluxo de trabalho assíncrono. 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 otimizações incluem o seguinte contexto de criptografia em todas as operações do KMS:
```
{
"aws:bedrock-agentcore:recommendationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/recommendation-id"
}
```
Você pode usar esse contexto de criptografia nas principais condições de política para restringir as operações do KMS a recomendações específicas, 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 recomendação com uma chave KMS gerenciada pelo cliente
Especifique o `kmsKeyArn` parâmetro ao chamar`StartRecommendation`:
**Example**
```
agentcore run recommendation \
-t system-prompt \
-r MyAgent \
-e Builtin.Correctness \
--inline "You are a helpful assistant" \
--kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
```
aws bedrock-agentcore start-recommendation \
--name "MyEncryptedRecommendation" \
--type SYSTEM_PROMPT_RECOMMENDATION \
--kms-key-arn "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
--recommendation-config '{
"systemPromptRecommendationConfig": {
"systemPrompt": {
"text": "You are a helpful assistant."
},
"agentTraces": {
"cloudwatchLogs": {
"logGroupArns": ["arn:aws:logs:us-east-1:111122223333:log-group:/aws/bedrock-agentcore/sessions/my-agent"],
"serviceNames": ["my-agent.DEFAULT"],
"startTime": "2025-01-01T00:00:00Z",
"endTime": "2025-01-02T00:00:00Z"
}
},
"evaluationConfig": {
"evaluators": [{"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness"}]
}
}
}'
```
```
import boto3
client = boto3.client('bedrock-agentcore')
response = client.start_recommendation(
name='MyEncryptedRecommendation',
type='SYSTEM_PROMPT_RECOMMENDATION',
kmsKeyArn='arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
recommendationConfig={
'systemPromptRecommendationConfig': {
'systemPrompt': {
'text': 'You are a helpful assistant.'
},
'agentTraces': {
'cloudwatchLogs': {
'logGroupArns': ['arn:aws:logs:us-east-1:111122223333:log-group:/aws/bedrock-agentcore/sessions/my-agent'],
'serviceNames': ['my-agent.DEFAULT'],
'startTime': '2025-01-01T00:00:00Z',
'endTime': '2025-01-02T00:00:00Z'
}
},
'evaluationConfig': {
'evaluators': [{'evaluatorArn': 'arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness'}]
}
}
}
)
print(f"Recommendation ID: {response['recommendationId']}")
```
## Monitorando o uso do KMS para recomendações
Os seguintes nomes de CloudTrail eventos aparecem para operações de recomendação do KMS:
+ `GenerateDataKey`— Ao iniciar uma recomendação (configuração de criptografia) e quando o fluxo de trabalho de recomendação for concluído (criptografando o resultado). O `encryptionContext` campo contém`aws:bedrock-agentcore:recommendationArn`.
+ `Decrypt`— Quando o fluxo de trabalho de recomendação processa a configuração ou ao recuperar os resultados da recomendação.
+ `DescribeKey`— Ao validar a chave no momento da criação da recomendação.
## Comportamento quando uma chave fica indisponível
Se você desativar ou excluir a chave KMS gerenciada pelo cliente usada por uma recomendação:
+ **StartRecommendation**— Falha na validação com`ValidationException`.
+ **GetRecommendation**— Falha ao `ValidationException` indicar que a chave KMS está desativada ou excluída.
+ **ListRecommendations**— É bem-sucedido porque a listagem retorna somente metadados e não exige operações KMS.
+ **DeleteRecommendation**— É bem-sucedido porque a exclusão não exige a descriptografia dos dados de recomendação.