View a markdown version of this page

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

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.

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

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 medianteDescribeKey.

  • 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. 111122223333Sustitú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 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 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 aStartRecommendation:

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 (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 conValidationException.

  • 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.