Boring crypto that simply works


IETF Chacha20 encryption functions #include <monocypher.h>
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]);
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);


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 use differently-sized nonce and counter values. The nonce encompasses 12 bytes and the counter is correspondingly reduced to 4 bytes. The short counter limits a single pair of key and nonce to 256 GiB of data. A nonce of 12 bytes 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.


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.


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


These functions implement Chacha20 as described in RFC 8439.


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


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.
March 31, 2020 Linux 4.15.0-46-generic