tc_digest
Shared traits for streaming message digests and extendable-output functions
(XOFs). Digest crates such as tc_sha and
tc_md implement them, and generic code that
hashes a message names only the capabilities it uses. The crate implements no
algorithm.
It is no_std and contains no unsafe code. By default it needs no allocator
and has no dependencies; the alloc feature adds three adapter digests,
which need an allocator and depend on
tc_zeroize to wipe what they hold.
Requires Rust 1.85 or later (edition 2024).
Traits
TryDigest— absorbs input withtry_update, writes the digest withtry_do_finaland resets; each operation returns aResultwith the implementation's error type.Digest— the infallible form:update,update_byte,do_finalandreset.TryXof— an extendable-output function:try_outputsqueezes any amount of output,try_output_finalsqueezes and resets.Xof— the infallible form:outputandoutput_final.
An implementation writes only TryDigest, and TryXof for an XOF. When its
error type is core::convert::Infallible, blanket implementations supply
Digest and Xof, so callers of an infallible digest never handle a Result.
All four traits are dyn-compatible, so &mut dyn Digest works wherever the
digest is chosen at run time.
Besides processing, a digest reports digest_size, the number of bytes
do_final writes, and byte_length, its internal block length, which HMAC
pads its key to. The traits carry no algorithm name: digest crates implement
Display to write it, such as SHA-256, and generic code that needs the name
adds a Display bound.
Adapters
With the alloc feature, off by default, the util module has three digests
built on the traits, none of them a hash algorithm, ported from Bouncy
Castle:
util::NullDigest— keeps every input byte and writes them back unchanged; a signer uses it when the message is already the value to sign.util::Prehash— takes exactly one digest value computed elsewhere and writes it back, returningPrehashErrorfor a wrong length.util::ShortenedDigest— the first bytes of another digest's output.
NullDigest and Prehash are constant time with respect to the bytes they
hold, whose number is public, and wipe them when written out, on reset and on
drop. ShortenedDigest is constant time when its base digest is, and wipes
the base's full output after copying the prefix. Each panics, before
changing any state, when the output buffer is shorter than its digest size.
Display writes NULL, the name given to Prehash, or the base's name and
the length in bits, such as SHA-256(128).
Usage
Add the crate next to a digest crate:
[]
= "0.1.0"
= "0.1.0"
Import Digest to reach a digest's methods:
use Digest;
use Sha256Digest;
let mut sha256 = new;
sha256.update;
sha256.update;
let mut output = ;
assert_eq!;
The crate documentation has an executable example of implementing
TryDigest for a digest.
Contract and limitations
try_do_final and do_final need an output buffer of at least
digest_size bytes; each implementation documents whether a shorter buffer
panics or returns an error. A successful finalization resets the digest for the
next message, and so does try_output_final for an XOF. Once an XOF has
started squeezing, later try_output calls continue the same output stream;
whether it still accepts input is up to the implementation.
The traits make no constant-time promise. Whether a digest's running time depends on the message is documented by each implementation. A digest provides no authentication on its own; use a MAC such as HMAC to protect messages.
Validation
The crate documentation carries an executable example that implements
TryDigest and Display and hashes through a function generic over both.
Unit tests check that
infallible implementations receive Digest and Xof, that XOF output
continues across calls and restarts after output_final, and that both
infallible traits work as trait objects. Missing public documentation is
rejected by a crate-level lint, and unsafe code is forbidden. The digests in
tc_md and tc_sha exercise the traits against published known-answer
vectors. With the alloc feature, integration tests check each adapter
against a toy digest, including the panic on a short output buffer before any
state changes, and another test requires every adapter type and helper to
document whether it is constant or variable time.
Run these commands from the workspace root:
cargo test -p tc_digest --locked
cargo test -p tc_digest --all-features --locked
cargo clippy -p tc_digest --all-targets --locked -- -D warnings
cargo clippy -p tc_digest --all-targets --all-features --locked -- -D warnings
cargo fmt -p tc_digest --check
cargo doc -p tc_digest --no-deps --all-features --locked
Before a release, check the archive contents and run publication validation from a committed checkout:
cargo package -p tc_digest --list --locked
cargo publish -p tc_digest --dry-run --locked
The archive includes both license texts, this README, the changelog, the
source and the tests. 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.