CRYPTO_CHACHA20(3MONOCYPHER)

💖 crypto_chacha20 — ChaCha20 & XChaCha20 encryption functions 💖

okay bestie, you're looking at the 3monocypher manual page for the ChaCha20 squad: crypto_chacha20_djb, crypto_chacha20_ietf, crypto_chacha20_x, and crypto_chacha20_h. Part 1 is giving low-level encryption realness, and we are keeping every literal detail — no cap. 💅

---

✨ NAME ✨

crypto_chacha20_djb, crypto_chacha20_ietf, crypto_chacha20_x, crypto_chacha20_h — ChaCha20 and XChaCha20 encryption functions.

---

🌸 SYNOPSIS 🌸

#include <monocypher.h>

uint64_t
crypto_chacha20_djb(uint8_t *cipher_text, const uint8_t *plain_text,
    size_t text_size, const uint8_t key[32], const uint8_t nonce[8],
    uint64_t ctr);

uint32_t
crypto_chacha20_ietf(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 ctr);

uint64_t
crypto_chacha20_x(uint8_t *cipher_text, const uint8_t *plain_text,
    size_t text_size, const uint8_t key[32], const uint8_t nonce[24],
    uint64_t ctr);

void
crypto_chacha20_h(uint8_t out[32], const uint8_t key[32],
    const uint8_t in[16]);

---

🦋 DESCRIPTION 🦋

These functions hand you an interface for the ChaCha20 encryption primitive. ChaCha20 is a low-level primitive, so consider using authenticated encryption instead — that's implemented by crypto_aead_lock(3monocypher). 🫶

The arguments are:

• key — a 32-byte secret key.
• nonce — an 8-byte, 12-byte, or 24-byte number used only once with any given key. It does not need to be secret or random, but it does have to be unique. Repeating a nonce with the same key reveals the XOR of two different messages, which allows decryption. 24-byte nonces can be selected at random. 8-byte and 12-byte nonces cannot because they are too small and the same nonce may be selected twice by accident. See intro(3monocypher) for advice about generating random numbers (use the operating system's random number generator).
• plain_text — the message to encrypt. It is allowed to be NULL, in which case it will be interpreted as an all-zero input. cipher_text will then contain the raw ChaCha20 stream.
• cipher_text — the encrypted message.
• text_size — length of both plain_text and cipher_text, in bytes.
• ctr — the number of 64-byte blocks we skip from the beginning of the stream. This can be used to encrypt (or decrypt) part of a long message or to implement some AEAD constructions such as the one described in RFC 8439. Should be zero by default. When using this, be careful not to accidentally reuse parts of the random stream as that would destroy confidentiality. The return value can help here. 👑

The key and nonce buffers may overlap. plain_text and cipher_text must either be the same buffer (for in-place encryption) or non-overlapping.

crypto_chacha20_djb(), crypto_chacha20_ietf(), and crypto_chacha20_x() perform a ChaCha20 operation. Their main difference is the size of their nonce and counter. crypto_chacha20_ietf() in particular implements RFC 8439, and is provided strictly for compatibility with existing systems or standards compliance.

crypto_chacha20_x() is the only function that uses a nonce long enough to be random. This makes it easier to use securely, and the performance hit of the extended nonce is often negligible in practice. Use it instead of crypto_chacha20_djb() and crypto_chacha20_ietf() if possible. ✨

The crypto_chacha20_djb(), crypto_chacha20_ietf(), and crypto_chacha20_x() encrypt plain_text by XORing it with a pseudo-random stream of numbers, seeded by the provided key and nonce.

Since XOR is its own inverse, decryption is the same operation as encryption. To decrypt the cipher text, “encrypt” it again with the same key and nonce. You will likely want to wipe the key when you are done with encryption or decryption. Use crypto_wipe(3monocypher) to wipe them. 🧚

The plain_text pointer is allowed to be NULL, in which case it will be interpreted as an all-zero input. This is useful as a user space random number generator. While this should not be used as a random number generator for secrets, for which the operating system random number generator should be preferred, it can be handy outside of a security context. Deterministic procedural generation and reproducible property-based tests come to mind. Additionally, it can be used to generate large amounts of random-looking data quickly — for example to generate padding. 💜

---

⭐ RETURN VALUES ⭐

crypto_chacha20_djb(), crypto_chacha20_ietf(), and crypto_chacha20_x() return the next ctr to use with the same key and nonce values; this is the previous ctr, plus text_size divided by 64 (rounded up).

---

🌈 EXAMPLES 🌈

The following examples assume the existence of arc4random_buf(), which fills the given buffer with cryptographically secure random bytes. If arc4random_buf() does not exist on your system, see intro(3monocypher) for advice about how to generate cryptographically secure random bytes.

Simple encryption: ✨

uint8_t key        [ 32]; /* Secret random key              */
uint8_t nonce      [ 24]; /* Unique nonce (possibly random) */
uint8_t plain_text [500] = {1}; /* Secret message           */
uint8_t cipher_text[500]; /* Encrypted message              */
arc4random_buf(key,   32);
arc4random_buf(nonce, 24);
crypto_chacha20_x(cipher_text, plain_text, 500, key, nonce, 0);
/* Wipe secrets if they are no longer needed */
crypto_wipe(key,        32);
crypto_wipe(plain_text, 500);

To decrypt the above:

uint8_t       key        [ 32]; /* Same key as above        */
const uint8_t nonce      [ 24]; /* Same nonce as above      */
uint8_t       cipher_text[500]; /* Message to decrypt       */
uint8_t       plain_text [500]; /* Secret message           */
crypto_chacha20_x(plain_text, cipher_text, 500, key, nonce, 0);
/* Wipe secrets if they are no longer needed */
crypto_wipe(key,        32);
/* The plaintext likely needs to be processed before you wipe it */
crypto_wipe(plain_text, 12);

Incremental encryption (in blocks of 64 bytes):

uint8_t  key        [ 32]; /* Secret random key              */
uint8_t  nonce      [ 24]; /* Unique nonce (possibly random) */
uint8_t  plain_text [500]; /* Secret message                 */
uint8_t  cipher_text[500]; /* Encrypted message              */
uint64_t ctr = 0;          /* Block counter                  */
unsigned int i;
arc4random_buf(key,   32);
arc4random_buf(nonce, 24);
for(i = 0; i < 500; i += 64) {
    ctr = crypto_chacha20_x(cipher_text+i, plain_text+i, 64,
                            key, nonce, ctr);
}
/* Process data that didn't fit into 64-byte pieces */
crypto_chacha20_x(cipher_text+500-(i-64),
                  plain_text+500-(i-64),
                  500-(i-64),
                  key, nonce, ctr);
/* Wipe secrets if they are no longer needed */
crypto_wipe(key,        32);
crypto_wipe(plain_text, 500);

Encryption by jumping around (do not do this, this is only meant to show how the counter works): 💀

uint8_t key        [ 32]; /* Secret random key              */
uint8_t nonce      [ 24]; /* Unique nonce (possibly random) */
uint8_t plain_text [500] = {1}; /* Message to be encrypted  */
uint8_t cipher_text[500]; /* Will be the encrypted message  */
arc4random_buf(key,   32);
arc4random_buf(nonce, 24);
/* Encrypt the second part of the message first... */
crypto_chacha20_x(cipher_text + (3 * 64),
                  plain_text  + (3 * 64),
                  500         - (3 * 64),
                  key, nonce, 3);
/* ...then encrypt the first part */
crypto_chacha20_x(cipher_text, plain_text, 3 * 64, key, nonce, 0);
/* Wipe secrets if they are no longer needed */
crypto_wipe(key,        32);
crypto_wipe(plain_text, 500);

🔐 SECURITY CONSIDERATIONS 🔐

🚨 Encrypted does not mean secure 🚨

Okay bestie, this is the part where we get real: ChaCha20 only protects against eavesdropping, not forgeries. Most applications need protection against forgeries to be properly secure. To ensure the integrity of a message, use BLAKE2b in keyed mode or authenticated encryption; see crypto_blake2b(3monocypher) and crypto_aead_lock(3monocypher).

---

🌸 Nonce reuse 🌸

Repeating a nonce with the same key exposes the XOR of two or more plaintext messages, effectively destroying confidentiality. Like, literally the whole point of confidentiality? Gone. 😭

For the same reason, do not select small nonces at random. The crypto_chacha20_djb() nonce spans only 64 bits, which is small enough to trigger accidental reuses. A message counter should be used instead.

If multiple parties send out messages, each can start with an initial nonce of 0, 1, 2 (...) n-1 respectively, and increment them by n for each new message. Make sure the counters never wrap around. No accidental loop-de-loops, bestie — that's not the vibe. 💅

---

🎲 Secure random number generation 🎲

Do not use these functions as a cryptographic random number generator. Always use the operating system's random number generator for cryptographic purposes; see intro(3monocypher).

---

🛡️ Protection against side channels 🛡️

Secrets should not dwell in memory longer than needed. Use crypto_wipe(3monocypher) to erase secrets you no longer need. For ChaCha20, this means the key and in some cases the plaintext itself. Wipe it, don't leave it lingering like an unread group chat. 🫶

---

That's the tea from the Debian build, dated February 25, 2023, for CRYPTO_CHACHA20(3MONOCYPHER) — stay secret, stay secure, and wipe your keys, bestie. 💖✨