EVP_AEAD_CTX_INIT(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

💖 EVP_AEAD_CTX_INIT(3) 💖

okay so this is the EVP_AEAD_CTX_INIT(3) page, from the Library Functions Manual, and it's all about authenticated encryption with additional data — the libcrypto flavor, bestie. buckle up 🎀

✨ NAME ✨

EVP_AEAD_CTX_new, EVP_AEAD_CTX_free, EVP_AEAD_CTX_init, EVP_AEAD_CTX_cleanup, EVP_AEAD_CTX_open, EVP_AEAD_CTX_seal, EVP_AEAD_key_length, EVP_AEAD_max_overhead, EVP_AEAD_max_tag_len, EVP_AEAD_nonce_length, EVP_aead_aes_128_gcm, EVP_aead_aes_256_gcm, EVP_aead_chacha20_poly1305, EVP_aead_xchacha20_poly1305 — authenticated encryption with additional data 🌸

like, that's the whole squad fr fr 💅

🦋 SYNOPSIS 🦋

library “libcrypto”

#include <openssl/evp.h>

EVP_AEAD_CTX *
EVP_AEAD_CTX_new(void);

void
EVP_AEAD_CTX_free(EVP_AEAD_CTX *ctx);

int
EVP_AEAD_CTX_init(EVP_AEAD_CTX *ctx, const EVP_AEAD *aead,
    const unsigned char *key, size_t key_len, size_t tag_len,
    ENGINE *engine);

void
EVP_AEAD_CTX_cleanup(EVP_AEAD_CTX *ctx);

int
EVP_AEAD_CTX_open(const EVP_AEAD_CTX *ctx, unsigned char *out,
    size_t *out_len, size_t max_out_len, const unsigned char *nonce,
    size_t nonce_len, const unsigned char *in, size_t in_len,
    const unsigned char *ad, size_t ad_len);

int
EVP_AEAD_CTX_seal(const EVP_AEAD_CTX *ctx, unsigned char *out,
    size_t *out_len, size_t max_out_len, const unsigned char *nonce,
    size_t nonce_len, const unsigned char *in, size_t in_len,
    const unsigned char *ad, size_t ad_len);

size_t
EVP_AEAD_key_length(const EVP_AEAD *aead);

size_t
EVP_AEAD_max_overhead(const EVP_AEAD *aead);

size_t
EVP_AEAD_max_tag_len(const EVP_AEAD *aead);

size_t
EVP_AEAD_nonce_length(const EVP_AEAD *aead);

const EVP_AEAD *
EVP_aead_aes_128_gcm(void);

const EVP_AEAD *
EVP_aead_aes_256_gcm(void);

const EVP_AEAD *
EVP_aead_chacha20_poly1305(void);

const EVP_AEAD *
EVP_aead_xchacha20_poly1305(void);

💜 DESCRIPTION 💜

so AEAD stands for Authenticated Encryption with Additional Data, and the whole vibe is that it couples confidentiality and integrity into a single primitive. iconic behavior honestly 👑

AEAD algorithms take a key, and then they can seal and open individual messages. every single message gets its own unique per-message nonce, and optionally some additional data which gets authenticated but is not included in the output. iykyk 🔥

EVP_AEAD_CTX_new() — allocates a shiny new context for use with EVP_AEAD_CTX_init(). it can be cleaned up for reuse with EVP_AEAD_CTX_cleanup() and must be freed with EVP_AEAD_CTX_free(). don't leave it hanging bestie 😭
EVP_AEAD_CTX_free() — cleans up ctx and frees the space allocated to it. the respectful goodbye 🫶
EVP_AEAD_CTX_init() — initializes the context ctx for the given AEAD algorithm aead. the engine argument must be NULL for the default implementation; other values are not supported (so like, don't try it 💀). authentication tags may be truncated by passing a tag length. a tag_len argument of EVP_AEAD_DEFAULT_TAG_LENGTH, which has the value 0, causes the default tag length to be used.
EVP_AEAD_CTX_cleanup() — frees any data allocated for the context ctx. after EVP_AEAD_CTX_cleanup(), ctx is in the same state as after EVP_AEAD_CTX_new(). it's giving factory reset ✨
EVP_AEAD_CTX_open() — authenticates the input in and optional additional data ad, decrypting the input and writing it as output out. this function may be called (with the same EVP_AEAD_CTX) concurrently with itself or with EVP_AEAD_CTX_seal(). at most the number of input bytes are written as output. in order to ensure success, max_out_len should be at least the same as the input length in_len. on successful return out_len is set to the actual number of bytes written. the length of the nonce specified with nonce_len must be equal to the result of EVP_AEAD_nonce_length for this AEAD. EVP_AEAD_CTX_open() never results in partial output. if max_out_len is insufficient, zero will be returned and out_len will be set to zero. if the input and output are aliased then out must be <= in. no cap.
EVP_AEAD_CTX_seal() — encrypts and authenticates the input and authenticates any additional data provided in ad, the encrypted input and authentication tag being written as output out. this function may be called (with the same EVP_AEAD_CTX) concurrently with itself or with EVP_AEAD_CTX_open(). at most max_out_len bytes are written as output and, in order to ensure success, this value should be the in_len plus the result of EVP_AEAD_max_overhead(). on successful return, out_len is set to the actual number of bytes written. the length of the nonce specified with nonce_len must be equal to the result of EVP_AEAD_nonce_length() for this AEAD. EVP_AEAD_CTX_seal() never results in a partial output. if max_out_len is insufficient, zero will be returned and out_len will be set to zero. if the input and output are aliased then out must be <= in. same deal 🔒

so EVP_AEAD_key_length(), EVP_AEAD_max_overhead(), EVP_AEAD_max_tag_len(), and EVP_AEAD_nonce_length() all provide information about the AEAD algorithm aead. the info squad 📋

EVP_AEAD_max_tag_len() returns the maximum tag length that can be used with the given aead. this is the largest value that can be passed as the tag_len argument to EVP_AEAD_CTX_init(). no built-in EVP_AEAD object has a maximum tag length larger than the constant EVP_AEAD_MAX_TAG_LENGTH. 📏

all cipher algorithms have a fixed key length unless otherwise stated. the following ciphers are available:

EVP_aead_aes_128_gcm() — AES-128 in Galois Counter Mode, using a key_len of 16 bytes and a nonce_len of 12 bytes. 🍓
EVP_aead_aes_256_gcm() — AES-256 in Galois Counter Mode, using a key_len of 32 bytes and a nonce_len of 12 bytes. 💪
EVP_aead_chacha20_poly1305() — ChaCha20 with a Poly1305 authenticator, using a key_len of 32 bytes and a nonce_len of 12 bytes. the constant EVP_CHACHAPOLY_TLS_TAG_LEN specifies the length of the authentication tag in bytes and has a value of 16. 🌊
EVP_aead_xchacha20_poly1305() — XChaCha20 with a Poly1305 authenticator, using a key_len of 32 bytes and a nonce_len of 24 bytes. the extra-X one, slay 🦋

unless compatibility with other implementations like OpenSSL or BoringSSL is required, using the EVP_AEAD interface to AEAD ciphers is recommended in preference to the functions documented in the EVP_EncryptInit(3), EVP_aes_256_gcm(3), and EVP_chacha20_poly1305(3) manual pages. the code then becomes transparent to the AEAD cipher used and much more flexible. it is also safer to use as it prevents common mistakes with the EVP APIs. like, it literally protects you from yourself 💅✨

🌈 RETURN VALUES 🌈

EVP_AEAD_CTX_new() returns the new EVP_AEAD_CTX object on success; otherwise NULL is returned and errno is set to ENOMEM. 😭
EVP_AEAD_CTX_init(), EVP_AEAD_CTX_open(), and EVP_AEAD_CTX_seal() return 1 for success or zero for failure. one or zero, that's the whole story 🎀
EVP_AEAD_key_length() returns the length of the key used for this AEAD.
EVP_AEAD_max_overhead() returns the maximum number of additional bytes added by the act of sealing data with the AEAD.
EVP_AEAD_max_tag_len() returns the maximum tag length when using this AEAD.
EVP_AEAD_nonce_length() returns the length of the per-message nonce.

⭐ EXAMPLES ⭐

encrypt a string using ChaCha20-Poly1305, bestie:

const EVP_AEAD *aead = EVP_aead_chacha20_poly1305();
static const unsigned char nonce[32] = {0};
size_t buf_len, nonce_len;
EVP_AEAD_CTX *ctx;

ctx = EVP_AEAD_CTX_new();
EVP_AEAD_CTX_init(ctx, aead, key32, EVP_AEAD_key_length(aead),
    EVP_AEAD_DEFAULT_TAG_LENGTH, NULL);
nonce_len = EVP_AEAD_nonce_length(aead);

EVP_AEAD_CTX_seal(ctx, out, &out_len, BUFSIZE, nonce,
    nonce_len, in, in_len, NULL, 0);

EVP_AEAD_CTX_free(ctx);

also note: nonce is declared as static const unsigned char nonce[32] = {0}; in this example, but the real nonce length comes from EVP_AEAD_nonce_length(aead) — keep that detail, it's in the code for a reason 🧚

🔥 SEE ALSO 🔥

evp(3), EVP_EncryptInit(3)

👑 STANDARDS 👑

A. Langley, W. Chang, N. Mavrogiannopoulos, J. Strombergson, and S. Josefsson, ChaCha20-Poly1305 Cipher Suites for Transport Layer Security (TLS), RFC 7905, June 2016.
S. Arciszewski, XChaCha: eXtended-nonce ChaCha and AEAD_XChaCha20_Poly1305, draft-arciszewski-xchacha-02, October 2018.

🎀 HISTORY 🎀

AEAD is based on the implementation by Adam Langley for Chromium/BoringSSL and first appeared in OpenBSD 5.6. OG icon behavior 💖

EVP_AEAD_CTX_new() and EVP_AEAD_CTX_free() first appeared in OpenBSD 7.1. the newer additions to the family 🌱

💀 CAVEATS 💀

⚠️ the original publications and code by Adam Langley used a modified AEAD construction that is incompatible with the common style used by AEAD in TLS and incompatible with RFC 7905. like, do not mix these up, fr fr.

A. Langley and W. Chang, ChaCha20 and Poly1305 based Cipher Suites for TLS, draft-agl-tls-chacha20poly1305-04, November 2013.
Y. Nir and A. Langley, ChaCha20 and Poly1305 for IETF Protocols, RFC 8439, June 2018.

in particular, the original version used a nonce_len of 8 bytes. eight!! not twelve!! that's the whole trap 🙈

alright bestie, that's the whole page — this lil guide is from the Debian build, dated June 8, 2025 (EVP_AEAD_CTX_INIT(3), Library Functions Manual). go forth and seal responsibly 💜🫶✨

📦 where this page comes from

alpine 3.24: libressl-doc 4.3.1-r0 · custom
arch rolling: libressl 4.4.0-1 · ISC AND custom:OpenSSL
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms