Skip to main content

Crate tc_digest

Crate tc_digest 

Source
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: NullDigest writes its input back unchanged, Prehash passes through one digest value computed elsewhere, and ShortenedDigest truncates another digest’s output.

Traits§

Digest
An infallible streaming message digest.
TryDigest
A streaming message digest whose operations may fail.
TryXof
A streaming extendable-output function whose operations may fail.
Xof
An infallible streaming extendable-output function.