Menu
AWS Key Management Service
Developer Guide

Encryption Context

Encryption context is a set of key-value pairs that you can pass to AWS KMS when you call the Encrypt, Decrypt, ReEncrypt, GenerateDataKey, and GenerateDataKeyWithoutPlaintext APIs. It is checked for integrity but not stored as part of the ciphertext that is returned. Although the encryption context is not included in the ciphertext, it is cryptographically bound to the ciphertext during encryption and must be passed again when you call the Decrypt (or ReEncrypt) API. Decryption only succeeds if the encryption context you pass for decryption is exactly the same as the encryption context you passed during encryption. The encryption context is logged by AWS CloudTrail.

To learn how to use encryption context to protect the integrity of encrypted data, see the post How to Protect the Integrity of Your Encrypted Data by Using AWS Key Management Service and EncryptionContext on the AWS Security Blog.

Encryption context can consist of any values that you want. However, because it is not encrypted and because it is logged if CloudTrail logging is turned on, your encryption context should not include sensitive information. We further recommend that your encryption context describe the data being encrypted or decrypted so that you can better understand the CloudTrail log entries produced by AWS KMS. For example, Amazon EBS uses the ID of the encrypted volume as the encryption context for server-side encryption. If you are encrypting a file, you might use part of the file path as encryption context.

Encryption Context in Grants and Key Policies

In addition to using encryption context to check ciphertext integrity and authenticity, AWS KMS supports authorization by using grants and key policies that incorporate encryption context. Authorization that uses encryption context more tightly controls access to encrypted resources. When you create a grant, for example, you can optionally specify a set of constraints that specify an encryption context that unambiguously identifies the resource to which long-term access is being granted. For example, consider encrypted volumes with Amazon EBS and Amazon EC2: When an EBS volume is attached to an EC2 instance, a grant is created that allows only that instance to decrypt only that volume. This is accomplished by encoding the volume ID as the encryption context in the Constraint that is passed to the CreateGrant API. Without the encryption context in the constraint, the Amazon EC2 instance would obtain access to all volumes encrypted under the customer master key (CMK) rather than a specific volume.

Logging Encryption Context

AWS KMS uses AWS CloudTrail to log the encryption context so you can determine which CMKs and data have been accessed. That is, the log entry shows exactly which CMK was used to encrypt or decrypt specific data referenced by the encryption context in the log entry.

Important

Because the encryption context is logged, it must not contain sensitive information.

Storing Encryption Context

You should store the encryption context alongside the encrypted data to simplify using it when you call the Decrypt (or ReEncrypt) API. One security enhancement you might consider is to store only enough of the encryption context to help you create the full encryption context on the fly when needed for encryption or decryption. For example, if you are encrypting a file and decide that the encryption context should be the full file path, store only part of that path alongside the encrypted file contents. Then, when you need the full encryption context, reconstruct it from the stored fragment. If someone then moves the file to a different location, when you recreate the encryption context, the context will be different and the decryption process will fail, indicating that your data has been tampered with.