NAME

#include <monocypher.h>

void
crypto_ietf_chacha20(uint8_t *cipher_text, const uint8_t *plain_text, size_t text_size, const uint8_t key[32], const uint8_t nonce[12]);

uint32_t
crypto_ietf_chacha20_ctr(uint8_t *cipher_text, const uint8_t *plain_text, size_t text_size, const uint8_t key[32], const uint8_t nonce[12], const uint32_t ctr);

DESCRIPTION

These functions provide an interface for the ChaCha20 encryption primitive as specified by the IETF in RFC 8439. They are provided strictly for compatibility with existing systems or strict standards compliance. New programs are strongly encouraged to use crypto_xchacha20() instead.

ChaCha20 is a low-level primitive. Consider using authenticated encryption, implemented by crypto_lock().

The crypto_ietf_chacha20() and crypto_ietf_chacha20_ctr() functions behave the same as crypto_chacha20 and crypto_chacha20_ctr, respectively, but their counter and nonce have different sizes. The nonce encompasses 12 bytes and the counter is correspondingly reduced to 4 bytes. The short counter limits a single key and nonce pair to 256 GiB of data. A 12-bytes nonce is just barely too short to be safely chosen at random; use a message counter instead. RFC 8439 also permits linear feedback shift registers to generate nonces.

RETURN VALUES

crypto_ietf_chacha20() returns nothing. crypto_ietf_chacha20_ctr() returns the next ctr to use with the same key and nonce values; this is always text_size divided by 64, plus one if there was a remainder.

SEE ALSO

crypto_chacha20(), crypto_lock(), crypto_wipe(), intro()

STANDARDS

These functions implement ChaCha20 as described in RFC 8439.

HISTORY

crypto_ietf_chacha20() and crypto_ietf_chacha20_ctr() were added in Monocypher 3.0.0.

SECURITY CONSIDERATIONS

These functions exhibit a nonce reuse issue if the internal counter overflows, losing all confidentiality for the parts of the data for which the nonces overlap. When using crypto_ietf_chacha20(), this occurs when encrypting more than 256 GiB of data and then incrementing the nonce. More specifically, this can be triggered by encrypting more than 512 bytes with crypto_ietf_chacha20_ctr() at ctr = 0xffffffff then encrypting a message at nonce[0]+1 and ctr = 0; it can be observed that the keystreams are identical.

RFC 8439 only specifies that the upper limit of data per message is 256 GiB of data for a nonce pair with a counter starting at 0. It does not specify what actions can or should be taken when this limit is exceeded. Encrypting more than 256 GiB of data is therefore undefined behaviour. Monocypher may change the way it handles counter overflows at any time.