Switch from compile-time to install-time parameters

This allows customizing many settings at the time the applet is
installed.

Author: BryanJacobs

README.md

@@ -74,6 +74,8 @@ If you want to, feel free! Just raise a pull request or open an issue.
 
 ## Where to go Next
 
+If you just want to install the app, look at [what you can configure](docs/installation.md).
+
 I suggest [reading the FAQ](docs/FAQ.md) and perhaps [the security model](docs/security_model.md).
 
 If you're a really detail-oriented person, you might enjoy reading

docs/certs.md

@@ -10,9 +10,8 @@ certificates (ECDSA) are supported for the authenticator's own certificate; any
 may be used for CAs further up the chain.
 
 These may be provided via a vendor CTAP command (command byte 0x46). In order
-to enable the vendor CTAP command, you must provide an install parameter of a single byte,
-`0x01`. By default, the vendor command will be rejected to avoid inadvertently allowing
-an attacker to switch the authenticator to basic attestation mode.
+to enable the vendor CTAP command, you must install the applet with parameters enabling it:
+see [the install guide](installation.md).
 
 The vendor CTAP command will be rejected if the authenticator already contains a certificate,
 or if the authenticator has been used to make any credentials since the last reset, so it must

docs/installation.md

@@ -0,0 +1,11 @@
+# Installation Parameters
+
+This applet provides a variety of install-time configurable settings. These are configured via a
+CBOR map provided when the applet is installed (for example, via `gpp --install <applet> --params <params>`).
+
+To generate the parameter string, use the `get_install_parameters.py` script at the root of the repository.
+The help the script provides (`--help`) explains each options.
+
+The defaults - when no install parameters are provided - are for maximum FIDO standards compatibility, but
+won't accept an attestation certificate. So if you want CTAP1/U2F, you'll need to install the applet with
+parameters.

docs/security_model.md

@@ -42,11 +42,13 @@ is then AES256-CBC encrypted along with the RP ID, using a random
 IV, and the result is used as the "credential ID". Which wrapping key
 is used depends on how the credential is generated:
 
+- all credentials use the high security key if `FORCE_ALWAYS_UV`
 - credentials created with `credProtect` level 3, "require user
-  verification for any discovery" always use the high security key
+  verification for any discovery" always use the high security key,
+  unless `LOW_SECURITY_MAXIMUM_COMPATIBILITY` is set
 - credentials stored on the authenticator itself ("discoverable") use
-  the high security if the tunable `USE_LOW_SECURITY_FOR_SOME_RKS` is
-  false
+  the high security key if the tunable `USE_LOW_SECURITY_FOR_SOME_RKS`
+  is false
 - other credentials (non-discoverable, `credProtect` level zero
   through two) use the low security key
 
@@ -237,6 +239,8 @@ Open source is open.
 
 ## That's all too complicated! Show me a table!
 
+The below table applies with `FORCE_ALWAYS_UV` and `LOW_SECURITY_HIGH_COMPATIBILITY` disabled.
+
 | Usage / Creation                      | L1D     | L2D      | L3D      | L1 | L2 | L3       |
 |---------------------------------------|---------|----------|----------|----|----|----------|
 | Provided, no PIN set                  | OK      | OK       | Software | OK | OK | Software |

get_install_parameters.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python
+
+import argparse
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser("get_install_parameters",
+                                     description="Return parameters for installing FIDO2Applet with custom settings")
+    parser.add_argument('--enable-attestation', action='store_true', default=None,
+                        help="Allows loading an attestation certificate after installing the applet")
+    parser.add_argument('--high-security', action='store_true', default=None,
+                        help="Does not comply with the FIDO standards, but protects credentials against bugs or "
+                             "faulty authenticator hardware. Implies high-security RKs.")
+    parser.add_argument('--force-always-uv', action='store_true', default=None,
+                        help="Requires the PIN for all operations, always")
+    parser.add_argument('--high-security-rks', action='store_true', default=None,
+                        help="Protects discoverable credentials against bugs and faulty authenticator hardware,"
+                             "at the cost of standards compliance")
+    parser.add_argument('--protect-against-reset', action='store_true', default=None,
+                        help="Require sending a reset command twice, across two power cycles, to truly reset "
+                             "the authenticator")
+    parser.add_argument('--kdf-iterations', type=int, default=5,
+                        help="Number of iterations of the Key Derivation Function used. Protects against "
+                             "brute-force attacks against the PIN (when authenticator hardware is faulty), "
+                             "at the cost of performance")
+    parser.add_argument('--max-cred-blob-len', type=int, default=32,
+                        help="Maximum length of the blob stored with every discoverable credential. Must be >=32")
+    parser.add_argument('--large-blob-store-size', type=int, default=1024,
+                        help="Length of the large blob array in flash memory. Must be >=1024")
+    parser.add_argument('--max-rk-rp-length', type=int, default=32,
+                        help="Number of bytes of the relying party identifier stored with each RK. Must be >=32")
+    parser.add_argument('--max-ram-scratch', type=int, default=254,
+                        help="Number of bytes of RAM to use for working memory. Reduces flash wear. Must be <=254")
+    parser.add_argument('--buffer-mem', type=int, default=1024,
+                        help="Number of bytes of RAM to use for request processing. Reduces flash wear. Must be >=1024")
+    parser.add_argument('--flash-scratch', type=int, default=1024,
+                        help="Number of bytes of flash to use when RAM is exhausted. For low-memory situations")
+
+    args = parser.parse_args()
+
+    num_options_set = 0
+    install_param_bytes = []
+    for option_number, option_string in enumerate([
+        'enable_attestation',
+        'high_security',
+        'force_always_uv',
+        'high_security_rks',
+        'protect_against_reset',
+        'kdf_iterations',
+        'max_cred_blob_len',
+        'large_blob_store_size',
+        'max_rk_rp_length',
+        'max_ram_scratch',
+        'buffer_mem',
+        'flash_scratch'
+    ]):
+        val = getattr(args, option_string)
+        if val is None:
+            continue
+        num_options_set += 1
+
+        bytes_for_option = []
+        if val is True:
+            bytes_for_option = [0xF5]
+        elif val is False:
+            bytes_for_option = [0xF4]
+        else:
+            if val <= 23:
+                bytes_for_option = [val]
+            elif val <= 255:
+                bytes_for_option = [0x18, val]
+            else:
+                bytes_for_option = [0x19, (val & 0xFF00) >> 8, val & 0x00FF]
+
+        install_param_bytes += [option_number] + bytes_for_option
+
+    install_param_bytes = [0xA0 + num_options_set] + install_param_bytes
+    print(bytes(install_param_bytes).hex())

python_tests/ctap/ctap_test.py

@@ -221,7 +221,7 @@ def setUp(self, install_params: Optional[bytes] = None) -> None:
             ],
         }
         if install_params is None:
-            install_params = bytes([0x01])
+            install_params = bytes([0xA1, 0x00, 0xF5])
         super().setUp(install_params)
         if self.PCSC_MODE:
             devs = list(CtapPcscDevice.list_devices(self.VIRTUAL_DEVICE_NAME))

python_tests/ctap/test_ctap_attestation_mode_switch.py

@@ -10,7 +10,7 @@
 
 class AttestationModeSwitchTestCase(BasicAttestationTestCase):
     def setUp(self, install_params: Optional[bytes] = None) -> None:
-        super().setUp(bytes([0x01]))
+        super().setUp(bytes([0xA1, 0x00, 0xF5]))
 
     @parameterized.expand([
         ("tiny", 3),

python_tests/ctap/test_extended_apdus.py

@@ -15,7 +15,7 @@ def setUpClass(cls) -> None:
         super().setUpClass()
 
     def setUp(self, install_params: Optional[bytes] = None) -> None:
-        super().setUp(bytes([0x01]))
+        super().setUp(bytes([0xA1, 0x00, 0xF5]))
 
     def test_get_info(self):
         info = self.ctap2.get_info()