The crypto material contained in key versions isn't available in unencrypted form outside KMS. Encryption and decryption in KMS is carried out through two cryptographic operations: encrypt and decrypt.
The encrypt operation:
plaintextas input data.
To perform encryption using a non-primary key version, pass the ID of any active key version (
versionId) to the operation input.
Encrypts plaintext using the algorithm and cryptographic material of the primary key version.
Returns the resulting
The encrypt operation is suitable for encrypting small amounts of data. The maximum size of
plaintext is 32 KB. To encrypt large amounts of data, use envelope encryption.
The decrypt operation
ciphertextas input data.
The ciphertext generated by the encrypt operation contains the
versionIdused for encryption. The algorithm and cryptographic material for decryption are taken from this version of the key.
Decrypts the text.
The encrypt and decrypt operations in KMS support the transmission of AAD ( Additional Authenticated Data) context as a parameter named
aadContext. This helps to additionally secure the encrypted data.
The encrypt and decrypt operations in KMS are based on symmetric encryption: a scheme that uses the same (symmetric) key for both encryption and decryption. KMS supports the AES with 128, 192, or 256-bit keys in GCM mode.
An important condition for secure encryption is the use of a cryptographically stable pseudo-random number generator (necessary for generating encryption keys and initialization vectors). KMS uses its own implementation of the Fortuna algorithm, which collects entropy from various sources (RDSEED and RDRAND, /dev/urandom, host entropy).
Additional Authenticated Data (AAD) is additional data passed to the input of the encrypt and decrypt operations. To successfully decrypt data, pass the same AAD context that was passed for encryption.
The AAD context is closely related to the encrypted data (without knowing the AAD context, it's impossible to decrypt the ciphertext), but it doesn't increase the cryptographic stability of the ciphertext and is not part of it. The AAD context is designed to protect against confused deputy attacks through additional verification of the data when decrypting it.
In the AAD context, specify as much information as possible to uniquely identify where the ciphertext is located and where it belongs (for a database, this may be the name of the table and the value of the primary key, for a file – the path to this file, and so on).
Example of a confused deputy attack
The service stores the users' residential addresses in relation to their usernames. The addresses are saved to the database in encrypted form. They are encrypted with a key but no AAD context. Each DB record is marked as belonging to a particular user.
- Alice used the service and gave her address.
- A new entry is added to the database and marked as belonging to Alice. It contains the address in encrypted form.
- Alice can see her address: records belonging to her will be selected from the database, decrypted, and shown to Alice.
- Another user, Trudy, was granted access to the database.
- Trudy has no encryption key and can't decrypt the content of the database, but can modify it.
- Trudy marks the entry with Alice's encrypted address as belonging to herself and can now see Alice's address.
The problem is solved if you pass, for example, the username as AAD context during the encryption process. In this case:
- Trudy will try to view Alice's data marked as her own.
- The service will pass Trudy's username instead of Alice's one as AAD context.
- The data can't be decrypted.