AEAD Modes

AEAD Modes

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

The AEAD interface can be used directly, or as part of the filter system using AEADFilter (a subclass of KeyedFilter which will be returned by getCipher 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.

From interface AEADMode, we have:

void setKey(in SymmetricKey key);

Set the key

KeyLengthSpecification keySpec() const;

Return the key length specification

void setAssociatedData(in byte* ad, size_t ad_len);

Set any associated data for this message. For maximum portability between different modes, this must be called after setKey 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(in 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(SecureVector!ubyte 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 updateGranularity. 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(SecureVector!ubyte 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 finalMinimumSize bytes.

Note that if you have the entire message in hand, calling finish without ever calling update is both efficient and convenient.

size_t updateGranularity() const;

The AEAD interface requires update be called with blocks of this size.

size_t finalMinimumSize() const;

The AEAD interface requires finish be called with at least this many bytes (which may be zero, or greater than updateGranularity)

bool validNonceLength(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 defaultNonceLength() 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.