Skip to content

customization.md

Latest commit

 

History

History
110 lines (82 loc) · 4.05 KB

customization.md

File metadata and controls

110 lines (82 loc) · 4.05 KB

OpenSK logo

Customization

Cryptographic material

All the generated certificates and private keys are stored in the directory crypto_data/. Among them, the following are used by OpenSK:

File Purpose
aaguid.txt Text file containaing the AAGUID value
opensk_cert.pem PEM encoded certificate for the authenticator
opensk.key ECC secp256r1 private key 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/env.rs.

If you delete the key material, it will be randomly regenerated by setup.sh.

Certificate considerations

If you either use the ctap1 feature or set use_batch_attestation in the customization, OpenSK needs to send an attestation when you register a credential on a website. By default, OpenSK uses

  • an all-zero AAGUID,
  • a randomly generated batch attestation key,
  • an empty batch attestation certificate.

You can inject the above data into OpenSK with a custom vendor command. However, this means that all registered credentials using this batch attestation data can be correlated. For locked hardware security keys, this feature gives relying parties proof that they speak to secure hardware. They compare the AAGUID to those registered with the FIDO Alliance.

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 the privacy risk of using the configure tool.

The default randomly generated, ephemeral batch attestation keys, are helpful in practise: Without a key, U2F does not work. Also a few more relying parties accept OpenSK responses because of this trick. It is not meant to prove any hardware security properties.

To inject your own batch attestation key and AAGUID into the firmware, run:

# Read the privacy warning above!
uv run tools/configure.py \
    --certificate=crypto_data/opensk_cert.pem \
    --private-key=crypto_data/opensk.key \
    --aaguid=crypto_data/aaguid.txt

Personalization

If you bring your own security key for new hardware, you can customize buttons or LEDs and their colors, depending on your board.

Software personalization options are listed in libraries/opensk/src/api/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 memory requirements.

If you used the config-command feature, you can also turn some features on with a command over CTAP by calling, e.g.:

uv run -m tools.authenticator_config --always-uv

Testing and Fuzzing

You might want to test your changes before deploying them. Unit tests, formatting, lints and libraries can be checked with:

./run_desktop_tests.sh

You can also run individual commands from that script. 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.:

cd libraries/opensk/
cargo fuzz run fuzz_target_process_ctap1