Expand description
Shared message-digest and extendable-output function (XOF) traits.
Digest crates such as tc_sha implement
these traits, and generic code that hashes a message names only the
capabilities it uses. The crate implements no algorithm.
Each capability comes in two forms. TryDigest and TryXof return a
Result from every operation, with an error type chosen by the
implementation. Digest and Xof are their infallible counterparts:
an implementation whose error type is Infallible
receives them automatically through blanket implementations, so it never
implements them by hand.
The traits carry no algorithm name. Implementations write it through
Display, as the example below does, and generic code
that needs the name adds a Display bound.
§Adapters
With the alloc feature the util module has three digests built on the
traits, none of them a hash algorithm, as Bouncy Castle has them:
NullDigest writes its input back unchanged, Prehash passes through
one digest value computed elsewhere, and ShortenedDigest truncates
another digest’s output. They need an allocator and wipe what they hold
through tc_zeroize; without the feature the crate has no dependencies.
§Example
A toy digest that sums its input bytes. It implements TryDigest with an
infallible error type and so gains the Digest methods, and it names
itself through Display:
use core::{convert::Infallible, fmt};
use tc_digest::{Digest, TryDigest};
#[derive(Default)]
struct Sum8 {
sum: u8,
}
impl fmt::Display for Sum8 {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str("SUM-8")
}
}
impl TryDigest for Sum8 {
type Error = Infallible;
fn digest_size(&self) -> usize {
1
}
fn byte_length(&self) -> usize {
1
}
fn try_update(&mut self, input: &[u8]) -> Result<(), Infallible> {
for &byte in input {
self.sum = self.sum.wrapping_add(byte);
}
Ok(())
}
fn try_do_final(&mut self, output: &mut [u8]) -> Result<usize, Infallible> {
output[0] = self.sum;
self.sum = 0;
Ok(1)
}
fn try_reset(&mut self) -> Result<(), Infallible> {
self.sum = 0;
Ok(())
}
}
// Generic code asks only for the capabilities it uses.
fn hash_parts<D: Digest + fmt::Display>(
digest: &mut D,
parts: &[&[u8]],
output: &mut [u8],
) -> String {
for part in parts {
digest.update(part);
}
let written = digest.do_final(output);
format!("{digest} wrote {written} byte")
}
let mut output = [0u8; 1];
assert_eq!(
hash_parts(&mut Sum8::default(), &[&[1, 2], &[3]], &mut output),
"SUM-8 wrote 1 byte"
);
assert_eq!(output, [6]);Modules§
- util
- Digests built on the traits that are not hash algorithms, ported from
Bouncy Castle:
NullDigestwrites its input back unchanged,Prehashpasses through one digest value computed elsewhere, andShortenedDigesttruncates another digest’s output.