Skip to main content

blake2b_192/
lib.rs

1//! BLAKE2b with a fixed 24-byte (192-bit) digest.
2//!
3//! This crate's headline API implements exactly one primitive: **unkeyed,
4//! sequential BLAKE2b parameterized with a digest length of 24 bytes**, as
5//! defined by RFC 7693 and the BLAKE2 specification.
6//!
7//! The digest length is part of BLAKE2b's parameterization (it is mixed into
8//! the initial state), so this is **not** BLAKE2b-512 truncated to 24 bytes;
9//! the two functions produce unrelated outputs. The implemented function is
10//! byte-for-byte compatible with libsodium's
11//! `crypto_generichash(out, 24, msg, len, NULL, 0)`, CPython's
12//! `hashlib.blake2b(msg, digest_size=24)`, and RustCrypto's
13//! `Blake2b::<U24>`.
14//!
15//! Properties:
16//!
17//! - `no_std`, no heap allocation, zero dependencies;
18//! - no `unsafe` code (enforced by `#![forbid(unsafe_code)]`);
19//! - keyed hashing, salts, personalization, and tree mode are deliberately
20//!   out of scope. Other digest lengths are out of scope for the headline
21//!   API; the [`engine`] module exposes the validated engine at 1..=64 bytes
22//!   for crates that build on it.
23//!
24//! A 24-byte digest provides at most ~96-bit collision resistance (and
25//! ~192-bit preimage resistance); use a longer digest where general-purpose
26//! collision resistance matters.
27//!
28//! # Examples
29//!
30//! One-shot:
31//!
32//! ```
33//! let digest: [u8; 24] = blake2b_192::hash(b"abc");
34//! assert_eq!(
35//!     digest[..4],
36//!     [0x56, 0xa1, 0x7e, 0x38],
37//! );
38//! ```
39//!
40//! Streaming:
41//!
42//! ```
43//! let mut hasher = blake2b_192::Blake2b192::new();
44//! hasher.update(b"ab");
45//! hasher.update(b"c");
46//! assert_eq!(hasher.finalize(), blake2b_192::hash(b"abc"));
47//! ```
48
49// Provenance: written from RFC 7693 and the BLAKE2 specification, reviewed
50// against RustCrypto `blake2` 0.11.0-rc.6 (RustCrypto/hashes @ tag
51// blake2-v0.11.0-rc.6) and treated as a derivative of it for licensing
52// purposes; upstream notices are retained in LICENSE-MIT and COPYRIGHT.
53
54#![no_std]
55#![forbid(unsafe_code)]
56#![deny(missing_docs)]
57
58pub mod engine;
59
60use crate::engine::Blake2bCore;
61
62/// Digest length in bytes (24 bytes = 192 bits).
63pub const DIGEST_LEN: usize = 24;
64
65/// Streaming BLAKE2b-192 hasher.
66///
67/// Feed input with [`update`](Self::update) in any number of chunks;
68/// [`finalize`](Self::finalize) consumes the hasher and returns the digest.
69/// The result is identical to [`hash`] of the concatenated input.
70///
71/// ```
72/// let mut hasher = blake2b_192::Blake2b192::new();
73/// hasher.update(b"hello ");
74/// hasher.update(b"world");
75/// assert_eq!(hasher.finalize(), blake2b_192::hash(b"hello world"));
76/// ```
77pub struct Blake2b192 {
78    state: Blake2bCore,
79}
80
81impl Blake2b192 {
82    /// Creates a hasher for a new message.
83    #[must_use]
84    pub fn new() -> Self {
85        Blake2b192 {
86            state: Blake2bCore::init(DIGEST_LEN as u64),
87        }
88    }
89
90    /// Absorbs more message bytes.
91    pub fn update(&mut self, input: &[u8]) {
92        self.state.update(input);
93    }
94
95    /// Completes hashing and returns the 24-byte digest.
96    #[must_use]
97    pub fn finalize(self) -> [u8; DIGEST_LEN] {
98        let out = self.state.finalize();
99        let mut digest = [0u8; DIGEST_LEN];
100        digest.copy_from_slice(&out[..DIGEST_LEN]);
101        digest
102    }
103}
104
105impl Default for Blake2b192 {
106    fn default() -> Self {
107        Self::new()
108    }
109}
110
111/// Computes the BLAKE2b-192 digest of `input` in one call.
112#[must_use]
113pub fn hash(input: &[u8]) -> [u8; DIGEST_LEN] {
114    let mut hasher = Blake2b192::new();
115    hasher.update(input);
116    hasher.finalize()
117}
118
119#[cfg(test)]
120mod tests;