EVP_CHACHA20(3)

NAME
EVP_chacha20, EVP_chacha20_poly1305 - ChaCha20 stream cipher for EVP

SYNOPSIS
#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). Due to the symmetry of the internal cipher state, interpreting the iv argument as a 4 byte counter followed by a 12 byte nonce or interpreting it as an 8 byte counter followed by an 8 byte nonce is functionally equivalent. 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. 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 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 irgnored. 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 contol 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, November 2013, draft-agl-tls-chacha20poly1305-04, ChaCha20 and Poly1305 based Cipher Suites for TLS.

Y. Nir, A. Langley, May 2015, RFC 7539, ChaCha20 and Poly1305 for IETF Protocols.

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.