e5ba9db644
* Reworks some workflows to run a script instead Advantages are: - Only one set of tests needs maintenance. - Local results match workflows, no surprises. - Reduced reliance on GitHub actions. Fixes #50, #168, #169, #171, #507 * Adds macos to the test matrix
96 lines
3.8 KiB
Markdown
96 lines
3.8 KiB
Markdown
# <img alt="OpenSK logo" src="img/OpenSK.svg" width="200px">
|
|
|
|
## 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`.
|
|
1. 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`.
|
|
1. 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.:
|
|
|
|
```shell
|
|
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:
|
|
|
|
```shell
|
|
./run_desktop_tests.sh
|
|
```
|
|
|
|
OpenSK is fuzzed with the [OSS-Fuzz](https://github.com/google/oss-fuzz)
|
|
project. You can also run fuzzing locally. First install:
|
|
|
|
```shell
|
|
./fuzzing_setup.sh
|
|
```
|
|
|
|
Then choose a fuzz target from `fuzz/fuzz_targets/`, e.g.:
|
|
|
|
```shell
|
|
cargo fuzz run fuzz_target_process_ctap1
|
|
```
|