Uv bio enrollment, continued (#734)

* Add fingerprint and UV support

* Refactors fingerprint code

Introduces a compile flag to toggle fingerprint code.
Makes data structures and style match the library's current standard.
Removes some undesired customization and debug features.

* Makes template IDs unique

Also applies clippy lints.

* Use all features for clippy, to reduce maintenance

* Fixes misfiring unit test

For some non-default customization settings, the test would give a false
negative.

---------

Co-authored-by: Brad Campbell <[email protected]>

Author: kaczmarczyck

Cargo.toml

@@ -43,6 +43,7 @@ with_ctap1 = ["opensk/with_ctap1"]
 with_nfc = ["libtock_drivers/with_nfc"]
 vendor_hid = ["opensk/vendor_hid"]
 ed25519 = ["ed25519-compact", "opensk/ed25519"]
+fingerprint = ["opensk/fingerprint"]
 
 [dev-dependencies]
 enum-iterator = "0.6.0"

libraries/opensk/Cargo.toml

@@ -42,6 +42,7 @@ with_ctap1 = []
 vendor_hid = []
 fuzz = ["arbitrary", "std"]
 ed25519 = ["ed25519-compact"]
+fingerprint = []
 
 [dev-dependencies]
 enum-iterator = "0.6.0"

libraries/opensk/src/api/customization.rs

@@ -145,7 +145,7 @@ pub trait Customization {
     /// this value.
     fn max_msg_size(&self) -> usize;
 
-    /// Sets the number of consecutive failed PINs before blocking interaction.
+    /// The number of consecutive failed PINs before blocking interaction.
     ///
     /// # Invariant
     ///
@@ -155,6 +155,42 @@ pub trait Customization {
     /// The fail retry counter is reset after entering the correct PIN.
     fn max_pin_retries(&self) -> u8;
 
+    /// Maximum number of UV retries performed before returning an error.
+    ///
+    /// Corresponds to maxUvAttemptsForInternalRetries in CTAP 2.1 onwards.
+    /// When internal retries are allowed, the authenticator will retry UV
+    /// before communicating its result through CTAP.
+    ///
+    /// # Invariant
+    ///
+    /// - Must be in the range [1, `max_uv_retries`].
+    /// - If `preferred_platform_uv_attempts` is not 1, must be in [1, 5].
+    #[cfg(feature = "fingerprint")]
+    fn max_uv_attempts_for_internal_retries(&self) -> u8;
+
+    /// The number of consecutive failed UV attempts before blocking built-in UV.
+    ///
+    /// Corresponds to maxUvRetries in CTAP 2.1 onwards.
+    ///
+    /// # Invariant
+    ///
+    /// - Must be in the range [1, 25].
+    #[cfg(feature = "fingerprint")]
+    fn max_uv_retries(&self) -> u8;
+
+    /// Preferred number of UV attempts before falling back to PIN.
+    ///
+    /// Corresponds to preferredPlatformUvAttempts in CTAP 2.1 onwards.
+    /// States the preference how often the platform should invoke
+    /// `getPinUvAuthTokenUsingUvWithPermissions` before falling back to
+    /// `getPinUvAuthTokenUsingPinWithPermissions` or displaying an error.
+    ///
+    /// # Invariant
+    ///
+    /// - Must be greater than 0.
+    #[cfg(feature = "fingerprint")]
+    fn preferred_platform_uv_attempts(&self) -> usize;
+
     /// Enables or disables basic attestation for FIDO2.
     ///
     /// # Invariant
@@ -252,6 +288,12 @@ pub trait Customization {
     /// With P=20 and K=150, we have I=2M which is enough for 500 increments per day
     /// for 10 years.
     fn max_supported_resident_keys(&self) -> usize;
+
+    /// Maximum size of a friendly name for a UV template.
+    ///
+    /// This value limits storage requirements for fingerprints.
+    #[cfg(feature = "fingerprint")]
+    fn max_template_friendly_name(&self) -> usize;
 }
 
 #[derive(Clone)]
@@ -266,13 +308,21 @@ pub struct CustomizationImpl {
     pub enterprise_rp_id_list: &'static [&'static str],
     pub max_msg_size: usize,
     pub max_pin_retries: u8,
+    #[cfg(feature = "fingerprint")]
+    pub max_uv_attempts_for_internal_retries: u8,
+    #[cfg(feature = "fingerprint")]
+    pub max_uv_retries: u8,
+    #[cfg(feature = "fingerprint")]
+    pub preferred_platform_uv_attempts: usize,
     pub use_batch_attestation: bool,
     pub use_signature_counter: bool,
     pub max_cred_blob_length: usize,
     pub max_credential_count_in_list: Option<usize>,
     pub max_large_blob_array_size: usize,
     pub max_rp_ids_length: usize,
     pub max_supported_resident_keys: usize,
+    #[cfg(feature = "fingerprint")]
+    pub max_template_friendly_name: usize,
 }
 
 pub const DEFAULT_CUSTOMIZATION: CustomizationImpl = CustomizationImpl {
@@ -286,13 +336,21 @@ pub const DEFAULT_CUSTOMIZATION: CustomizationImpl = CustomizationImpl {
     enterprise_rp_id_list: &[],
     max_msg_size: 7609,
     max_pin_retries: 8,
+    #[cfg(feature = "fingerprint")]
+    max_uv_attempts_for_internal_retries: 1,
+    #[cfg(feature = "fingerprint")]
+    max_uv_retries: 8,
+    #[cfg(feature = "fingerprint")]
+    preferred_platform_uv_attempts: 1,
     use_batch_attestation: false,
     use_signature_counter: true,
     max_cred_blob_length: 32,
     max_credential_count_in_list: None,
     max_large_blob_array_size: 2048,
     max_rp_ids_length: 8,
     max_supported_resident_keys: 150,
+    #[cfg(feature = "fingerprint")]
+    max_template_friendly_name: 64,
 };
 
 impl Customization for CustomizationImpl {
@@ -347,6 +405,21 @@ impl Customization for CustomizationImpl {
         self.max_pin_retries
     }
 
+    #[cfg(feature = "fingerprint")]
+    fn max_uv_attempts_for_internal_retries(&self) -> u8 {
+        self.max_uv_attempts_for_internal_retries
+    }
+
+    #[cfg(feature = "fingerprint")]
+    fn max_uv_retries(&self) -> u8 {
+        self.max_uv_retries
+    }
+
+    #[cfg(feature = "fingerprint")]
+    fn preferred_platform_uv_attempts(&self) -> usize {
+        self.preferred_platform_uv_attempts
+    }
+
     fn use_batch_attestation(&self) -> bool {
         self.use_batch_attestation
     }
@@ -374,6 +447,11 @@ impl Customization for CustomizationImpl {
     fn max_supported_resident_keys(&self) -> usize {
         self.max_supported_resident_keys
     }
+
+    #[cfg(feature = "fingerprint")]
+    fn max_template_friendly_name(&self) -> usize {
+        self.max_template_friendly_name
+    }
 }
 
 #[cfg(feature = "std")]
@@ -446,6 +524,32 @@ pub fn is_valid(customization: &impl Customization) -> bool {
         return false;
     }
 
+    #[cfg(feature = "fingerprint")]
+    {
+        // Maximum UV retries must be in range [1, 25].
+        if customization.max_uv_retries() < 1 || customization.max_uv_retries() > 25 {
+            return false;
+        }
+
+        // Maximum internal UV attemps must be in range [1, `max_uv_retries`].
+        // If preferred platform UV attemps is not 1, must additionally be in [1, 5].
+        if customization.max_uv_attempts_for_internal_retries() < 1
+            || customization.max_uv_attempts_for_internal_retries() > customization.max_uv_retries()
+        {
+            return false;
+        }
+        if customization.preferred_platform_uv_attempts() != 1
+            && customization.max_uv_attempts_for_internal_retries() > 5
+        {
+            return false;
+        }
+
+        // Preferred number of UV attempts must be positive.
+        if customization.preferred_platform_uv_attempts() == 0 {
+            return false;
+        }
+    }
+
     true
 }
 
@@ -471,13 +575,21 @@ mod test {
             enterprise_rp_id_list: &[],
             max_msg_size: 7609,
             max_pin_retries: 8,
+            #[cfg(feature = "fingerprint")]
+            max_uv_attempts_for_internal_retries: 1,
+            #[cfg(feature = "fingerprint")]
+            max_uv_retries: 8,
+            #[cfg(feature = "fingerprint")]
+            preferred_platform_uv_attempts: 1,
             use_batch_attestation: true,
             use_signature_counter: true,
             max_cred_blob_length: 32,
             max_credential_count_in_list: Some(3),
             max_large_blob_array_size: 2048,
             max_rp_ids_length: 8,
             max_supported_resident_keys: 150,
+            #[cfg(feature = "fingerprint")]
+            max_template_friendly_name: 64,
         };
         assert_eq!(customization.aaguid(), &[0; AAGUID_LENGTH]);
         assert!(customization.allows_pin_protocol_v1());
@@ -492,12 +604,20 @@ mod test {
         assert!(customization.enterprise_rp_id_list().is_empty());
         assert_eq!(customization.max_msg_size(), 7609);
         assert_eq!(customization.max_pin_retries(), 8);
+        #[cfg(feature = "fingerprint")]
+        assert_eq!(customization.max_uv_attempts_for_internal_retries(), 1);
+        #[cfg(feature = "fingerprint")]
+        assert_eq!(customization.max_uv_retries(), 8);
+        #[cfg(feature = "fingerprint")]
+        assert_eq!(customization.preferred_platform_uv_attempts(), 1);
         assert!(customization.use_batch_attestation());
         assert!(customization.use_signature_counter());
         assert_eq!(customization.max_cred_blob_length(), 32);
         assert_eq!(customization.max_credential_count_in_list(), Some(3));
         assert_eq!(customization.max_large_blob_array_size(), 2048);
         assert_eq!(customization.max_rp_ids_length(), 8);
         assert_eq!(customization.max_supported_resident_keys(), 150);
+        #[cfg(feature = "fingerprint")]
+        assert_eq!(customization.max_template_friendly_name(), 64);
     }
 }

libraries/opensk/src/api/fingerprint.rs

@@ -0,0 +1,100 @@
+use crate::ctap::status_code::CtapResult;
+use alloc::vec::Vec;
+use sk_cbor as cbor;
+
+#[derive(Debug, PartialEq, Eq)]
+pub enum FingerprintKind {
+    Touch = 1,
+    Swipe = 2,
+}
+
+#[derive(Debug, PartialEq, Eq)]
+pub enum FingerprintCheckError {
+    NoMatch,
+    Timeout,
+    Other,
+}
+
+/// Status code for enrolling fingerprints
+///
+/// See lastEnrollSampleStatus in section authenticatorBioEnrollment
+#[derive(Debug, PartialEq, Eq)]
+pub enum Ctap2EnrollFeedback {
+    FpGood = 0x00,
+    FpTooHigh = 0x01,
+    FpTooLow = 0x02,
+    FpTooLeft = 0x03,
+    FpTooRight = 0x04,
+    FpTooFast = 0x05,
+    FpTooSlow = 0x06,
+    FpPoorQuality = 0x07,
+    FpTooSkewed = 0x08,
+    FpTooShort = 0x09,
+    FpMergeFailure = 0x0A,
+    FpExists = 0x0B,
+    // 0x0C is intentionally unused
+    NoUserActivity = 0x0D,
+    NoUserPresenceTransition = 0x0E,
+}
+
+impl From<Ctap2EnrollFeedback> for cbor::Value {
+    fn from(feedback: Ctap2EnrollFeedback) -> Self {
+        (feedback as u64).into()
+    }
+}
+
+pub trait Fingerprint {
+    /// Starts the fingerprint enrollment process.
+    ///
+    /// Returns the newly assigned template ID.
+    fn prepare_enrollment(&mut self) -> CtapResult<Vec<u8>>;
+
+    /// Captures a fingerprint image.
+    ///
+    /// Waits for the user to present a finger.
+    /// If `timeout_ms` is provided, the function times out on user inaction.
+    /// `prepare_enrollment` must be called first.
+    /// A returned `Ctap2StatusCode` indicates an unexpected failure processing
+    /// the command.
+    /// The `Ctap2EnrollFeedback` contains expected errors from the fingerprint
+    /// capture process.
+    /// Also returns the expected number of remaining samples.
+    fn capture_sample(
+        &mut self,
+        template_id: &[u8],
+        timeout_ms: Option<usize>,
+    ) -> CtapResult<(Ctap2EnrollFeedback, usize)>;
+
+    /// Cancel a fingerprint enrollment.
+    fn cancel_enrollment(&mut self) -> CtapResult<()>;
+
+    /// Delete the fingerprint matching the given template ID.
+    ///
+    /// Does not delete stored information from persistent storage.
+    /// This function signals to the sensor to remove the enrollment only.
+    fn remove_enrollment(&mut self, template_id: &[u8]) -> CtapResult<()>;
+
+    /// Initialize hardware to prepare a fingerprint check.
+    ///
+    /// Called before [`check_fingerprint`].
+    /// Useful for starting any operation that needs to happen before
+    /// potentially repeated fingerprint checks, such as blinking LEDs.
+    fn check_fingerprint_init(&mut self);
+
+    /// Collects a fingerprint from the user and verifies it.
+    ///
+    /// Waits for the user to present a finger, or the timeout to pass.
+    /// Returns Ok if the fingerprint was valid, and an error otherwise.
+    fn check_fingerprint(&mut self, timeout_ms: usize) -> Result<(), FingerprintCheckError>;
+
+    /// Deinitilize hardware after a fingerprint check.
+    ///
+    /// Called after [`check_fingerprint`] is finished.
+    fn check_fingerprint_complete(&mut self);
+
+    /// The kind of fingerprint sensor.
+    fn fingerprint_kind(&self) -> FingerprintKind;
+
+    /// Maximum number of good samples required for enrollment.
+    fn max_capture_samples_required_for_enroll(&self) -> usize;
+}

libraries/opensk/src/api/mod.rs

@@ -21,6 +21,8 @@ pub mod clock;
 pub mod connection;
 pub mod crypto;
 pub mod customization;
+#[cfg(feature = "fingerprint")]
+pub mod fingerprint;
 pub mod firmware_protection;
 pub mod key_store;
 pub mod persist;