Skip to content

Latest commit

 

History

History
78 lines (65 loc) · 4.07 KB

customization.md

File metadata and controls

78 lines (65 loc) · 4.07 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

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 main.rs.
  2. Decide whether you want to use batch attestation. There is a boolean flag in ctap/mod.rs. It is mandatory for U2F, and you can create your own self-signed certificate. The flag is used for FIDO2 and has some privacy implications. Please check WebAuthn for more information.
  3. Decide whether you want to use signature counters. Currently, only global signature counters are implemented, as they are the default option for U2F. The flag in ctap/mod.rs only turns them off for FIDO2. The most privacy preserving solution is individual or no signature counters. Again, please check WebAuthn for documentation.
  4. Depending on your available flash storage, choose an appropriate maximum number of supported resident keys and number of pages in ctap/storage.rs.
  5. Change the default level for the credProtect extension in ctap/mod.rs. When changing the default, resident credentials become undiscoverable without user verification. This helps privacy, but can make usage less comfortable for credentials that need less protection.
  6. Increase the default minimum length for PINs in ctap/storage.rs. The current minimum is 4. Values from 4 to 63 are allowed. 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 of their Digital Identity Guidelines. You can add relying parties to the list of readers of the minimum PIN length.