Skip to main content

qualia_core_db/net/qdnf/biometrics/
policy.rs

1//! Template publication, reuse, identity assertion and recovery (E15.2, E15.4).
2//!
3//! Public templates, unsalted reusable hashes, cross-purpose linking and
4//! silent identification/surveillance reuse are Denied. Identity assertion
5//! requires an independent authorised instrument. A non-biometric PIN/key-ref
6//! recovery path remains available.
7
8use crate::net::qdnf::errors::QdnfError;
9use crate::net::qdnf::profiles::{load_key_ref, KeyRef, LocalVault};
10use crate::net::qdnf::types::{Generation, StrongDigest};
11
12use super::capture::RawCapture;
13use super::match_local::MatchResult;
14use super::template::DerivedTemplate;
15use super::BiometricObjectKind;
16
17/// Independent credential/identity decision. Never implicit sameAs from a match.
18#[repr(C)]
19#[derive(Clone, Copy, Debug, PartialEq, Eq)]
20pub struct IdentityAssertion {
21    issuer: StrongDigest,
22    instrument: StrongDigest,
23    purpose: StrongDigest,
24    generation: Generation,
25}
26
27impl IdentityAssertion {
28    /// Builds `IdentityAssertion` from `independent_instrument`.
29    pub fn from_independent_instrument(
30        issuer: StrongDigest,
31        instrument: StrongDigest,
32        purpose: StrongDigest,
33        generation: Generation,
34    ) -> Result<Self, QdnfError> {
35        if issuer.is_zero() || instrument.is_zero() || purpose.is_zero() {
36            return Err(QdnfError::Unauthorized);
37        }
38        if generation == Generation::ZERO {
39            return Err(QdnfError::Unauthorized);
40        }
41        Ok(Self {
42            issuer,
43            instrument,
44            purpose,
45            generation,
46        })
47    }
48
49    #[inline]
50    /// Biometric object kind.
51    pub const fn kind(self) -> BiometricObjectKind {
52        BiometricObjectKind::IdentityAssertion
53    }
54
55    #[inline]
56    /// Issuer digest.
57    pub const fn issuer(self) -> StrongDigest {
58        self.issuer
59    }
60
61    #[inline]
62    /// Instrument digest.
63    pub const fn instrument(self) -> StrongDigest {
64        self.instrument
65    }
66
67    #[inline]
68    /// Purpose digest.
69    pub const fn purpose(self) -> StrongDigest {
70        self.purpose
71    }
72
73    #[inline]
74    /// Generation.
75    pub const fn generation(self) -> Generation {
76        self.generation
77    }
78}
79
80/// A match result is not an identity assertion and cannot mint one.
81pub fn assert_identity_from_match(_result: &MatchResult) -> Result<IdentityAssertion, QdnfError> {
82    Err(QdnfError::Denied)
83}
84
85/// Public template indexes are not permitted.
86pub fn publish_template(_template: &DerivedTemplate) -> Result<(), QdnfError> {
87    Err(QdnfError::Denied)
88}
89
90/// Unsalted reusable biometric hashes are never allowed.
91#[inline]
92pub const fn unsalted_reusable_hash_allowed() -> bool {
93    false
94}
95
96/// Fail-closed: linkable unsalted hashes are denied.
97pub fn unsalted_reusable_hash(_capture: &RawCapture) -> Result<StrongDigest, QdnfError> {
98    Err(QdnfError::Denied)
99}
100
101/// Cross-purpose / cross-domain template linking is Denied (S19).
102pub fn cross_purpose_link(a: &DerivedTemplate, b: &DerivedTemplate) -> Result<(), QdnfError> {
103    let _ = (a, b);
104    Err(QdnfError::Denied)
105}
106
107/// Requested reuse of a stored template.
108#[repr(u8)]
109#[derive(Clone, Copy, Debug, PartialEq, Eq)]
110pub enum ReuseIntent {
111    AuthorisedLocalMatch = 1,
112    Identification = 2,
113    Surveillance = 3,
114}
115
116/// Silent identification and surveillance reuse are Denied. Authorised local
117/// match is allowed only for the recorded purpose on a live template.
118pub fn reuse_template(
119    template: &DerivedTemplate,
120    intent: ReuseIntent,
121    requested_purpose: StrongDigest,
122) -> Result<(), QdnfError> {
123    match intent {
124        ReuseIntent::Identification | ReuseIntent::Surveillance => Err(QdnfError::Denied),
125        ReuseIntent::AuthorisedLocalMatch => {
126            if template.is_revoked() {
127                return Err(QdnfError::Revoked);
128            }
129            if requested_purpose.is_zero() || requested_purpose != template.purpose() {
130                return Err(QdnfError::Denied);
131            }
132            Ok(())
133        }
134    }
135}
136
137/// Covert population identification from a template is Denied.
138pub fn silent_identify(_template: &DerivedTemplate) -> Result<(), QdnfError> {
139    Err(QdnfError::Denied)
140}
141
142/// Non-biometric recovery/access alternative remains available (S20).
143#[inline]
144pub const fn recovery_without_biometric() -> bool {
145    true
146}
147
148/// PIN knowledge check. `pin_digest` is not a biometric hash.
149pub fn recover_with_pin(
150    pin_digest: StrongDigest,
151    stored_pin_digest: StrongDigest,
152) -> Result<(), QdnfError> {
153    if pin_digest.is_zero() || stored_pin_digest.is_zero() {
154        return Err(QdnfError::Malformed);
155    }
156    if pin_digest != stored_pin_digest {
157        return Err(QdnfError::Denied);
158    }
159    Ok(())
160}
161
162/// Hardware/vault key-ref recovery. Possession of a slot handle, not a sample.
163pub fn recover_with_key_ref(
164    vault: &mut LocalVault,
165    key_ref: KeyRef,
166    now_unix: u64,
167) -> Result<StrongDigest, QdnfError> {
168    load_key_ref(vault, key_ref, now_unix)
169}
170
171#[cfg(test)]
172mod tests {
173    use super::*;
174    use crate::net::qdnf::biometrics::capture::{Modality, RawCapture};
175    use crate::net::qdnf::biometrics::match_local::match_local;
176    use crate::net::qdnf::biometrics::template::{derive_template, revoke_template};
177    use crate::net::qdnf::profiles::store_ref;
178
179    fn d(tag: u8) -> StrongDigest {
180        let mut x = StrongDigest::ZERO;
181        x.0[0] = tag;
182        x.0[47] = 0xC5;
183        x
184    }
185
186    fn capture() -> RawCapture {
187        RawCapture::acquire(Modality::Face, d(1), d(2), 30, 1).unwrap()
188    }
189
190    fn template_for(purpose: u8) -> DerivedTemplate {
191        derive_template(&capture(), d(purpose), d(11), d(12), Generation(5)).unwrap()
192    }
193
194    #[test]
195    fn identity_assertion_is_independent_of_match() {
196        let probe = capture();
197        let reference = template_for(10);
198        let matched = match_local(&probe, &reference, true, 1, 50).unwrap();
199        assert_eq!(
200            assert_identity_from_match(&matched).unwrap_err(),
201            QdnfError::Denied
202        );
203        let assertion =
204            IdentityAssertion::from_independent_instrument(d(20), d(21), d(22), Generation(1))
205                .unwrap();
206        assert_eq!(assertion.kind(), BiometricObjectKind::IdentityAssertion);
207        assert_ne!(assertion.kind(), matched.kind());
208    }
209
210    #[test]
211    fn public_templates_and_unsalted_hashes_denied() {
212        let t = template_for(10);
213        assert_eq!(publish_template(&t).unwrap_err(), QdnfError::Denied);
214        assert!(!unsalted_reusable_hash_allowed());
215        assert_eq!(
216            unsalted_reusable_hash(&capture()).unwrap_err(),
217            QdnfError::Denied
218        );
219    }
220
221    #[test]
222    fn cross_purpose_linking_denied() {
223        let a = template_for(10);
224        let b = template_for(11);
225        assert_ne!(a.purpose(), b.purpose());
226        assert_eq!(cross_purpose_link(&a, &b).unwrap_err(), QdnfError::Denied);
227        assert_eq!(cross_purpose_link(&a, &a).unwrap_err(), QdnfError::Denied);
228    }
229
230    #[test]
231    fn silent_identification_and_surveillance_denied() {
232        let t = template_for(10);
233        assert_eq!(silent_identify(&t).unwrap_err(), QdnfError::Denied);
234        assert_eq!(
235            reuse_template(&t, ReuseIntent::Identification, d(10)).unwrap_err(),
236            QdnfError::Denied
237        );
238        assert_eq!(
239            reuse_template(&t, ReuseIntent::Surveillance, d(10)).unwrap_err(),
240            QdnfError::Denied
241        );
242        reuse_template(&t, ReuseIntent::AuthorisedLocalMatch, d(10)).unwrap();
243        assert_eq!(
244            reuse_template(&t, ReuseIntent::AuthorisedLocalMatch, d(99)).unwrap_err(),
245            QdnfError::Denied
246        );
247    }
248
249    #[test]
250    fn revoked_template_cannot_be_reused_locally() {
251        let mut t = template_for(10);
252        revoke_template(&mut t).unwrap();
253        assert_eq!(
254            reuse_template(&t, ReuseIntent::AuthorisedLocalMatch, d(10)).unwrap_err(),
255            QdnfError::Revoked
256        );
257    }
258
259    #[test]
260    fn pin_and_key_ref_recovery_are_not_biometric_hashes() {
261        assert!(recovery_without_biometric());
262        recover_with_pin(d(7), d(7)).unwrap();
263        assert_eq!(recover_with_pin(d(7), d(8)).unwrap_err(), QdnfError::Denied);
264        assert_eq!(
265            recover_with_pin(StrongDigest::ZERO, d(7)).unwrap_err(),
266            QdnfError::Malformed
267        );
268
269        let mut vault = LocalVault::new();
270        let slot = store_ref(&mut vault, d(40), 1, 100).unwrap();
271        let key_ref = vault.issued_ref(slot).unwrap();
272        let loaded = recover_with_key_ref(&mut vault, key_ref, 2).unwrap();
273        assert_eq!(loaded, d(40));
274        assert_ne!(loaded, capture().device());
275    }
276}