# <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
cargo +stable install cargo-fuzz --version 0.10.2
```

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

```shell
cargo fuzz run fuzz_target_process_ctap1
```
