# Verschlüsselung der Batch-Auswertung
Wenn Sie `kmsKeyArn` bei einer Batch-Auswertung eine angeben, verschlüsselt der Dienst alle in S3 gespeicherten Ausgabeartefakte mithilfe der serverseitigen S3-Verschlüsselung mit KMS ()SSE-KMS. Dazu gehören die Datenquellenkonfiguration, die Sitzungsmetadaten und die Auswertungsergebnisse.
Das `kmsKeyArn` wird bei der Erstellung über angegeben`StartBatchEvaluation`.
## Funktionsweise
Die Verschlüsselung der Batch-Auswertung verwendet S3 SSE-KMS. Wenn der Dienst die Batch-Evaluierungsausgabe in S3 schreibt oder liest, ruft S3 im Namen des Dienstes KMS auf, um die Daten zu verschlüsseln oder zu entschlüsseln. Der Dienstprinzipal (`bedrock-agentcore.amazonaws.com`) muss in der Schlüsselrichtlinie über KMS-Berechtigungen verfügen.
Zur API-Zeit überprüft der Dienst mithilfe einer Testlaufprüfung (Forward Access Sessions), ob der Aufrufer über KMS-Berechtigungen verfügt. Dadurch werden Berechtigungsprobleme sofort erkannt, anstatt während des Workflows zur Batch-Auswertung asynchron fehlschlagen zu müssen.
Der Dienst überprüft außerdem, ob er `kms:GenerateDataKey` mit seinen eigenen Anmeldeinformationen arbeiten kann, um sicherzustellen, dass die Schlüsselrichtlinie dem Dienstprinzipal die erforderlichen Berechtigungen zum Schreiben verschlüsselter Ausgaben gewährt.
AgentCore Evaluations unterstützt nur KMS-Schlüssel mit symmetrischer Verschlüsselung. Der KMS-Schlüssel muss sich in derselben AWS Region wie die Batch-Auswertung befinden.
### Konfiguration von Berechtigungen zur Verwendung eines vom Kunden verwalteten KMS-Schlüssels
Die folgende Schlüsselrichtlinie bietet die Mindestberechtigungen, die für die Verschlüsselung der Batch-Evaluierung 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 das Verschlüsseln und Entschlüsseln von Batch-Auswertungsdaten in S3, aufgeteilt nach Quellkonto und Quell-ARN.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowCallerAccess",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/MyBatchEvaluationRole"
},
"Action": "kms:DescribeKey",
"Resource": "*"
},
{
"Sid": "AllowCallerCryptoOps",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/MyBatchEvaluationRole"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "*",
"Condition": {
"StringLike": {
"kms:EncryptionContext:aws:bedrock-agentcore:batchEvaluationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*"
}
}
},
{
"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:batch-evaluate/*"
}
}
}
]
}
```
Die Richtlinie enthält die folgenden Aussagen:
+ **AllowCallerAccess**— Erteilt der IAM-Rolle die `kms:DescribeKey` Berechtigung zur Schlüsselvalidierung bei der Erstellung der Batch-Auswertung. {{111122223333}}Ersetzen Sie es durch Ihre Konto-ID und {{MyBatchEvaluationRole}} durch die IAM-Rolle oder den IAM-Benutzer, der die Batch-Evaluierungen startet.
+ **AllowCallerCryptoOps**— Gewährt die IAM-Rolle `kms:GenerateDataKey` und die `kms:Decrypt` Berechtigungen, die vom Verschlüsselungskontext abhängig sind. `aws:bedrock-agentcore:batchEvaluationArn` Ersetzen Sie {{111122223333}}{{MyBatchEvaluationRole}}, und {{us-east-1}} durch Ihre Werte. Um Zugriff auf alle Batch-Auswertungen in Ihrem Konto zu gewähren, verwenden Sie einen Platzhalter mit`StringLike`:`arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*`.
+ **AllowServicePrincipalAccess**— Gewährt dem AgentCore Dienstprinzipal `kms:GenerateDataKey` und `kms:Decrypt` Berechtigungen zum Verschlüsseln und Entschlüsseln von Batch-Bewertungsdaten in S3. 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 Die Evaluierungen umfassen den folgenden Verschlüsselungskontext in allen KMS-Vorgängen:
```
{
"aws:bedrock-agentcore:batchEvaluationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/batch-evaluation-id"
}
```
Sie können diesen Verschlüsselungskontext in wichtigen Richtlinienbedingungen verwenden, um KMS-Operationen auf bestimmte Batch-Auswertungen zu beschränken, wie in der `AllowCallerCryptoOps` Anweisung 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.
## Starten einer Batch-Evaluierung mit einem vom Kunden verwalteten KMS-Schlüssel
Geben Sie den `kmsKeyArn` Parameter an, wenn Sie Folgendes aufrufen`StartBatchEvaluation`:
**Example**
Verwenden Sie mit der AgentCore CLI die `--kms-key` Option, um einen einzelnen KMS-Schlüssel-ARN für die Verschlüsselung der Ergebnisse der Batch-Auswertung anzugeben. Die AgentCore CLI verwendet das `--kms-key` Flag, das sich vom `--kms-key-arn` Flag der AWS CLI und dem `kmsKeyArn` boto3-Parameter unterscheidet.
```
agentcore run batch-evaluation \
-r MyAgent \
-e Builtin.Correctness \
--kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
```
aws bedrock-agentcore start-batch-evaluation \
--batch-evaluation-name "MyEncryptedBatchEval" \
--kms-key-arn "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
--evaluators '[{"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness"}]' \
--data-source-config '{
"cloudwatchLogs": {
"logGroupNames": ["/aws/bedrock-agentcore/sessions/my-agent"],
"serviceNames": ["my-agent.DEFAULT"],
"filterConfig": {
"timeRange": {
"startTime": "2025-01-01T00:00:00Z",
"endTime": "2025-01-02T00:00:00Z"
}
}
}
}'
```
```
import boto3
client = boto3.client('bedrock-agentcore')
response = client.start_batch_evaluation(
batchEvaluationName='MyEncryptedBatchEval',
kmsKeyArn='arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
evaluators=[{'evaluatorArn': 'arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness'}],
dataSourceConfig={
'cloudwatchLogs': {
'logGroupNames': ['/aws/bedrock-agentcore/sessions/my-agent'],
'serviceNames': ['my-agent.DEFAULT'],
'filterConfig': {
'timeRange': {
'startTime': '2025-01-01T00:00:00Z',
'endTime': '2025-01-02T00:00:00Z'
}
}
}
}
)
print(f"Batch Evaluation ID: {response['batchEvaluationId']}")
```
## Überwachung der KMS-Nutzung für Batch-Auswertungen
Die folgenden CloudTrail Ereignisnamen werden für KMS-Operationen zur Batch-Auswertung angezeigt:
+ `GenerateDataKey`— Beim Schreiben einer verschlüsselten Batch-Evaluierungsausgabe nach S3 (Datenquellenkonfiguration, Sitzungsmetadaten, Auswertungsergebnisse). Das `encryptionContext` Feld enthält`aws:bedrock-agentcore:batchEvaluationArn`.
+ `Decrypt`— Beim Lesen der verschlüsselten Batch-Evaluierungsausgabe von S3.
+ `DescribeKey`— Bei der Validierung des Schlüssels bei der Erstellung der Batch-Auswertung.
Weitere Informationen zur Überwachung der KMS-Nutzung finden Sie unter [Protokollieren von AWS KMS-API-Aufrufen mit AWS CloudTrail](https://docs.aws.amazon.com/kms/latest/developerguide/logging-using-cloudtrail.html) im * AWS Key Management Service Developer Guide*.
## Verhalten, wenn ein Schlüssel nicht mehr verfügbar ist
Wenn Sie den vom Kunden verwalteten KMS-Schlüssel, der bei einer Batch-Auswertung verwendet wurde, deaktivieren oder löschen:
+ **StartBatchEvaluation**— Schlägt bei der Validierung mit fehl`ValidationException`.
+ **GetBatchEvaluation**— Gibt Metadaten (Name, Status, Zeitstempel) zurück, aber die in verschlüsselten S3-Objekten gespeicherten Evaluationsergebnisse können vom Dienst nicht gelesen werden.
+ **ListBatchEvaluations**— Erfolgreich, da beim Auflisten nur Metadaten zurückgegeben werden und keine KMS-Operationen erforderlich sind.
+ **StopBatchEvaluation**— Erfolgreich, weil für das Stoppen keine Daten entschlüsselt werden müssen.
+ **DeleteBatchEvaluation**— Erfolgreich, weil für das Löschen von S3-Objekten keine KMS-Entschlüsselung erforderlich ist.
Um den Zugriff wiederherzustellen, aktivieren Sie den Schlüssel erneut oder aktualisieren Sie die Schlüsselrichtlinie, um die erforderlichen Berechtigungen zu gewähren.
Die oben beschriebenen Lebenszyklusoperationen für die Batch-Evaluierung sind AgentCore CLI-Befehlen zugeordnet. Die `archive` Befehle `stop` und zielen über die `-i, --id ` Option auf den Job ab. Der `view batch-evaluation` Befehl verwendet die ID als Positionsargument:
+ **StartBatchEvaluation**— `agentcore run batch-evaluation --kms-key ` (benutze `-r/--runtime` und`-e/--evaluator`)
+ **GetBatchEvaluation** — `agentcore view batch-evaluation `
+ **ListBatchEvaluations**— `agentcore view batch-evaluation` oder `agentcore batch-evaluations history`
+ **StopBatchEvaluation** — `agentcore stop batch-evaluation -i `
+ **DeleteBatchEvaluation** — `agentcore archive batch-evaluation -i `