# Chiffrement des recommandations
Lorsque vous spécifiez une recommandation, `kmsKeyArn` le service chiffre la **configuration de la recommandation et le **résultat** de la recommandation** à l'aide du chiffrement d'enveloppe avec le SDK de AWS chiffrement. Toutes les autres métadonnées de recommandation (nom, type, statut) restent cryptées avec la clé AWS détenue.
Le `kmsKeyArn` est spécifié au moment de la création via`StartRecommendation`.
## Comment ça marche
Le chiffrement des recommandations utilise le SDK AWS de chiffrement pour le chiffrement des enveloppes. Lorsque le service écrit ou lit des données de recommandation, il appelle KMS pour générer ou déchiffrer des clés de données. Le résultat de la recommandation est également stocké dans S3 en SSE-KMS utilisant la même clé gérée par le client.
Au moment de l'API, le service vérifie que l'appelant dispose des autorisations KMS à l'aide d'une vérification à sec (Forward Access Sessions). Cela permet de détecter immédiatement les problèmes d'autorisation plutôt que d'échouer de manière asynchrone pendant le flux de travail de recommandation.
Lorsque le flux de travail de recommandation s'exécute de manière asynchrone, le principal de service (`bedrock-agentcore.amazonaws.com`) déchiffre la configuration et chiffre le résultat. Le directeur du service doit disposer `kms:GenerateDataKey` d'une `kms:Decrypt` autorisation dans la politique clé.
AgentCore les optimisations ne prennent en charge que les clés KMS de chiffrement symétriques. La clé KMS doit se trouver dans la même AWS région que la recommandation.
### Configuration des autorisations pour utiliser une clé KMS gérée par le client
La politique clé suivante fournit les autorisations minimales requises pour le chiffrement des recommandations. La stratégie comporte trois déclarations :
+ **AllowCallerAccess**— Permet à l'utilisateur ou au rôle IAM de valider la clé via`DescribeKey`.
+ **AllowCallerCryptoOps**— Permet à l'utilisateur ou au rôle IAM de chiffrer et de déchiffrer, en fonction du contexte de chiffrement.
+ **AllowServicePrincipalAccess**— Permet au principal du AgentCore service de chiffrer et de déchiffrer les données de recommandation pendant le flux de travail de recommandation asynchrone, défini par compte source et ARN source.
```
{
"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 politique contient les déclarations suivantes :
+ **AllowCallerAccess**— Accorde au rôle IAM l'`kms:DescribeKey`autorisation de valider les clés au moment de la création de la recommandation. {{111122223333}}Remplacez-le par votre identifiant de compte et {{MyRecommendationRole}} par le rôle ou l'utilisateur IAM qui lance les recommandations.
+ **AllowCallerCryptoOps**— Accorde le rôle `kms:GenerateDataKey` et les `kms:Decrypt` autorisations IAM, dans le cadre du contexte de `aws:bedrock-agentcore:recommendationArn` chiffrement. Remplacez {{111122223333}}{{MyRecommendationRole}}, et {{us-east-1}} par vos valeurs. Pour autoriser l'accès à toutes les recommandations de votre compte, utilisez un caractère générique avec `StringLike` :`arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/*`.
+ **AllowServicePrincipalAccess**— Accorde le principal du AgentCore service `kms:GenerateDataKey` et `kms:Decrypt` les autorisations nécessaires pour chiffrer et déchiffrer les données de recommandation pendant le flux de travail asynchrone. Délimité par compte source et ARN source (`aws:SourceArn`) pour éviter les attaques secondaires confuses. Remplacez {{us-east-1}} et {{111122223333}} par votre région et votre numéro de compte.
### Délimitation de l'accès à la clé KMS gérée par le client
Vous pouvez utiliser le contexte de chiffrement pour limiter l'accès à la clé gérée par le client. AgentCore les optimisations incluent le contexte de chiffrement suivant dans toutes les opérations KMS :
```
{
"aws:bedrock-agentcore:recommendationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/recommendation-id"
}
```
Vous pouvez utiliser ce contexte de chiffrement dans des conditions de politique clés pour limiter les opérations KMS à des recommandations spécifiques, comme indiqué dans la `AllowCallerCryptoOps` déclaration figurant dans l'exemple de politique clé ci-dessus. Notez que cela est `AllowServicePrincipalAccess` utilisé `aws:SourceArn` à des fins de cadrage plutôt que de contexte de chiffrement.
## Commencer une recommandation avec une clé KMS gérée par le client
Spécifiez le `kmsKeyArn` paramètre lors de l'appel `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']}")
```
## Surveillance de l'utilisation du KMS pour obtenir des recommandations
Les noms CloudTrail d'événements suivants apparaissent pour les opérations KMS recommandées :
+ `GenerateDataKey`— Lors du lancement d'une recommandation (configuration de chiffrement) et lorsque le flux de travail de recommandation est terminé (chiffrement du résultat). Le `encryptionContext` champ contient`aws:bedrock-agentcore:recommendationArn`.
+ `Decrypt`— Lorsque le flux de travail de recommandation traite la configuration ou lorsqu'il récupère les résultats des recommandations.
+ `DescribeKey`— Lors de la validation de la clé au moment de la création de la recommandation.
## Comportement lorsqu'une clé n'est plus disponible
Si vous désactivez ou supprimez la clé KMS gérée par le client utilisée par une recommandation :
+ **StartRecommendation**— Échoue lors de la validation avec`ValidationException`.
+ **GetRecommendation**— Impossible d'`ValidationException`indiquer que la clé KMS est désactivée ou supprimée.
+ **ListRecommendations**— Succès car le listage renvoie uniquement des métadonnées et ne nécessite aucune opération KMS.
+ **DeleteRecommendation**— Succès car la suppression ne nécessite pas le déchiffrement des données de recommandation.