# 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 angegeben`StartRecommendation`.
## 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. {{111122223333}}Ersetzen 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 {{111122223333}}{{MyRecommendationRole}}, und {{us-east-1}} durch Ihre Werte. Um Zugriff auf alle Empfehlungen in Ihrem Konto zu gewähren, verwenden Sie einen Platzhalter mit`StringLike`:`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 an`StartRecommendation`:
**Example**
```
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 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"}]
}
}
}'
```
```
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 fehl`ValidationException`.
+ **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.