AEAD Modes¶
New in version 1.11.3.
AEAD (Authenticated Encryption with Associated Data) modes provide message
encryption, message authentication, and the ability to authenticate additional
data that is not included in the ciphertext (such as a sequence number or
header). It is a subclass of Symmetric_Algorithm
.
The AEAD interface can be used directly, or as part of the filter system by
using AEAD_Filter
(a subclass of Keyed_Filter
which
will be returned by get_cipher
if the named cipher is an AEAD mode).
AEAD modes currently available include GCM, OCB, and EAX. All three use a 128-bit block cipher such as AES.
-
class
AEAD_Mode
¶ -
void
set_key
(const SymmetricKey &key)¶ Set the key
-
Key_Length_Specification
key_spec
() const¶ Return the key length specification
-
void
set_associated_data
(const byte ad[], size_t ad_len)¶ Set any associated data for this message. For maximum portability between different modes, this must be called after
set_key
and beforestart
.If the associated data does not change, it is not necessary to call this function more than once, even across multiple calls to
start
andfinish
.
-
void
start
(const byte nonce[], size_t nonce_len)¶ Start processing a message, using nonce as the unique per-message value.
Returns any initial data that should be emitted (for instance a header).
-
void
update
(secure_vector<byte> &buffer, size_t offset = 0)¶ Continue processing a message. The buffer is an in/out parameter and may be resized. In particular, some modes require that all input be consumed before any output is produced; with these modes, buffer will be returned empty.
On input, the buffer must be sized in blocks of size
update_granularity
. For instance if the update granularity was 64, then buffer could be 64, 128, 192, ... bytes.The first offset bytes of buffer will be ignored (this allows in place processing of a buffer that contains an initial plaintext header)
-
void
finish
(secure_vector<byte> &buffer, size_t offset = 0)¶ Complete processing a message with a final input of buffer, which is treated the same as with
update
. It must contain at leastfinal_minimum_size
bytes.Note that if you have the entire message in hand, calling finish without ever calling update is both efficient and convenient.
Note
During decryption, finish will throw an instance of Integrity_Failure if the MAC does not validate. If this occurs, all plaintext previously output via calls to update must be destroyed and not used in any way that an attacker could observe the effects of.
One simply way to assure this could never happen is to never call update, and instead always marshall the entire message into a single buffer and call finish on it when decrypting.
-
size_t
update_granularity
() const¶ The AEAD interface requires
update
be called with blocks of this size.
-
size_t
final_minimum_size
() const¶ The AEAD interface requires
finish
be called with at least this many bytes (which may be zero, or greater thanupdate_granularity
)
-
bool
valid_nonce_length
(size_t nonce_len) const¶ Returns true if nonce_len is a valid nonce length for this scheme. For EAX and GCM, any length nonces are allowed. OCB allows any value between 8 and 15 bytes.
-
size_t
default_nonce_length
() const¶ Returns a reasonable length for the nonce, typically either 96 bits, or the only supported length for modes which don’t support 96 bit nonces.
-
void