Skip to content

Latest commit

 

History

History
95 lines (73 loc) · 3.83 KB

customization.md

File metadata and controls

95 lines (73 loc) · 3.83 KB
Raw

OpenSK logo

Customization

Cryptographic material

All the generated certificates and private keys are stored in the directory crypto_data/. The expected content after running our setup.sh script is:

File Purpose
aaguid.txt Text file containaing the AAGUID value
opensk_ca.csr Certificate sign request for the Root CA
opensk_ca.key ECC secp256r1 private key used for the Root CA
opensk_ca.pem PEM encoded certificate of the Root CA
opensk_ca.srl File generated by OpenSSL
opensk_cert.csr Certificate sign request for the attestation certificate
opensk_cert.pem PEM encoded certificate used for the authenticator
opensk.key ECC secp256r1 private key used for the autenticator
opensk_upgrade.key Private key for signing upgrades through CTAP
opensk_upgrade_pub.pem Public key added to the firmware for verifying upgrades

If you want to use your own attestation certificate and private key, replace the opensk_cert.pem and opensk.key files. The script at tools/configure.py customizes an OpenSK device with the correct certificate and private key.

Our build script build.rs is responsible for converting the aaguid.txt file into raw data that is then used by the Rust file src/ctap/key_material.rs.

Please make sure to safely store all private key material before calling reset.sh, or the files will be lost.

Certificate considerations

The certificate on OpenSK is used for attestation. That means, whenever you register OpenSK on a website, you attest the legitimacy of your hardware. For self-generated certificates, this claim is rather trivial. Still, it is required by some websites and to use U2F.

Usually, the attestation private key is shared between a batch of at least 100,000 security keys of the same model. If you build your own OpenSK, your private key is unique to you. This makes you identifiable across registrations: Two websites could collaborate to track if registrations were attested with the same key material. If you use OpenSK beyond experimentation, please consider carefully if you want to take this privacy risk.

Software personalization

If you build your own security key, depending on the hardware you use, there are a few things you can personalize:

  1. If you have multiple buttons, choose the buttons responsible for user presence in src/main.rs.
  2. If you have colored LEDs, like different blinking patterns and want to play around with the code in src/main.rs more, take a look at e.g. wink_leds.
  3. You find more options and documentation in src/ctap/customization.rs, including:
    • The default level for the credProtect extension.
    • The default minimum PIN length, and what relying parties can set it.
    • Whether you want to enforce alwaysUv.
    • Settings for enterprise attestation.
    • The maximum PIN retries.
    • Whether you want to use batch attestation.
    • Whether you want to use signature counters.
    • Various constants to adapt to different hardware.

Testing and Fuzzing

You might want to test your changes before deploying them. To run unit tests, make sure that at least the std feature is included, e.g.:

cargo test --features=std,with_ctap1

Alternatively, you can simply call our test script to also test all libraries, run clippy, check formatting and more:

./run_desktop_tests.sh

OpenSK is fuzzed with the OSS-Fuzz project. You can also run fuzzing locally. First install:

./fuzzing_setup.sh

Then choose a fuzz target from fuzz/fuzz_targets/, e.g.:

cargo fuzz run fuzz_target_process_ctap1