tc_chacha
The original ChaCha, IETF ChaCha20 (RFC 8439) and XChaCha20 stream ciphers,
with portable and RustCrypto engines. Every engine implements the
tc_stream_cipher traits, and a
selecting engine for each variant uses RustCrypto where the build provides it
and it covers the request. Every engine is constant time.
The crate is no_std, needs no allocator and contains no unsafe code. It
depends on tc_stream_cipher and
tc_zeroize, and on RustCrypto's
chacha20 and
cipher only with the default-off
rustcrypto feature.
Requires Rust 1.85 or later (edition 2024) for the default build. The optional
rustcrypto feature follows the minimum Rust version of the chacha20 and
cipher crates instead, which is 1.85 for chacha20 0.10.2 and cipher
0.5.2.
Types
ChaChaEngine— the original ChaCha on the RustCrypto engine withrustcryptofor a 32-byte key at 20 rounds, otherwise on the portable engine; constant time.ChaCha7539Engine— IETF ChaCha20 on the RustCrypto engine withrustcrypto, otherwise on the portable engine; constant time.XChaCha20Engine— XChaCha20, chosen the same way; constant time.ChaChaPortableEngine,ChaCha7539PortableEngine,XChaCha20PortableEngine— portable Rust; constant time.ChaChaRustCryptoEngine,ChaCha7539RustCryptoEngine,XChaCha20RustCryptoEngine(rustcrypto) — RustCrypto'schacha20, which uses SIMD where the processor has it; constant time, 32-byte keys and 20 rounds only.
The original ChaCha takes a 16- or 32-byte key and an 8-byte nonce, with a
64-bit block counter and an even round count, 20 unless
ChaChaEngine::with_rounds or ChaChaPortableEngine::with_rounds picks
another; 8 and 12 are the reduced-round variants, and a zero or odd count
returns InitError::InvalidRounds. IETF ChaCha20 takes a 32-byte key and a
12-byte nonce, with a 32-bit block counter. XChaCha20 takes a 32-byte key and a
24-byte nonce, long enough to choose at random: HChaCha20 derives a subkey from
the key and the first 16 nonce bytes, and IETF ChaCha20 runs on the rest.
Another key or nonce length returns InitError::InvalidKeyLength or
InitError::InvalidIvLength and keeps the previous key, nonce and position.
The direction is ignored, since both apply the same keystream, which starts at
block zero. process_bytes XORs the input into the start of the output and
returns the input length, leaving any longer tail of the output untouched. It
returns StreamError::NotInitialised before init,
StreamError::BufferTooShort for an output shorter than the input, and
StreamError::CounterExhausted once IETF ChaCha20 or XChaCha20 would pass 232
blocks (256 GiB); errors leave the output and the position unchanged. The
original ChaCha stops just under 269 bytes with StreamError::MaxBytesExceeded
on the portable engine, and at 2^70 bytes on RustCrypto; neither is reachable
in practice.
Display writes "ChaCha20", or "ChaCha" and the round count,
"ChaCha7539" or "XChaCha20" without inspecting key material. Each engine
has KEY_BYTES and IV_BYTES constants, implements Default and has
const fn new. The crate constants DEFAULT_ROUNDS and BLOCK_BYTES hold the
default round count, 20, and the keystream block length, 64.
Features
rustcrypto(off by default) — adds the three RustCrypto engines, which the selecting engines then use wherever they cover the request; pulls in thechacha20andciphercrates and their minimum Rust version.
Enabling the feature never changes which keys, nonces or round counts are
accepted: 16-byte keys and reduced round counts, which RustCrypto lacks, stay
on ChaChaPortableEngine.
Usage
[]
= "0.1.0"
= "0.1.0"
This example checks the first keystream bytes of RFC 8439's appendix A.1 test vector 1, an all-zero key and nonce, then encrypts and decrypts a message:
use ChaCha7539Engine;
use ;
let = ;
let params = new;
let mut engine = new;
engine
.init
.expect;
let mut keystream = ;
assert_eq!;
assert_eq!;
engine.reset;
let mut ciphertext = ;
assert_eq!;
engine.init.unwrap;
let mut plaintext = ;
assert_eq!;
assert_eq!;
The crate documentation carries an executable example.
Security
Every engine is constant time. ChaCha uses only 32-bit additions, XORs and fixed rotations, and the engines branch only on lengths, the round count and the keystream position, which are public. The selecting engines choose their backend from the key length and the round count, and RustCrypto chooses its SIMD backend from the processor's features, all of which are public.
The portable engines wipe their key words and current keystream block on drop,
and XChaCha20 wipes its subkey once it is installed. The RustCrypto engines
wipe the cipher state and its buffered keystream through the zeroize
features of chacha20 and cipher. Wiping does not reach the caller's key
buffer or copies left in registers and on the stack.
This is a stream-cipher primitive, not a message-encryption format. It supplies no authentication. Never reuse a key and nonce pair, and use an AEAD such as ChaCha20-Poly1305 to protect messages. RFC 8439's encryption examples start the keystream at block one, leaving block zero for the Poly1305 key; these engines start at block zero.
Benchmarks
Key setup and keystream throughput for the portable and RustCrypto engines, and the commands to reproduce them, are in BENCHES.md.
Validation
The engines are tested against the original ChaCha vectors from the eSTREAM
reference implementation that Bouncy Castle's tests use: ChaCha20 with a
128-bit key at four offsets and with a 256-bit key past 64 KiB, and ChaCha12
and ChaCha8. IETF ChaCha20 is tested against the RFC 8439 encryption example,
and XChaCha20 against the XChaCha draft's encryption example and HChaCha20
vector. Contract tests cover error state, untouched output on errors, preserved
output tails, agreement between chunked, bulk and single-byte processing, both
directions, round-count validation, and ChaChaEngine switching backends as
the key length changes. Unit tests drive the byte limit and the 32-bit counter
to their ends. With rustcrypto, the portable engines are cross-checked
against RustCrypto's chacha20 on pseudorandom keys, nonces, lengths and
chunkings.
Missing public documentation and unsafe code are rejected by crate-level
lints.
Run these commands from the workspace root:
cargo test -p tc_chacha --locked
cargo test -p tc_chacha --locked --features rustcrypto
cargo clippy -p tc_chacha --all-targets --all-features --locked -- -D warnings
cargo fmt -p tc_chacha --check
cargo doc -p tc_chacha --no-deps --all-features --locked
Before a release, check the archive contents and run publication validation from a committed checkout:
cargo package -p tc_chacha --list --locked
cargo publish -p tc_chacha --dry-run --locked
The archive includes both license texts, this README, the changelog, the
benchmark results, the source, the integration tests and the benchmark. It must
not include target/ or other build artifacts.
License
Licensed under either the MIT license or the Apache License, Version 2.0, at your option.