The AEAD cipher API is used with the ciphers of type CRYPTO_ALG_TYPE_AEAD (listed as type “aead” in /proc/crypto)

The most prominent examples for this type of encryption is GCM and CCM. However, the kernel supports other types of AEAD ciphers which are defined with the following cipher string:

authenc(keyed message digest, block cipher)

For example: authenc(hmac(sha256), cbc(aes))

The example code provided for the asynchronous block cipher operation applies here as well. Naturally all *ablkcipher* symbols must be exchanged the *aead* pendants discussed in the following. In addition, for the AEAD operation, the aead_request_set_assoc function must be used to set the pointer to the associated data memory location before performing the encryption or decryption operation. In case of an encryption, the associated data memory is filled during the encryption operation. For decryption, the associated data memory must contain data that is used to verify the integrity of the decrypted data. Another deviation from the asynchronous block cipher operation is that the caller should explicitly check for -EBADMSG of the crypto_aead_decrypt. That error indicates an authentication error, i.e. a breach in the integrity of the message. In essence, that -EBADMSG error code is the key bonus an AEAD cipher has over “standard” block chaining modes.

Memory Structure:

To support the needs of the most prominent user of AEAD ciphers, namely IPSEC, the AEAD ciphers have a special memory layout the caller must adhere to.

The scatter list pointing to the input data must contain:

* for RFC4106 ciphers, the concatenation of associated authentication data || IV || plaintext or ciphertext. Note, the same IV (buffer) is also set with the aead_request_set_crypt call. Note, the API call of aead_request_set_ad must provide the length of the AAD and the IV. The API call of aead_request_set_crypt only points to the size of the input plaintext or ciphertext.

* for “normal” AEAD ciphers, the concatenation of associated authentication data || plaintext or ciphertext.

It is important to note that if multiple scatter gather list entries form the input data mentioned above, the first entry must not point to a NULL buffer. If there is any potential where the AAD buffer can be NULL, the calling code must contain a precaution to ensure that this does not result in the first scatter gather list entry pointing to a NULL buffer.