# Criptaggio delle raccomandazioni
Quando si specifica un no `kmsKeyArn` su una raccomandazione, il servizio crittografa la **configurazione del consiglio** e il **risultato del consiglio** utilizzando la crittografia a busta con Encryption AWS SDK. Tutti gli altri metadati delle raccomandazioni (nome, tipo, stato) rimangono crittografati con la chiave proprietaria. AWS
`kmsKeyArn`Viene specificato al momento della creazione tramite`StartRecommendation`.
## Come funziona
La crittografia delle raccomandazioni utilizza AWS Encryption SDK per la crittografia delle buste. Quando il servizio scrive o legge i dati delle raccomandazioni, chiama KMS per generare o decrittografare le chiavi di dati. Il risultato della raccomandazione viene inoltre archiviato in S3 SSE-KMS utilizzando la stessa chiave gestita dal cliente.
Al momento dell'API, il servizio verifica che il chiamante disponga delle autorizzazioni KMS utilizzando un controllo a secco (Forward Access Sessions). In questo modo vengono rilevati immediatamente i problemi di autorizzazione anziché fallire in modo asincrono durante il flusso di lavoro di raccomandazione.
Quando il flusso di lavoro di raccomandazione viene eseguito in modo asincrono, il service principal (`bedrock-agentcore.amazonaws.com`) decrittografa la configurazione e crittografa il risultato. Il responsabile del servizio deve disporre `kms:GenerateDataKey` dell'autorizzazione nella politica chiave. `kms:Decrypt`
AgentCore le ottimizzazioni supportano solo chiavi KMS di crittografia simmetrica. La chiave KMS deve trovarsi nella stessa AWS regione della raccomandazione.
### Configurazione delle autorizzazioni per l'utilizzo di una chiave KMS gestita dal cliente
La seguente politica chiave fornisce le autorizzazioni minime richieste per la crittografia delle raccomandazioni. La policy ha tre istruzioni:
+ **AllowCallerAccess**— Consente all'utente o al ruolo IAM di convalidare la chiave tramite. `DescribeKey`
+ **AllowCallerCryptoOps**— Consente all'utente o al ruolo IAM di crittografare e decrittografare, in base al contesto di crittografia.
+ **AllowServicePrincipalAccess**— Consente al responsabile del AgentCore servizio di crittografare e decrittografare i dati delle raccomandazioni durante il flusso di lavoro di raccomandazione asincrono, con ambito per account di origine e ARN di origine.
```
{
"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/*"
}
}
}
]
}
```
La politica contiene le seguenti dichiarazioni:
+ **AllowCallerAccess**— Concede al ruolo IAM l'`kms:DescribeKey`autorizzazione per la convalida delle chiavi al momento della creazione della raccomandazione. {{111122223333}}Sostituiscilo con l'ID del tuo account e {{MyRecommendationRole}} con il ruolo o l'utente IAM che avvia i consigli.
+ **AllowCallerCryptoOps**— Concede il ruolo `kms:GenerateDataKey` e le `kms:Decrypt` autorizzazioni IAM, in base al `aws:bedrock-agentcore:recommendationArn` contesto di crittografia. Sostituisci {{111122223333}} e {{us-east-1}} con {{MyRecommendationRole}} i tuoi valori. Per consentire l'accesso a tutti i consigli nel tuo account, usa una jolly con`StringLike`:`arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/*`.
+ **AllowServicePrincipalAccess**- Concede il principale AgentCore servizio e le `kms:Decrypt` autorizzazioni per crittografare `kms:GenerateDataKey` e decrittografare i dati delle raccomandazioni durante il flusso di lavoro asincrono. Elaborato in base all'account di origine e all'ARN di origine `aws:SourceArn` () per evitare confusi attacchi secondari. Sostituisci {{us-east-1}} e {{111122223333}} con la tua regione e l'ID dell'account.
### Definizione dell'accesso alla chiave KMS gestita dal cliente
È possibile utilizzare il contesto di crittografia per limitare l'accesso alla chiave gestita dal cliente. AgentCore le ottimizzazioni includono il seguente contesto di crittografia in tutte le operazioni KMS:
```
{
"aws:bedrock-agentcore:recommendationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/recommendation-id"
}
```
È possibile utilizzare questo contesto di crittografia nelle condizioni politiche chiave per limitare le operazioni KMS a raccomandazioni specifiche, come illustrato nella `AllowCallerCryptoOps` dichiarazione contenuta nella politica chiave di esempio riportata sopra. Nota che `AllowServicePrincipalAccess` viene utilizzato `aws:SourceArn` per l'ambito piuttosto che per il contesto di crittografia.
## Avvio di una raccomandazione con una chiave KMS gestita dal cliente
Specificare il `kmsKeyArn` parametro quando si chiama`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']}")
```
## Monitoraggio dell'utilizzo di KMS per suggerimenti
I seguenti nomi di CloudTrail eventi vengono visualizzati per le operazioni KMS di raccomandazione:
+ `GenerateDataKey`— Quando si avvia una raccomandazione (configurazione di crittografia) e quando il flusso di lavoro di raccomandazione viene completato (crittografia del risultato). Il `encryptionContext` campo contiene. `aws:bedrock-agentcore:recommendationArn`
+ `Decrypt`— Quando il flusso di lavoro di raccomandazione elabora la configurazione o quando recupera i risultati dei consigli.
+ `DescribeKey`— Durante la convalida della chiave al momento della creazione del consiglio.
## Comportamento quando una chiave diventa non disponibile
Se disabiliti o elimini la chiave KMS gestita dal cliente utilizzata in un consiglio:
+ **StartRecommendation**— Non riesce a convalidare con. `ValidationException`
+ **GetRecommendation**— Non riesce a `ValidationException` indicare che la chiave KMS è disabilitata o eliminata.
+ **ListRecommendations**— Ha successo perché l'elenco restituisce solo i metadati e non richiede operazioni KMS.
+ **DeleteRecommendation**— Ha esito positivo perché l'eliminazione non richiede la decrittografia dei dati delle raccomandazioni.