View a markdown version of this page

Empfehlungsverschlüsselung - Amazon Grundgestein AgentCore
FunktionsweiseEine Empfehlung mit einem vom Kunden verwalteten KMS-Schlüssel startenÜberwachung der KMS-Nutzung im Hinblick auf EmpfehlungenVerhalten, wenn ein Schlüssel nicht mehr verfügbar ist

Empfehlungsverschlüsselung

Wenn Sie kmsKeyArn auf einer Empfehlung angeben, verschlüsselt der Dienst die Konfiguration der Empfehlung und das Ergebnis der Empfehlung mithilfe der Umschlagverschlüsselung mit dem AWS Encryption SDK. Alle anderen Empfehlungsmetadaten (Name, Typ, Status) bleiben mit dem AWS eigenen Schlüssel verschlüsselt.

Das kmsKeyArn wird bei der Erstellung über angegebenStartRecommendation.

Funktionsweise

Die Empfehlungsverschlüsselung verwendet das AWS Encryption SDK für die Verschlüsselung von Umschlägen. Wenn der Dienst Empfehlungsdaten schreibt oder liest, ruft er KMS auf, um Datenschlüssel zu generieren oder zu entschlüsseln. Das Empfehlungsergebnis wird ebenfalls in S3 gespeichert, SSE-KMS wobei derselbe vom Kunden verwaltete Schlüssel verwendet wird.

Zur API-Zeit überprüft der Dienst mithilfe eines Testlaufs (Forward Access Sessions), ob der Anrufer über KMS-Berechtigungen verfügt. Dadurch werden Berechtigungsprobleme sofort erkannt, anstatt während des Empfehlungsworkflows asynchron fehlschlagen zu müssen.

Wenn der Empfehlungsworkflow asynchron ausgeführt wird, entschlüsselt der Dienstprinzipal (bedrock-agentcore.amazonaws.com) die Konfiguration und verschlüsselt das Ergebnis. Der Dienstprinzipal muss in der kms:GenerateDataKey Schlüsselrichtlinie über eine kms:Decrypt entsprechende Berechtigung verfügen.

AgentCore Optimizations unterstützt nur KMS-Schlüssel mit symmetrischer Verschlüsselung. Der KMS-Schlüssel muss sich in derselben AWS Region wie die Empfehlung befinden.

Konfiguration von Berechtigungen zur Verwendung eines vom Kunden verwalteten KMS-Schlüssels

Die folgende Schlüsselrichtlinie bietet die Mindestberechtigungen, die für die Empfehlungsverschlüsselung erforderlich sind. Die Richtlinie enthält drei Anweisungen:

  • AllowCallerAccess— Ermöglicht dem IAM-Benutzer oder der IAM-Rolle, den Schlüssel über DescribeKey zu validieren.

  • AllowCallerCryptoOps— Ermöglicht dem IAM-Benutzer oder der IAM-Rolle das Ver- und Entschlüsseln, je nach Verschlüsselungskontext.

  • AllowServicePrincipalAccess— Ermöglicht dem AgentCore Dienstprinzipal, Empfehlungsdaten während des asynchronen Empfehlungsworkflows zu verschlüsseln und zu entschlüsseln, wobei der Bereich auf das Quellkonto und den Quell-ARN beschränkt ist.

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

Die Richtlinie enthält die folgenden Aussagen:

  • AllowCallerAccess— Erteilt der IAM-Rolle bei der Erstellung der Empfehlung die kms:DescribeKey Berechtigung zur Schlüsselvalidierung. 111122223333Ersetzen Sie es durch Ihre Konto-ID und MyRecommendationRole durch die IAM-Rolle oder den IAM-Benutzer, der Empfehlungen startet.

  • AllowCallerCryptoOps— Gewährt die IAM-Rolle kms:GenerateDataKey und die kms:Decrypt Berechtigungen, die vom Verschlüsselungskontext abhängig sind. aws:bedrock-agentcore:recommendationArn Ersetzen Sie 111122223333MyRecommendationRole, und us-east-1 durch Ihre Werte. Um Zugriff auf alle Empfehlungen in Ihrem Konto zu gewähren, verwenden Sie einen Platzhalter mitStringLike:arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/*.

  • AllowServicePrincipalAccess— Erteilt dem AgentCore Dienstprinzipal kms:GenerateDataKey und kms:Decrypt Berechtigungen zum Verschlüsseln und Entschlüsseln von Empfehlungsdaten während des asynchronen Workflows. Eingeschränkt nach Quellkonto und Quell-ARN (aws:SourceArn), um verwirrte Deputy-Angriffe zu verhindern. Ersetzen Sie us-east-1 und 111122223333 durch Ihre Region und Konto-ID.

Einschränkung des Zugriffs auf den vom Kunden verwalteten KMS-Schlüssel

Sie können den Verschlüsselungskontext verwenden, um den Zugriff auf den vom Kunden verwalteten Schlüssel einzuschränken. AgentCore Optimierungen beinhalten den folgenden Verschlüsselungskontext in allen KMS-Vorgängen:

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

Sie können diesen Verschlüsselungskontext in wichtigen Richtlinienbedingungen verwenden, um KMS-Operationen auf bestimmte Empfehlungen zu beschränken, wie in der AllowCallerCryptoOps Erklärung im obigen Beispiel für eine Schlüsselrichtlinie dargestellt. Beachten Sie, dass der Kontext eher aws:SourceArn für das Scoping als für den Verschlüsselungskontext AllowServicePrincipalAccess verwendet wird.

Eine Empfehlung mit einem vom Kunden verwalteten KMS-Schlüssel starten

Geben Sie den kmsKeyArn Parameter beim Aufrufen anStartRecommendation:

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

Überwachung der KMS-Nutzung im Hinblick auf Empfehlungen

Die folgenden CloudTrail Ereignisnamen werden für empfohlene KMS-Operationen angezeigt:

  • GenerateDataKey— Beim Starten einer Empfehlung (Verschlüsselungskonfiguration) und beim Abschluss des Empfehlungsworkflows (Verschlüsseln des Ergebnisses). Das encryptionContext Feld enthält. aws:bedrock-agentcore:recommendationArn

  • Decrypt— Wenn der Empfehlungs-Workflow die Konfiguration verarbeitet oder wenn Empfehlungsergebnisse abgerufen werden.

  • DescribeKey— Bei der Validierung des Schlüssels bei der Erstellung der Empfehlung.

Verhalten, wenn ein Schlüssel nicht mehr verfügbar ist

Wenn Sie den vom Kunden verwalteten KMS-Schlüssel, der in einer Empfehlung verwendet wird, deaktivieren oder löschen:

  • StartRecommendation— Schlägt bei der Validierung mit fehlValidationException.

  • GetRecommendation— Schlägt fehl und gibt an, ValidationException dass der KMS-Schlüssel deaktiviert oder gelöscht ist.

  • ListRecommendations— Erfolgreich, da beim Auflisten nur Metadaten zurückgegeben werden und keine KMS-Operationen erforderlich sind.

  • DeleteRecommendation— Erfolgreich, weil für das Löschen keine Entschlüsselung der Empfehlungsdaten erforderlich ist.