Skip to main content

qualia_core_db/net/qdnf/profiles/
vault.rs

1//! Protected local vaults (E16.2).
2//!
3//! Keys are stored as [`KeyRef`] (slot + generation), never as exported raw
4//! key bytes on this path. A digest in a slot is a handle, not a secret dump.
5//!
6//! # What this module cannot enforce (E16.7)
7//!
8//! Remote wipe and attestation cannot guarantee safety after endpoint
9//! compromise or seizure. An unlocked or coerced device can disclose
10//! accessible plaintext. Crash dumps must omit key material
11//! ([`crash_dump_redacted`] is true when `crash_dump_allowed` is false).
12//! Hardware-backed references are reported only when a real token exists;
13//! this Linux CI path does not fake a TPM.
14
15use crate::crypto::network::aead::{decrypt_in_place, encrypt_in_place};
16use crate::crypto::network::types::{AEAD_KEY_LEN, AEAD_NONCE_LEN, AEAD_TAG_LEN};
17use crate::net::qdnf::errors::QdnfError;
18use crate::net::qdnf::types::{Generation, StrongDigest};
19
20use super::catalog::{catalog_entry, ProtectionProfile};
21
22/// AEAD AAD for sealed catalog-profile blobs.
23const SEALED_PROFILE_AAD: &[u8] = b"qdnf-profile-vault-v1";
24/// `profile_u8` + `control_count` + catalog digest.
25pub const SEALED_PROFILE_PLAIN_LEN: usize = 1 + 1 + 48;
26
27/// Maximum notification preview size. Not a full payload.
28pub const NOTIFICATION_PREVIEW_MAX_BYTES: usize = 32;
29pub const VAULT_SLOTS: usize = 8;
30
31/// Slot + generation handle. Not raw key bytes.
32#[repr(C)]
33#[derive(Clone, Copy, Debug, PartialEq, Eq)]
34pub struct KeyRef {
35    pub slot: u8,
36    pub generation: Generation,
37}
38
39#[repr(C)]
40#[derive(Clone, Copy, Debug, PartialEq, Eq)]
41pub struct VaultSlot {
42    pub occupied: bool,
43    pub expiry_unix: u64,
44    pub locked: bool,
45    pub crash_dump_allowed: bool,
46}
47
48impl VaultSlot {
49    pub const EMPTY: Self = Self {
50        occupied: false,
51        expiry_unix: 0,
52        locked: false,
53        crash_dump_allowed: false,
54    };
55}
56
57#[repr(C)]
58#[derive(Clone, Copy, Debug)]
59pub struct LocalVault {
60    slots: [VaultSlot; VAULT_SLOTS],
61    refs: [StrongDigest; VAULT_SLOTS],
62    generations: [Generation; VAULT_SLOTS],
63    last_seen_unix: u64,
64    locked: bool,
65}
66
67impl LocalVault {
68    /// Creates a default `LocalVault`.
69    pub const fn new() -> Self {
70        Self {
71            slots: [VaultSlot::EMPTY; VAULT_SLOTS],
72            refs: [StrongDigest::ZERO; VAULT_SLOTS],
73            generations: [Generation::ZERO; VAULT_SLOTS],
74            last_seen_unix: 0,
75            locked: false,
76        }
77    }
78
79    #[inline]
80    /// `true` when locked.
81    pub const fn is_locked(&self) -> bool {
82        self.locked
83    }
84
85    #[inline]
86    /// Slot.
87    pub fn slot(&self, index: u8) -> Result<&VaultSlot, QdnfError> {
88        let i = index as usize;
89        if i >= VAULT_SLOTS {
90            return Err(QdnfError::Range);
91        }
92        Ok(&self.slots[i])
93    }
94
95    #[inline]
96    /// `LocalVault::issued_ref`.
97    pub fn issued_ref(&self, slot: u8) -> Result<KeyRef, QdnfError> {
98        let i = slot as usize;
99        if i >= VAULT_SLOTS || !self.slots[i].occupied {
100            return Err(QdnfError::Denied);
101        }
102        Ok(KeyRef {
103            slot,
104            generation: self.generations[i],
105        })
106    }
107}
108
109impl Default for LocalVault {
110    fn default() -> Self {
111        Self::new()
112    }
113}
114
115fn note_time(vault: &LocalVault, now: u64) -> Result<(), QdnfError> {
116    if now < vault.last_seen_unix {
117        // Clock rollback: do not extend expiry; fail closed.
118        return Err(QdnfError::Conflict);
119    }
120    Ok(())
121}
122
123/// Store a key *reference* digest. Raw secret bytes are not accepted here.
124pub fn store_ref(
125    vault: &mut LocalVault,
126    digest: StrongDigest,
127    now: u64,
128    expiry: u64,
129) -> Result<u8, QdnfError> {
130    if vault.locked {
131        return Err(QdnfError::Denied);
132    }
133    note_time(vault, now)?;
134    if digest.is_zero() {
135        return Err(QdnfError::Malformed);
136    }
137    if expiry <= now {
138        return Err(QdnfError::Expired);
139    }
140    let mut free = None;
141    let mut i = 0usize;
142    while i < VAULT_SLOTS {
143        if !vault.slots[i].occupied {
144            free = Some(i);
145            break;
146        }
147        i += 1;
148    }
149    let idx = free.ok_or(QdnfError::Capacity)?;
150    let next_gen = vault.generations[idx].next()?;
151    vault.slots[idx] = VaultSlot {
152        occupied: true,
153        expiry_unix: expiry,
154        locked: false,
155        crash_dump_allowed: false,
156    };
157    vault.refs[idx] = digest;
158    vault.generations[idx] = next_gen;
159    vault.last_seen_unix = now;
160    Ok(idx as u8)
161}
162
163/// Load the stored digest. Denied if the vault/slot is locked; Expired if
164/// `now` is at or past the slot deadline. Generation mismatch is stale.
165pub fn load_ref(vault: &mut LocalVault, slot: u8, now: u64) -> Result<StrongDigest, QdnfError> {
166    load_key_ref(
167        vault,
168        KeyRef {
169            slot,
170            generation: {
171                let i = slot as usize;
172                if i >= VAULT_SLOTS {
173                    return Err(QdnfError::Range);
174                }
175                vault.generations[i]
176            },
177        },
178        now,
179    )
180}
181
182/// Loads `key_ref`; error when absent/invalid.
183pub fn load_key_ref(
184    vault: &mut LocalVault,
185    key_ref: KeyRef,
186    now: u64,
187) -> Result<StrongDigest, QdnfError> {
188    note_time(vault, now)?;
189    let i = key_ref.slot as usize;
190    if i >= VAULT_SLOTS {
191        return Err(QdnfError::Range);
192    }
193    let slot = vault.slots[i];
194    if vault.locked || slot.locked {
195        return Err(QdnfError::Denied);
196    }
197    if !slot.occupied {
198        return Err(QdnfError::Denied);
199    }
200    if vault.generations[i] != key_ref.generation {
201        return Err(QdnfError::StaleGeneration);
202    }
203    if now >= slot.expiry_unix {
204        return Err(QdnfError::Expired);
205    }
206    vault.last_seen_unix = now;
207    Ok(vault.refs[i])
208}
209
210/// Irreversible local lock. There is no unlock / backdoor API.
211pub fn lock(vault: &mut LocalVault) {
212    vault.locked = true;
213    let mut i = 0usize;
214    while i < VAULT_SLOTS {
215        vault.slots[i].locked = true;
216        i += 1;
217    }
218}
219
220/// True when dumps must not include key material (`crash_dump_allowed` is false).
221pub fn crash_dump_redacted(vault: &LocalVault) -> bool {
222    let mut i = 0usize;
223    while i < VAULT_SLOTS {
224        if vault.slots[i].occupied && vault.slots[i].crash_dump_allowed {
225            return false;
226        }
227        i += 1;
228    }
229    true
230}
231
232/// `notification-preview-max` size in bytes.
233pub fn notification_preview_max_bytes() -> usize {
234    NOTIFICATION_PREVIEW_MAX_BYTES
235}
236
237/// Hardware-backed [`KeyRef`] support. Presence of `/dev/tpm0` is not enough:
238/// this crate has no TPM token binding and must not fake one.
239pub fn hardware_key_ref_supported() -> bool {
240    false
241}
242
243/// P4-with-hardware-token requirement. Unsupported hardware is unavailable,
244/// never a silent software downgrade.
245pub fn require_hardware_backed_p4() -> Result<(), QdnfError> {
246    if hardware_key_ref_supported() {
247        Ok(())
248    } else {
249        Err(QdnfError::UnknownProfile)
250    }
251}
252
253/// Catalog profile sealed under a wrap key. Ciphertext is not a key dump.
254#[repr(C)]
255#[derive(Clone, Copy, Debug, PartialEq, Eq)]
256pub struct SealedProfileBlob {
257    pub ct: [u8; SEALED_PROFILE_PLAIN_LEN],
258    pub tag: [u8; AEAD_TAG_LEN],
259    pub nonce: [u8; AEAD_NONCE_LEN],
260}
261
262fn encode_profile_plain(profile: ProtectionProfile) -> [u8; SEALED_PROFILE_PLAIN_LEN] {
263    let set = catalog_entry(profile);
264    let mut plain = [0u8; SEALED_PROFILE_PLAIN_LEN];
265    plain[0] = profile.to_u8();
266    plain[1] = set.control_count;
267    plain[2..].copy_from_slice(set.digest.as_bytes());
268    plain
269}
270
271/// Seal a catalog profile. Locked vaults fail closed. Zero keys are Malformed.
272pub fn seal_profile_blob(
273    vault: &LocalVault,
274    profile: ProtectionProfile,
275    key: &[u8; AEAD_KEY_LEN],
276    nonce: &[u8; AEAD_NONCE_LEN],
277) -> Result<SealedProfileBlob, QdnfError> {
278    if vault.locked {
279        return Err(QdnfError::Denied);
280    }
281    if key == &[0u8; AEAD_KEY_LEN] {
282        return Err(QdnfError::Malformed);
283    }
284    let mut ct = encode_profile_plain(profile);
285    let mut tag = [0u8; AEAD_TAG_LEN];
286    encrypt_in_place(key, nonce, SEALED_PROFILE_AAD, &mut ct, &mut tag)?;
287    Ok(SealedProfileBlob {
288        ct,
289        tag,
290        nonce: *nonce,
291    })
292}
293
294/// Open a sealed catalog profile. Wrong key is CryptoFailure (fail closed).
295pub fn open_profile_blob(
296    vault: &LocalVault,
297    blob: &SealedProfileBlob,
298    key: &[u8; AEAD_KEY_LEN],
299) -> Result<ProtectionProfile, QdnfError> {
300    if vault.locked {
301        return Err(QdnfError::Denied);
302    }
303    let mut plain = blob.ct;
304    match decrypt_in_place(key, &blob.nonce, SEALED_PROFILE_AAD, &mut plain, &blob.tag) {
305        Ok(()) => {}
306        Err(e) => {
307            let mut i = 0usize;
308            while i < plain.len() {
309                plain[i] = 0;
310                i += 1;
311            }
312            return Err(e);
313        }
314    }
315    let profile = ProtectionProfile::from_u8(plain[0])?;
316    let expected = encode_profile_plain(profile);
317    let mut i = 0usize;
318    while i < SEALED_PROFILE_PLAIN_LEN {
319        if plain[i] != expected[i] {
320            return Err(QdnfError::Malformed);
321        }
322        i += 1;
323    }
324    Ok(profile)
325}
326
327#[cfg(test)]
328mod tests {
329    use super::*;
330
331    fn digest(b: u8) -> StrongDigest {
332        let mut d = StrongDigest::ZERO;
333        d.0[0] = b;
334        d.0[47] = 7;
335        d
336    }
337
338    #[test]
339    fn store_and_load_ref_round_trip() {
340        let mut v = LocalVault::new();
341        let slot = store_ref(&mut v, digest(1), 10, 100).unwrap();
342        assert_eq!(load_ref(&mut v, slot, 11).unwrap(), digest(1));
343        let kr = v.issued_ref(slot).unwrap();
344        assert_eq!(kr.slot, slot);
345        assert_ne!(kr.generation, Generation::ZERO);
346    }
347
348    #[test]
349    fn load_expired_is_expired() {
350        let mut v = LocalVault::new();
351        let slot = store_ref(&mut v, digest(2), 10, 20).unwrap();
352        assert_eq!(load_ref(&mut v, slot, 20).unwrap_err(), QdnfError::Expired);
353    }
354
355    #[test]
356    fn lock_denies_load_and_store() {
357        let mut v = LocalVault::new();
358        let slot = store_ref(&mut v, digest(3), 1, 50).unwrap();
359        lock(&mut v);
360        assert_eq!(load_ref(&mut v, slot, 2).unwrap_err(), QdnfError::Denied);
361        assert_eq!(
362            store_ref(&mut v, digest(4), 3, 50).unwrap_err(),
363            QdnfError::Denied
364        );
365        assert!(v.is_locked());
366    }
367
368    #[test]
369    fn crash_dump_redacted_when_not_allowed() {
370        let mut v = LocalVault::new();
371        let _ = store_ref(&mut v, digest(5), 1, 50).unwrap();
372        assert!(!v.slot(0).unwrap().crash_dump_allowed);
373        assert!(crash_dump_redacted(&v));
374    }
375
376    #[test]
377    fn notification_preview_is_small() {
378        assert_eq!(notification_preview_max_bytes(), 32);
379        assert!(notification_preview_max_bytes() < 256);
380    }
381
382    #[test]
383    fn hardware_key_ref_not_faked() {
384        assert!(!hardware_key_ref_supported());
385        assert_eq!(require_hardware_backed_p4(), Err(QdnfError::UnknownProfile));
386    }
387
388    #[test]
389    fn clock_rollback_does_not_extend_expiry() {
390        let mut v = LocalVault::new();
391        let slot = store_ref(&mut v, digest(6), 50, 200).unwrap();
392        let expiry = v.slot(slot).unwrap().expiry_unix;
393        assert_eq!(load_ref(&mut v, slot, 40).unwrap_err(), QdnfError::Conflict);
394        assert_eq!(v.slot(slot).unwrap().expiry_unix, expiry);
395    }
396
397    #[test]
398    fn stale_generation_rejected() {
399        let mut v = LocalVault::new();
400        let slot = store_ref(&mut v, digest(8), 1, 50).unwrap();
401        let mut kr = v.issued_ref(slot).unwrap();
402        kr.generation = Generation::ZERO;
403        assert_eq!(
404            load_key_ref(&mut v, kr, 2).unwrap_err(),
405            QdnfError::StaleGeneration
406        );
407    }
408
409    #[test]
410    fn capacity_eight() {
411        let mut v = LocalVault::new();
412        let mut i = 0u8;
413        while i < VAULT_SLOTS as u8 {
414            store_ref(&mut v, digest(10 + i), 1, 100).unwrap();
415            i += 1;
416        }
417        assert_eq!(
418            store_ref(&mut v, digest(99), 2, 100).unwrap_err(),
419            QdnfError::Capacity
420        );
421    }
422
423    #[test]
424    fn sealed_profile_blob_round_trip() {
425        let v = LocalVault::new();
426        let key = [7u8; AEAD_KEY_LEN];
427        let nonce = [3u8; AEAD_NONCE_LEN];
428        let blob = seal_profile_blob(&v, ProtectionProfile::P2, &key, &nonce).unwrap();
429        assert_eq!(
430            open_profile_blob(&v, &blob, &key).unwrap(),
431            ProtectionProfile::P2
432        );
433    }
434
435    #[test]
436    fn sealed_profile_wrong_key_fails_closed() {
437        let v = LocalVault::new();
438        let key = [7u8; AEAD_KEY_LEN];
439        let nonce = [3u8; AEAD_NONCE_LEN];
440        let blob = seal_profile_blob(&v, ProtectionProfile::P3, &key, &nonce).unwrap();
441        let wrong = [8u8; AEAD_KEY_LEN];
442        assert_eq!(
443            open_profile_blob(&v, &blob, &wrong).unwrap_err(),
444            QdnfError::CryptoFailure
445        );
446        let mut locked = LocalVault::new();
447        lock(&mut locked);
448        assert_eq!(
449            seal_profile_blob(&locked, ProtectionProfile::P1, &key, &nonce).unwrap_err(),
450            QdnfError::Denied
451        );
452    }
453}