Skip to main content

second_brain_core/keys/
subkey.rs

1use anyhow::{Result, anyhow, ensure};
2use hkdf::Hkdf;
3use sha2::Sha256;
4
5use super::KeyGuard;
6use super::identity::{Epoch, IdentityKey};
7
8const INFO_DOMAIN: &[u8] = b"second-brain subkey v1 ";
9
10#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
11pub enum Subkey {
12    Wire,
13    Snapshot,
14    ArchiveKek,
15    StoreWrap,
16}
17
18impl Subkey {
19    fn label(self) -> &'static [u8] {
20        match self {
21            Subkey::Wire => b"wire",
22            Subkey::Snapshot => b"snapshot",
23            Subkey::ArchiveKek => b"archive-kek",
24            Subkey::StoreWrap => b"store-wrap",
25        }
26    }
27}
28
29pub fn derive_subkey(
30    key: &IdentityKey,
31    epoch: &Epoch,
32    purpose: Subkey,
33) -> Result<KeyGuard<[u8; 32]>> {
34    ensure!(
35        key.key_id() == epoch.key_id,
36        "the identity key does not belong to epoch {} (key id {})",
37        epoch.number,
38        epoch.key_id
39    );
40    ensure!(
41        epoch.number != 0 || purpose == Subkey::Wire,
42        "epoch 0 derives only the wire subkey, not {purpose:?}"
43    );
44    let mut salt = [0u8; 12];
45    salt[..4].copy_from_slice(&epoch.number.to_be_bytes());
46    salt[4..].copy_from_slice(&epoch.key_id.0);
47    let hkdf = Hkdf::<Sha256>::new(Some(&salt), key.expose());
48    let mut out = KeyGuard::new([0u8; 32]);
49    hkdf.expand_multi_info(&[INFO_DOMAIN, purpose.label()], out.expose_mut())
50        .map_err(|e| anyhow!("deriving the {purpose:?} subkey: {e}"))?;
51    Ok(out)
52}
53
54#[cfg(test)]
55mod tests {
56    use super::*;
57
58    const ALL: [Subkey; 4] = [
59        Subkey::Wire,
60        Subkey::Snapshot,
61        Subkey::ArchiveKek,
62        Subkey::StoreWrap,
63    ];
64
65    fn key(byte: u8) -> IdentityKey {
66        IdentityKey::from_bytes(KeyGuard::new([byte; 32]))
67    }
68
69    fn epoch(number: u32, key: &IdentityKey) -> Epoch {
70        Epoch {
71            number,
72            key_id: key.key_id(),
73        }
74    }
75
76    #[test]
77    fn subkeys_are_stable_per_epoch() {
78        let k = key(1);
79        let e = epoch(1, &k);
80        for purpose in ALL {
81            let a = derive_subkey(&k, &e, purpose).unwrap();
82            let b = derive_subkey(&k, &e, purpose).unwrap();
83            assert_eq!(a.expose(), b.expose());
84            assert_ne!(a.expose(), &[0u8; 32]);
85            assert_ne!(a.expose(), k.expose());
86        }
87    }
88
89    #[test]
90    fn purposes_derive_different_subkeys() {
91        let k = key(2);
92        let e = epoch(1, &k);
93        let derived: Vec<[u8; 32]> = ALL
94            .iter()
95            .map(|p| *derive_subkey(&k, &e, *p).unwrap().expose())
96            .collect();
97        for (i, a) in derived.iter().enumerate() {
98            for (j, b) in derived.iter().enumerate().skip(i + 1) {
99                assert_ne!(a, b, "{:?} vs {:?}", ALL[i], ALL[j]);
100            }
101        }
102    }
103
104    #[test]
105    fn epoch_numbers_derive_different_subkeys() {
106        let k = key(3);
107        for purpose in ALL {
108            let one = derive_subkey(&k, &epoch(1, &k), purpose).unwrap();
109            let two = derive_subkey(&k, &epoch(2, &k), purpose).unwrap();
110            assert_ne!(one.expose(), two.expose(), "{purpose:?}");
111        }
112        let zero = derive_subkey(&k, &epoch(0, &k), Subkey::Wire).unwrap();
113        let one = derive_subkey(&k, &epoch(1, &k), Subkey::Wire).unwrap();
114        assert_ne!(zero.expose(), one.expose());
115    }
116
117    #[test]
118    fn epoch_zero_derives_only_wire() {
119        let k = key(4);
120        let e = epoch(0, &k);
121        assert!(derive_subkey(&k, &e, Subkey::Wire).is_ok());
122        for purpose in [Subkey::Snapshot, Subkey::ArchiveKek, Subkey::StoreWrap] {
123            let err = derive_subkey(&k, &e, purpose).unwrap_err();
124            assert!(err.to_string().contains("epoch 0"), "{err}");
125        }
126    }
127
128    #[test]
129    fn a_key_from_another_epoch_is_refused() {
130        let k = key(5);
131        let other = epoch(1, &key(6));
132        for purpose in ALL {
133            assert!(derive_subkey(&k, &other, purpose).is_err(), "{purpose:?}");
134        }
135    }
136}