Skip to content

Commit

Permalink
Ported documentation (#413)
Browse files Browse the repository at this point in the history 
* ported documentation from develop

* adapted instructions

* fix broken English
  • Loading branch information
@kaczmarczyck
kaczmarczyck committed Nov 19, 2021
1 parent e4d8208 commit f2496a8
Show file tree
Hide file tree
Showing 9 changed files with 528 additions and 458 deletions.
221 changes: 47 additions & 174 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,194 +10,67 @@

This repository contains a Rust implementation of a
[FIDO2](https://fidoalliance.org/fido2/) authenticator.
We developed OpenSK as a [Tock OS](https://tockos.org) application.

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:
We intend to bring a full open source experience to security keys, from
application to operating system. You can even 3D print your own open source
enclosure!
You can see OpenSK in action in this
[video on YouTube](https://www.youtube.com/watch?v=klEozvpw0xg)!

### FIDO2

The stable branch implements the published
[CTAP2.0 specifications](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html)
and is FIDO certified.
The stable branch implements the
[CTAP2.0 specification](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html)
and is FIDO certified. OpenSK supports U2F, and non-discoverable credentials
created with either protocol are compatible with the other.

<img alt="FIDO2 certified L1" src="docs/img/FIDO2_Certified_L1.png" width="200px">
If you want to use features of the newer FIDO 2.1, you can try our
[develop branch](https://github.com/google/OpenSK/tree/develop). This version is
NOT certified and less thoroughly tested though. If you plan to add features to
OpenSK, you should switch to develop.

It already contains some preview features of 2.1, that you can try by adding the
flag `--ctap2.1` to the deploy command. The full
[CTAP2.1 specification](https://fidoalliance.org/specs/fido-v2.1-rd-20201208/fido-client-to-authenticator-protocol-v2.1-rd-20201208.html)
is work in progress in the develop branch and is tested less thoroughly.
### :warning: Disclaimer

### Cryptography
This project is **proof-of-concept and a research platform**. It is **NOT**
meant for a daily usage. The cryptography implementations are not resistent
against side-channel attacks.

We're currently still in the process on making the
We're still in the process of integrating the
[ARM&reg; 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.
to enable hardware-accelerated cryptography. Our placeholder implementations of required
cryptography algorithms (ECDSA, ECC secp256r1, HMAC-SHA256 and AES256) in Rust are research-quality
code. They haven't been reviewed and don't provide constant-time guarantees.

## Hardware

You will need one the following supported boards:

* [Nordic nRF52840-DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK)
development kit. This board is more convenient for development and debug
scenarios as the JTAG probe is already on the board.
* [Nordic nRF52840 Dongle](https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF52840-Dongle)
to have a more practical form factor.
* [Makerdiary nRF52840-MDK USB dongle](https://wiki.makerdiary.com/nrf52840-mdk/).
* [Feitian OpenSK dongle](https://feitiantech.github.io/OpenSK_USB/).

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

1. Next step is to install Tock OS as well as the OpenSK application on your
board. Run:

```shell
# Nordic nRF52840-DK board
./deploy.py --board=nrf52840dk --opensk
# Nordic nRF52840-Dongle
./deploy.py --board=nrf52840_dongle --opensk
```

1. Finally you need to inject the cryptographic material if you enabled
batch attestation or CTAP1/U2F compatibility (which is the case by
default):

```shell
./tools/configure.py \
--certificate=crypto_data/opensk_cert.pem \
--private-key=crypto_data/opensk.key
```

1. 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. 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:
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.

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

## Development and testing

### Printing panic messages to the console

By default, libtock-rs blinks some LEDs when the userspace application panicks.
This is not always convenient as the panic message is lost. In order to enable
a custom panic handler that first writes the panic message via Tock's console
driver, before faulting the app, you can use the `--panic-console` flag of the
`deploy.py` script.
```shell
# Example on Nordic nRF52840-DK board
./deploy.py --board=nrf52840dk --opensk --panic-console
```
### Debugging memory allocations
You may want to track memory allocations to understand the heap usage of
OpenSK. This can be useful if you plan to port it to a board with fewer
available RAM for example. To do so, you can enable the `--debug-allocations`
flag of the `deploy.py` script. This enables a custom (userspace) allocator
that prints a message to the console for each allocation and deallocation
operation.
The additional output looks like the following.
```text
# Allocation of 256 byte(s), aligned on 1 byte(s). The allocated address is
# 0x2002401c. After this operation, 2 pointers have been allocated, totalling
# 384 bytes (the total heap usage may be larger, due to alignment and
# fragmentation of allocations within the heap).
alloc[256, 1] = 0x2002401c (2 ptrs, 384 bytes)
# Deallocation of 64 byte(s), aligned on 1 byte(s), from address 0x2002410c.
# After this operation, 1 pointers are allocated, totalling 512 bytes.
dealloc[64, 1] = 0x2002410c (1 ptrs, 512 bytes)
```
A tool is provided to analyze such reports, in `tools/heapviz`. This tool
parses the console output, identifies the lines corresponding to (de)allocation
operations, and first computes some statistics:
* Address range used by the heap over this run of the program,
* Peak heap usage (how many useful bytes are allocated),
* Peak heap consumption (how many bytes are used by the heap, including
unavailable bytes between allocated blocks, due to alignment constraints and
memory fragmentation),
* Fragmentation overhead (difference between heap consumption and usage).
Then, the `heapviz` tool displays an animated "movie" of the allocated bytes in
heap memory. Each frame in this "movie" shows bytes that are currently
allocated, that were allocated but are now freed, and that have never been
allocated. A new frame is generated for each (de)allocation operation. This tool
uses the `ncurses` library, that you may have to install beforehand.
You can control the tool with the following parameters:
* `--logfile` (required) to provide the file which contains the console output
to parse,
* `--fps` (optional) to customize the number of frames per second in the movie
animation.
```shell
cargo run --manifest-path tools/heapviz/Cargo.toml -- --logfile console.log --fps 50
```
To install OpenSK,
1. follow the [general setup steps](docs/install.md),
1. then continue with the instructions for your specific hardware:
* [Nordic nRF52840-DK](docs/boards/nrf52840dk.md)
* [Nordic nRF52840 Dongle](docs/boards/nrf52840_dongle.md)
* [Makerdiary nRF52840-MDK USB dongle](docs/boards/nrf52840_mdk.md)
* [Feitian OpenSK dongle](docs/boards/nrf52840_feitian.md)

To test whether the installation was successful, visit a
[demo website](https://webauthn.io/) and try to register and login.
Please check our [Troubleshooting and Debugging](docs/debugging.md) section if you
have problems with the installation process or during development. To find out what
else you can do with your OpenSK, see [Customization](docs/customization.md).

## Contributing

Expand Down
85 changes: 85 additions & 0 deletions docs/boards/nrf52840_dongle.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# <img alt="OpenSK logo" src="../img/OpenSK.svg" width="200px">

## Nordic nRF52840 Dongle

![Nordic dongle](../img/dongle_front.jpg)

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

![OpenSK Enclosure](../img/enclosure.jpg)

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.

### Flashing using DFU (preferred method)

To flash the firmware, run:

```shell
./deploy.py --board=nrf52840_dongle_dfu --opensk --programmer=nordicdfu
```

The script will ask you to switch to DFU mode. To activate that on your dongle,
keep the button pressed while inserting the device into your USB port. You may
additionally need to press the tiny, sideways facing reset button. The device
indicates DFU mode with a slowly blinking red LED.

### Flashing with an external programmer (JLink, OpenOCD, etc.)

If you want to use JTAG with the dongle, you need additional hardware.

* a [Segger J-Link](https://www.segger.com/products/debug-probes/j-link/) JTAG
probe.
* a
[TC2050 Tag-Connect programming cable](https://www.tag-connect.com/product/tc2050-idc-nl-10-pin-no-legs-cable-with-ribbon-connector).
* a [Tag-Connect TC2050 ARM2010](http://www.tag-connect.com/TC2050-ARM2010)
adaptor
* optionally a
[Tag-Connect TC2050 retainer clip](http://www.tag-connect.com/TC2050-CLIP)
to keep the spring loaded connector pressed to the PCB.

Follow these steps:

1. The JTAG probe used for programming won't provide power to the board.
Therefore you will need to use a USB-A extension cable to power the dongle
through its USB port.

1. Connect the TC2050 cable to the pads below the PCB:

![Nordic dongle pads](../img/dongle_pads.jpg)

1. You can use the retainer clip if you have one to avoid maintaining pressure
between the board and the cable:

![Nordic dongle retainer clip](../img/dongle_clip.jpg)

1. Depending on the programmer you're using, you may have to adapt the next
command line. Run our script for compiling/flashing Tock OS on your device:

```shell
$ ./deploy.py --board=nrf52840_dongle --programmer=jlink
```

1. Remove the programming cable and the USB-A extension cable.

### Buttons and LEDs

The bigger, white button conveys user presence to the application. Some actions
like register and login will make the dongle blink, asking you to confirm the
transaction with a button press. The small, sideways pointing buttong next to it
restarts the dongle.

The 2 LEDs show the state of the app. There are different patterns:

| Pattern | Cause |
|------------------------------------|------------------------|
| all LEDs and colors | app panic |
| green and blue blinking | asking for touch |
| all LEDs and colors for 5s | wink (just saying Hi!) |
| red slow blink | DFU mode |
23 changes: 23 additions & 0 deletions docs/boards/nrf52840_feitian.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# <img alt="OpenSK logo" src="../img/OpenSK.svg" width="200px">

## Feitian OpenSK USB Dongle

### Flashing using DFU

This board is similar in hardware to the Nordic nRF52840 Dongle. You can use DFU
to flash it, instructions to enter DFU mode depend on the version of your
hardware. See
[Feitian's instructions](https://feitiantech.github.io/OpenSK_USB/). In short:

* In V1, use a paperclip to press the Reset button through the tiny hole.
* In V2, push and hold the user button for more than 10 seconds after
connecting your device.

Afterwards, you can flash your Feitian OpenSK using DFU following the
[instructions for the Nordic nRF52840 Dongle](nrf52840_dongle.md#Flashing-using-DFU).

### Buttons and LEDs

For both hardware versions, the buttons and LEDs are described in detail in the
[hardware section](https://feitiantech.github.io/OpenSK_USB/hardware/) of
Feitian's website.
47 changes: 47 additions & 0 deletions docs/boards/nrf52840_mdk.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# <img alt="OpenSK logo" src="../img/OpenSK.svg" width="200px">

## Nordic nRF52840 MDK

Makerdiary has instructions on their [website](https://wiki.makerdiary.com/nrf52840-mdk-usb-dongle/opensk/). They use a custom script to deploy via DFU.

After general setup, you still need these steps:

1. Create the hexfile with the firmware.

```shell
./deploy.py --board=nrf52840_mdk_dfu --opensk --programmer=none
```

1. Download the
[script](https://github.com/makerdiary/nrf52840-mdk-usb-dongle/blob/master/tools/uf2conv.py)
from Makerdiary's GitHub into the OpenSK repository.
1. Run the script:
```shell
python3 uf2conv.py -c -f 0xada52840 -o target/opensk.uf2 target/nrf52840_mdk_dfu_merged.hex
```
1. Boot into DFU mode. Keep the user button pressed on your hardware while
inserting it into a USB slot. You should see a bit of red blinking, and then
a constant green light.
1. Your dongle should appear in your normal file browser like other USB sticks.
Copy the file `target/opensk.uf2` over.
1. Replug to reboot.
### Buttons and LEDs
The big, white button conveys user presence to the application. Some actions
like register and login will make the device blink, asking you to confirm the
transaction with a button press.
The LED shows the state of the app. There are different patterns:
| Pattern | Cause |
|------------------------------------|------------------------|
| red glow | busy |
| red and blue blinking | asking for touch |
| red, green, white pattern for 5s | wink (just saying Hi!) |
| constant green | DFU mode |
Loading

0 comments on commit f2496a8

Please sign in to comment.