/rust/registry/src/index.crates.io-1949cf8c6b5b557f/rustls-0.23.23/src/crypto/hash.rs

Source
use alloc::boxed::Box;

pub use crate::msgs::enums::HashAlgorithm;

/// Describes a single cryptographic hash function.
///
/// This interface can do both one-shot and incremental hashing, using
/// [`Hash::hash()`] and [`Hash::start()`] respectively.
pub trait Hash: Send + Sync {
    /// Start an incremental hash computation.
    fn start(&self) -> Box<dyn Context>;

    /// Return the output of this hash function with input `data`.
    fn hash(&self, data: &[u8]) -> Output;

    /// The length in bytes of this hash function's output.
    fn output_len(&self) -> usize;

    /// Which hash function this is, eg, `HashAlgorithm::SHA256`.
    fn algorithm(&self) -> HashAlgorithm;

    /// Return `true` if this is backed by a FIPS-approved implementation.
    fn fips(&self) -> bool {
        false
    }
}

/// A hash output, stored as a value.
pub struct Output {
    buf: [u8; Self::MAX_LEN],
    used: usize,
}

impl Output {
    /// Build a `hash::Output` from a slice of no more than `Output::MAX_LEN` bytes.
    pub fn new(bytes: &[u8]) -> Self {
        let mut output = Self {
            buf: [0u8; Self::MAX_LEN],
            used: bytes.len(),
        };
        debug_assert!(bytes.len() <= Self::MAX_LEN);
        output.buf[..bytes.len()].copy_from_slice(bytes);
        output
    }

    /// Maximum supported hash output size: supports up to SHA512.
    pub const MAX_LEN: usize = 64;
}

impl AsRef<[u8]> for Output {
    fn as_ref(&self) -> &[u8] {
        &self.buf[..self.used]
    }
}

/// How to incrementally compute a hash.
pub trait Context: Send + Sync {
    /// Finish the computation, returning the resulting output.
    ///
    /// The computation remains valid, and more data can be added later with
    /// [`Context::update()`].
    ///
    /// Compare with [`Context::finish()`] which consumes the computation
    /// and prevents any further data being added.  This can be more efficient
    /// because it avoids a hash context copy to apply Merkle-Damgård padding
    /// (if required).
    fn fork_finish(&self) -> Output;

    /// Fork the computation, producing another context that has the
    /// same prefix as this one.
    fn fork(&self) -> Box<dyn Context>;

    /// Terminate and finish the computation, returning the resulting output.
    ///
    /// Further data cannot be added after this, because the context is consumed.
    /// Compare [`Context::fork_finish()`].
    fn finish(self: Box<Self>) -> Output;

    /// Add `data` to computation.
    fn update(&mut self, data: &[u8]);
}

Coverage Report

Created: 2025-12-28 06:31

Line	Count	Source
1		use alloc::boxed::Box;
2
3		pub use crate::msgs::enums::HashAlgorithm;
4
5		/// Describes a single cryptographic hash function.
6		///
7		/// This interface can do both one-shot and incremental hashing, using
8		/// [`Hash::hash()`] and [`Hash::start()`] respectively.
9		pub trait Hash: Send + Sync {
10		/// Start an incremental hash computation.
11		fn start(&self) -> Box<dyn Context>;
12
13		/// Return the output of this hash function with input `data`.
14		fn hash(&self, data: &[u8]) -> Output;
15
16		/// The length in bytes of this hash function's output.
17		fn output_len(&self) -> usize;
18
19		/// Which hash function this is, eg, `HashAlgorithm::SHA256`.
20		fn algorithm(&self) -> HashAlgorithm;
21
22		/// Return `true` if this is backed by a FIPS-approved implementation.
23	0	fn fips(&self) -> bool {
24	0	false
25	0	}
26		}
27
28		/// A hash output, stored as a value.
29		pub struct Output {
30		buf: [u8; Self::MAX_LEN],
31		used: usize,
32		}
33
34		impl Output {
35		/// Build a `hash::Output` from a slice of no more than `Output::MAX_LEN` bytes.
36	0	pub fn new(bytes: &[u8]) -> Self {
37	0	let mut output = Self {
38	0	buf: [0u8; Self::MAX_LEN],
39	0	used: bytes.len(),
40	0	};
41	0	debug_assert!(bytes.len() <= Self::MAX_LEN);
42	0	output.buf[..bytes.len()].copy_from_slice(bytes);
43	0	output
44	0	}
45
46		/// Maximum supported hash output size: supports up to SHA512.
47		pub const MAX_LEN: usize = 64;
48		}
49
50		impl AsRef<[u8]> for Output {
51	0	fn as_ref(&self) -> &[u8] {
52	0	&self.buf[..self.used]
53	0	}
54		}
55
56		/// How to incrementally compute a hash.
57		pub trait Context: Send + Sync {
58		/// Finish the computation, returning the resulting output.
59		///
60		/// The computation remains valid, and more data can be added later with
61		/// [`Context::update()`].
62		///
63		/// Compare with [`Context::finish()`] which consumes the computation
64		/// and prevents any further data being added. This can be more efficient
65		/// because it avoids a hash context copy to apply Merkle-Damgård padding
66		/// (if required).
67		fn fork_finish(&self) -> Output;
68
69		/// Fork the computation, producing another context that has the
70		/// same prefix as this one.
71		fn fork(&self) -> Box<dyn Context>;
72
73		/// Terminate and finish the computation, returning the resulting output.
74		///
75		/// Further data cannot be added after this, because the context is consumed.
76		/// Compare [`Context::fork_finish()`].
77		fn finish(self: Box<Self>) -> Output;
78
79		/// Add `data` to computation.
80		fn update(&mut self, data: &[u8]);
81		}