AUTHENTICATED ENCRYPTION WITH ASSOCIATED DATA (AEAD) CIPHER API(9)

📦 version 7.3.1, in nixpkgs unstable

💖 Authenticated Encryption With Associated Data (AEAD) Cipher API 💖

okay bestie so this is the Kernel API Manual, section 9, and today's main character is the AEAD cipher API. pull up a chair, this one's actually so good 🫶

✨ DESCRIPTION ✨

The AEAD cipher API is the one you use with ciphers of type CRYPTO_ALG_TYPE_AEAD — and you'll see those listed as type "aead" over in /proc/crypto, so go peek, it's right there 👀

The most prominent examples of this encryption type are GCM and CCM — iconic, we know them, they're famous. 🌈 But the kernel also supports other types of AEAD ciphers that you define with the following cipher string:

authenc(keyed message digest, block cipher)

For example:

authenc(hmac(sha256), cbc(aes))

And the example code provided for the symmetric key cipher operation applies here too! 💅 Naturally you gotta swap out all the skcipher symbols for the aead pendants discussed in the following. On top of that, for the AEAD operation you must use the aead_request_set_ad function to set the pointer to the associated data memory location before you perform the encryption or decryption operation. no skipping steps bestie, that's not the vibe 🙈

Another deviation from the asynchronous block cipher operation: the caller should explicitly check for -EBADMSG of the crypto_aead_decrypt. Like, literally check it yourself. That error indicates an authentication error, i.e. a breach in the integrity of the message. 😭 And honestly? That -EBADMSG error code is the key bonus an AEAD cipher has over "standard" block chaining modes. it's giving glow-up, it's giving upgraded security model, periodt. 👑

🎀 Memory Structure 🎀

The source scatterlist must contain the concatenation of associated data || plaintext or ciphertext.

The destination scatterlist has the same layout, except that the plaintext (resp. ciphertext) will grow (resp. shrink) by the authentication tag size during encryption (resp. decryption). The authentication tag is generated during the encryption operation and appended to the ciphertext. During decryption, the authentication tag is consumed along with the ciphertext and used to verify the integrity of the plaintext and the associated data. 🦋

In-place encryption/decryption is enabled by using the same scatterlist pointer for both the source and destination. slay, one pointer, both jobs. ✨

Even in the out-of-place case, space must be reserved in the destination for the associated data, even though it won't be written to. This makes the in-place and out-of-place cases more consistent. ngl that's kind of thoughtful of them 💜 It is permissible for the "destination" associated data to alias the "source" associated data.

As with the other scatterlist crypto APIs, zero-length scatterlist elements are not allowed in the used part of the scatterlist. 🚫 Thus, if there is no associated data, the first element must point to the plaintext/ciphertext. like, no ad? first element carries the team, that's the rule.

⚠️ To meet the needs of IPsec, a special quirk applies to rfc4106, rfc4309, rfc4543, and rfc7539esp ciphers. For these ciphers, the final 'ivsize' bytes of the associated data buffer must contain a second copy of the IV. This is in addition to the copy passed to aead_request_set_crypt. These two IV copies must not differ; different implementations of the same algorithm may behave differently in that case. 💀 Note that the algorithm might not actually treat the IV as associated data; nevertheless the length passed to aead_request_set_ad must include it. so yes, it counts even if it's kind of vibing off to the side, fr fr.

🌸 SEE ALSO 🌸

Kernel file ./include/crypto/aead.h

💖 okay that's the whole page bestie, you ate that 💖

this gem lives in ./include/crypto, and it's dated October 2026 — so yeah, future manpage, main character energy only. go forth and authenticate your associated data, ily, bye! 🎀✨🦋💅

📦 where this page comes from