Skip to main content

Crate tc_chacha

Crate tc_chacha 

Source
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§

ChaCha7539Engine
IETF ChaCha20 (RFC 8439): a 96-bit nonce and a 32-bit block counter, on RustCrypto’s ChaCha20 with the rustcrypto feature and on ChaCha7539PortableEngine without it. Both accept the same keys and IVs and stop after 2^32 blocks (256 GiB) with CounterExhausted.
ChaCha7539PortableEngine
IETF ChaCha20 (RFC 8439) in portable Rust: a 96-bit nonce and a 32-bit block counter.
ChaCha7539RustCryptoEngine
IETF ChaCha20 (RFC 8439): a 96-bit nonce and a 32-bit block counter, through RustCrypto’s ChaCha20.
ChaChaEngine
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_rounds picks another.
ChaChaPortableEngine
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_rounds picks another (8 and 12 are the reduced-round variants).
ChaChaRustCryptoEngine
The original ChaCha20 (Bernstein, 2008): a 64-bit nonce and a 64-bit block counter, through RustCrypto’s ChaCha20Legacy.
XChaCha20Engine
XChaCha20: a 192-bit nonce, long enough to choose at random, on RustCrypto’s XChaCha20 with the rustcrypto feature and on XChaCha20PortableEngine without it. Both accept the same keys and IVs.
XChaCha20PortableEngine
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.
XChaCha20RustCryptoEngine
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_rounds picks another.