second_brain_core/keys/
subkey.rs1use 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}