---
name: "libressl-EVP_AEAD_CTX_init"
section: "3"
platform: "linux"
package: "libressl"
version: "4.4.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libressl-EVP_AEAD_CTX_init"
---

# libressl-EVP\_AEAD\_CTX\_init(3)

authenticated encryption with additional data

## 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

## SYNOPSIS

Crypto Library (libcrypto, -lcrypto)

**#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

AEAD (Authenticated Encryption with Additional Data) couples confidentiality and integrity in a single primitive. AEAD algorithms take a key and can then seal and open individual messages. Each message has a unique, per-message nonce and, optionally, additional data which is authenticated but not included in the output.

**EVP\_AEAD\_CTX\_new**() allocates a 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**().

**EVP\_AEAD\_CTX\_free**() cleans up *ctx* and frees the space allocated to it.

**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. 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**().

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

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

**EVP\_AEAD\_key\_length**(), **EVP\_AEAD\_max\_overhead**(), **EVP\_AEAD\_max\_tag\_len**(), and **EVP\_AEAD\_nonce\_length**() provide information about the AEAD algorithm *aead*.

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

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.

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

**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:

```
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);
```

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

**EVP\_AEAD\_CTX\_new**() and **EVP\_AEAD\_CTX\_free**() first appeared in OpenBSD 7.1.

## 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:

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.