---
name: "libressl-EVP_chacha20"
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_chacha20"
---

# libressl-EVP\_chacha20(3)

ChaCha20 stream cipher for EVP

## NAME

**EVP\_chacha20**, **EVP\_chacha20\_poly1305** – ChaCha20 stream cipher for EVP

## SYNOPSIS

Crypto Library (libcrypto, -lcrypto)

**#include \<openssl/evp.h\>**

*const* *EVP\_CIPHER* *\**\

**EVP\_chacha20**(*void*);

*const* *EVP\_CIPHER* *\**\

**EVP\_chacha20\_poly1305**(*void*);

## DESCRIPTION

**EVP\_chacha20**() provides the ChaCha20 stream cipher in the EVP framework. EVP\_EncryptInit\_ex(3), EVP\_DecryptInit\_ex(3), and EVP\_CipherInit\_ex(3) take a *key* argument of 32 bytes = 256 bits and an *iv* argument of 16 bytes = 128 bits, internally using ChaCha\_set\_key(3) and ChaCha\_set\_iv(3). The lower 8 bytes = 64 bits of *iv* are used as counter and the remaining 8 bytes are used as the initialization vector of ChaCha\_set\_iv(3). EVP\_EncryptUpdate(3), EVP\_EncryptFinal\_ex(3), EVP\_DecryptUpdate(3), and EVP\_DecryptFinal\_ex(3) internally use ChaCha(3) to perform encryption and decryption. EVP\_CIPHER\_CTX\_ctrl(3) always fails for *ctx* objects created from **EVP\_chacha20**().

**EVP\_chacha20\_poly1305**() provides authenticated encryption with ChaCha20-Poly1305. Unless compatibility with other implementations like OpenSSL or BoringSSL is required, using EVP\_AEAD\_CTX\_init(3) with EVP\_aead\_chacha20\_poly1305(3) is recommended instead because the code then becomes transparent to the AEAD cipher used, more flexible, and less error prone.

With **EVP\_chacha20\_poly1305**(), EVP\_EncryptInit\_ex(3), EVP\_DecryptInit\_ex(3), and EVP\_CipherInit\_ex(3) take a *key* argument of 32 bytes = 256 bits and an *iv* argument of 12 bytes = 96 bits. This supports additional authenticated data (AAD) and produces a 128-bit authentication tag. The constant EVP\_CHACHAPOLY\_TLS\_TAG\_LEN specifies the length of the authentication tag in bytes and has a value of 16.

The following *type* arguments are supported for EVP\_CIPHER\_CTX\_ctrl(3):

- EVP\_CTRL\_AEAD\_GET\_TAG

  Copy the number of bytes indicated by the *arg* argument from the tag to the location indicated by the *ptr* argument; to be called after EVP\_EncryptFinal\_ex(3). This control operation fails if the *ctx* is not configured for encryption or if *arg* is less than 1 or greater than 16.

- EVP\_CTRL\_AEAD\_SET\_TAG

  Copy the number of bytes indicated by the *arg* argument from the location indicated by the *ptr* argument and designate them as the expected tag length and tag, causing subsequent EVP\_DecryptFinal\_ex(3) to fail if the tag calculated during decryption does not match. It is strongly recommended to specify *arg* as exactly 16. Otherwise, only the initial part of the tag may be compared and mismatches near the end of the tag may get silently ignored. This control operation fails if the *ctx* is configured for encryption or if *arg* is less than 1 or greater than 16. If the *ptr* argument is a NULL pointer, this control operation succeeds without having any effect.

- EVP\_CTRL\_AEAD\_SET\_IV\_FIXED

  Set the initialization vector by reading the 12 bytes pointed to by the *ptr* argument, independently of EVP\_EncryptInit\_ex(3), EVP\_DecryptInit\_ex(3), and EVP\_CipherInit\_ex(3). This control operation fails if the *arg* argument is not exactly 12.

- EVP\_CTRL\_AEAD\_SET\_IVLEN

  Instruct subsequent EVP\_EncryptInit\_ex(3), EVP\_DecryptInit\_ex(3), or EVP\_CipherInit\_ex(3) to expect an *iv* argument shorter than the default of 12 bytes; the *arg* argument specifies the number of bytes to be used. The initialization functions will only read the specified smaller number of bytes from *iv* and internally zero-pad them on the left. Using this is not recommended because it is likely more fragile and less often tested than the equivalent method of simply providing a full-sized *iv*. This control operation fails if *arg* is less than 1 or greater than 16.

- EVP\_CTRL\_INIT

  Set the length of the initialization vector to the default value of 12 bytes and clear the Poly1305 internal state. The application program usually does not need to invoke this control operation manually because it is automatically called internally by EVP\_EncryptInit\_ex(3), EVP\_DecryptInit\_ex(3), and EVP\_CipherInit\_ex(3).

## RETURN VALUES

**EVP\_chacha20**() and **EVP\_chacha20\_poly1305**() return pointers to static *EVP\_CIPHER* objects that contain the implementations of the symmetric cipher.

If *ctx* was created from **EVP\_chacha20**() or **EVP\_chacha20\_poly1305**(), EVP\_CIPHER\_CTX\_ctrl(3) returns 1 for success or 0 for failure.

## SEE ALSO

ChaCha(3), evp(3), EVP\_aead\_chacha20\_poly1305(3), EVP\_CIPHER\_meth\_new(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.

## HISTORY

**EVP\_chacha20**() first appeared in OpenBSD 5.6.

**EVP\_chacha20\_poly1305**() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 7.2.

## 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, May 2018.

In particular, the original version used a nonce of 8 instead of 12 bytes.