Skip to main content

qualia_core_db/net/qdnf/biometrics/
template.rs

1//! Derived cancellable templates (E15.1, E15.5).
2//!
3//! Stored value is a revocable domain identifier, not a reusable global
4//! biometric hash. Rekeying an envelope does not revoke an already disclosed
5//! raw sample; revocation here isolates the local reference.
6
7use crate::crypto::network::digest::sha384;
8use crate::net::qdnf::errors::QdnfError;
9use crate::net::qdnf::types::{Generation, StrongDigest};
10
11use super::capture::{Modality, RawCapture};
12use super::BiometricObjectKind;
13
14pub const MAX_TEMPLATE_SLOTS: usize = 8;
15
16/// Domain-bound revocable identifier. Not an unsalted biometric hash.
17#[repr(C)]
18#[derive(Clone, Copy, Debug, PartialEq, Eq)]
19pub struct CancellableId(pub StrongDigest);
20
21impl CancellableId {
22    /// Bind purpose, algorithm/transform version and generation. Raw sample
23    /// bytes are intentionally absent from this derivation.
24    pub fn derive(
25        purpose: StrongDigest,
26        algorithm_version: StrongDigest,
27        generation: Generation,
28    ) -> Result<Self, QdnfError> {
29        if purpose.is_zero() || algorithm_version.is_zero() {
30            return Err(QdnfError::Malformed);
31        }
32        if generation == Generation::ZERO {
33            return Err(QdnfError::Incomplete);
34        }
35        let mut buf = [0u8; 104];
36        buf[..48].copy_from_slice(&purpose.0);
37        buf[48..96].copy_from_slice(&algorithm_version.0);
38        buf[96..104].copy_from_slice(&generation.0.to_le_bytes());
39        Ok(Self(sha384(&buf)))
40    }
41}
42
43/// Encrypted, purpose-bound template handle. No public lookup.
44#[repr(C)]
45#[derive(Clone, Copy, Debug, PartialEq, Eq)]
46pub struct DerivedTemplate {
47    revocable_id: CancellableId,
48    modality: Modality,
49    algorithm_version: StrongDigest,
50    provenance: StrongDigest,
51    purpose: StrongDigest,
52    generation: Generation,
53    revoked: bool,
54}
55
56impl DerivedTemplate {
57    #[inline]
58    /// Biometric object kind.
59    pub const fn kind(self) -> BiometricObjectKind {
60        BiometricObjectKind::DerivedTemplate
61    }
62
63    #[inline]
64    /// Cancellable template id.
65    pub const fn revocable_id(self) -> CancellableId {
66        self.revocable_id
67    }
68
69    #[inline]
70    /// Modality.
71    pub const fn modality(self) -> Modality {
72        self.modality
73    }
74
75    #[inline]
76    /// Algorithm-version digest.
77    pub const fn algorithm_version(self) -> StrongDigest {
78        self.algorithm_version
79    }
80
81    #[inline]
82    /// Provenance digest.
83    pub const fn provenance(self) -> StrongDigest {
84        self.provenance
85    }
86
87    #[inline]
88    /// Purpose digest.
89    pub const fn purpose(self) -> StrongDigest {
90        self.purpose
91    }
92
93    #[inline]
94    /// Generation.
95    pub const fn generation(self) -> Generation {
96        self.generation
97    }
98
99    #[inline]
100    /// `true` when revoked.
101    pub const fn is_revoked(self) -> bool {
102        self.revoked
103    }
104
105    /// A template is not a reusable global biometric hash.
106    pub fn as_global_hash(&self) -> Result<StrongDigest, QdnfError> {
107        Err(QdnfError::Denied)
108    }
109}
110
111/// Derive a cancellable template from a local capture. The raw sample is not
112/// hashed into a reusable identifier.
113pub fn derive_template(
114    capture: &RawCapture,
115    purpose: StrongDigest,
116    algorithm_version: StrongDigest,
117    provenance: StrongDigest,
118    generation: Generation,
119) -> Result<DerivedTemplate, QdnfError> {
120    if provenance.is_zero() {
121        return Err(QdnfError::Incomplete);
122    }
123    let revocable_id = CancellableId::derive(purpose, algorithm_version, generation)?;
124    Ok(DerivedTemplate {
125        revocable_id,
126        modality: capture.modality(),
127        algorithm_version,
128        provenance,
129        purpose,
130        generation,
131        revoked: false,
132    })
133}
134
135/// Isolate a compromised reference. The identifier is no longer usable.
136pub fn revoke_template(template: &mut DerivedTemplate) -> Result<(), QdnfError> {
137    if template.revoked {
138        return Ok(());
139    }
140    template.revoked = true;
141    Ok(())
142}
143
144#[cfg(test)]
145mod tests {
146    use super::*;
147
148    fn d(tag: u8) -> StrongDigest {
149        let mut x = StrongDigest::ZERO;
150        x.0[0] = tag;
151        x.0[47] = 0xC2;
152        x
153    }
154
155    fn capture() -> RawCapture {
156        RawCapture::acquire(Modality::Fingerprint, d(1), d(2), 20, 1).unwrap()
157    }
158
159    #[test]
160    fn cancellable_id_is_domain_bound_not_raw_hash() {
161        let a = CancellableId::derive(d(10), d(11), Generation(1)).unwrap();
162        let b = CancellableId::derive(d(99), d(11), Generation(1)).unwrap();
163        assert_ne!(a.0, b.0);
164        assert_ne!(a.0, d(1));
165        assert_eq!(
166            CancellableId::derive(d(10), d(11), Generation::ZERO).unwrap_err(),
167            QdnfError::Incomplete
168        );
169    }
170
171    #[test]
172    fn derive_stores_revocable_identifier() {
173        let t = derive_template(&capture(), d(10), d(11), d(12), Generation(2)).unwrap();
174        assert_eq!(t.kind(), BiometricObjectKind::DerivedTemplate);
175        assert!(!t.is_revoked());
176        assert_eq!(t.purpose(), d(10));
177        assert_eq!(t.modality(), Modality::Fingerprint);
178        assert_eq!(t.as_global_hash().unwrap_err(), QdnfError::Denied);
179        let expected = CancellableId::derive(d(10), d(11), Generation(2)).unwrap();
180        assert_eq!(t.revocable_id(), expected);
181    }
182
183    #[test]
184    fn revoke_isolates_reference() {
185        let mut t = derive_template(&capture(), d(10), d(11), d(12), Generation(3)).unwrap();
186        revoke_template(&mut t).unwrap();
187        assert!(t.is_revoked());
188        revoke_template(&mut t).unwrap();
189        assert!(t.is_revoked());
190    }
191
192    #[test]
193    fn missing_provenance_is_incomplete() {
194        assert_eq!(
195            derive_template(&capture(), d(10), d(11), StrongDigest::ZERO, Generation(1))
196                .unwrap_err(),
197            QdnfError::Incomplete
198        );
199    }
200}