chacha20.h File Reference

ChaCha20 stream cipher (D. J. Bernstein; RFC 8439). More...

#include "protocore_config.h"

Go to the source code of this file.

Classes
struct	Chacha20Ns
	Dispatch table. Addressed by offset, so the layout is asserted below. More...

Macros
#define	PROTOCORE_CHACHA20_KEY_LEN   32
	ChaCha20 key length in bytes.
#define	PROTOCORE_CHACHA20_BLOCK_LEN   64
	ChaCha20 keystream block length in bytes.

Functions
	PROTOCORE_NS_LAYOUT (Chacha20Ns, xor_, block_ietf)
proto_bool	protocore_chacha20_xor_ (uint8_t *work, const uint8_t *key, const uint8_t *iv, uint64_t counter, const uint8_t *in, uint8_t *out, size_t len)
	XOR the OpenSSH-layout keystream over in into out.
proto_bool	protocore_chacha20_block_ietf (uint8_t *work, const uint8_t *key, uint32_t counter, const uint8_t *nonce, uint8_t *out)
	One 64-byte keystream block in the RFC 8439 layout.

Variables
PROTOCORE_NS Chacha20Ns Chacha20	PROTOCORE_UNUSED
	Module namespace.

Detailed Description

ChaCha20 stream cipher (D. J. Bernstein; RFC 8439).

The 20-round ARX permutation used by the chach.nosp@m.a20-.nosp@m.poly1.nosp@m.305@.nosp@m.opens.nosp@m.sh.c.nosp@m.om cipher. Two views of the same core are exposed:

• Chacha20Ns::xor_ : the original ChaCha layout OpenSSH uses - a 64-bit little-endian block counter (state words 12-13) and a 64-bit nonce/IV (words 14-15). This is what the SSH AEAD drives; the counter increments per 64-byte block.
• Chacha20Ns::block_ietf : the RFC 8439 layout (32-bit counter in word 12, 96-bit nonce in words 13-15), exposed so the core can be checked against the published RFC 8439 Section 2.3.2 block test vector.

Pure ARX (add-rotate-xor): naturally constant-time, no tables, ~64-byte state. No heap.

The member is spelled xor_ because xor is an alternative token in C++, and this header reaches the C++ translation units.

work is PROTOCORE_CHACHA20_BORROW secure bytes the CALLER took, at an address it knows. It is not held past the call, so nothing here aliases it. The caller releases it, and the pool wipes on release; this module neither takes it, holds it, releases it, nor wipes it. The borrow IS the working state, so two keystreams in flight are two borrows and never collide.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file chacha20.h.

Macro Definition Documentation

PROTOCORE_CHACHA20_KEY_LEN

#define PROTOCORE_CHACHA20_KEY_LEN   32

ChaCha20 key length in bytes.

Definition at line 40 of file chacha20.h.

PROTOCORE_CHACHA20_BLOCK_LEN

#define PROTOCORE_CHACHA20_BLOCK_LEN   64

ChaCha20 keystream block length in bytes.

Definition at line 43 of file chacha20.h.

Function Documentation

PROTOCORE_NS_LAYOUT()

PROTOCORE_NS_LAYOUT	(	Chacha20Ns	,
		xor_	,
		block_ietf
	)

protocore_chacha20_xor_()

proto_bool protocore_chacha20_xor_	(	uint8_t *	work,
		const uint8_t *	key,
		const uint8_t *	iv,
		uint64_t	counter,
		const uint8_t *	in,
		uint8_t *	out,
		size_t	len
	)

XOR the OpenSSH-layout keystream over in into out.

Parameters

work	PROTOCORE_CHACHA20_BORROW bytes the caller took. Not held past the call.
key	PROTOCORE_CHACHA20_KEY_LEN bytes
iv	8-byte nonce; OpenSSH uses the packet sequence number, big-endian
counter	initial 64-bit block counter, stepping once per 64-byte block
in	plaintext, or ciphertext when decrypting; nullptr emits raw keystream
out	len bytes; may alias in
len	how many

Returns

PROTO_TRUE on success.

protocore_chacha20_block_ietf()

proto_bool protocore_chacha20_block_ietf	(	uint8_t *	work,
		const uint8_t *	key,
		uint32_t	counter,
		const uint8_t *	nonce,
		uint8_t *	out
	)

One 64-byte keystream block in the RFC 8439 layout.

Parameters

work	PROTOCORE_CHACHA20_BORROW bytes the caller took. Not held past the call.
key	PROTOCORE_CHACHA20_KEY_LEN bytes
counter	32-bit block counter, state word 12
nonce	12-byte nonce, state words 13-15
out	PROTOCORE_CHACHA20_BLOCK_LEN bytes

Returns

PROTO_TRUE on success.

Variable Documentation

PROTOCORE_UNUSED

PROTOCORE_NS Chacha20Ns Chacha20 PROTOCORE_UNUSED

Initial value:

= {.xor_ = protocore_chacha20_xor_,
                                                     .block_ietf = protocore_chacha20_block_ietf}

Module namespace.

Definition at line 79 of file chacha20.h.