79 lines
4.1 KiB
Markdown
79 lines
4.1 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
|
|
|
|
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.
|