Skip to main content

zwave_security/
ckdf.rs

1//! S2 key derivation (CKDF), per the Security 2 specification.
2//!
3//! All derivations are AES-128-CMAC over fixed constants, so the outputs are
4//! the same on every implementation; the controller and the joining node
5//! derive the same temporary keys from the ECDH secret and both public keys.
6
7use crate::crypto::cmac;
8
9const CONST_PRK: [u8; 16] = [0x33; 16];
10const CONST_TE: [u8; 15] = [0x88; 15];
11const CONST_NK: [u8; 15] = [0x55; 15];
12const CONST_NONCE: [u8; 16] = [0x26; 16];
13const CONST_EI: [u8; 15] = [0x88; 15];
14
15/// Keys derived from a permanent network key (or, during bootstrapping, from the ECDH secret).
16#[derive(Clone, PartialEq, Eq, zeroize::Zeroize, zeroize::ZeroizeOnDrop)]
17pub struct DerivedKeys {
18    /// The AES-CCM key for encapsulation.
19    pub key_ccm: [u8; 16],
20    /// The CTR_DRBG personalization string for SPAN nonces.
21    pub personalization: [u8; 32],
22    /// The key that turns the MPAN inner state into multicast nonces (zero for temporary keys).
23    pub key_mpan: [u8; 16],
24}
25
26impl std::fmt::Debug for DerivedKeys {
27    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
28        f.write_str("DerivedKeys(..)")
29    }
30}
31
32fn cat(parts: &[&[u8]]) -> Vec<u8> {
33    parts.concat()
34}
35
36/// CKDF-TempExtract: the pseudo random key from the ECDH shared secret.
37///
38/// `pub_a` is the including node's (controller's) public key and `pub_b` the
39/// joining node's.
40pub fn temp_prk(shared_secret: &[u8; 32], pub_a: &[u8; 32], pub_b: &[u8; 32]) -> [u8; 16] {
41    cmac(&CONST_PRK, &cat(&[shared_secret, pub_a, pub_b]))
42}
43
44/// CKDF-TempExpand: the temporary CCM key and personalization string.
45pub fn temp_keys(prk: &[u8; 16]) -> DerivedKeys {
46    let t1 = cmac(prk, &cat(&[&CONST_TE, &[0x01]]));
47    let t2 = cmac(prk, &cat(&[&t1, &CONST_TE, &[0x02]]));
48    let t3 = cmac(prk, &cat(&[&t2, &CONST_TE, &[0x03]]));
49    let mut personalization = [0u8; 32];
50    personalization[..16].copy_from_slice(&t2);
51    personalization[16..].copy_from_slice(&t3);
52    DerivedKeys {
53        key_ccm: t1,
54        personalization,
55        key_mpan: [0; 16],
56    }
57}
58
59/// CKDF-NetworkKeyExpand: CCM key, personalization string and MPAN key from a network key.
60pub fn network_keys(pnk: &[u8; 16]) -> DerivedKeys {
61    let t1 = cmac(pnk, &cat(&[&CONST_NK, &[0x01]]));
62    let t2 = cmac(pnk, &cat(&[&t1, &CONST_NK, &[0x02]]));
63    let t3 = cmac(pnk, &cat(&[&t2, &CONST_NK, &[0x03]]));
64    let t4 = cmac(pnk, &cat(&[&t3, &CONST_NK, &[0x04]]));
65    let mut personalization = [0u8; 32];
66    personalization[..16].copy_from_slice(&t2);
67    personalization[16..].copy_from_slice(&t3);
68    DerivedKeys {
69        key_ccm: t1,
70        personalization,
71        key_mpan: t4,
72    }
73}
74
75/// CKDF-MEI-Extract: the nonce PRK from the sender's and receiver's entropy inputs.
76pub fn nonce_prk(sender_ei: &[u8; 16], receiver_ei: &[u8; 16]) -> [u8; 16] {
77    cmac(&CONST_NONCE, &cat(&[sender_ei, receiver_ei]))
78}
79
80/// CKDF-MEI-Expand: the 32-byte mixed entropy input that seeds a SPAN's CTR_DRBG.
81pub fn mei(nonce_prk: &[u8; 16]) -> [u8; 32] {
82    let t1 = cmac(nonce_prk, &cat(&[&CONST_EI, &[0x00], &CONST_EI, &[0x01]]));
83    let t2 = cmac(nonce_prk, &cat(&[&t1, &CONST_EI, &[0x02]]));
84    let mut out = [0u8; 32];
85    out[..16].copy_from_slice(&t1);
86    out[16..].copy_from_slice(&t2);
87    out
88}