View a markdown version of this page

crittografia dei consigli - Fondamento Amazon AgentCore
Come funzionaAvvio di una raccomandazione con una chiave KMS gestita dal clienteMonitoraggio dell'utilizzo del KMS per ottenere consigliComportamento quando una chiave diventa non disponibile

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

crittografia dei consigli

Quando si specifica a kmsKeyArn su un consiglio, il servizio crittografa la configurazione del consiglio e il risultato del consiglio utilizzando la crittografia delle buste con Encryption AWS SDK. Tutti gli altri metadati dei consigli (nome, tipo, stato) rimangono crittografati con la chiave di proprietà. AWS

kmsKeyArnÈ specificato al momento della creazione tramite. StartRecommendation

Come funziona

La crittografia delle raccomandazioni utilizza l' AWS Encryption SDK per la crittografia delle buste. Quando il servizio scrive o legge i dati dei consigli, chiama KMS per generare o decrittografare le chiavi di dati. Il risultato della raccomandazione viene inoltre archiviato in S3 SSE-KMS utilizzando la stessa chiave gestita dal cliente.

Al momento dell'API, il servizio verifica che il chiamante disponga delle autorizzazioni KMS utilizzando un controllo a secco (Forward Access Sessions). In questo modo vengono rilevati immediatamente i problemi di autorizzazione anziché fallire in modo asincrono durante il flusso di lavoro dei consigli.

Quando il flusso di lavoro dei consigli viene eseguito in modo asincrono, il service principal (bedrock-agentcore.amazonaws.com) decrittografa la configurazione e crittografa il risultato. Il responsabile del servizio deve disporre di un'autorizzazione nella politica kms:GenerateDataKey chiavekms:Decrypt.

AgentCore le ottimizzazioni supportano solo chiavi KMS di crittografia simmetrica. La chiave KMS deve trovarsi nella stessa AWS regione della raccomandazione.

Configurazione delle autorizzazioni per l'utilizzo di una chiave KMS gestita dal cliente

La seguente politica chiave fornisce le autorizzazioni minime richieste per la crittografia dei consigli. La policy ha tre istruzioni:

  • AllowCallerAccess— Consente all'utente o al ruolo IAM di convalidare la chiave tramite. DescribeKey

  • AllowCallerCryptoOps— Consente all'utente o al ruolo IAM di crittografare e decrittografare, in base al contesto di crittografia.

  • AllowServicePrincipalAccess— Consente al responsabile del AgentCore servizio di crittografare e decrittografare i dati dei consigli durante il flusso di lavoro asincrono dei consigli, in base all'account di origine e all'ARN di origine.

{
"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 policy contiene le seguenti dichiarazioni:

  • AllowCallerAccess— Concede al ruolo IAM l'kms:DescribeKeyautorizzazione per la convalida delle chiavi al momento della creazione della raccomandazione. Sostituiscilo 111122223333 con l'ID del tuo account e MyRecommendationRole con il ruolo o l'utente IAM che avvia i consigli.

  • AllowCallerCryptoOps— Concede il ruolo kms:GenerateDataKey e le kms:Decrypt autorizzazioni IAM, in base al aws:bedrock-agentcore:recommendationArn contesto di crittografia. Sostituisci 111122223333 e us-east-1 con MyRecommendationRole i tuoi valori. Per consentire l'accesso a tutti i consigli nel tuo account, usa una jolly conStringLike:arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/*.

  • AllowServicePrincipalAccess— Concede il principio del AgentCore servizio e le kms:Decrypt autorizzazioni per la crittografia kms:GenerateDataKey e la decrittografia dei dati dei consigli durante il flusso di lavoro asincrono. Elaborato in base all'account di origine e all'ARN di origine () per prevenire attacchi confusi. aws:SourceArn Sostituisci us-east-1 e 111122223333 con la tua regione e l'ID dell'account.

Riduzione dell'accesso alla chiave KMS gestita dal cliente

È possibile utilizzare il contesto di crittografia per limitare l'accesso alla chiave gestita dal cliente. AgentCore le ottimizzazioni includono il seguente contesto di crittografia in tutte le operazioni KMS:

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

È possibile utilizzare questo contesto di crittografia in condizioni politiche chiave per limitare le operazioni KMS a raccomandazioni specifiche, come mostrato nella AllowCallerCryptoOps dichiarazione contenuta nella politica chiave di esempio riportata sopra. Nota che AllowServicePrincipalAccess viene utilizzato aws:SourceArn per l'ambito anziché per il contesto di crittografia.

Avvio di una raccomandazione con una chiave KMS gestita dal cliente

Specifica il kmsKeyArn parametro quando StartRecommendation chiami:

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

Monitoraggio dell'utilizzo del KMS per ottenere consigli

Per le operazioni KMS consigliate vengono visualizzati i seguenti nomi di CloudTrail eventi:

  • GenerateDataKey— Quando si avvia un consiglio (configurazione di crittografia) e quando il flusso di lavoro del consiglio viene completato (crittografia del risultato). Il encryptionContext campo contiene. aws:bedrock-agentcore:recommendationArn

  • Decrypt— Quando il flusso di lavoro dei consigli elabora la configurazione o quando recupera i risultati dei consigli.

  • DescribeKey— Quando si convalida la chiave al momento della creazione della raccomandazione.

Comportamento quando una chiave diventa non disponibile

Se disabiliti o elimini la chiave KMS gestita dal cliente utilizzata da una raccomandazione:

  • StartRecommendation— La convalida non riesce con. ValidationException

  • GetRecommendation— Non riesce a ValidationException indicare che la chiave KMS è disabilitata o eliminata.

  • ListRecommendations— Ha esito positivo perché l'elenco restituisce solo metadati e non richiede operazioni KMS.

  • DeleteRecommendation— Ha esito positivo perché l'eliminazione non richiede la decrittografia dei dati dei consigli.