AWS bedrock: Document KMS encryption for Bedrock knowledge base retrieval instructions
Summary
Adds a new 'Encryption of retrieval instructions' section to the Bedrock knowledge base encryption page, covering encryption at rest with an AWS owned key by default, opting into a customer managed KMS key via customerEncryptionKeyArn on CreateRetrievalInstruction, key requirements (symmetric, same Region/account, ARN only), envelope encryption with GenerateDataKey/Decrypt, a sample key policy with kms:ViaService, aws:SourceArn and encryption-context conditions, behavior when the key is unavailable, and CloudTrail monitoring of KMS calls. Also adds the topic to the page's TOC and resource lists.
Security assessment
The change is purely additive documentation of a data-at-rest encryption capability and its IAM/KMS key policy scoping (kms:ViaService, aws:SourceArn, encryption context) plus CloudTrail auditability. It describes a security feature and hardening guidance rather than remediating a specific vulnerability or incident, so it is security documentation, not a fix.
Evidence
+To control the key yourself, specify a symmetric encryption AWS KMS key in the `customerEncryptionKeyArn` parameter when you call `CreateRetrievalInstruction`. Amazon Bedrock then uses that customer managed key instead of the AWS owned key. AWS KMS charges apply. Retrieval instructions do not support an AWS managed key.
Diff
diff --git a/bedrock/latest/userguide/encryption-kb.md b/bedrock/latest/userguide/encryption-kb.md index 2b66e1a..1cc3c95 100644 --- a//bedrock/latest/userguide/encryption-kb.md +++ b//bedrock/latest/userguide/encryption-kb.md @@ -7 +7 @@ -Encryption of data storage in fully managed knowledge baseEncryption of knowledge base retrievalEncryption of transient data storage during data ingestionEncryption of information passed to Amazon OpenSearch ServiceEncryption of information passed to Amazon S3 VectorsPermissions to decrypt your AWS KMS key for your data sources in Amazon S3Permissions to decrypt an AWS Secrets Manager secret for the vector store containing your knowledge basePermissions for Bedrock Data Automation (BDA) with AWS KMS encryption +Encryption of data storage in fully managed knowledge baseEncryption of knowledge base retrievalEncryption of retrieval instructionsEncryption of transient data storage during data ingestionEncryption of information passed to Amazon OpenSearch ServiceEncryption of information passed to Amazon S3 VectorsPermissions to decrypt your AWS KMS key for your data sources in Amazon S3Permissions to decrypt an AWS Secrets Manager secret for the vector store containing your knowledge basePermissions for Bedrock Data Automation (BDA) with AWS KMS encryption @@ -29,0 +30,2 @@ The following resources used by your knowledge bases can be encrypted with a KMS + * Retrieval instructions + @@ -66,0 +69,2 @@ Amazon Bedrock knowledge bases uses TLS encryption for communication with third- + * Encryption of retrieval instructions + @@ -233,0 +238,126 @@ JSON +## Encryption of retrieval instructions + +### Encryption at rest + +Amazon Bedrock encrypts the content of your retrieval instructions at rest. By default it uses an AWS owned key, with no configuration from you. Encryption cannot be disabled. + +To control the key yourself, specify a symmetric encryption AWS KMS key in the `customerEncryptionKeyArn` parameter when you call `CreateRetrievalInstruction`. Amazon Bedrock then uses that customer managed key instead of the AWS owned key. AWS KMS charges apply. Retrieval instructions do not support an AWS managed key. + +The key encrypts the instruction content (the `retrievalGuidance`, `persona`, `answerFormat`, and `answerPolicy` fields) in the working copy of the instruction, in every version you create, and in content that is waiting to be reviewed. The instruction's name, description, status, and tags are not encrypted with your key. + +Amazon Bedrock uses envelope encryption: it calls `GenerateDataKey` on your key for each encryption and stores the encrypted data key with the ciphertext. Data keys are not cached, so every read calls `Decrypt`. + +### Requirements for the key + + * A symmetric encryption KMS key. + + * In the same AWS Region and the same AWS account as the retrieval instruction. + + * Specified by key ARN. Aliases and key IDs are not accepted. + + * You can use a multi-Region key, but Amazon Bedrock does not use its multi-Region features. + + + + +The key is set when you create the instruction and cannot be changed afterward. `UpdateRetrievalInstruction` does not accept a key, and there is no way to move an existing instruction to a different key. To change keys, create a new retrieval instruction and delete the old one. Versions stay encrypted under the key the instruction was created with. + +### Key policy + +Your key policy must allow the IAM role that creates, updates, and reads retrieval instructions (shown below as `RetrievalInstructionAuthor`), and the Amazon Bedrock service principal, which decrypts your content during the automatic content review. + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "AllowAccountAdministration", + "Effect": "Allow", + "Principal": { "AWS": "arn:aws:iam::111122223333:root" }, + "Action": "kms:*", + "Resource": "*" + }, + { + "Sid": "AllowBedrockToDescribeTheKey", + "Effect": "Allow", + "Principal": { "AWS": "arn:aws:iam::111122223333:role/RetrievalInstructionAuthor" }, + "Action": "kms:DescribeKey", + "Resource": "*", + "Condition": { + "StringEquals": { "kms:ViaService": "bedrock.region.amazonaws.com" } + } + }, + { + "Sid": "AllowBedrockToEncryptAndDecryptInstructionContent", + "Effect": "Allow", + "Principal": { "AWS": "arn:aws:iam::111122223333:role/RetrievalInstructionAuthor" }, + "Action": [ "kms:GenerateDataKey", "kms:Decrypt" ], + "Resource": "*", + "Condition": { + "StringEquals": { + "kms:ViaService": "bedrock.region.amazonaws.com", + "kms:EncryptionContext:aws:bedrock:retrieval-instruction:account-id": "111122223333" + } + } + }, + { + "Sid": "AllowBedrockToDecryptForContentReview", + "Effect": "Allow", + "Principal": { "Service": "bedrock.amazonaws.com" }, + "Action": "kms:Decrypt", + "Resource": "*", + "Condition": { + "StringEquals": { + "kms:EncryptionContext:aws:bedrock:retrieval-instruction:account-id": "111122223333" + }, + "ArnLike": { + "aws:SourceArn": "arn:aws:bedrock:region:111122223333:retrieval-instruction/*" + } + } + } + ] + } + +You can narrow this further with three conditions, all shown above: + + * `kms:ViaService` limits principals in your account to using the key only through Amazon Bedrock. + + * `aws:SourceArn` limits the Amazon Bedrock service principal to retrieval instructions in your account. + + * Amazon Bedrock includes `aws:bedrock:retrieval-instruction:account-id` and `aws:bedrock:retrieval-instruction:id` in the encryption context of every call, so you can require either one. + + + + +### When the key is unavailable + +If you disable the key or remove the permissions above, content encrypted under it cannot be read: + + * `CreateRetrievalInstruction` and `UpdateRetrievalInstruction` return a `ValidationException` naming the key. + + * `GetRetrievalInstruction` returns a `ValidationException`, including for an instruction that was previously usable. + + * `AgenticRetrieveStream` requests that apply the instruction fail instead of continuing without it. + + * A content review that cannot read the content ends with a failure reason of `CLIENT_ERROR`. + + + + +Re-enabling the key or restoring the permissions makes the content readable again. + +### Monitoring + +Amazon Bedrock's calls to AWS KMS appear in your AWS CloudTrail logs. See [Logging AWS KMS API calls with AWS CloudTrail](https://docs.aws.amazon.com/kms/latest/developerguide/logging-using-cloudtrail.html#searching-kms-ct). + +Operation | AWS KMS calls | Recorded caller +---|---|--- +`CreateRetrievalInstruction` | `DescribeKey`, `GenerateDataKey`, `Decrypt` | your IAM principal, with `kms:ViaService` of `bedrock.`region`.amazonaws.com` +`UpdateRetrievalInstruction` | `GenerateDataKey`, `Decrypt` | your IAM principal, with `kms:ViaService` +`GetRetrievalInstruction`, and `AgenticRetrieveStream` when an instruction is applied | `Decrypt` | your IAM principal, with `kms:ViaService` +Automatic content review after create or update | `Decrypt` | the `bedrock.amazonaws.com` service principal, with `sourceAccount` and `sourceArn` + +`CreateRetrievalInstructionVersion`, the `List` and `Delete` operations, and tagging make no calls to AWS KMS. + +Every record carries an `encryptionContext` containing `aws:bedrock:retrieval-instruction:account-id` and `aws:bedrock:retrieval-instruction:id`. +