1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
//! Shared message-digest and extendable-output function (XOF) traits.
//!
//! Digest crates such as [`tc_sha`](https://crates.io/crates/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`](core::convert::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`](core::fmt::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]);
//! ```
extern crate alloc;
pub use ;
pub use ;