facil.io
Cryptography & TLS

#ChaCha20 & Poly1305

c
#define FIO_CHACHA
#include "fio-stl.h"

ChaCha20 stream cipher, Poly1305 authenticator, and the ChaCha20-Poly1305 AEAD combination. Also includes XChaCha20-Poly1305 with a 192-bit nonce, which is safer for random nonces than the 96-bit variant.

Security note: this implementation has not been independently audited. Use at your own risk, and prefer a tested cryptographic library when one is available.

#ChaCha20-Poly1305 API

#fio_chacha20_poly1305_enc

c
SFUNC void fio_chacha20_poly1305_enc(void *restrict mac,
                                     void *restrict data,
                                     size_t len,
                                     const void *ad,
                                     size_t adlen,
                                     const void *key,
                                     const void *nonce);

In-place encryption with a 16-byte Poly1305 tag.

Parameters:

  • mac — output buffer; must have at least 16 writable bytes.
  • data — plaintext buffer; encrypted in place.
  • len — data length.
  • ad — additional authenticated data (not encrypted); may be NULL.
  • adlen — length of ad.
  • key — 32-byte key.
  • nonce — 12-byte nonce.

#fio_chacha20_poly1305_dec

c
SFUNC int fio_chacha20_poly1305_dec(void *restrict mac,
                                    void *restrict data,
                                    size_t len,
                                    const void *ad,
                                    size_t adlen,
                                    const void *key,
                                    const void *nonce);

In-place decryption with tag verification.

Returns: 0 on success, -1 if authentication fails. On failure data is zeroed.

#fio_chacha20_poly1305_auth

c
SFUNC void fio_chacha20_poly1305_auth(void *restrict mac,
                                      void *restrict data,
                                      size_t len,
                                      const void *ad,
                                      size_t adlen,
                                      const void *key,
                                      const void *nonce);

Computes the Poly1305 tag for already-encrypted data without decrypting it.

#Standalone ChaCha20 / Poly1305

#fio_chacha20

c
SFUNC void fio_chacha20(void *restrict data,
                        size_t len,
                        const void *key,
                        const void *nonce,
                        uint32_t counter);

In-place ChaCha20 encryption or decryption.

Parameters:

  • data — buffer to transform in place.
  • len — buffer length.
  • key — 32-byte key.
  • nonce — 12-byte nonce.
  • counter — block counter; usually 1 unless resuming mid-ciphertext.

#fio_poly1305_auth

c
SFUNC void fio_poly1305_auth(void *restrict mac_dest,
                             void *restrict message,
                             size_t len,
                             const void *ad,
                             size_t ad_len,
                             const void *key256bits);

Computes a Poly1305 MAC for message and ad using a 32-byte key.

Parameters:

  • mac_dest — output buffer; must have at least 16 writable bytes.
  • message — message to authenticate; may be NULL if len is 0.
  • len — message length.
  • ad — additional data; may be NULL.
  • ad_len — additional data length.
  • key256bits — 32-byte Poly1305 key.

#XChaCha20-Poly1305 API

XChaCha20 uses a 24-byte nonce, making random nonces safe from birthday-bound collisions.

#fio_xchacha20_poly1305_enc

c
SFUNC void fio_xchacha20_poly1305_enc(void *restrict mac,
                                      void *restrict data,
                                      size_t len,
                                      const void *ad,
                                      size_t adlen,
                                      const void *key,
                                      const void *nonce);

Same shape as fio_chacha20_poly1305_enc, but nonce must be 24 bytes.

#fio_xchacha20_poly1305_dec

c
SFUNC int fio_xchacha20_poly1305_dec(void *restrict mac,
                                     void *restrict data,
                                     size_t len,
                                     const void *ad,
                                     size_t adlen,
                                     const void *key,
                                     const void *nonce);

Same shape as fio_chacha20_poly1305_dec, but nonce must be 24 bytes.

#fio_xchacha20

c
SFUNC void fio_xchacha20(void *restrict data,
                         size_t len,
                         const void *key,
                         const void *nonce,
                         uint32_t counter);

In-place XChaCha20 encryption or decryption.

#Example

c
#define FIO_CHACHA
#include "fio-stl.h"

int main(void) {
  uint8_t key[32] = {0};
  uint8_t nonce[12] = {0};
  uint8_t msg[32] = "hello, chacha world!";
  uint8_t tag[16];

  fio_rand_bytes_secure(key, sizeof(key));
  fio_rand_bytes_secure(nonce, sizeof(nonce));

  fio_chacha20_poly1305_enc(tag, msg, sizeof(msg), NULL, 0, key, nonce);

  if (fio_chacha20_poly1305_dec(tag, msg, sizeof(msg), NULL, 0, key, nonce)) {
    printf("authentication failed\n");
    return 1;
  }
  return 0;
}