# <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

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](https://www.w3.org/TR/webauthn/#attestation) 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](https://www.w3.org/TR/webauthn/#signature-counter) 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](https://pages.nist.gov/800-63-3/sp800-63b.html).
    You can add relying parties to the list of readers of the minimum PIN length.