tc_stream_cipher
Shared traits, error types and key and IV containers for stream ciphers.
Engine crates such as tc_chacha
implement the traits, and generic code that applies a keystream names only the
capabilities it uses. The crate implements no algorithm or authentication.
It is no_std, contains no unsafe code, and depends only on
tc_zeroize, which wipes the owned
containers. A single, default-off alloc feature adds heap-backed containers
through the sysroot alloc crate.
Requires Rust 1.85 or later (edition 2024).
Traits
StreamCipherInit<P>—initinstalls a key and IV, or engine-specific parameters, for one direction.StreamCipher—process_bytesandreturn_byteapply the keystream;resetreturns to its start.KeyParams—keyborrows the key bytes.IvParams—ivborrows the IV (nonce) bytes.
Initialization and processing are separate traits so generic callers can state
exactly which capabilities they need, and StreamCipher stays usable as a
trait object. The key and the IV are separate traits because some stream
ciphers, such as RC4, take no IV. Accepted key and IV lengths, round counts,
keystream limits, the state left by a rejected initialization, and every
timing guarantee belong to the engine, not to these traits.
Types
CipherDirection—EncryptorDecrypt.InitError,StreamError— reusable initialization and processing errors.KeyRef— borrows a key slice.KeyFixed<N>— owns a key array and wipes it on drop.KeyOwned(alloc) — owns a key vector and wipes it on drop.KeyWithIvRef— borrows a key slice and an IV slice.KeyWithIvFixed<K, I>— owns a key array and an IV array and wipes both on drop.KeyWithIvOwned(alloc) — owns a key vector and an IV vector and wipes both on drop.
Both error enums are #[non_exhaustive] and implement Clone, Copy, Debug,
PartialEq, Eq, Display and core::error::Error. Engines may use them as
their associated error types or expose more specific failures of their own.
Every container implements KeyParams, and the KeyWithIv containers also
implement IvParams. The owning containers implement tc_zeroize::Zeroize
and tc_zeroize::ZeroizeOnDrop, and wipe the IV along with the key although
it is not secret. No container validates algorithm-specific lengths; the
receiving engine does.
Features
alloc(off by default) — addsKeyOwnedandKeyWithIvOwned; stillno_std.
Usage
Add the crate next to an engine crate:
[]
= "0.1.0"
= "0.1.0"
KeyOwned and KeyWithIvOwned need the default-off alloc feature:
[]
= { = "0.1.0", = ["alloc"] }
Import the traits to reach an engine's methods and pick a container:
use ChaCha7539Engine;
use ;
let params = new;
let mut engine = new;
engine
.init
.expect;
let mut ciphertext = ;
assert_eq!;
The crate documentation has an executable example of implementing both traits for an engine.
Key handling and limitations
KeyRef and KeyWithIvRef leave the caller's bytes untouched; the caller owns
and wipes them. The owning containers wipe only their own storage. Wiping does
not reach the caller's original arrays, copies made before a vector was moved
in, engine state, or temporaries left in registers and on the stack. Drop-based
wiping requires the destructor to run.
The traits make no constant-time promise. Whether key setup and keystream processing are constant time is documented by each engine. A stream cipher alone provides confidentiality only: never reuse a key and IV pair, and use an authenticated-encryption construction to protect messages.
Validation
The crate documentation carries an executable example that implements both
traits and drives them through KeyWithIvFixed and KeyWithIvRef. Unit tests
cover the containers' accessors and wiping and the error messages. Missing
public documentation is rejected by a crate-level lint, and unsafe code is
forbidden. The ChaCha engines in tc_chacha exercise the traits and error
types against the RFC 8439, XChaCha and Bouncy Castle known-answer vectors.
Run these commands from the workspace root:
cargo test -p tc_stream_cipher --locked
cargo test -p tc_stream_cipher --locked --features alloc
cargo clippy -p tc_stream_cipher --all-targets --all-features --locked -- -D warnings
cargo fmt -p tc_stream_cipher --check
cargo doc -p tc_stream_cipher --no-deps --all-features --locked
Before a release, check the archive contents and run publication validation from a committed checkout:
cargo package -p tc_stream_cipher --list --locked
cargo publish -p tc_stream_cipher --dry-run --locked
The archive includes both license texts, this README, the changelog and the
source. 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.