NAME

EVP_chacha20, EVP_chacha20_poly1305 — ChaCha20 stream cipher for EVP

SYNOPSIS

library “libcrypto”
#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.