# Cifrado de recomendaciones
Al especificar una recomendación, `kmsKeyArn` el servicio cifra la **configuración de la recomendación y el **resultado** de la recomendación** mediante el cifrado de sobres con el SDK de AWS cifrado. Todos los demás metadatos de recomendación (nombre, tipo, estado) permanecen cifrados con la clave AWS propia.
`kmsKeyArn`Se especifica en el momento de la creación mediante`StartRecommendation`.
## Funcionamiento
El cifrado recomendado utiliza el SDK de AWS cifrado para el cifrado de sobres. Cuando el servicio escribe o lee los datos de recomendación, llama a KMS para generar o descifrar las claves de datos. El resultado de la recomendación también se almacena en S3 SSE-KMS con la misma clave administrada por el cliente.
En el momento de la API, el servicio valida que la persona que llama tiene permisos de KMS mediante una comprobación preliminar (sesiones de acceso directo). De este modo, se detectan los problemas de permisos de forma inmediata, en lugar de que se produzcan errores de forma asíncrona durante el flujo de trabajo de recomendación.
Cuando el flujo de trabajo de recomendaciones se ejecuta de forma asíncrona, el principal de servicio (`bedrock-agentcore.amazonaws.com`) descifra la configuración y cifra el resultado. El director del servicio debe tener un `kms:Decrypt` permiso en la política `kms:GenerateDataKey` de claves.
AgentCore las optimizaciones solo admiten claves KMS de cifrado simétrico. La clave KMS debe estar en la misma AWS región que la recomendación.
### Configurar los permisos para usar una clave KMS administrada por el cliente
La siguiente política de claves proporciona los permisos mínimos necesarios para el cifrado recomendado. La política tiene tres instrucciones:
+ **AllowCallerAccess**— Permite al usuario o rol de IAM validar la clave mediante`DescribeKey`.
+ **AllowCallerCryptoOps**— Permite al usuario o rol de IAM cifrar y descifrar, según el contexto de cifrado.
+ **AllowServicePrincipalAccess**— Permite al director del AgentCore servicio cifrar y descifrar los datos de recomendación durante el flujo de trabajo de recomendación asíncrono, según el alcance de la cuenta de origen y el ARN de origen.
```
{
"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 política contiene las siguientes declaraciones:
+ **AllowCallerAccess**— Otorga al rol de IAM `kms:DescribeKey` permiso para validar la clave en el momento de crear la recomendación. {{111122223333}}Sustitúyalo por tu ID de cuenta y {{MyRecommendationRole}} por el rol o usuario de IAM que inicia las recomendaciones.
+ **AllowCallerCryptoOps**— Otorga la función `kms:GenerateDataKey` y `kms:Decrypt` los permisos de IAM, según el `aws:bedrock-agentcore:recommendationArn` contexto de cifrado. Sustituya {{111122223333}} {{MyRecommendationRole}} y por sus {{us-east-1}} valores. Para permitir el acceso a todas las recomendaciones de tu cuenta, usa un comodín con`StringLike`:`arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/*`.
+ **AllowServicePrincipalAccess**— Otorga al director del AgentCore servicio `kms:GenerateDataKey` y `kms:Decrypt` los permisos para cifrar y descifrar los datos de las recomendaciones durante el flujo de trabajo asincrónico. Analizado por cuenta de origen y ARN de origen `aws:SourceArn` () para evitar confusos ataques de diputados. Sustituya {{us-east-1}} y {{111122223333}} por su región e ID de cuenta.
### Limitar el acceso a la clave KMS administrada por el cliente
Puede usar el contexto de cifrado para limitar el acceso a la clave administrada por el cliente. AgentCore las optimizaciones incluyen el siguiente contexto de cifrado en todas las operaciones de KMS:
```
{
"aws:bedrock-agentcore:recommendationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/recommendation-id"
}
```
Puede usar este contexto de cifrado en las condiciones de la política clave para restringir las operaciones de KMS a recomendaciones específicas, como se muestra en la `AllowCallerCryptoOps` declaración del ejemplo de política clave anterior. Tenga en cuenta que se `AllowServicePrincipalAccess` utiliza `aws:SourceArn` para el ámbito más que para el contexto de cifrado.
## Comenzar una recomendación con una clave KMS administrada por el cliente
Especifique el `kmsKeyArn` parámetro al llamar a`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']}")
```
## Supervisar el uso de KMS para obtener recomendaciones
Aparecen los siguientes nombres de CloudTrail eventos para las operaciones de KMS recomendadas:
+ `GenerateDataKey`— Al iniciar una recomendación (configuración de cifrado) y cuando finaliza el flujo de trabajo de recomendación (cifrado del resultado). El `encryptionContext` campo contiene. `aws:bedrock-agentcore:recommendationArn`
+ `Decrypt`— Cuando el flujo de trabajo de recomendaciones procesa la configuración o cuando recupera los resultados de las recomendaciones.
+ `DescribeKey`— Al validar la clave en el momento de crear la recomendación.
## Comportamiento cuando una clave deja de estar disponible
Si inhabilitas o eliminas la clave de KMS administrada por el cliente utilizada por una recomendación:
+ **StartRecommendation**— No se realiza la validación con`ValidationException`.
+ **GetRecommendation**— No se puede `ValidationException` indicar que la clave KMS está desactivada o eliminada.
+ **ListRecommendations**— Se realiza correctamente porque el listado solo devuelve metadatos y no requiere operaciones de KMS.
+ **DeleteRecommendation**— Se realiza correctamente porque la eliminación no requiere descifrar los datos de recomendación.