1//! This crate provides traits which describe functionality of cryptographic hash
2//! functions and Message Authentication algorithms.
3//!
4//! Traits in this repository are organized into the following levels:
5//!
6//! - **High-level convenience traits**: [`Digest`], [`DynDigest`], [`Mac`].
7//! Wrappers around lower-level traits for most common use-cases. Users should
8//! usually prefer using these traits.
9//! - **Mid-level traits**: [`Update`], [`FixedOutput`], [`FixedOutputReset`],
10//! [`ExtendableOutput`], [`ExtendableOutputReset`], [`XofReader`],
11//! [`VariableOutput`], [`Reset`], [`KeyInit`], and [`InnerInit`]. These
12//! traits atomically describe available functionality of an algorithm.
13//! - **Marker traits**: [`HashMarker`], [`MacMarker`]. Used to distinguish
14//! different algorithm classes.
15//! - **Low-level traits** defined in the [`core_api`] module. These traits
16//! operate at a block-level and do not contain any built-in buffering.
17//! They are intended to be implemented by low-level algorithm providers only.
18//! Usually they should not be used in application-level code.
19//!
20//! Additionally hash functions implement traits from the standard library:
21//! [`Default`], [`Clone`], [`Write`][std::io::Write]. The latter is
22//! feature-gated behind `std` feature, which is usually enabled by default
23//! by hash implementation crates.
24
25#![no_std]
26#![cfg_attr(docsrs, feature(doc_cfg))]
27#![forbid(unsafe_code)]
28#![doc(
29 html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
30 html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg"
31)]
32#![warn(missing_docs, rust_2018_idioms)]
33
34#[cfg(feature = "alloc")]
35#[macro_use]
36extern crate alloc;
37
38#[cfg(feature = "std")]
39extern crate std;
40
41#[cfg(feature = "rand_core")]
42#[cfg_attr(docsrs, doc(cfg(feature = "rand_core")))]
43pub use crypto_common::rand_core;
44
45#[cfg(feature = "alloc")]
46use alloc::boxed::Box;
47
48#[cfg(feature = "dev")]
49#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
50pub mod dev;
51
52#[cfg(feature = "core-api")]
53#[cfg_attr(docsrs, doc(cfg(feature = "core-api")))]
54pub mod core_api;
55mod digest;
56#[cfg(feature = "mac")]
57mod mac;
58
59#[cfg(feature = "core-api")]
60#[cfg_attr(docsrs, doc(cfg(feature = "core-api")))]
61pub use block_buffer;
62#[cfg(feature = "oid")]
63#[cfg_attr(docsrs, doc(cfg(feature = "oid")))]
64pub use const_oid;
65pub use crypto_common;
66
67pub use crate::digest::{Digest, DynDigest, HashMarker};
68pub use crypto_common::{generic_array, typenum, typenum::consts, Output, OutputSizeUser, Reset};
69#[cfg(feature = "mac")]
70pub use crypto_common::{InnerInit, InvalidLength, Key, KeyInit};
71#[cfg(feature = "mac")]
72pub use mac::{CtOutput, Mac, MacError, MacMarker};
73
74use core::fmt;
75
76/// Types which consume data with byte granularity.
77pub trait Update {
78 /// Update state using the provided data.
79 fn update(&mut self, data: &[u8]);
80
81 /// Digest input data in a chained manner.
82 #[must_use]
83 fn chain(mut self, data: impl AsRef<[u8]>) -> Self
84 where
85 Self: Sized,
86 {
87 self.update(data.as_ref());
88 self
89 }
90}
91
92/// Trait for hash functions with fixed-size output.
93pub trait FixedOutput: Update + OutputSizeUser + Sized {
94 /// Consume value and write result into provided array.
95 fn finalize_into(self, out: &mut Output<Self>);
96
97 /// Retrieve result and consume the hasher instance.
98 #[inline]
99 fn finalize_fixed(self) -> Output<Self> {
100 let mut out: GenericArray::OutputSize> = Default::default();
101 self.finalize_into(&mut out);
102 out
103 }
104}
105
106/// Trait for hash functions with fixed-size output able to reset themselves.
107pub trait FixedOutputReset: FixedOutput + Reset {
108 /// Write result into provided array and reset the hasher state.
109 fn finalize_into_reset(&mut self, out: &mut Output<Self>);
110
111 /// Retrieve result and reset the hasher state.
112 #[inline]
113 fn finalize_fixed_reset(&mut self) -> Output<Self> {
114 let mut out: GenericArray::OutputSize> = Default::default();
115 self.finalize_into_reset(&mut out);
116 out
117 }
118}
119
120/// Trait for reader types which are used to extract extendable output
121/// from a XOF (extendable-output function) result.
122pub trait XofReader {
123 /// Read output into the `buffer`. Can be called an unlimited number of times.
124 fn read(&mut self, buffer: &mut [u8]);
125
126 /// Read output into a boxed slice of the specified size.
127 ///
128 /// Can be called an unlimited number of times in combination with `read`.
129 ///
130 /// `Box<[u8]>` is used instead of `Vec<u8>` to save stack space, since
131 /// they have size of 2 and 3 words respectively.
132 #[cfg(feature = "alloc")]
133 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
134 fn read_boxed(&mut self, n: usize) -> Box<[u8]> {
135 let mut buf: Box<[u8]> = vec![0u8; n].into_boxed_slice();
136 self.read(&mut buf);
137 buf
138 }
139}
140
141/// Trait for hash functions with extendable-output (XOF).
142pub trait ExtendableOutput: Sized + Update {
143 /// Reader
144 type Reader: XofReader;
145
146 /// Retrieve XOF reader and consume hasher instance.
147 fn finalize_xof(self) -> Self::Reader;
148
149 /// Finalize XOF and write result into `out`.
150 fn finalize_xof_into(self, out: &mut [u8]) {
151 self.finalize_xof().read(out);
152 }
153
154 /// Compute hash of `data` and write it into `output`.
155 fn digest_xof(input: impl AsRef<[u8]>, output: &mut [u8])
156 where
157 Self: Default,
158 {
159 let mut hasher = Self::default();
160 hasher.update(input.as_ref());
161 hasher.finalize_xof().read(output);
162 }
163
164 /// Retrieve result into a boxed slice of the specified size and consume
165 /// the hasher.
166 ///
167 /// `Box<[u8]>` is used instead of `Vec<u8>` to save stack space, since
168 /// they have size of 2 and 3 words respectively.
169 #[cfg(feature = "alloc")]
170 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
171 fn finalize_boxed(self, output_size: usize) -> Box<[u8]> {
172 let mut buf = vec![0u8; output_size].into_boxed_slice();
173 self.finalize_xof().read(&mut buf);
174 buf
175 }
176}
177
178/// Trait for hash functions with extendable-output (XOF) able to reset themselves.
179pub trait ExtendableOutputReset: ExtendableOutput + Reset {
180 /// Retrieve XOF reader and reset hasher instance state.
181 fn finalize_xof_reset(&mut self) -> Self::Reader;
182
183 /// Finalize XOF, write result into `out`, and reset the hasher state.
184 fn finalize_xof_reset_into(&mut self, out: &mut [u8]) {
185 self.finalize_xof_reset().read(buffer:out);
186 }
187
188 /// Retrieve result into a boxed slice of the specified size and reset
189 /// the hasher state.
190 ///
191 /// `Box<[u8]>` is used instead of `Vec<u8>` to save stack space, since
192 /// they have size of 2 and 3 words respectively.
193 #[cfg(feature = "alloc")]
194 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
195 fn finalize_boxed_reset(&mut self, output_size: usize) -> Box<[u8]> {
196 let mut buf: Box<[u8]> = vec![0u8; output_size].into_boxed_slice();
197 self.finalize_xof_reset().read(&mut buf);
198 buf
199 }
200}
201
202/// Trait for hash functions with variable-size output.
203pub trait VariableOutput: Sized + Update {
204 /// Maximum size of output hash.
205 const MAX_OUTPUT_SIZE: usize;
206
207 /// Create new hasher instance with the given output size.
208 ///
209 /// It will return `Err(InvalidOutputSize)` in case if hasher can not return
210 /// hash of the specified output size.
211 fn new(output_size: usize) -> Result<Self, InvalidOutputSize>;
212
213 /// Get output size of the hasher instance provided to the `new` method
214 fn output_size(&self) -> usize;
215
216 /// Write result into the output buffer.
217 ///
218 /// Returns `Err(InvalidOutputSize)` if `out` size is not equal to
219 /// `self.output_size()`.
220 fn finalize_variable(self, out: &mut [u8]) -> Result<(), InvalidBufferSize>;
221
222 /// Compute hash of `data` and write it to `output`.
223 ///
224 /// Length of the output hash is determined by `output`. If `output` is
225 /// bigger than `Self::MAX_OUTPUT_SIZE`, this method returns
226 /// `InvalidOutputSize`.
227 fn digest_variable(
228 input: impl AsRef<[u8]>,
229 output: &mut [u8],
230 ) -> Result<(), InvalidOutputSize> {
231 let mut hasher = Self::new(output.len())?;
232 hasher.update(input.as_ref());
233 hasher
234 .finalize_variable(output)
235 .map_err(|_| InvalidOutputSize)
236 }
237
238 /// Retrieve result into a boxed slice and consume hasher.
239 ///
240 /// `Box<[u8]>` is used instead of `Vec<u8>` to save stack space, since
241 /// they have size of 2 and 3 words respectively.
242 #[cfg(feature = "alloc")]
243 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
244 fn finalize_boxed(self) -> Box<[u8]> {
245 let n = self.output_size();
246 let mut buf = vec![0u8; n].into_boxed_slice();
247 self.finalize_variable(&mut buf)
248 .expect("buf length is equal to output_size");
249 buf
250 }
251}
252
253/// Trait for hash functions with variable-size output able to reset themselves.
254pub trait VariableOutputReset: VariableOutput + Reset {
255 /// Write result into the output buffer and reset the hasher state.
256 ///
257 /// Returns `Err(InvalidOutputSize)` if `out` size is not equal to
258 /// `self.output_size()`.
259 fn finalize_variable_reset(&mut self, out: &mut [u8]) -> Result<(), InvalidBufferSize>;
260
261 /// Retrieve result into a boxed slice and reset the hasher state.
262 ///
263 /// `Box<[u8]>` is used instead of `Vec<u8>` to save stack space, since
264 /// they have size of 2 and 3 words respectively.
265 #[cfg(feature = "alloc")]
266 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
267 fn finalize_boxed_reset(&mut self) -> Box<[u8]> {
268 let n: usize = self.output_size();
269 let mut buf: Box<[u8]> = vec![0u8; n].into_boxed_slice();
270 self.finalize_variable_reset(&mut buf)
271 .expect(msg:"buf length is equal to output_size");
272 buf
273 }
274}
275
276/// The error type used in variable hash traits.
277#[derive(Clone, Copy, Debug, Default)]
278pub struct InvalidOutputSize;
279
280impl fmt::Display for InvalidOutputSize {
281 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
282 f.write_str(data:"invalid output size")
283 }
284}
285
286#[cfg(feature = "std")]
287#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
288impl std::error::Error for InvalidOutputSize {}
289
290/// Buffer length is not equal to hash output size.
291#[derive(Default, Debug, Copy, Clone, Eq, PartialEq)]
292pub struct InvalidBufferSize;
293
294impl fmt::Display for InvalidBufferSize {
295 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
296 f.write_str(data:"invalid buffer length")
297 }
298}
299
300#[cfg(feature = "std")]
301impl std::error::Error for InvalidBufferSize {}
302