Expand description
ChaCha, IETF ChaCha20 (RFC 8439) and XChaCha20 stream ciphers.
Every engine implements the tc_stream_cipher traits and takes its key
and nonce through any container that implements both
KeyParams and
IvParams, such as
KeyWithIvRef.
§Choosing an engine
ChaChaEngine, ChaCha7539Engine and XChaCha20Engine pick their
backend: RustCrypto’s chacha20, which uses SIMD where the processor has
it, when the rustcrypto Cargo feature is enabled and covers the request,
otherwise the portable engines. 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. Every
engine is constant time. For explicit selection, the portable engines are
always available, and ChaChaRustCryptoEngine,
ChaCha7539RustCryptoEngine and XChaCha20RustCryptoEngine are available
with the rustcrypto feature.
§Example
The first keystream bytes of RFC 8439’s appendix A.1 test vector 1, an all-zero key and nonce:
use tc_chacha::ChaCha7539Engine;
use tc_stream_cipher::{CipherDirection, KeyWithIvRef, StreamCipher, StreamCipherInit};
let (key, nonce) = ([0u8; 32], [0u8; 12]);
let mut engine = ChaCha7539Engine::new();
engine.init(CipherDirection::Encrypt, &KeyWithIvRef::new(&key, &nonce))?;
let mut keystream = [0u8; 8];
assert_eq!(engine.process_bytes(&[0; 8], &mut keystream)?, 8);
assert_eq!(keystream, [0x76, 0xb8, 0xe0, 0xad, 0xa0, 0xf1, 0x3d, 0x90]);Every engine starts the keystream at block zero, whereas RFC 8439’s encryption examples start at block one, leaving block zero for the Poly1305 key. The crate provides no authentication: never reuse a key and nonce pair, and use an AEAD such as ChaCha20-Poly1305 to protect messages.
Structs§
- ChaCha7539
Engine - IETF ChaCha20 (RFC 8439): a 96-bit nonce and a 32-bit block counter,
on RustCrypto’s
ChaCha20with therustcryptofeature and onChaCha7539PortableEnginewithout it. Both accept the same keys and IVs and stop after 2^32 blocks (256 GiB) withCounterExhausted. - ChaCha7539
Portable Engine - IETF ChaCha20 (RFC 8439) in portable Rust: a 96-bit nonce and a 32-bit block counter.
- ChaCha7539
Rust Crypto Engine - IETF ChaCha20 (RFC 8439): a 96-bit nonce and a 32-bit block counter,
through RustCrypto’s
ChaCha20. - ChaCha
Engine - The original ChaCha (Bernstein, 2008): a 64-bit nonce and a 64-bit block
counter, with a 16- or 32-byte key and an even round count, 20 unless
with_roundspicks another. - ChaCha
Portable Engine - The original ChaCha (Bernstein, 2008) in portable Rust: a 64-bit nonce
and a 64-bit block counter, with a 16- or 32-byte key and an even round
count, 20 unless
with_roundspicks another (8 and 12 are the reduced-round variants). - ChaCha
Rust Crypto Engine - The original ChaCha20 (Bernstein, 2008): a 64-bit nonce and a 64-bit
block counter, through RustCrypto’s
ChaCha20Legacy. - XCha
Cha20 Engine - XChaCha20: a 192-bit nonce, long enough to choose at random, on
RustCrypto’s
XChaCha20with therustcryptofeature and onXChaCha20PortableEnginewithout it. Both accept the same keys and IVs. - XCha
Cha20 Portable Engine - XChaCha20 in portable Rust: HChaCha20 derives a subkey from the key and the first 16 nonce bytes, then IETF ChaCha20 runs on the rest. The 192-bit nonce is long enough to choose at random.
- XCha
Cha20 Rust Crypto Engine - XChaCha20: HChaCha20 derives a subkey from the key and the first 16
nonce bytes, then IETF ChaCha20 runs on the rest, through RustCrypto’s
XChaCha20. The 192-bit nonce is long enough to choose at random.
Constants§
- BLOCK_
BYTES - Keystream block length in bytes.
- DEFAULT_
ROUNDS - Round count of ChaCha20, used unless
ChaChaEngine::with_roundspicks another.