nish/crypto/chacha20poly1305

The ChaCha20 stream cipher, the Poly1305 one-time authenticator and the AEAD built from the two, as RFC 8439 defines them, plus the ChaCha20 header-protection mask of RFC 9001 §5.4.4.

import {
  CHACHA20POLY1305_NONCE_SIZE,
  CHACHA20_BLOCK_SIZE,
  CHACHA20_HEADER_MASK_SIZE,
  CHACHA20_HEADER_SAMPLE_SIZE,
  CHACHA20_KEY_SIZE,
  POLY1305_KEY_SIZE,
  POLY1305_TAG_SIZE,
  chacha20,
  chacha20Block,
  chacha20HeaderMask,
  chacha20Poly1305Open,
  chacha20Poly1305Seal,
  chacha20QuarterRound,
  poly1305,
  poly1305KeyGen,
} from "nish/crypto/chacha20poly1305";
import { chacha20Poly1305Seal, chacha20Poly1305Open } from "nish/crypto/chacha20poly1305";

const sealed: u8[] | null = chacha20Poly1305Seal(key, nonce, aad, plaintext);
const opened: u8[] | null = chacha20Poly1305Open(key, nonce, aad, sealed);

A sealed message is the ciphertext followed by the 16-byte tag, the layout TLS 1.3 and QUIC put on the wire. Every function answers null for an input of the wrong length, and chacha20Poly1305Open answers null for a message that does not authenticate; nothing here panics on what a peer sent.

Written from the specification (RFC 8439 §2 and RFC 9001 §5.4.4), in this module's own structure: nothing here is ported from another implementation.

ChaCha20

ChaCha20 is sixteen u32 words of additions, rotations and xors, which is constant time as written: u32 arithmetic wraps by definition, and there is nothing to branch on. The twenty rounds run on locals rather than on an array so that the words stay in registers, and, as RFC 8439 §3 suggests, the state is built once per message and only its counter moves per block.

What is wiped

Every array a call fills from the key — the ChaCha20 state, the keystream block, the Poly1305 one-time key, its r and the accumulator, and on open the tag computed for comparison — is zeroed with wipe's volatile stores before the call returns, on the refusal path too, so that no optimiser can drop the zeroing of an array about to die. The caller's own key, and the words the rounds keep in registers, are not this module's to reach.

Poly1305

Poly1305 keeps its accumulator and its key r as five limbs of 26 bits each in u64, so limb i holds bits 26i to 26i + 25 of a 130-bit number. RFC 8439 §3 asks for constant-time arithmetic without saying how; 26-bit limbs are the common idea for 64-bit multiplies, and they are what makes the arithmetic fit: a limb product is below 2^56, five of them sum below 2^58, and 2^130 = 5 (mod p) folds the top of a product back into the bottom as a multiply by five.

poly1305Block says why each sum fits. The reduction is by carries and masks, and the final reduction into [0, p) picks between h and h - p with ctSelect on a mask made from a borrow, never with a comparison.

Constant time

Nothing branches on, or indexes by, a key, a keystream word, the accumulator or a tag. Every if and every loop bound is on a length, an offset or a block number, all of which the peer already knows. chacha20Poly1305Open computes the tag over the received ciphertext and compares all sixteen bytes by ORing their differences into one word before it decrypts anything, and a mismatch is decided on that one word.

Verified by disassembly (tests/cases/ct_asm_chacha20poly1305, read by tests/ct-asm.js for x86-64 and aarch64): the key clamp, one Poly1305 block (the load, the multiply and the partial reduction), the final reduction and the addition of s, and the tag compare, each straight-line with no secret-addressed load. The fixture holds copies of those four functions, because the check reads one compiled module; tests/link/crypto_chacha20poly1305 holds the copies to these originals. The ChaCha20 rounds and the loops that drive both halves are discipline, not proof: the check refuses a loop's own back-edge, so it cannot read them.

Private names carry the chacha20 / poly1305 prefix because a std/ module's private functions share the importing program's flat symbol namespace (docs/wp26-stdlib.md §3e).

Functions

chacha20

ChaCha20 encryption (RFC 8439 §2.4): data xored with the keystream from block counter on, which both encrypts and decrypts. Answers null unless key is CHACHA20_KEY_SIZE bytes and nonce is CHACHA20POLY1305_NONCE_SIZE, and null when data would run the 32-bit counter past its last value rather than repeat the keystream.

const chacha20: (
  key: u8[],
  counter: u32,
  nonce: u8[],
  data: u8[],
) => u8[] | null
keyu8[]required

The 32-byte key; it is read, not kept, and the caller still wipes it.

counteru32required

The block number the keystream starts at.

nonceu8[]required

The 12-byte nonce.

datau8[]required

The bytes to encrypt or decrypt; it is read, not changed.

returnsu8[] | null

A fresh array of data.length bytes, or null for bad input.

chacha20Block

The ChaCha20 block function (RFC 8439 §2.3): the 64 bytes of keystream for block counter under key and nonce. Answers null unless key is CHACHA20_KEY_SIZE bytes and nonce is CHACHA20POLY1305_NONCE_SIZE.

const chacha20Block: (
  key: u8[],
  counter: u32,
  nonce: u8[],
) => u8[] | null
keyu8[]required

The 32-byte key; it is read, not kept, and the caller still wipes it.

counteru32required

The block number.

nonceu8[]required

The 12-byte nonce.

returnsu8[] | null

64 fresh bytes of keystream, secret like the key, or null for a bad key or nonce length.

chacha20HeaderMask

The ChaCha20 header-protection mask of RFC 9001 §5.4.4: the first five bytes of the keystream block whose counter is the first four bytes of sample (little-endian) and whose nonce is the other twelve, under the header-protection key hpKey. Answers null unless hpKey is CHACHA20_KEY_SIZE bytes and sample is CHACHA20_HEADER_SAMPLE_SIZE.

const chacha20HeaderMask: (
  hpKey: u8[],
  sample: u8[],
) => u8[] | null
hpKeyu8[]required

The 32-byte header-protection key; it is read, not kept.

sampleu8[]required

The 16 bytes sampled from the packet's ciphertext.

returnsu8[] | null

A fresh 5-byte mask, or null for a bad key or sample length.

chacha20Poly1305Open

AEAD_CHACHA20_POLY1305 decryption (RFC 8439 §2.8): the plaintext of sealed, ciphertext then tag, when the tag authenticates it and aad.

The tag is computed over the received ciphertext and compared in constant time before a byte is decrypted, so a forgery gets null and nothing else. Answers null too unless key is CHACHA20_KEY_SIZE bytes and nonce is CHACHA20POLY1305_NONCE_SIZE, and when sealed is shorter than a tag.

const chacha20Poly1305Open: (
  key: u8[],
  nonce: u8[],
  aad: u8[],
  sealed: u8[],
) => u8[] | null
keyu8[]required

The 32-byte key; it is read, not kept, and the caller still wipes it.

nonceu8[]required

The 12-byte nonce the message was sealed with.

aadu8[]required

The data authenticated with it; must match what was sealed.

sealedu8[]required

The ciphertext followed by its 16-byte tag.

returnsu8[] | null

A fresh array holding the plaintext, or null if the tag fails or the input is bad.

chacha20Poly1305Seal

AEAD_CHACHA20_POLY1305 encryption (RFC 8439 §2.8): the ciphertext of plaintext followed by the 16-byte tag over it and aad. A nonce must never be used twice with one key. Answers null unless key is CHACHA20_KEY_SIZE bytes and nonce is CHACHA20POLY1305_NONCE_SIZE, or when the sealed message would not fit in an array.

const chacha20Poly1305Seal: (
  key: u8[],
  nonce: u8[],
  aad: u8[],
  plaintext: u8[],
) => u8[] | null
keyu8[]required

The 32-byte key; it is read, not kept, and the caller still wipes it.

nonceu8[]required

The 12-byte nonce; it must never repeat under one key.

aadu8[]required

Data authenticated but not encrypted; may be empty.

plaintextu8[]required

The message to encrypt; it is read, not kept.

returnsu8[] | null

A fresh array of ciphertext then tag, plaintext.length + 16 bytes, or null for bad input.

chacha20QuarterRound

One quarter round (RFC 8439 §2.1, §2.2) on a copy of state, at the four word positions a, b, c and d, which is what §2.1.1 and §2.2.1 test. chacha20Core does the same on locals. Answers null when a position is not inside state.

const chacha20QuarterRound: (
  state: u32[],
  a: i32,
  b: i32,
  c: i32,
  d: i32,
) => u32[] | null
stateu32[]required

The words to start from; it is read, not changed.

ai32required

The first word position.

bi32required

The second word position.

ci32required

The third word position.

di32required

The fourth word position.

returnsu32[] | null

A fresh copy of state with the quarter round applied, or null for a position outside it.

poly1305

Poly1305 (RFC 8439 §2.5): the 16-byte tag of msg under the one-time key key, r then s. A key must never authenticate two messages; the AEAD below makes a fresh one per nonce. Answers null unless key is POLY1305_KEY_SIZE bytes.

const poly1305: (key: u8[], msg: u8[]) => u8[] | null
keyu8[]required

The 32-byte one-time key, r then s; it is read, not kept, and the caller still wipes it.

msgu8[]required

The message to authenticate.

returnsu8[] | null

A fresh 16-byte tag, or null for a bad key length.

poly1305KeyGen

The Poly1305 one-time key of RFC 8439 §2.6: the first 32 bytes of the ChaCha20 block with counter 0 under the AEAD's key and nonce. Answers null unless key is CHACHA20_KEY_SIZE bytes and nonce is CHACHA20POLY1305_NONCE_SIZE.

const poly1305KeyGen: (
  key: u8[],
  nonce: u8[],
) => u8[] | null
keyu8[]required

The 32-byte key; it is read, not kept, and the caller still wipes it.

nonceu8[]required

The 12-byte nonce.

returnsu8[] | null

A fresh 32-byte one-time key, which the caller wipes, or null for a bad key or nonce length.

Constants

12

CHACHA20POLY1305_NONCE_SIZE: i32

The length of the AEAD's nonce, and of ChaCha20's, in bytes (RFC 8439 §2.3, §2.8).

64

CHACHA20_BLOCK_SIZE: i32

The length of a ChaCha20 block, and of the keystream one block makes, in bytes.

5

CHACHA20_HEADER_MASK_SIZE: i32

The length of a header-protection mask in bytes (RFC 9001 §5.4.1).

16

CHACHA20_HEADER_SAMPLE_SIZE: i32

The length of the header-protection sample in bytes (RFC 9001 §5.4.2).

32

CHACHA20_KEY_SIZE: i32

The length of a ChaCha20 key in bytes (RFC 8439 §2.3).

32

POLY1305_KEY_SIZE: i32

The length of a Poly1305 one-time key, r then s, in bytes (RFC 8439 §2.5).

16

POLY1305_TAG_SIZE: i32

The length of a Poly1305 tag in bytes (RFC 8439 §2.5).