ms_codec/
hashlock.rs

1//! The hashlock preimage derivation (SPEC_ms_hashlock §2).
2//!
3//! THE RULE LIVES HERE, in the codec, beside the kind that carries its
4//! output: one crate, one corpus, one SHA pin, one provenance pin for the Go
5//! port. `ms hashlock` is a thin verb over these four functions.
6//!
7//! Two methods, the operator's choice (brainstorm L5): `preimage_hardened`
8//! is PBKDF2-HMAC-SHA256 with a fixed salt, 100,000 iterations and dkLen 32
9//! (L4); `preimage_sha256` is one SHA-256 of the phrase bytes. Both take the
10//! phrase as BYTES, exactly as given -- no trimming, folding or normalising
11//! happens here or in any caller (§4.3). `digest` is SHA-256 of X, the value
12//! the policy carries; it is public the moment the policy is engraved and is
13//! therefore NOT zeroized.
14//!
15//! THE SALT IS FIXED AND HAS NO PARAMETER (L13). Changing it after any vector
16//! ships is a new method, not a tweak: every engraved policy's preimage was
17//! derived under this exact byte string.
18
19use pbkdf2::pbkdf2_hmac;
20use sha2::{Digest, Sha256};
21use zeroize::Zeroizing;
22
23use crate::error::{Error, Result};
24
25/// The fixed salt (ASCII, copyable by hand, domain-separated from BIP-39's
26/// `"mnemonic"` and from `me`'s 16-byte random seal salt).
27pub const HASHLOCK_SALT: &[u8] = b"ms-hashlock-v1";
28/// PBKDF2 iteration count -- the operator's cap, chosen so a signer at a
29/// tenth of the SH2's measured rate still derives in reasonable time.
30pub const HASHLOCK_ITERATIONS: u32 = 100_000;
31/// Derived-key length: a miniscript `sha256(H)` preimage is exactly 32 bytes.
32pub const HASHLOCK_DKLEN: usize = 32;
33
34/// X = PBKDF2-HMAC-SHA256(phrase, HASHLOCK_SALT, HASHLOCK_ITERATIONS, 32).
35pub fn preimage_hardened(phrase: &[u8]) -> Zeroizing<[u8; 32]> {
36    let mut x = Zeroizing::new([0u8; HASHLOCK_DKLEN]);
37    pbkdf2_hmac::<Sha256>(phrase, HASHLOCK_SALT, HASHLOCK_ITERATIONS, &mut *x);
38    x
39}
40
41/// X = SHA-256(phrase). The brainwallet construction; the CLI warns on it at
42/// every length (L12) and this function does not judge.
43pub fn preimage_sha256(phrase: &[u8]) -> Zeroizing<[u8; 32]> {
44    let mut x = Zeroizing::new([0u8; 32]);
45    x.copy_from_slice(&Sha256::digest(phrase));
46    x
47}
48
49/// X from the OS CSPRNG, failing closed: an error, never a zeroed buffer.
50/// Lives here rather than in the CLI so the whole preimage surface -- and its
51/// randomness contract -- is one crate's (R0 r0 correctness I-2).
52pub fn preimage_random() -> Result<Zeroizing<[u8; 32]>> {
53    let mut x = Zeroizing::new([0u8; 32]);
54    getrandom::fill(&mut *x).map_err(|_| Error::RandomnessUnavailable)?;
55    Ok(x)
56}
57
58/// H = SHA-256(X): what the policy carries and the plate shows. Public.
59pub fn digest(preimage: &[u8; 32]) -> [u8; 32] {
60    let mut h = [0u8; 32];
61    h.copy_from_slice(&Sha256::digest(preimage));
62    h
63}
64
65#[cfg(test)]
66mod tests {
67    use super::*;
68
69    #[test]
70    fn hardened_output_is_zeroizing_and_32() {
71        let x = preimage_hardened(b"x");
72        assert_eq!(x.len(), 32);
73        // Two calls agree: the salt and count are constants, not state.
74        assert_eq!(&preimage_hardened(b"x")[..], &x[..]);
75    }
76}
ms_codec/hashlock.rs

ms_codec/
hashlock.rs
