View a markdown version of this page

Cifrado de recomendaciones - Base amazónica AgentCore
FuncionamientoComenzar una recomendación con una clave de KMS administrada por el clienteSupervisar el uso de KMS para obtener recomendacionesComportamiento cuando una clave deja de estar disponible

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Cifrado de recomendaciones

Cuando especificas 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 propia AWS .

kmsKeyArnSe especifica en el momento de la creación medianteStartRecommendation.

Funcionamiento

El cifrado de recomendaciones utiliza el SDK AWS de 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 gestionada 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 en seco (sesiones de acceso directo). Esto detecta los problemas de permisos de forma inmediata, en lugar de fallar de forma asincrónica durante el flujo de trabajo de recomendaciones.

Cuando el flujo de trabajo de recomendaciones se ejecuta de forma asincrónica, el servicio principal (bedrock-agentcore.amazonaws.com) descifra la configuración y cifra el resultado. El principal de 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 de KMS debe estar en la misma AWS región que la recomendación.

Configurar los permisos para usar una clave de KMS administrada por el cliente

La siguiente política de claves proporciona los permisos mínimos necesarios para el cifrado de recomendaciones. La política tiene tres instrucciones:

  • AllowCallerAccess— Permite al usuario o rol de IAM validar la clave medianteDescribeKey.

  • AllowCallerCryptoOps— Permite al usuario o rol de IAM cifrar y descifrar según el contexto de cifrado.

  • AllowServicePrincipalAccess— Permite al principal del AgentCore servicio cifrar y descifrar los datos de recomendación durante el flujo de trabajo de recomendaciones asincrónico, desglosado por cuenta de origen y 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— Concede al rol de IAM kms:DescribeKey permiso para validar la clave en el momento de crear la recomendación. 111122223333Sustitúyelo por el identificador de tu 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 111122223333MyRecommendationRole, y por us-east-1 sus valores. Para permitir el acceso a todas las recomendaciones de tu cuenta, usa un comodín conStringLike: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 recomendación durante el flujo de trabajo asincrónico. Se divide en función de la cuenta de origen y el ARN de origen () aws:SourceArn para evitar ataques confusos de los subalternos. Sustituye us-east-1 y 111122223333 por tu región y tu ID de cuenta.

Disminuir el acceso a la clave de KMS administrada por el cliente

Puede usar el contexto de cifrado para restringir 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 clave de la política para restringir las operaciones de KMS a recomendaciones específicas, como se muestra en la AllowCallerCryptoOps declaración del ejemplo de política de claves anterior. Tenga en cuenta que se AllowServicePrincipalAccess usa aws:SourceArn para determinar el alcance en lugar de para el contexto de cifrado.

Comenzar una recomendación con una clave de KMS administrada por el cliente

Especifique el kmsKeyArn parámetro al llamarStartRecommendation:

ejemplo
AgentCore CLI
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 CLI
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"}]
      }
    }
  }'
Python (Boto3)
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 (al cifrar la configuración) y al finalizar el flujo de trabajo de la recomendación (al cifrar el 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 que se utiliza en una recomendación:

  • StartRecommendation— No se realiza la validación conValidationException.

  • GetRecommendation— No ValidationException indica que la clave de KMS está deshabilitada o eliminada.

  • ListRecommendations— Se realiza correctamente porque la lista 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.