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). 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
NULLpointer, 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.