2908941137

Build Type

github

Committed by GitHub

Commit Message

<a href="https://github.com/google/OpenSK/commit/<a class=hub.com/google/OpenSK/commit/<a class="double-link" href="https://git"><a class=hub.com/google/OpenSK/commit/<a class="double-link" href="https://git"><a class=hub.com/google/OpenSK/commit/<a class="double-link" href="https://git"><a class=hub.com/google/OpenSK/commit/787c8a79571f7239c24e5f6075102de9c274dcb0">787c8a795">&lt;a href=&quot;https://github.com/google/OpenSK/commit/</a><a class="double-link" href="https://github.com/google/OpenSK/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/google/OpenSK/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/google/OpenSK/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/google/OpenSK/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/google/OpenSK/commit/787c8a79571f7239c24e5f6075102de9c274dcb0">787c8a795</a><a href="https://github.com/google/OpenSK/commit/787c8a79571f7239c24e5f6075102de9c274dcb0">&quot;&gt;&amp;lt;a href=&amp;quot;https://github.com/google/OpenSK/commit/&lt;/a&gt;&lt;a class=&quot;double-link&quot; href=&quot;https://github.com/google/OpenSK/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://git&quot;&gt;&amp;lt;a class=&lt;/a&gt;hub.com/google/OpenSK/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://git&quot;&gt;&amp;lt;a class=&lt;/a&gt;hub.com/google/OpenSK/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://git&quot;&gt;&amp;lt;a class=&lt;/a&gt;hub.com/google/OpenSK/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://git&quot;&gt;&amp;lt;a class=&lt;/a&gt;hub.com/google/OpenSK/commit/787c8a79571f7239c24e5f6075102de9c274dcb0&quot;&gt;787c8a795&lt;/a&gt;&lt;a href=&quot;https://github.com/google/OpenSK/commit/787c8a79571f7239c24e5f6075102de9c274dcb0&quot;&gt;&amp;quot;&amp;gt;&amp;amp;lt;a href=&amp;amp;quot;https://github.com/google/OpenSK/commit/&amp;lt;/a&amp;gt;&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://github.com/google/OpenSK/commit/&amp;amp;lt;a class=&amp;amp;quot;double-link&amp;amp;quot; href=&amp;amp;quot;htt... (continued)

Pull Request Pull Request #530: Add basic setup for multi-PIN

Run Details

529 of 529 new or added lines in 10 files covered. (100.0%)

14641 of 16596 relevant lines covered (88.22%)

506400.03 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

66.06

/src/api/customization.rs

// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! This file contains all customizable constants.
//!
//! If you adapt them, make sure to run the tests before flashing the firmware.
//! Our deploy script enforces the invariants.

use crate::ctap::data_formats::{CredentialProtectionPolicy, EnterpriseAttestationMode};
use alloc::string::String;
use alloc::vec::Vec;

pub trait Customization {
    // ###########################################################################
    // Constants for adjusting privacy and protection levels.
    // ###########################################################################

    /// Changes the default level for the credProtect extension.
    ///
    /// You can change this value to one of the following for more privacy:
    /// - CredentialProtectionPolicy::UserVerificationOptionalWithCredentialIdList
    /// - CredentialProtectionPolicy::UserVerificationRequired
    ///
    /// UserVerificationOptionalWithCredentialIdList
    /// Resident credentials are discoverable with
    /// - an allowList,
    /// - an excludeList,
    /// - user verification.
    ///
    /// UserVerificationRequired
    /// Resident credentials are discoverable with user verification only.
    ///
    /// This can improve privacy, but can make usage less comfortable.
    fn default_cred_protect(&self) -> Option<CredentialProtectionPolicy>;

    /// Sets the initial minimum PIN length in code points.
    ///
    /// # Invariant
    ///
    /// - The minimum PIN length must be at least 4.
    /// - The minimum PIN length must be at most 63.
    /// - default_min_pin_length_rp_ids() must be non-empty if max_rp_ids_length() is 0.
    ///
    /// Requiring longer PINs can help establish trust between users and relying
    /// parties. It makes user verification harder to break, but less convenient.
    /// NIST recommends at least 6-digit PINs in section 5.1.9.1:
    /// https://pages.nist.gov/800-63-3/sp800-63b.html
    ///
    /// Reset reverts the minimum PIN length to this DEFAULT_MIN_PIN_LENGTH.
    fn default_min_pin_length(&self) -> u8;

    /// Lists relying parties that can read the minimum PIN length.
    ///
    /// # Invariant
    ///
    /// - default_min_pin_length_rp_ids() must be non-empty if max_rp_ids_length() is 0
    ///
    /// Only the RP IDs listed in default_min_pin_length_rp_ids are allowed to read
    /// the minimum PIN length with the minPinLength extension.
    fn default_min_pin_length_rp_ids(&self) -> Vec<String>;

    /// Enforces the alwaysUv option.
    ///
    /// When setting to true, commands require a PIN.
    /// Also, alwaysUv can not be disabled by commands.
    ///
    /// A certification (additional to FIDO Alliance's) might require enforcing
    /// alwaysUv. Otherwise, users should have the choice to configure alwaysUv.
    /// Calling toggleAlwaysUv is preferred over enforcing alwaysUv here.
    fn enforce_always_uv(&self) -> bool;

    /// Allows usage of enterprise attestation.
    ///
    /// # Invariant
    ///
    /// - Enterprise and batch attestation can not both be active.
    /// - If the mode is VendorFacilitated, enterprise_attestation_mode() must be non-empty.
    ///
    /// For privacy reasons, it is disabled by default. You can choose between:
    /// - EnterpriseAttestationMode::VendorFacilitated
    /// - EnterpriseAttestationMode::PlatformManaged
    ///
    /// VendorFacilitated
    /// Enterprise attestation is restricted to enterprise_attestation_mode(). Add your
    /// enterprises domain, e.g. "example.com", to the list below.
    ///
    /// PlatformManaged
    /// All relying parties can request an enterprise attestation. The authenticator
    /// trusts the platform to filter requests.
    ///
    /// To enable the feature, send the subcommand enableEnterpriseAttestation in
    /// AuthenticatorConfig. An enterprise might want to customize the type of
    /// attestation that is used. OpenSK defaults to batch attestation. Configuring
    /// individual certificates then makes authenticators identifiable.
    ///
    /// OpenSK prevents activating batch and enterprise attestation together. The
    /// current implementation uses the same key material at the moment, and these
    /// two modes have conflicting privacy guarantees.
    /// If you implement your own enterprise attestation mechanism, and you want
    /// batch attestation at the same time, proceed carefully and remove the
    /// assertion.
    fn enterprise_attestation_mode(&self) -> Option<EnterpriseAttestationMode>;

    /// Lists relying party IDs that can perform enterprise attestation.
    ///
    /// # Invariant
    ///
    /// - If the mode is VendorFacilitated, enterprise_attestation_mode() must be non-empty.
    ///
    /// This list is only considered if enterprise attestation is used.
    #[cfg(feature = "std")]
    fn enterprise_rp_id_list(&self) -> Vec<String>;

    /// Returns whether the rp_id is contained in enterprise_rp_id_list().
    fn is_enterprise_rp_id(&self, rp_id: &str) -> bool;

    /// Maximum message size send for CTAP commands.
    ///
    /// The maximum value is 7609, as HID packets can not encode longer messages.
    /// 1024 is the default mentioned in the authenticatorLargeBlobs commands.
    /// Larger values are preferred, as that allows more parameters in commands.
    /// If long commands are too unreliable on your hardware, consider decreasing
    /// this value.
    fn max_msg_size(&self) -> usize;

    /// Sets the number of consecutive failed PINs before blocking interaction.
    ///
    /// # Invariant
    ///
    /// - CTAP2.0: Maximum PIN retries must be 8.
    /// - CTAP2.1: Maximum PIN retries must be 8 at most.
    ///
    /// The fail retry counter is reset after entering the correct PIN.
    fn max_pin_retries(&self) -> u8;

    /// Enables or disables basic attestation for FIDO2.
    ///
    /// # Invariant
    ///
    /// - Enterprise and batch attestation can not both be active (see above).
    ///
    /// The basic attestation uses the signing key configured with a vendor command
    /// as a batch key. If you turn batch attestation on, be aware that it is your
    /// responsibility to safely generate and store the key material. Also, the
    /// batches must have size of at least 100k authenticators before using new key
    /// material.
    /// U2F is unaffected by this setting.
    ///
    /// https://www.w3.org/TR/webauthn/#attestation
    fn use_batch_attestation(&self) -> bool;

    /// Enables or disables signature counters.
    ///
    /// The signature counter is currently implemented as a global counter.
    /// The specification strongly suggests to have per-credential counters.
    /// Implementing those means you can't have an infinite amount of server-side
    /// credentials anymore. Also, since counters need frequent writes on the
    /// persistent storage, we might need a flash friendly implementation. This
    /// solution is a compromise to be compatible with U2F and not wasting storage.
    ///
    /// https://www.w3.org/TR/webauthn/#signature-counter
    fn use_signature_counter(&self) -> bool;

    // ###########################################################################
    // Constants for performance optimization or adapting to different hardware.
    //
    // Those constants may be modified before compilation to tune the behavior of
    // the key.
    // ###########################################################################

    /// Sets the maximum blob size stored with the credBlob extension.
    ///
    /// # Invariant
    ///
    /// - The length must be at least 32.
    /// - OpenSK puts a limit that the length must be at most 64, as it needs to
    ///   be persisted in the credential ID.
    fn max_cred_blob_length(&self) -> usize;

    /// Limits the number of considered entries in credential lists.
    ///
    /// # Invariant
    ///
    /// - This value, if present, must be at least 1 (more is preferred).
    ///
    /// Depending on your memory, you can use Some(n) to limit request sizes in
    /// MakeCredential and GetAssertion. This affects allowList and excludeList.
    fn max_credential_count_in_list(&self) -> Option<usize>;

    /// Limits the size of largeBlobs the authenticator stores.
    ///
    /// # Invariant
    ///
    /// - The allowed size must be at least 1024.
    /// - The array must fit into the shards reserved in storage/key.rs.
    fn max_large_blob_array_size(&self) -> usize;

    /// Limits the number of RP IDs that can change the minimum PIN length.
    ///
    /// # Invariant
    ///
    /// - If this value is 0, default_min_pin_length_rp_ids() must be non-empty.
    ///
    /// You can use this constant to have an upper limit in storage requirements.
    /// This might be useful if you want to more reliably predict the remaining
    /// storage. Stored string can still be of arbitrary length though, until RP ID
    /// truncation is implemented.
    /// Outside of memory considerations, you can set this value to 0 if only RP IDs
    /// in default_min_pin_length_rp_ids() should be allowed to change the minimum
    /// PIN length.
    fn max_rp_ids_length(&self) -> usize;

    /// Sets the number of resident keys you can store.
    ///
    /// # Invariant
    ///
    /// - The storage key CREDENTIALS must fit at least this number of credentials.
    ///
    /// Limiting the number of resident keys permits to ensure a minimum number of
    /// counter increments.
    /// Let:
    /// - P the number of pages (NUM_PAGES in the board definition)
    /// - K the maximum number of resident keys (max_supported_resident_keys())
    /// - S the maximum size of a resident key (about 500)
    /// - C the number of erase cycles (10000)
    /// - I the minimum number of counter increments
    ///
    /// We have: I = (P * 4084 - 5107 - K * S) / 8 * C
    ///
    /// 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;

    /// Sets the slot count of the multi-PIN feature.
    ///
    /// # Invariant
    ///
    /// - The slot count may not:
    ///   - make the storage entries that concatenate data of each slots
    ///     become larger than the storage page size,
    ///   - go over u8, as we only reserve 1 byte for the array index for
    ///     concatenated entries, or
    ///   - exceed the number of keys we reserve for the storage entries
    ///     that use unique keys for each slot.
    ///
    /// The upper bound of this is currently 8.
    fn slot_count(&self) -> usize;
}

#[derive(Clone)]
pub struct CustomizationImpl {
    pub default_cred_protect: Option<CredentialProtectionPolicy>,
    pub default_min_pin_length: u8,
    pub default_min_pin_length_rp_ids: &'static [&'static str],
    pub enforce_always_uv: bool,
    pub enterprise_attestation_mode: Option<EnterpriseAttestationMode>,
    pub enterprise_rp_id_list: &'static [&'static str],
    pub max_msg_size: usize,
    pub max_pin_retries: u8,
    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,
    pub slot_count: usize,
}

pub const DEFAULT_CUSTOMIZATION: CustomizationImpl = CustomizationImpl {
    default_cred_protect: None,
    default_min_pin_length: 4,
    default_min_pin_length_rp_ids: &[],
    enforce_always_uv: false,
    enterprise_attestation_mode: None,
    enterprise_rp_id_list: &[],
    max_msg_size: 7609,
    max_pin_retries: 8,
    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,
    slot_count: 1,
};

impl Customization for CustomizationImpl {
    fn default_cred_protect(&self) -> Option<CredentialProtectionPolicy> {
        self.default_cred_protect
    }

    fn default_min_pin_length(&self) -> u8 {
        self.default_min_pin_length
    }

    fn default_min_pin_length_rp_ids(&self) -> Vec<String> {
        self.default_min_pin_length_rp_ids
            .iter()
            .map(|s| String::from(*s))
            .collect()
    }

    fn enforce_always_uv(&self) -> bool {
        self.enforce_always_uv
    }

    fn enterprise_attestation_mode(&self) -> Option<EnterpriseAttestationMode> {
        self.enterprise_attestation_mode
    }

    #[cfg(feature = "std")]
    fn enterprise_rp_id_list(&self) -> Vec<String> {
        self.enterprise_rp_id_list
            .iter()
            .map(|s| String::from(*s))
            .collect()
    }

    fn is_enterprise_rp_id(&self, rp_id: &str) -> bool {
        self.enterprise_rp_id_list.contains(&rp_id)
    }

    fn max_msg_size(&self) -> usize {
        self.max_msg_size
    }

    fn max_pin_retries(&self) -> u8 {
        self.max_pin_retries
    }

    fn use_batch_attestation(&self) -> bool {
        self.use_batch_attestation
    }

    fn use_signature_counter(&self) -> bool {
        self.use_signature_counter
    }

    fn max_cred_blob_length(&self) -> usize {
        self.max_cred_blob_length
    }

    fn max_credential_count_in_list(&self) -> Option<usize> {
        self.max_credential_count_in_list
    }

    fn max_large_blob_array_size(&self) -> usize {
        self.max_large_blob_array_size
    }

    fn max_rp_ids_length(&self) -> usize {
        self.max_rp_ids_length
    }

    fn max_supported_resident_keys(&self) -> usize {
        self.max_supported_resident_keys
    }

    fn slot_count(&self) -> usize {
        self.slot_count
    }
}

#[cfg(feature = "std")]
pub fn is_valid(customization: &impl Customization) -> bool {
    // Two invariants are currently tested in different files:
    // - storage.rs: if max_large_blob_array_size() fits the shards
    // - storage/key.rs: if max_supported_resident_keys() fits CREDENTIALS

    // Max message size must be between 1024 and 7609.
    if customization.max_msg_size() < 1024 || customization.max_msg_size() > 7609 {
        return false;
    }

    // Default min pin length must be between 4 and 63.
    if customization.default_min_pin_length() < 4 || customization.default_min_pin_length() > 63 {
        return false;
    }

    // OpenSK prevents activating batch and enterprise attestation together. The
    // current implementation uses the same key material at the moment, and these
    // two modes have conflicting privacy guarantees.
    if customization.use_batch_attestation()
        && customization.enterprise_attestation_mode().is_some()
    {
        return false;
    }

    // enterprise_rp_id_list() should be non-empty in vendor facilitated mode.
    if matches!(
        customization.enterprise_attestation_mode(),
        Some(EnterpriseAttestationMode::VendorFacilitated)
    ) && customization.enterprise_rp_id_list().is_empty()
    {
        return false;
    }

    // enterprise_rp_id_list() should be empty without an enterprise attestation mode.
    if customization.enterprise_attestation_mode().is_none()
        && !customization.enterprise_rp_id_list().is_empty()
    {
        return false;
    }

    // Max pin retries must be less or equal than 8.
    if customization.max_pin_retries() > 8 {
        return false;
    }

    // Max cred blob length should be at least 32, and at most 64.
    if customization.max_cred_blob_length() < 32 || customization.max_cred_blob_length() > 64 {
        return false;
    }

    // Max credential count in list should be positive if exists.
    if let Some(count) = customization.max_credential_count_in_list() {
        if count < 1 {
            return false;
        }
    }

    // Max large blob array size should not be less than 1024.
    if customization.max_large_blob_array_size() < 1024 {
        return false;
    }

    // Default min pin length rp ids must be non-empty if max rp ids length is 0.
    if customization.max_rp_ids_length() == 0
        && customization.default_min_pin_length_rp_ids().is_empty()
    {
        return false;
    }

    // Slot count should be at most 8.
    if customization.slot_count() > 8 {
        return false;
    }

    true
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_invariants() {
        assert!(is_valid(&DEFAULT_CUSTOMIZATION));
    }
}

1	// Copyright 2022 Google LLC
2	//
3	// Licensed under the Apache License, Version 2.0 (the "License");
4	// you may not use this file except in compliance with the License.
5	// You may obtain a copy of the License at
6	//
7	// http://www.apache.org/licenses/LICENSE-2.0
8	//
9	// Unless required by applicable law or agreed to in writing, software
10	// distributed under the License is distributed on an "AS IS" BASIS,
11	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12	// See the License for the specific language governing permissions and
13	// limitations under the License.
14
15	//! This file contains all customizable constants.
16	//!
17	//! If you adapt them, make sure to run the tests before flashing the firmware.
18	//! Our deploy script enforces the invariants.
19
20	use crate::ctap::data_formats::{CredentialProtectionPolicy, EnterpriseAttestationMode};
21	use alloc::string::String;
22	use alloc::vec::Vec;
23
24	pub trait Customization {
25	// ###########################################################################
26	// Constants for adjusting privacy and protection levels.
27	// ###########################################################################
28
29	/// Changes the default level for the credProtect extension.
30	///
31	/// You can change this value to one of the following for more privacy:
32	/// - CredentialProtectionPolicy::UserVerificationOptionalWithCredentialIdList
33	/// - CredentialProtectionPolicy::UserVerificationRequired
34	///
35	/// UserVerificationOptionalWithCredentialIdList
36	/// Resident credentials are discoverable with
37	/// - an allowList,
38	/// - an excludeList,
39	/// - user verification.
40	///
41	/// UserVerificationRequired
42	/// Resident credentials are discoverable with user verification only.
43	///
44	/// This can improve privacy, but can make usage less comfortable.
45	fn default_cred_protect(&self) -> Option<CredentialProtectionPolicy>;
46
47	/// Sets the initial minimum PIN length in code points.
48	///
49	/// # Invariant
50	///
51	/// - The minimum PIN length must be at least 4.
52	/// - The minimum PIN length must be at most 63.
53	/// - default_min_pin_length_rp_ids() must be non-empty if max_rp_ids_length() is 0.
54	///
55	/// Requiring longer PINs can help establish trust between users and relying
56	/// parties. It makes user verification harder to break, but less convenient.
57	/// NIST recommends at least 6-digit PINs in section 5.1.9.1:
58	/// https://pages.nist.gov/800-63-3/sp800-63b.html
59	///
60	/// Reset reverts the minimum PIN length to this DEFAULT_MIN_PIN_LENGTH.
61	fn default_min_pin_length(&self) -> u8;
62
63	/// Lists relying parties that can read the minimum PIN length.
64	///
65	/// # Invariant
66	///
67	/// - default_min_pin_length_rp_ids() must be non-empty if max_rp_ids_length() is 0
68	///
69	/// Only the RP IDs listed in default_min_pin_length_rp_ids are allowed to read
70	/// the minimum PIN length with the minPinLength extension.
71	fn default_min_pin_length_rp_ids(&self) -> Vec<String>;
72
73	/// Enforces the alwaysUv option.
74	///
75	/// When setting to true, commands require a PIN.
76	/// Also, alwaysUv can not be disabled by commands.
77	///
78	/// A certification (additional to FIDO Alliance's) might require enforcing
79	/// alwaysUv. Otherwise, users should have the choice to configure alwaysUv.
80	/// Calling toggleAlwaysUv is preferred over enforcing alwaysUv here.
81	fn enforce_always_uv(&self) -> bool;
82
83	/// Allows usage of enterprise attestation.
84	///
85	/// # Invariant
86	///
87	/// - Enterprise and batch attestation can not both be active.
88	/// - If the mode is VendorFacilitated, enterprise_attestation_mode() must be non-empty.
89	///
90	/// For privacy reasons, it is disabled by default. You can choose between:
91	/// - EnterpriseAttestationMode::VendorFacilitated
92	/// - EnterpriseAttestationMode::PlatformManaged
93	///
94	/// VendorFacilitated
95	/// Enterprise attestation is restricted to enterprise_attestation_mode(). Add your
96	/// enterprises domain, e.g. "example.com", to the list below.
97	///
98	/// PlatformManaged
99	/// All relying parties can request an enterprise attestation. The authenticator
100	/// trusts the platform to filter requests.
101	///
102	/// To enable the feature, send the subcommand enableEnterpriseAttestation in
103	/// AuthenticatorConfig. An enterprise might want to customize the type of
104	/// attestation that is used. OpenSK defaults to batch attestation. Configuring
105	/// individual certificates then makes authenticators identifiable.
106	///
107	/// OpenSK prevents activating batch and enterprise attestation together. The
108	/// current implementation uses the same key material at the moment, and these
109	/// two modes have conflicting privacy guarantees.
110	/// If you implement your own enterprise attestation mechanism, and you want
111	/// batch attestation at the same time, proceed carefully and remove the
112	/// assertion.
113	fn enterprise_attestation_mode(&self) -> Option<EnterpriseAttestationMode>;
114
115	/// Lists relying party IDs that can perform enterprise attestation.
116	///
117	/// # Invariant
118	///
119	/// - If the mode is VendorFacilitated, enterprise_attestation_mode() must be non-empty.
120	///
121	/// This list is only considered if enterprise attestation is used.
122	#[cfg(feature = "std")]
123	fn enterprise_rp_id_list(&self) -> Vec<String>;
124
125	/// Returns whether the rp_id is contained in enterprise_rp_id_list().
126	fn is_enterprise_rp_id(&self, rp_id: &str) -> bool;
127
128	/// Maximum message size send for CTAP commands.
129	///
130	/// The maximum value is 7609, as HID packets can not encode longer messages.
131	/// 1024 is the default mentioned in the authenticatorLargeBlobs commands.
132	/// Larger values are preferred, as that allows more parameters in commands.
133	/// If long commands are too unreliable on your hardware, consider decreasing
134	/// this value.
135	fn max_msg_size(&self) -> usize;
136
137	/// Sets the number of consecutive failed PINs before blocking interaction.
138	///
139	/// # Invariant
140	///
141	/// - CTAP2.0: Maximum PIN retries must be 8.
142	/// - CTAP2.1: Maximum PIN retries must be 8 at most.
143	///
144	/// The fail retry counter is reset after entering the correct PIN.
145	fn max_pin_retries(&self) -> u8;
146
147	/// Enables or disables basic attestation for FIDO2.
148	///
149	/// # Invariant
150	///
151	/// - Enterprise and batch attestation can not both be active (see above).
152	///
153	/// The basic attestation uses the signing key configured with a vendor command
154	/// as a batch key. If you turn batch attestation on, be aware that it is your
155	/// responsibility to safely generate and store the key material. Also, the
156	/// batches must have size of at least 100k authenticators before using new key
157	/// material.
158	/// U2F is unaffected by this setting.
159	///
160	/// https://www.w3.org/TR/webauthn/#attestation
161	fn use_batch_attestation(&self) -> bool;
162
163	/// Enables or disables signature counters.
164	///
165	/// The signature counter is currently implemented as a global counter.
166	/// The specification strongly suggests to have per-credential counters.
167	/// Implementing those means you can't have an infinite amount of server-side
168	/// credentials anymore. Also, since counters need frequent writes on the
169	/// persistent storage, we might need a flash friendly implementation. This
170	/// solution is a compromise to be compatible with U2F and not wasting storage.
171	///
172	/// https://www.w3.org/TR/webauthn/#signature-counter
173	fn use_signature_counter(&self) -> bool;
174
175	// ###########################################################################
176	// Constants for performance optimization or adapting to different hardware.
177	//
178	// Those constants may be modified before compilation to tune the behavior of
179	// the key.
180	// ###########################################################################
181
182	/// Sets the maximum blob size stored with the credBlob extension.
183	///
184	/// # Invariant
185	///
186	/// - The length must be at least 32.
187	/// - OpenSK puts a limit that the length must be at most 64, as it needs to
188	/// be persisted in the credential ID.
189	fn max_cred_blob_length(&self) -> usize;
190
191	/// Limits the number of considered entries in credential lists.
192	///
193	/// # Invariant
194	///
195	/// - This value, if present, must be at least 1 (more is preferred).
196	///
197	/// Depending on your memory, you can use Some(n) to limit request sizes in
198	/// MakeCredential and GetAssertion. This affects allowList and excludeList.
199	fn max_credential_count_in_list(&self) -> Option<usize>;
200
201	/// Limits the size of largeBlobs the authenticator stores.
202	///
203	/// # Invariant
204	///
205	/// - The allowed size must be at least 1024.
206	/// - The array must fit into the shards reserved in storage/key.rs.
207	fn max_large_blob_array_size(&self) -> usize;
208
209	/// Limits the number of RP IDs that can change the minimum PIN length.
210	///
211	/// # Invariant
212	///
213	/// - If this value is 0, default_min_pin_length_rp_ids() must be non-empty.
214	///
215	/// You can use this constant to have an upper limit in storage requirements.
216	/// This might be useful if you want to more reliably predict the remaining
217	/// storage. Stored string can still be of arbitrary length though, until RP ID
218	/// truncation is implemented.
219	/// Outside of memory considerations, you can set this value to 0 if only RP IDs
220	/// in default_min_pin_length_rp_ids() should be allowed to change the minimum
221	/// PIN length.
222	fn max_rp_ids_length(&self) -> usize;
223
224	/// Sets the number of resident keys you can store.
225	///
226	/// # Invariant
227	///
228	/// - The storage key CREDENTIALS must fit at least this number of credentials.
229	///
230	/// Limiting the number of resident keys permits to ensure a minimum number of
231	/// counter increments.
232	/// Let:
233	/// - P the number of pages (NUM_PAGES in the board definition)
234	/// - K the maximum number of resident keys (max_supported_resident_keys())
235	/// - S the maximum size of a resident key (about 500)
236	/// - C the number of erase cycles (10000)
237	/// - I the minimum number of counter increments
238	///
239	/// We have: I = (P * 4084 - 5107 - K * S) / 8 * C
240	///
241	/// With P=20 and K=150, we have I=2M which is enough for 500 increments per day
242	/// for 10 years.
243	fn max_supported_resident_keys(&self) -> usize;
244
245	/// Sets the slot count of the multi-PIN feature.
246	///
247	/// # Invariant
248	///
249	/// - The slot count may not:
250	/// - make the storage entries that concatenate data of each slots
251	/// become larger than the storage page size,
252	/// - go over u8, as we only reserve 1 byte for the array index for
253	/// concatenated entries, or
254	/// - exceed the number of keys we reserve for the storage entries
255	/// that use unique keys for each slot.
256	///
257	/// The upper bound of this is currently 8.
258	fn slot_count(&self) -> usize;
259	}
260
261	#[derive(Clone)]	1✔
262	pub struct CustomizationImpl {
263	pub default_cred_protect: Option<CredentialProtectionPolicy>,
264	pub default_min_pin_length: u8,
265	pub default_min_pin_length_rp_ids: &'static [&'static str],
266	pub enforce_always_uv: bool,
267	pub enterprise_attestation_mode: Option<EnterpriseAttestationMode>,
268	pub enterprise_rp_id_list: &'static [&'static str],
269	pub max_msg_size: usize,
270	pub max_pin_retries: u8,
271	pub use_batch_attestation: bool,
272	pub use_signature_counter: bool,
273	pub max_cred_blob_length: usize,
274	pub max_credential_count_in_list: Option<usize>,
275	pub max_large_blob_array_size: usize,
276	pub max_rp_ids_length: usize,
277	pub max_supported_resident_keys: usize,
278	pub slot_count: usize,
279	}
280
281	pub const DEFAULT_CUSTOMIZATION: CustomizationImpl = CustomizationImpl {
282	default_cred_protect: None,
283	default_min_pin_length: 4,
284	default_min_pin_length_rp_ids: &[],
285	enforce_always_uv: false,
286	enterprise_attestation_mode: None,
287	enterprise_rp_id_list: &[],
288	max_msg_size: 7609,
289	max_pin_retries: 8,
290	use_batch_attestation: false,
291	use_signature_counter: true,
292	max_cred_blob_length: 32,
293	max_credential_count_in_list: None,
294	max_large_blob_array_size: 2048,
295	max_rp_ids_length: 8,
296	max_supported_resident_keys: 150,
297	slot_count: 1,
298	};
299
300	impl Customization for CustomizationImpl {
301	fn default_cred_protect(&self) -> Option<CredentialProtectionPolicy> {	×
302	self.default_cred_protect	×
303	}	×
304
305	fn default_min_pin_length(&self) -> u8 {	2✔
306	self.default_min_pin_length	2✔
307	}	2✔
308
309	fn default_min_pin_length_rp_ids(&self) -> Vec<String> {	×
310	self.default_min_pin_length_rp_ids	×
311	.iter()	×
312	.map(\|s\| String::from(*s))	×
313	.collect()	×
314	}	×
315
316	fn enforce_always_uv(&self) -> bool {	×
317	self.enforce_always_uv	×
318	}	×
319
320	fn enterprise_attestation_mode(&self) -> Option<EnterpriseAttestationMode> {	2✔
321	self.enterprise_attestation_mode	2✔
322	}	2✔
323
324	#[cfg(feature = "std")]
325	fn enterprise_rp_id_list(&self) -> Vec<String> {	1✔
326	self.enterprise_rp_id_list	1✔
327	.iter()	1✔
328	.map(\|s\| String::from(*s))	1✔
329	.collect()	1✔
330	}	1✔
331
332	fn is_enterprise_rp_id(&self, rp_id: &str) -> bool {	×
333	self.enterprise_rp_id_list.contains(&rp_id)	×
334	}	×
335
336	fn max_msg_size(&self) -> usize {	2✔
337	self.max_msg_size	2✔
338	}	2✔
339
340	fn max_pin_retries(&self) -> u8 {	1✔
341	self.max_pin_retries	1✔
342	}	1✔
343
344	fn use_batch_attestation(&self) -> bool {	1✔
345	self.use_batch_attestation	1✔
346	}	1✔
347
348	fn use_signature_counter(&self) -> bool {	×
349	self.use_signature_counter	×
350	}	×
351
352	fn max_cred_blob_length(&self) -> usize {	2✔
353	self.max_cred_blob_length	2✔
354	}	2✔
355
356	fn max_credential_count_in_list(&self) -> Option<usize> {	1✔
357	self.max_credential_count_in_list	1✔
358	}	1✔
359
360	fn max_large_blob_array_size(&self) -> usize {	1✔
361	self.max_large_blob_array_size	1✔
362	}	1✔
363
364	fn max_rp_ids_length(&self) -> usize {	1✔
365	self.max_rp_ids_length	1✔
366	}	1✔
367
368	fn max_supported_resident_keys(&self) -> usize {	×
369	self.max_supported_resident_keys	×
370	}	×
371
372	fn slot_count(&self) -> usize {	1✔
373	self.slot_count	1✔
374	}	1✔
375	}
376
377	#[cfg(feature = "std")]
378	pub fn is_valid(customization: &impl Customization) -> bool {	3✔
379	// Two invariants are currently tested in different files:
380	// - storage.rs: if max_large_blob_array_size() fits the shards
381	// - storage/key.rs: if max_supported_resident_keys() fits CREDENTIALS
382
383	// Max message size must be between 1024 and 7609.
384	if customization.max_msg_size() < 1024 \|\| customization.max_msg_size() > 7609 {	3✔
385	return false;	×
386	}	3✔
387
388	// Default min pin length must be between 4 and 63.
389	if customization.default_min_pin_length() < 4 \|\| customization.default_min_pin_length() > 63 {	3✔
390	return false;	×
391	}	3✔
392
393	// OpenSK prevents activating batch and enterprise attestation together. The
394	// current implementation uses the same key material at the moment, and these
395	// two modes have conflicting privacy guarantees.
396	if customization.use_batch_attestation()	3✔
397	&& customization.enterprise_attestation_mode().is_some()	×
398	{
399	return false;	×
400	}	3✔
401
402	// enterprise_rp_id_list() should be non-empty in vendor facilitated mode.
403	if matches!(
404	customization.enterprise_attestation_mode(),	3✔
405	Some(EnterpriseAttestationMode::VendorFacilitated)	1✔
406	) && customization.enterprise_rp_id_list().is_empty()	×
407	{
408	return false;	×
409	}	3✔
410
411	// enterprise_rp_id_list() should be empty without an enterprise attestation mode.
412	if customization.enterprise_attestation_mode().is_none()	3✔
413	&& !customization.enterprise_rp_id_list().is_empty()	2✔
414	{
415	return false;	×
416	}	3✔
417		3✔
418	// Max pin retries must be less or equal than 8.	3✔
419	if customization.max_pin_retries() > 8 {	3✔
420	return false;	×
421	}	3✔
422
423	// Max cred blob length should be at least 32, and at most 64.
424	if customization.max_cred_blob_length() < 32 \|\| customization.max_cred_blob_length() > 64 {	3✔
425	return false;	×
426	}	3✔
427
428	// Max credential count in list should be positive if exists.
429	if let Some(count) = customization.max_credential_count_in_list() {	3✔
430	if count < 1 {	×
431	return false;	×
432	}	×
433	}	3✔
434
435	// Max large blob array size should not be less than 1024.
436	if customization.max_large_blob_array_size() < 1024 {	3✔
437	return false;	×
438	}	3✔
439
440	// Default min pin length rp ids must be non-empty if max rp ids length is 0.
441	if customization.max_rp_ids_length() == 0	3✔
442	&& customization.default_min_pin_length_rp_ids().is_empty()	×
443	{
444	return false;	×
445	}	3✔
446		3✔
447	// Slot count should be at most 8.	3✔
448	if customization.slot_count() > 8 {	3✔
449	return false;	×
450	}	3✔
451		3✔
452	true	3✔
453	}	3✔
454
455	#[cfg(test)]
456	mod test {
457	use super::*;
458
459	#[test]
460	fn test_invariants() {	1✔
461	assert!(is_valid(&DEFAULT_CUSTOMIZATION));	1✔
462	}	1✔
463	}

google / OpenSK / 2908941137

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous