Skip to content

install.md

Latest commit

 

History

History
142 lines (101 loc) · 4.49 KB

install.md

File metadata and controls

142 lines (101 loc) · 4.49 KB

OpenSK logo

Installation guide

This document lists required steps to start build your own OpenSK.

OpenSK is installed as a native Wasefire applet.

Software requirements

In order to compile and flash a working OpenSK firmware, you will need the following:

  • rustup (can be installed with Rustup)
  • the OpenSSL command line tool (can be installed and configured with the libssl-dev and pkg-config packages on Debian)
  • uv and python3 (optional, for sending CTAP commands for configuration, can be installed with uv)

Setup

Run the setup script and follow install instructions for rustup and uv, if necessary.

./setup.sh

The setup script is idempotent, so you can always rerun it, either because you don't remember you've run it or because you just pulled a newer version of the main branch with git pull. Rerun it if any command below fails.

If this is the first time installing OpenSK on a Linux host machine, you need to install a udev rule file to allow non-root users to interact with OpenSK devices. To install it, execute:

sudo cp rules.d/99-wasefire.rules /etc/udev/rules.d/
sudo udevadm control --reload

Storage

OpenSK stores data in the devices flash storage, for example your credentials. When you flash Wasefire, you will erase that storage.

If you flash Wasefire and OpenSK for the second time, and want to keep your storage, replace flash in the below commands with update --both.

Features

The applet provides a few customization features (all disabled by default):

  • config-command recommended, enables the authenticatorConfig CTAP command
  • ctap1 recommended, enables CTAP 1 (the applet always implements CTAP 2)
  • debug enables logging of the applet's debug messages
  • ed25519 enables support for Ed25519 (the applet always implements ECDSA P-256)
  • fingerprint enables support for fingerprints (requires a sensor)

The hardware specific commands below to flash a firmware contain the default argument --features=ctap1,config-command. Add or remove features there.

Platforms

The applet needs the platform to implement the following features of the board API:

  • api-button
  • api-clock
  • api-crypto-aes256-cbc
  • api-crypto-ed25519 if the applet ed25519 feature is enabled
  • api-crypto-hmac-sha256
  • api-crypto-p256-ecdh
  • api-crypto-p256-ecdsa
  • api-crypto-sha256
  • api-fingerprint-matcher if the applet fingerprint feature is enabled
  • api-led
  • api-rng
  • api-storage
  • api-timer
  • api-usb-ctap

Run commands below from the directory third_party/wasefire/. They contain the necessary platform features. If you want to use applet features like fingerprint, you may need to add the corresponding platform feature. Set them using --features= prefix for the runner. Some applet features only work for some targets, special notes will indicate when a feature is not supported, or extra steps need to be taken.

In the following sections, we provide instructions to flash an OpenSK applet for each platform provided by this repository.

Host

The applet feature fingerprint is not supported.

To install, run:

cargo xtask --native applet rust ../.. --features=ctap1,config-command \
  runner host flash --usb-ctap --interface=web

nRF52840

The applet feature ed25519 is not supported.

The applet feature fingerprint is supported for the development kit if an FPC 2534 is connected to the board. In that case, the fpc2534 platform feature must be enabled.

An FPC 2532 should theoretically also be supported (but has not been tested) using the same platform feature.

Boards

For more details on the boards, see:

OpenTitan

The applet feature ed25519 is supported and needs the ed25519 platform feature.

The applet feature fingerprint is not supported.

Board: Teacup A2

A LED (active high) needs to be connected to R10. A capacitive touch needs to be connected to R13.

cargo xtask --release --native \
  applet rust ../.. --opt-level=z --features=ctap1,config-command \
  runner opentitan --opt-level=z --features=usb-ctap \
  flash