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);
chacha20
ChaCha20 encryption (RFC 8439 §2.4): data xored with the keystream from block counter on, which both encrypts and decrypts.
chacha20Block
The ChaCha20 block function (RFC 8439 §2.3): the 64 bytes of keystream for block counter under key and nonce.
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.
chacha20Poly1305Open
AEAD_CHACHA20_POLY1305 decryption (RFC 8439 §2.8): the plaintext of sealed, ciphertext then tag, when the tag authenticates it and aad.
chacha20Poly1305Seal
AEAD_CHACHA20_POLY1305 encryption (RFC 8439 §2.8): the ciphertext of plaintext followed by the 16-byte tag over it and aad.
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.
poly1305
Poly1305 (RFC 8439 §2.5): the 16-byte tag of msg under the one-time key key, r then s.
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.
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[]requiredThe 32-byte key; it is read, not kept, and the caller still wipes it.
counteru32requiredThe block number the keystream starts at.
nonceu8[]requiredThe 12-byte nonce.
datau8[]requiredThe bytes to encrypt or decrypt; it is read, not changed.
returnsu8[] | nullA 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[]requiredThe 32-byte key; it is read, not kept, and the caller still wipes it.
counteru32requiredThe block number.
nonceu8[]requiredThe 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[]requiredThe 32-byte header-protection key; it is read, not kept.
sampleu8[]requiredThe 16 bytes sampled from the packet's ciphertext.
returnsu8[] | nullA 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[]requiredThe 32-byte key; it is read, not kept, and the caller still wipes it.
nonceu8[]requiredThe 12-byte nonce the message was sealed with.
aadu8[]requiredThe data authenticated with it; must match what was sealed.
sealedu8[]requiredThe 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[]requiredThe 32-byte key; it is read, not kept, and the caller still wipes it.
nonceu8[]requiredThe 12-byte nonce; it must never repeat under one key.
aadu8[]requiredData authenticated but not encrypted; may be empty.
plaintextu8[]requiredThe 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[]requiredThe words to start from; it is read, not changed.
ai32requiredThe first word position.
bi32requiredThe second word position.
ci32requiredThe third word position.
di32requiredThe 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[]requiredThe message to authenticate.
returnsu8[] | nullA 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[]requiredThe 32-byte key; it is read, not kept, and the caller still wipes it.
nonceu8[]requiredThe 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).

