Minor Description
There are some use cases where callers to aes_encrypt may want to provide initialization vectors (IVs) or additional authenticated data (AAD). The most common cases will be:
1. Ensuring that ciphertext matches values that have been encrypted by external tools. In those cases, the caller will need to provide an identical IV value.
2. For AES-CBC mode, there are some cases where callers want to generate deterministic encrypted output.
3. For AES-GCM mode, providing AAD fields allows callers to bind additional data to an encrypted ciphertext so that it can only be decrypted by a caller providing the same value. This is often used to enforce some context.
The proposed new API is the following:
- aes_encrypt(expr, key [, mode [, padding [, iv [, aad]]]])
- aes_decrypt(expr, key [, mode [, padding [, aad]]])
These fields are only supported for specific modes:
- ECB: Does not support either IV or AAD and will return an error if either are provided.
- CBC: Only supports an IV and will return an error if an AAD is provided
- GCM: Supports either IV, AAD, or both.
If a caller is only providing an AAD to GCM mode, they would need to pass a null value in the IV field.
