Criptografia de recomendação

Quando você especifica um kmsKeyArn em uma recomendação, o serviço criptografa a configuração da recomendação e o resultado da recomendação usando criptografia de envelope com o SDK de AWS criptografia. Todos os outros metadados de recomendação (nome, tipo, status) permanecem criptografados com a chave AWS própria.

O kmsKeyArn é especificado no momento da criação por meio deStartRecommendation.

Como funciona

A criptografia de recomendação usa o SDK de AWS criptografia para criptografia de envelopes. Quando o serviço grava ou lê dados de recomendação, ele chama o KMS para gerar ou descriptografar chaves de dados. O resultado da recomendação também é armazenado no S3 SSE-KMS usando a mesma chave gerenciada pelo cliente.

No momento da API, o serviço valida se o chamador tem permissões KMS usando uma verificação de execução a seco (sessões de acesso direto). Isso detecta problemas de permissão imediatamente, em vez de falhar de forma assíncrona durante o fluxo de trabalho de recomendação.

Quando o fluxo de trabalho de recomendação é executado de forma assíncrona, o principal do serviço (bedrock-agentcore.amazonaws.com) descriptografa a configuração e criptografa o resultado. O responsável pelo serviço deve ter uma kms:GenerateDataKey kms:Decrypt permissão na política de chaves.

AgentCore as otimizações oferecem suporte somente a chaves KMS de criptografia simétrica. A chave KMS deve estar na mesma AWS região da recomendação.

Configurando permissões para usar uma chave KMS gerenciada pelo cliente

A política de chaves a seguir fornece as permissões mínimas necessárias para a criptografia recomendada. A política tem três instruções:

• AllowCallerAccess— Permite que o usuário ou a função do IAM valide a chave por meio DescribeKey de.

• AllowCallerCryptoOps— Permite que o usuário ou a função do IAM criptografe e descriptografe, de acordo com o contexto de criptografia.

• AllowServicePrincipalAccess— permite que o responsável pelo AgentCore serviço criptografe e descriptografe dados de recomendação durante o fluxo de trabalho de recomendação assíncrona, com escopo definido pela conta de origem e pelo ARN de origem.

{
"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/*"
        }
      }
    }
  ]
}

A política contém as seguintes declarações:

• AllowCallerAccess— Concede kms:DescribeKey permissão à função do IAM para a validação da chave no momento da criação da recomendação. 111122223333Substitua pelo ID da sua conta e MyRecommendationRole pela função ou usuário do IAM que inicia as recomendações.

• AllowCallerCryptoOps— Concede a função kms:GenerateDataKey e kms:Decrypt as permissões do IAM, de acordo com o contexto de aws:bedrock-agentcore:recommendationArn criptografia. Substitua 111122223333MyRecommendationRole,, e us-east-1 por seus valores. Para permitir o acesso a todas as recomendações em sua conta, use um curinga comStringLike:arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/*.

• AllowServicePrincipalAccess— concede ao diretor do AgentCore serviço kms:GenerateDataKey e kms:Decrypt permissões para criptografar e descriptografar dados de recomendação durante o fluxo de trabalho assíncrono. Definido por conta de origem e ARN de origem aws:SourceArn () para evitar ataques confusos de deputados. Substitua us-east-1 e 111122223333 por sua região e ID da conta.

Definindo o escopo do acesso à chave KMS gerenciada pelo cliente

Você pode usar o contexto de criptografia para reduzir o acesso à chave gerenciada pelo cliente. AgentCore as otimizações incluem o seguinte contexto de criptografia em todas as operações do KMS:

{
  "aws:bedrock-agentcore:recommendationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/recommendation-id"
}

Você pode usar esse contexto de criptografia nas principais condições de política para restringir as operações do KMS a recomendações específicas, conforme mostrado na AllowCallerCryptoOps declaração no exemplo de política de chaves acima. Observe que AllowServicePrincipalAccess usa aws:SourceArn para escopo em vez de contexto de criptografia.

Iniciando uma recomendação com uma chave KMS gerenciada pelo cliente

Especifique o kmsKeyArn parâmetro ao chamarStartRecommendation:

exemplo

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']}")

Monitorando o uso do KMS para recomendações

Os seguintes nomes de CloudTrail eventos aparecem para operações de recomendação do KMS:

• GenerateDataKey— Ao iniciar uma recomendação (configuração de criptografia) e quando o fluxo de trabalho de recomendação for concluído (criptografando o resultado). O encryptionContext campo contémaws:bedrock-agentcore:recommendationArn.

• Decrypt— Quando o fluxo de trabalho de recomendação processa a configuração ou ao recuperar os resultados da recomendação.

• DescribeKey— Ao validar a chave no momento da criação da recomendação.

Comportamento quando uma chave fica indisponível

Se você desativar ou excluir a chave KMS gerenciada pelo cliente usada por uma recomendação:

• StartRecommendation— Falha na validação comValidationException.

• GetRecommendation— Falha ao ValidationException indicar que a chave KMS está desativada ou excluída.

• ListRecommendations— É bem-sucedido porque a listagem retorna somente metadados e não exige operações KMS.

• DeleteRecommendation— É bem-sucedido porque a exclusão não exige a descriptografia dos dados de recomendação.