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 before start.

If the associated data does not change, it is not necessary to call this function more than once, even across multiple calls to start and finish.

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 least final_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 than update_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.