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.
Topics
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.
