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
//! Cryptographic hash function implementations.
//!
//! This module provides concrete implementations of the [`Hasher`] trait
//! from `libvctrl_handler`. Each hasher is a stateless value that produces
//! a 64‑byte [`Hash`] for any input data.
//!
//! # Why a separate module for hashing?
//!
//! Hashing is the **foundation** of content‑addressable storage. Every object
//! in a `libvctrl` repository is identified by its hash. This means the
//! choice of hash function has profound implications for security,
//! performance, and interoperability. By isolating the hasher in its own
//! module, we make it easy to:
//!
//! - Swap implementations (e.g., SHA‑256, BLAKE3) without touching other code.
//! - Benchmark different algorithms on a per‑application basis.
//! - Audit the hashing code independently of the rest of the system.
//!
//! # Available hashers
//!
//! | Hasher | Algorithm | Output size | Crate |
//! |---|---|---|---|
//! | [`Sha512Hasher`] | SHA‑512 | 64 bytes | `libvctrl_sha512` |
//!
//! Additional hashers (SHA‑256, BLAKE3, etc.) may be added in the future as
//! separate crates.
//!
//! # Writing your own hasher
//!
//! To provide a custom hash function, implement the [`Hasher`] trait:
//!
//! ```rust
//! use libvctrl_handler::{Hash, Hasher};
//! // libvctrl_sha512 must be in your Cargo.toml dependencies
//!
//! struct MyHasher;
//!
//! impl Hasher for MyHasher {
//! fn hash(&self, data: &[u8]) -> Hash {
//! // Use the SHA‑512 function from the libvctrl_sha512 crate
//! let digest: [u8; 64] = libvctrl_sha512::Hash::hash(data);
//! Hash::from_bytes(&digest).expect("must produce 64 bytes")
//! }
//! }
//! ```
//!
//! # Security considerations
//!
//! - **Collision resistance** – The hasher must make it computationally
//! infeasible to find two different inputs with the same hash.
//! - **Preimage resistance** – Given a hash, it must be infeasible to find
//! an input that hashes to it.
//! - **Determinism** – The same input must always produce the same hash.
//!
//! The provided [`Sha512Hasher`] meets all these requirements and has been
//! audited as part of the `libvctrl_sha512` crate.
pub use Sha512Hasher;