124 lines
5.4 KiB
Markdown
124 lines
5.4 KiB
Markdown
# <img alt="OpenSK logo" src="docs/img/OpenSK.svg" width="200px">
|
|
|
|
[](https://travis-ci.org/google/OpenSK)
|
|
|
|
|
|
|
|
|
|
|
|
## OpenSK
|
|
|
|
This repository contains a Rust implementation of a
|
|
[FIDO2](https://fidoalliance.org/fido2/) authenticator.
|
|
|
|
We developed this as a [Tock OS](https://tockos.org) application and it has been
|
|
successfully tested on the following boards:
|
|
|
|
* [Nordic nRF52840-DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK)
|
|
* [Nordic nRF52840-dongle](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-Dongle)
|
|
|
|
## Disclaimer
|
|
|
|
This project is **proof-of-concept and a research platform**. It is **NOT**
|
|
meant for a daily usage. It's still under development and as such comes with a
|
|
few limitations:
|
|
|
|
### FIDO2
|
|
|
|
Although we tested and implemented our firmware based on the published
|
|
[CTAP2.0 specifications](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html),
|
|
our implementation was not reviewed nor officially tested and doesn't claim to
|
|
be FIDO Certified.
|
|
We started adding features of the upcoming next version of the
|
|
[CTAP2.1 specifications](https://fidoalliance.org/specs/fido2/fido-client-to-authenticator-protocol-v2.1-rd-20191217.html).
|
|
The development is currently between 2.0 and 2.1, with updates hidden behind a feature flag.
|
|
Please add the flag `--ctap2.1` to the deploy command to include them.
|
|
|
|
### Cryptography
|
|
|
|
We're currently still in the process on making the
|
|
[ARM® CryptoCell-310](https://developer.arm.com/ip-products/security-ip/cryptocell-300-family)
|
|
embedded in the
|
|
[Nordic nRF52840 chip](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fps_nrf52840%2Fcryptocell.html)
|
|
work to get hardware-accelerated cryptography. In the meantime we implemented
|
|
the required cryptography algorithms (ECDSA, ECC secp256r1, HMAC-SHA256 and
|
|
AES256) in Rust as a placeholder. Those implementations are research-quality
|
|
code and haven't been reviewed. They don't provide constant-time guarantees and
|
|
are not designed to be resistant against side-channel attacks.
|
|
|
|
## Installation
|
|
|
|
For a more detailed guide, please refer to our
|
|
[installation guide](docs/install.md).
|
|
|
|
1. If you just cloned this repository, run the following script (**Note**: you
|
|
only need to do this once):
|
|
|
|
```shell
|
|
./setup.sh
|
|
```
|
|
|
|
2. Next step is to install Tock OS as well as the OpenSK application on your
|
|
board (**Warning**: it will erase the locally stored credentials). Run:
|
|
|
|
```shell
|
|
# Nordic nRF52840-DK board
|
|
./deploy.py --board=nrf52840dk --opensk
|
|
# Nordic nRF52840-Dongle
|
|
./deploy.py --board=nrf52840_dongle --opensk
|
|
```
|
|
|
|
3. On Linux, you may want to avoid the need for `root` privileges to interact
|
|
with the key. For that purpose we provide a udev rule file that can be
|
|
installed with the following command:
|
|
|
|
```shell
|
|
sudo cp rules.d/55-opensk.rules /etc/udev/rules.d/ &&
|
|
sudo udevadm control --reload
|
|
```
|
|
|
|
### Customization
|
|
|
|
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 residential 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.
|
|
You can add relying parties to the list of readers of the minimum PIN length.
|
|
|
|
### 3D printed enclosure
|
|
|
|
To protect and carry your key, we partnered with a professional designer and we
|
|
are providing a custom enclosure that can be printed on both professional 3D
|
|
printers and hobbyist models.
|
|
|
|
All the required files can be downloaded from
|
|
[Thingiverse](https://www.thingiverse.com/thing:4132768) including the STEP
|
|
file, allowing you to easily make the modifications you need to further
|
|
customize it.
|
|
|
|
## Contributing
|
|
|
|
See [Contributing.md](docs/contributing.md).
|