pamoja_session/
kdf.rs

1//! Keyed hashing primitives: HMAC-SHA256 (RFC 2104, FIPS 198-1) and HKDF-SHA256
2//! (RFC 5869).
3//!
4//! These are the building blocks the session key agreement uses, exposed so a host can
5//! reuse the same audited, vector-pinned primitives instead of pulling in a second
6//! crypto stack. A local-first dashboard, for example, derives a per-session key from a
7//! pairing secret with [`hkdf_sha256`] and authenticates each command with
8//! [`hmac_sha256`].
9
10use hkdf::Hkdf;
11use hmac::digest::KeyInit;
12use hmac::{Hmac, Mac};
13use sha2::Sha256;
14
15/// Computes HMAC-SHA256 over a message with a key of any length.
16///
17/// # Arguments
18///
19/// * `key` - the secret key; any length is accepted, as HMAC defines.
20/// * `message` - the bytes to authenticate.
21///
22/// # Returns
23///
24/// The 32-byte message authentication code.
25///
26/// # Examples
27///
28/// ```
29/// // RFC 4231 test case 2.
30/// let mac = pamoja_session::hmac_sha256(b"Jefe", b"what do ya want for nothing?");
31/// assert_eq!(mac[..4], [0x5b, 0xdc, 0xc1, 0x46]);
32/// ```
33pub fn hmac_sha256(key: &[u8], message: &[u8]) -> [u8; 32] {
34    let mut mac = Hmac::<Sha256>::new_from_slice(key).expect("HMAC accepts a key of any length");
35    mac.update(message);
36    mac.finalize().into_bytes().into()
37}
38
39/// Derives output key material from input keying material with HKDF-SHA256.
40///
41/// Extracts a pseudorandom key from `salt` and `ikm`, then expands it under `info` to
42/// fill `out`.
43///
44/// # Arguments
45///
46/// * `salt` - a non-secret salt; a fresh per-session value gives each session its own key.
47/// * `ikm` - the input keying material, such as a shared or pairing secret.
48/// * `info` - a context label binding the output to its purpose.
49/// * `out` - the buffer to fill with derived key material.
50///
51/// # Panics
52///
53/// Panics if `out` is longer than HKDF-SHA256's `255 * 32`-byte limit.
54pub fn hkdf_sha256(salt: &[u8], ikm: &[u8], info: &[u8], out: &mut [u8]) {
55    Hkdf::<Sha256>::new(Some(salt), ikm)
56        .expand(info, out)
57        .expect("output length is within HKDF-SHA256's 255 * 32-byte limit");
58}
59
60#[cfg(test)]
61mod tests {
62    use super::*;
63
64    #[test]
65    fn hmac_matches_the_rfc_4231_test_case_1() {
66        // RFC 4231 section 4.2: 20 bytes of 0x0b keying "Hi There".
67        let mac = hmac_sha256(&[0x0b; 20], b"Hi There");
68        let expected: [u8; 32] = [
69            0xb0, 0x34, 0x4c, 0x61, 0xd8, 0xdb, 0x38, 0x53, 0x5c, 0xa8, 0xaf, 0xce, 0xaf, 0x0b,
70            0xf1, 0x2b, 0x88, 0x1d, 0xc2, 0x00, 0xc9, 0x83, 0x3d, 0xa7, 0x26, 0xe9, 0x37, 0x6c,
71            0x2e, 0x32, 0xcf, 0xf7,
72        ];
73        assert_eq!(mac, expected);
74    }
75
76    #[test]
77    fn hmac_matches_the_rfc_4231_test_case_2() {
78        // RFC 4231 section 4.3: a short ASCII key with a longer message.
79        let mac = hmac_sha256(b"Jefe", b"what do ya want for nothing?");
80        let expected: [u8; 32] = [
81            0x5b, 0xdc, 0xc1, 0x46, 0xbf, 0x60, 0x75, 0x4e, 0x6a, 0x04, 0x24, 0x26, 0x08, 0x95,
82            0x75, 0xc7, 0x5a, 0x00, 0x3f, 0x08, 0x9d, 0x27, 0x39, 0x83, 0x9d, 0xec, 0x58, 0xb9,
83            0x64, 0xec, 0x38, 0x43,
84        ];
85        assert_eq!(mac, expected);
86    }
87
88    #[test]
89    fn hkdf_matches_the_rfc_5869_basic_vector() {
90        // RFC 5869 Appendix A.1: the SHA-256 basic test case.
91        let ikm = [0x0bu8; 22];
92        let salt: [u8; 13] = [
93            0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c,
94        ];
95        let info: [u8; 10] = [0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7, 0xf8, 0xf9];
96        let expected: [u8; 42] = [
97            0x3c, 0xb2, 0x5f, 0x25, 0xfa, 0xac, 0xd5, 0x7a, 0x90, 0x43, 0x4f, 0x64, 0xd0, 0x36,
98            0x2f, 0x2a, 0x2d, 0x2d, 0x0a, 0x90, 0xcf, 0x1a, 0x5a, 0x4c, 0x5d, 0xb0, 0x2d, 0x56,
99            0xec, 0xc4, 0xc5, 0xbf, 0x34, 0x00, 0x72, 0x08, 0xd5, 0xb8, 0x87, 0x18, 0x58, 0x65,
100        ];
101        let mut okm = [0u8; 42];
102        hkdf_sha256(&salt, &ikm, &info, &mut okm);
103        assert_eq!(okm, expected);
104    }
105}
pamoja_session/kdf.rs

pamoja_session/
kdf.rs
