CHACHA(3) FreeBSD Library Functions Manual CHACHA(3)
NAME
ChaCha_set_key, ChaCha_set_iv, ChaCha, CRYPTO_chacha_20,
CRYPTO_hchacha_20, CRYPTO_xchacha_20 - ChaCha20 stream cipher
SYNOPSIS
#include <openssl/chacha.h>
void
ChaCha_set_key(ChaCha_ctx *ctx, const unsigned char *key,
unsigned int keybits);
void
ChaCha_set_iv(ChaCha_ctx *ctx, const unsigned char *iv,
const unsigned char *counter);
void
ChaCha(ChaCha_ctx *ctx, unsigned char *out, const unsigned char *in,
size_t len);
void
CRYPTO_chacha_20(unsigned char *out, const unsigned char *in, size_t len,
const unsigned char key[32], const unsigned char iv[8],
uint64_t counter);
void
CRYPTO_hchacha_20(unsigned char out[32], const unsigned char key[32],
const unsigned char iv[16]);
void
CRYPTO_xchacha_20(unsigned char *out, const unsigned char *in,
size_t len, const unsigned char key[32], const unsigned char iv[24]);
DESCRIPTION
These functions provide a low-level implementation of the ChaCha stream
cipher with 256 and 128-bit keys. The number of rounds is hardcoded to
20; variants with 8 or 12 rounds are not supported.
Instead of using these functions directly, application programs normally
use the more portable EVP_chacha20(3) high-level interface.
The ChaCha state is contained in the ChaCha_ctx structure and consists of
sixteen 32-bit unsigned integers.
For the recommended value of 256 keybits, ChaCha_set_key() copies 32
bytes (256 bits) from key to the middle eight integers of the ChaCha
state, using little endian order for each integer. For the alternative
value of 128 keybits, only 16 bytes (128 bits) are copied from key to the
ChaCha state, but they are copied twice, once to the second quarter and
once to the third quarter. The first quarter of the ChaCha state is set
to four constant integers; these constants differ depending on whether
keybits is 128 or 256. The last quarter of the ChaCha state remains
unchanged.
ChaCha_set_iv() copies eight bytes (64 bits) from counter and eight bytes
(64 bits) from iv to the last quarter of the ChaCha state, the counter to
the first two integers and the initialization vector to the last two
integers, again in little endian order. If counter is NULL, the two
respective integers are set to 0 instead. The first three quarters of
the ChaCha state remain unchanged.
ChaCha() encrypts len bytes of data from in to out using the ctx that was
previously set up with ChaCha_set_key() and ChaCha_set_iv(). Providing
an out buffer of at least len bytes is the responsibility of the caller.
This function can be called multiple times in a row with varying len
arguments. The len does not need to be a multiple of 64.
CRYPTO_chacha_20() encrypts len bytes of data from in to out in a one-
shot operation, using the given key and iv as described for
ChaCha_set_key() and ChaCha_set_iv() and copying the less significant
half of counter to the first counter integer in the initial ChaCha state
and the more significant half to the second integer. Providing an out
buffer of at least len bytes is again the responsibility of the caller.
The maximum supported value for len is 2^32 - 1.
XChaCha is a variant of ChaCha designed to support longer nonces, just
like XSalsa20 is a variant of Salsa20 supporting longer nonces.
CRYPTO_xchacha_20() encrypts len bytes of data from in to out in a one-
shot operation with the XChaCha algorithm, using the given key and iv.
It is equivalent to CRYPTO_chacha_20() with the last third of iv, a
counter of 0, and a key generated with CRYPTO_hchacha_20() from the first
two thirds of iv.
SEE ALSO
crypto(3), EVP_chacha20(3)
Daniel J. Bernstein, ChaCha, a variant of Salsa20,
https://cr.yp.to/chacha/chacha-20080128.pdf, Chicago, January 28, 2008.
Daniel J. Bernstein, Extending the Salsa20 nonce,
https://cr.yp.to/snuffle/xsalsa-20110204.pdf, Chicago, August 22, 2017.
STANDARDS
RFC 8439: ChaCha20 and Poly1305 for IETF Protocols
Note that the standard specifies a 32-bit counter and a 96-bit
initialization vector whereas this implementation follows Bernstein's
original specification and uses a 64-bit counter and a 64-bit
initialization vector.
These functions are specific to LibreSSL and not provided by OpenSSL.
BoringSSL does provide CRYPTO_chacha_20(), but with an incompatible
interface, taking a 96-bit iv and a 32-bit counter.
HISTORY
ChaCha_set_key(), ChaCha_set_iv(), ChaCha(), and CRYPTO_chacha_20() first
appeared in OpenBSD 5.6.
CRYPTO_hchacha_20() and CRYPTO_xchacha_20() first appeared in
OpenBSD 6.5.
AUTHORS
This implementation was written by Daniel J. Bernstein <
[email protected]>.
The API layer was added by Joel Sing <
[email protected]> for ChaCha, and
for XChaCha by David Gwynne <
[email protected]>.
FreeBSD 14.1-RELEASE-p8 February 18, 2022 FreeBSD 14.1-RELEASE-p8