| 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] |
| 36 |
extern crate alloc; |
| 37 |
|
| 38 |
#[cfg(feature = "std")] |
| 39 |
extern crate std; |
| 40 |
|
| 41 |
#[cfg(feature = "rand_core")] |
| 42 |
#[cfg_attr(docsrs, doc(cfg(feature = "rand_core")))] |
| 43 |
pub use crypto_common::rand_core; |
| 44 |
|
| 45 |
#[cfg(feature = "alloc")] |
| 46 |
use alloc::boxed::Box; |
| 47 |
|
| 48 |
#[cfg(feature = "dev")] |
| 49 |
#[cfg_attr(docsrs, doc(cfg(feature = "dev")))] |
| 50 |
pub mod dev; |
| 51 |
|
| 52 |
#[cfg(feature = "core-api")] |
| 53 |
#[cfg_attr(docsrs, doc(cfg(feature = "core-api")))] |
| 54 |
pub mod core_api; |
| 55 |
mod digest; |
| 56 |
#[cfg(feature = "mac")] |
| 57 |
mod mac; |
| 58 |
|
| 59 |
#[cfg(feature = "core-api")] |
| 60 |
#[cfg_attr(docsrs, doc(cfg(feature = "core-api")))] |
| 61 |
pub use block_buffer; |
| 62 |
#[cfg(feature = "oid")] |
| 63 |
#[cfg_attr(docsrs, doc(cfg(feature = "oid")))] |
| 64 |
pub use const_oid; |
| 65 |
pub use crypto_common; |
| 66 |
|
| 67 |
pub use crate::digest::{Digest, DynDigest, HashMarker}; |
| 68 |
pub use crypto_common::{generic_array, typenum, typenum::consts, Output, OutputSizeUser, Reset}; |
| 69 |
#[cfg(feature = "mac")] |
| 70 |
pub use crypto_common::{InnerInit, InvalidLength, Key, KeyInit}; |
| 71 |
#[cfg(feature = "mac")] |
| 72 |
pub use mac::{CtOutput, Mac, MacError, MacMarker}; |
| 73 |
|
| 74 |
use core::fmt; |
| 75 |
|
| 76 |
/// Types which consume data with byte granularity. |
| 77 |
pub 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. |
| 93 |
pub 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 = 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. |
| 107 |
pub 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 = 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. |
| 122 |
pub 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 = 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). |
| 142 |
pub 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. |
| 179 |
pub 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(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 = 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. |
| 203 |
pub 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. |
| 254 |
pub 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 = self.output_size(); |
| 269 |
let mut buf = vec![0u8; n].into_boxed_slice(); |
| 270 |
self.finalize_variable_reset(&mut buf) |
| 271 |
.expect("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)] |
| 278 |
pub struct InvalidOutputSize; |
| 279 |
|
| 280 |
impl fmt::Display for InvalidOutputSize { |
| 281 |
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 282 |
f.write_str("invalid output size") |
| 283 |
} |
| 284 |
} |
| 285 |
|
| 286 |
#[cfg(feature = "std")] |
| 287 |
#[cfg_attr(docsrs, doc(cfg(feature = "std")))] |
| 288 |
impl std::error::Error for InvalidOutputSize {} |
| 289 |
|
| 290 |
/// Buffer length is not equal to hash output size. |
| 291 |
#[derive(Default, Debug, Copy, Clone, Eq, PartialEq)] |
| 292 |
pub struct InvalidBufferSize; |
| 293 |
|
| 294 |
impl fmt::Display for InvalidBufferSize { |
| 295 |
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 296 |
f.write_str("invalid buffer length") |
| 297 |
} |
| 298 |
} |
| 299 |
|
| 300 |
#[cfg(feature = "std")] |
| 301 |
impl std::error::Error for InvalidBufferSize {} |