RS-Key

An open-source hardware passkey. Flash one file onto a Raspberry Pi RP2350 board and it becomes a USB security key: passkey logins in the browser, ssh and git signing, GPG, PIV, and TOTP codes.

This project is experimental. It has had no external security audit. The RP2350 is not a secure element. A stolen board is only as strong as the optional OTP / secure-boot hardening you have applied to it. Do not use it to guard credentials you cannot afford to lose or have stolen. Read the threat model and limitations before trusting it with anything real.

Written in Rust (no_std, embassy). Under the hood it is FIDO2/WebAuthn/U2F, an OpenPGP card, PIV, OATH and Yubico-style OTP, plus the host-side tooling to drive and provision all of it.

Start here

• Quick start: flash a released image, set a PIN, enroll something. No toolchain needed; the images are on the releases page and releases.md says which one to take
• No board yet? The emulator runs the same applet code over sockets, and its --display mode opens the trusted screen in a window — the Approve/Deny ceremony can be tried with a mouse before buying anything (testing.md)
• Hardware: supported boards and the knobs for them
• Build options: every compile-time flag and environment knob
• Using the device: per-feature guides for FIDO2, SSH, OpenPGP, PIV, OATH, OTP, seed backup, soft-lock, and more
• Production hardening: OTP master key + secure boot (irreversible fuses; read it end to end first)
• Security: threat model, limitations, and the unsafe audit
• Project: Contributing · Security policy · Licensing & compliance

What it is, plainly

• It aims to behave like a USB security key and to work with the host software people already use: ssh, gpg, browsers, libfido2, and ykman (which needs the opt-in VIDPID=Yubikey5 build, see below). What has actually been checked on hardware is recorded in the interop matrix, with dates.
• It is not a certified hardware security key, and not a drop-in replacement for an audited commercial key in production. There is no secure element.
• The default USB identity is RS-Key’s own (VID 0x1209 / PID 0x0001, from pid.codes, the open-source USB VID), presenting as “RS-Key Security Key”. An opt-in VIDPID=Yubikey5 build instead borrows a YubiKey’s identity (VID 0x1050 / PID 0x0407) so that ykman and Yubico Authenticator (which key off the “Yubico YubiKey” reader name) work without custom rules. That flavor is for interop only and is never distributed. See limitations. RS-Key is not affiliated with or endorsed by Yubico, Nitrokey, or Raspberry Pi.

License

AGPL-3.0-only. RS-Key is a from-scratch Rust reimplementation of the AGPL-3.0-only pico-keys firmware family, so it inherits that license and cannot be relicensed. See NOTICE and COMPLIANCE.md.

Quick start

From zero to a working security key in about ten minutes.

This is experimental firmware with no security audit and no secure element. It’s fine for trying things out and for credentials you can afford to lose. See the threat model before using it for anything real.

flowchart TD
    a["download rs-key-&lt;version&gt;-default.uf2<br/>(or build it yourself)"] --> c["hold BOOT, plug in"]
    c --> d["flash: drag-and-drop or picotool load"]
    d --> e["board reboots, enumerates over USB"]
    e --> f["set PIN, enroll a passkey / ssh key"]

What you need

• An RP2350 board (tested: Waveshare RP2350-One; any RP2350 with USB works)
• A USB cable

That is the whole list. You only need a toolchain if you want to build the firmware yourself instead of downloading it.

No board yet? The emulator runs the same applet code on your machine — enough to drive the protocol suites, and with --display, to try the trusted screen’s Approve/Deny ceremony with a mouse.

0. Easy way: use the web flasher

Use the RS-Key Web Flasher for a guided browser flow. It can download, verify, sign, and flash the firmware.

Browser requirement: Flashing requires a desktop Chromium-based browser, such as Google Chrome or Microsoft Edge.

1. Get the firmware

Download the newest rs-key-<version>-default.uf2 from the releases page. Take 2mb, 16mb or display instead if that is your board; releases.md has the table of all fourteen images, the cosign signature check, and the reproducibility check.

Every published image is a touch build: FIDO operations (registering, logging in) require a press of the presence button, BOOTSEL by default.

nix develop                                  # first run downloads the toolchain
cargo build --release -p firmware
scripts/pt.sh target/thumbv8m.main-none-eabihf/release/firmware firmware-pt.elf
picotool uf2 convert firmware-pt.elf -t elf firmware.uf2

2. Flash

To flash the firmware manually:

1. Hold the BOOT button while plugging the board in (or hold BOOT, tap RESET). A mass-storage drive named RP2350 appears.

2. Flash it, either way (firmware.uf2 here is whichever .uf2 you got in step 1):

   • Drag-and-drop: cp firmware.uf2 /Volumes/RP2350/ (macOS) or copy it to the mounted drive on Linux.
   • picotool (more reliable: it verifies and skips the mass-storage layer): picotool load -v firmware.uf2 && picotool reboot.

   The RP2350 drive is a fake FAT volume the bootrom emulates. It only understands the UF2 blocks written to it, not a real filesystem. On some machines the OS’s mass-storage layer breaks that (macOS resource-fork sidecar files and Spotlight, buffered or reordered writes, the board rebooting the instant the last block lands), so the copy errors or silently does nothing. picotool load speaks the bootrom’s PICOBOOT protocol directly, so reach for it whenever the drive never appears or the copy fails.

3. The board reboots itself and enumerates as RS-Key Security Key. (The default build uses the project’s own USB identity, VID:PID 0x1209:0x0001 from pid.codes; the PC/SC reader name contains “RS-Key”. For a build that presents the YubiKey USB identity so ykman/Yubico Authenticator auto-recognize it, build the opt-in VIDPID=Yubikey5 flavor; see build.md.)

Check it (optional, needs the host tools from the dev shell or tools/):

rsk status        # FIDO getInfo + secure-boot + backup state, over USB
ykman info        # needs the opt-in VIDPID=Yubikey5 build: YubiKey 5A, firmware 5.7.4, 6 apps

On Linux, the CCID half (OpenPGP/PIV/OATH) needs pcscd + a polkit rule first. See linux.md. FIDO works as soon as the udev rules are in place.

Or from a GUI, with no terminal at all: PicoForge (third-party, from the librekeys project) shows the same state on one screen — identity and firmware build, FIDO2 info, storage use, LED settings, boot mode — with sections for passkeys, PIV, OpenPGP, OTP slots, the audit journal, backup, soft-lock and attestation. It writes the same phy record rsk hw writes, over the interface documented in protocol.md §11. It is not part of this repo and ships on its own schedule.

That is a board straight out of step 2, so the screen reads the way yours will: the identity is the default 1209:0001, no PIN is set yet (that is step 3), and the boot mode is still Development. production.md is what turns the last one into a locked-down key — irreversibly, so read it first.

3. Set a PIN (recommended)

rsk fido set-pin

Without the host tools, your browser does the same job: it offers to set a PIN the first time you register a passkey.

Browsers and ssh-keygen will prompt for it when enrolling. 8 wrong attempts lock the PIN until a reset. Standard security-key behaviour.

4. Enroll something

A passkey: go to any WebAuthn site (or https://webauthn.io to try), register a security key, touch the button when the LED asks.

An SSH key:

ssh-keygen -t ed25519-sk -f ~/.ssh/id_ed25519_sk    # touch twice, enter PIN
ssh-copy-id -i ~/.ssh/id_ed25519_sk you@server
ssh -i ~/.ssh/id_ed25519_sk you@server              # one touch to log in

The id_ed25519_sk file is a handle, not a key. It is useless without the board. Copy it to other machines you ssh from.

macOS note: Apple’s /usr/bin/ssh has no FIDO support. Use Homebrew OpenSSH (brew install openssh, then the absolute path /opt/homebrew/opt/openssh/bin/ssh or put it first in PATH). Details: guides/ssh.md.

5. Back up your identity (optional but wise)

rsk backup export --scheme bip39          # 24 words, write them down
rsk backup finalize                       # seals the export window

The words recover your deterministic FIDO identity (ssh-sk logins, 2FA registrations) onto a fresh board with rsk backup restore. Anyone who has the words can recreate that identity on their own board, so store them like cash. They do not cover resident passkeys, OpenPGP or PIV keys. See guides/seed-backup.md.

Where next

• Feature guides: OpenPGP with gpg, PIV, OATH codes, OTP slots, soft-lock, LED colors
• production.md: fuse the master key into OTP + enable secure boot (irreversible, read first)
• threat-model.md: what this device protects against

Hardware

What RS-Key runs on, and the build knobs you need for a board other than the reference one. The full knob reference is in build.md. This page is the short version.

Supported boards

RP2350-One reference · USB-A WS2812 on GPIO16	RP2350-Zero mini stick · USB-C	TenStar RP2350-USB USB-A stick WS2812 on GP22	RP2350-Touch-LCD-2.8 trusted display · 2.8″ LCD

_{Board photos: Waveshare (RP2350-One / Zero / Touch-LCD-2.8).}

Any RP2350 board with a USB connector should work. Development and on-device testing happen on the Waveshare RP2350-One, where the WS2812 status LED on GPIO16 works out of the box. Boards without an addressable LED run fine. The indicator is optional and the firmware just runs dark. A board whose LED sits behind a power gate — the Seeed XIAO RP2350 powers its WS2812 through GP23 — lights up once that enable pin is set with LED_POWER_PIN (below).

The RP2350’s dual Cortex-M33, 520 KB SRAM, hardware TRNG, OTP fuses, and glitch detectors do the work. There is no secure element and no debugger requirement: the firmware flashes over USB BOOTSEL, so a bare board and a USB cable are enough.

Defaults and the knobs to change them

The default build targets a 4 MB flash chip with the LED on GPIO16, uses BOOTSEL for user presence, and assumes a standard 12 MHz crystal. For a different board, three compile-time knobs usually cover it:

# example: an 8 MB board with a plain LED on GPIO25
env FLASH_SIZE=8M LED_KIND=gpio LED_PIN=25 cargo build --release -p firmware

# example: a 16 MB TenStar RP2350-USB — WS2812 on GP22, standard GRB order
env FLASH_SIZE=16M LED_PIN=22 LED_ORDER=grb cargo build --release -p firmware

# example: a Seeed XIAO RP2350 — WS2812 on GP22, GRB, power-gated by GP23 (driven high),
# its active-low USR LED on GP25 parked off, and its 2 MB flash (smaller KVMAIN)
env FLASH_SIZE=2M KVMAIN=896K LED_PIN=22 LED_ORDER=grb LED_POWER_PIN=23 USR_LED_PIN=25 cargo build --release -p firmware

# example: WS2812 on GP22 and a button-to-GND on GP0 (active-low)
env LED_PIN=22 PRESENCE_PIN=0 cargo build --release -p firmware

# example: an active-high capacitive touch sensor on GP0
env PRESENCE_PIN=0 PRESENCE_ACTIVE_HIGH=1 cargo build --release -p firmware

The four LED knobs (LED_PIN / LED_KIND / LED_ORDER / MAX_LEDS) set only the boot defaults. A non-none build compiles all three backends, so the pin, driver, wire order, and buffer ceiling are also changeable at runtime (no reflash) with rsk hw or PicoForge, which write them to the device’s phy record (guides/led.md). The build knobs still matter for picking a lean none build and for the out-of-the-box default.

Most RP2350A boards work with at most a one-line change. Everything else (USB descriptors, applets, flash layout) is board-independent.

Enclosures

A bare board works fine, but a printed case makes it pocketable. Four community designs fit the boards above:

• Waveshare RP2040-One / RP2350-One case by Patrick van der Leer. Sized for the reference board.
• RP2350 USB case by Vladimir Varzaru (a remix of Patrick’s design). A slimmer USB-stick form.
• Pico 2 Zero FIDO2 case (RP2350) on MakerWorld. Fits the RP2350-Zero.
• Waveshare RP2350 2.8-inch case by @cofob. Designed for RS-Key and recommended for the RP2350-Touch-LCD-2.8. PETG is the recommended print material.
• Waveshare RP2350 2.8-inch case by Mono. Designed for RS-Key, reliable USB and button performance as well as sturdyness. PETG material recommended.

The two Printables designs as well as the Thingiverse design are licensed CC BY-SA 4.0: print, sell, and remix them freely, as long as you credit the authors and keep any derivative under the same license. Check each MakerWorld page for the design license before you reuse the design. All are third-party designs, linked for convenience, not part of this project.

What the hardware does not give you

The OTP fuses and secure boot (production.md) are real hardening, but the RP2350 is a general-purpose microcontroller, not a certified secure element. Physical attacks are out of scope: decapping, microprobing, fault injection beyond the on-chip glitch detectors, power/EM side channels. See the threat model and limitations.

Build options

Every knob is compile-time. Set environment variables and cargo features at cargo build and they bake into the image. Nothing here changes at runtime (except where noted for the phy record).

# the general shape
nix develop -c env KNOB=value cargo build --release -p firmware [--features ...]
nix develop -c scripts/pt.sh target/thumbv8m.main-none-eabihf/release/firmware firmware-pt.elf
picotool uf2 convert firmware-pt.elf -t elf firmware.uf2

The middle step embeds the partition table; skip it and the key ships with its storage exposed to the bootloader. nix build .#firmware folds all three together.

flowchart TD
    knobs["env knobs + cargo features"] --> build["cargo build (or nix build)"]
    build --> elf["firmware.elf"]
    elf --> pt["scripts/pt.sh<br/>embed partition table"]
    pt --> conv["picotool uf2 convert"]
    conv --> uf2["firmware.uf2"]
    uf2 --> flash["BOOTSEL flash"]
    pt -. "secure boot only — seal the ELF" .-> seal["picotool seal --sign<br/>signing key (host-only)"]
    seal -.-> sconv["picotool uf2 convert"]
    sconv -.-> signed["firmware-signed.uf2"]
    signed -.-> flash

Cargo features

Environment variables

The LED_PIN / LED_KIND / LED_ORDER / MAX_LEDS values are boot defaults only. A non-none build compiles all three backends, so the LED pin, driver, and wire order are runtime-configurable (no reflash) with rsk hw (or PicoForge), which write them to the device’s phy record. The build knobs decide the out-of-the-box behaviour and let you drop to a lean none build. Everything else is a rsk hw call away (guides/led.md).

Verify what got baked without flashing:

rg PK_USB_VID  target/thumbv8m.main-none-eabihf/release/build/firmware-*/output   # decimal: 4617 = 0x1209
rg PK_FW_VERSION target/thumbv8m.main-none-eabihf/release/build/rsk-sdk-*/output
rg PK_XOSC_DELAY_MULT target/thumbv8m.main-none-eabihf/release/build/firmware-*/output

The firmware-* glob matches one build dir per feature combination you have built, so a stale entry can show an old value. Read the freshest one (or cargo clean -p firmware first) if the output looks doubled.

Flash size and the memory map

FLASH_SIZE regenerates memory.x: the KV store stays pinned to the top of flash and only the code region grows. A 16 MB board just gets more (unused) code headroom. The credential capacity is unchanged (why the flash is mostly empty by design: architecture.md).

One exception, and only at 16 MB: the store stops a sector short of the top, because the bootrom’s RP2350-E10 workaround owns the last 256 bytes of the XIP window (0x10FFFF00) and picotool partition create refuses a table that claims them — so a 16 MB image could not carry the fence at all. The reserved 4 KB is outside every partition, which is where the bootrom needs it.

The KV store is 1.5 MB by default (KVMAIN 1408K + KVCNT 128K). On a 2 MB board that leaves too little for the ~900K image, so the firmware can’t link. KVMAIN shrinks the main partition to make room: build a 2 MB Seeed XIAO RP2350 or Waveshare RP2350-Zero-CM with FLASH_SIZE=2M KVMAIN=896K (896K creds + 128K counters + 1024K code). build.rs bakes the size into both memory.x and flash_storage.rs, so the two partitions never disagree, and it rejects a split that leaves under 1 MB for code with a message that names the fix. A fully provisioned key needs only a few hundred KB, so 896K is ample.

At the 4M default the code region is 2560K; the shipping image uses roughly a third of it. check.sh enforces a ratchet well under that: a ceiling that hugs the current image, so a runaway dependency (a whole extra EC curve is ~150 KiB) or any surprise growth trips it long before the linker’s hard limit. Lower FIRMWARE_FLASH_BUDGET_KIB when the image shrinks; raise it in the same commit when a real feature legitimately grows it.

RAM has the mirror-image ratchet, FIRMWARE_STACK_FLOOR_KIB. Whatever .data and .bss do not take is stack, so a new static costs stack depth — and the deepest paths on this chip (ML-DSA-65 keygen, the RSA modexp chain) run close enough to the ceiling that it has already wedged a device. The gate reads the figure straight out of the ELF and fails under the floor. The images link through flip-link, which places the stack below the statics, so an overflow faults on unmapped memory instead of quietly overwriting them; that needs rust-lld on PATH, which the dev shell arranges, so build inside nix develop.

The partition table

The shipped image carries an RP2350 partition table that fences the KV store off from the USB bootloader: picotool save and picotool load over the store answer permission failure, while the running firmware keeps full access to it. It is a defence-in-depth layer against the BOOTSEL snapshot/restore rollback, and it is a real barrier only where secure boot is on — read threat-model.md before quoting it as protection.

scripts/pt.sh reads the fence out of the built ELF’s own __kvmain_start / __kvcnt_end symbols — the same ones flash_storage.rs uses to find the store — so it follows FLASH_SIZE / KVMAIN / BOARD with no second copy of the layout to keep in step. check.sh asserts the emitted table back against those symbols, because a table that misses the store still links, still boots, and then loses the firmware’s writes at runtime.

⚠️ A bare cargo build does not produce it. The table is added after linking, so target/…/release/firmware carries none and a key flashed straight from that ELF is unfenced. nix build .#firmware applies it; for a local cargo build, apply it yourself:

cargo build --release -p firmware
scripts/pt.sh target/thumbv8m.main-none-eabihf/release/firmware firmware-pt.elf
picotool load firmware-pt.elf -t elf

Examples

# default: touch build, RS-Key identity (0x1209:0x0001), fw 5.7.4
cargo build --release -p firmware

# opt-in Yubico interop flavor (so ykman / Yubico Authenticator see the device)
env VIDPID=Yubikey5 cargo build --release -p firmware

# no-touch test build (for the automated suites)
cargo build --release -p firmware --features no-touch

# Nitrokey FIDO2 identity with its own version number
env VIDPID=NitroFIDO2 FW_VERSION=1.4.0 cargo build --release -p firmware

# advertise PQC in getInfo (breaks released Firefox — see above)
cargo build --release -p firmware --features advertise-pqc

# ship with CTAP 2.1 alwaysUv enabled by default (set a PIN after flashing)
cargo build --release -p firmware --features always-uv

# strict admin-write posture (the historical default; config writes stay gated)
cargo build --release -p firmware --features strict-config

nix build (hermetic, no dev shell)

The flake exposes the firmware as a package, so you can build a UF2 without entering the dev shell or having a Rust toolchain installed. Nix pins the toolchain, the cross target, and every dependency:

nix build .#firmware                 # default touch image
ls result/                           # firmware.elf  firmware.uf2

result/firmware.uf2 is functionally the image the dev-shell cargo build produces. Unlike the dev-shell build, it is bit-for-bit reproducible: the derivation remaps the two absolute build inputs out of the binary (the per-build sandbox dir and the toolchain store path; both land in panic-location strings in .rodata, plus DWARF in the .elf) with stable --remap-path-prefix, so one flake.lock yields one firmware.uf2 on every machine of a platform. The daily repro job in deep-checks proves it (nix build twice, the second with --rebuild so nix compares every output byte) and publishes the canonical sha256 in its run summary.

To verify a published image: nix build .#firmware at the release commit and compare hashes. A sealed image can’t be reproduced by a third party (the signature is the signer’s); verify the unsigned payload instead, then check the seal with picotool. The flavors mirror the CI matrix:

Two caveats:

• The output is UNSIGNED. On a secure-boot device you still seal it with your key. The signing key deliberately never enters the build sandbox:

  # the ELF, not the UF2: sealing a UF2 leaves the image's own unsigned
  # IMAGE_DEF first in the chain, and a secure-boot device refuses that
  picotool seal --sign --hash result/firmware.elf -t elf firmware-signed.elf -t elf \
      ~/.rs-key-secrets/secure_boot_key.pem ~/.rs-key-secrets/otp_secureboot.json \
      --major 1 --minor 0 --rollback 1
  picotool uf2 convert firmware-signed.elf -t elf firmware-signed.uf2
  

  The .pem is your signing key, the .json is where seal writes the boot-key fingerprint, and --major/--minor stamp an image version into the boot metadata: a plain major.minor label, separate from both the firmware version RS-Key reports (5.7.x) and the rollback version. The full meaning of each flag is in production.md.

  If you have enabled anti-rollback, the seal additionally needs --rollback <your board's floor>, a separate, deliberate step with its own rules and a finite OTP budget. Don’t add it blindly; the full flashing-with-rollback workflow is in anti-rollback.md.

• The env knobs above are declarative Nix args, not ambient env. A plain nix build bakes the defaults; to customize, pass them to the builder. For a config you reuse, add a one-line preset package (the flake ships firmware-pico = mkFirmware { name = "firmware-pico"; vidpid = "Pico"; } as a copy-me example) and build it:

  nix build .#firmware-pico
  

  For a one-off without committing a package, call the exposed builder. (The --impure here only lets getFlake read the working tree; the knobs themselves are pure. A committed/pushed flakeref needs no flag.)

  nix build --impure --expr \
    '(builtins.getFlake (toString ./.)).lib.${builtins.currentSystem}.mkFirmware
       { name = "fw"; vidpid = "Nitro3"; fwVersion = "2.0.0"; }'
  

  Knobs: vidpid, usbVid, usbPid, fwVersion, xoscDelayMult, flashSize, ledPin, presencePin, fakeMkek, fakeDevk (mirroring the env vars above). As a convenience each also falls back to the like-named env var, so VIDPID=Pico nix build --impure .#firmware works for a quick throwaway, but the declarative arg is the reproducible path and needs no --impure.

nix run — host tools without the dev shell

The host tooling is also exposed as flake apps, so it runs straight from the flake without nix develop (Nix pins every dependency):

nix run .#rsk -- status          # the Python device CLI (rsk --help for groups)
nix run .#rsk-tui                # the live ratatui dashboard (prebuilt binary)
nix run .#flash -- --help        # build + sign + flash, one command (secure boot)

#rsk wraps the bundled tools/rsk package on the pinned interpreter; #rsk-tui is a prebuilt host binary (no compile-on-run). Both are also buildable as packages (nix build .#rsk-tui).

nix run .#flash wraps the secure-boot flash ritual end to end: it seals (signs) an unsigned image, reboots the device into BOOTSEL, loads it, then reboots. With no argument it seals the reproducible default firmware (.#firmware); pass a path to seal a flavor you built yourself (nix run .#flash -- firmware-no-touch.uf2). It reads the signing key from the host (~/.rs-key-secrets/{secure_boot_key.pem,otp_secureboot.json} by default, override the directory with RS_KEY_SECRETS) and stamps --rollback 1 into the seal (set RSK_ROLLBACK to change). It prompts before flashing (-y skips). The device must already run secure boot with the matching boot key provisioned; the full ritual, the anti-rollback rules, and recovery are in production.md and anti-rollback.md.

Runtime overrides (phy record)

The rescue applet can store a small config record in flash (rsk / rsk-tui expose the safe fields). At boot, a stored VID/PID and product string override the compile-time defaults, useful to re-identify a device without rebuilding. A bad value can make the device enumerate strangely; recovery is a BOOTSEL reflash (which never reads the record) or rewriting the record over CCID.

The effective identity is resolved in this order:

flowchart TD
    a["VIDPID preset"] --> b["USB_VID / USB_PID raw override (compile time)"]
    b --> c["phy record (runtime, at boot)"]
    c --> d["effective VID/PID + product string"]

Notes

• The PC/SC reader name comes from the USB strings. The default build reads RS-Key RS-Key Security Key …, and the project’s own tools (rsk, rsk-tui) match the RS-Key token. ykman and Yubico Authenticator derive the device’s PID purely from that name. They need the Yubico YubiKey words and the OTP/FIDO/CCID tokens, which only the opt-in VIDPID=Yubikey5 flavor supplies (Yubico YubiKey RSK OTP+FIDO+CCID); on the default build those tools do not see the device. gpg, ssh -sk, browsers, libfido2 and OpenSC are identity-independent and work on either build.
• bcdDevice (USB device release) is an internal build counter, not the firmware version.
• The two UF2 flavors on a release build of this repo: firmware.uf2 (touch) and firmware-test.uf2 (no-touch). scripts/check.sh builds both.

Releases & verification

Releases live on the GitHub Releases page. Each is cut from a v* git tag by the release workflow. It builds every artifact reproducibly, hashes it, and signs the manifest.

What a release contains

• Fourteen firmware images: rs-key-<tag>-<flavor>.uf2. Every published image requires a physical touch; the no-touch test builds are never released (a signed presence-bypass asset would remove the consent gate):

  flavor	flags	use
  default	touch	the normal build; start here
  pqc	+ advertise-pqc	advertises all three ML-DSA sets in getInfo (breaks old Firefox)
  fips	+ fips-profile	the locked FIPS-style policy (guides/fips.md)
  fips-pqc	+ both
  strong-pin	+ strong-pin	6-code-point PIN floor + trivial-PIN block (build.md, threat-model.md)
  strong-pin-pqc	+ both
  always-uv	+ always-uv	bakes CTAP 2.1 alwaysUv on: user verification (a PIN) for every operation, U2F disabled. Set a PIN after flashing (build.md)
  always-uv-pqc	+ both
  strict-up	+ strict-up	not spec-conformant: a touch on every assertion, so a WebAuthn allowCredentials login asks for two touches (build.md). Pick it only if you want that stricter stance
  strict-up-pqc	+ both
  display	+ display	experimental trusted-display build (Waveshare RP2350-Touch-LCD-2.8, guides/display.md)
  2mb	FLASH_SIZE=2M KVMAIN=896K	2 MB boards (Seeed XIAO RP2350, Waveshare RP2350-Zero-CM)
  16mb	FLASH_SIZE=16M	16 MB boards (e.g. TenStar RP2350-USB)
  strict-config	+ strict-config	the historical strict admin-write posture: config writes stay presence/PIN-gated and the ungated transport writes are refused (build.md, threat-model.md). The default build is now the permissive full-ykman admin surface

  All fourteen present the default RS-Key USB identity (0x1209:0x0001). For the YubiKey-interop identity, build VIDPID=Yubikey5 yourself (build.md).

• SHA256SUMS: a checksum for every image and the SBOM.

• SHA256SUMS.sigstore.json: a keyless cosign signature of SHA256SUMS (sigstore/Fulcio; the signer is the reusable build workflow’s GitHub OIDC identity, release-build.yml, see the verify step below; logged in Rekor). Releases up to and including v0.4.10 carry the same file under the older name SHA256SUMS.cosign.bundle — identical bytes, and .sigstore.json is simply the canonical extension for what it always was (application/vnd.dev.sigstore.bundle.v0.3+json). Those releases are immutable and cannot be renamed in place, so both names exist in the wild.

• rs-key-<tag>.intoto.jsonl: the build-provenance attestation, as a file. The authoritative copy stays in GitHub’s attestation API and in Rekor; this one is for checking a download offline.

• rs-key-<tag>-sbom.cdx.json: a CycloneDX software bill of materials for the firmware’s dependency tree.

The images are UNSIGNED for secure boot. The cosign signature attests who built them, not the boot seal. On a secure-boot device you seal an image with your own key before flashing. nix run .#flash does it, or see production.md. The reproducibility claim is about the unsigned payload (a seal is signer-specific and not reproducible by a third party).

Verify a download

Grab the images you want plus SHA256SUMS and the signature — SHA256SUMS.sigstore.json, or SHA256SUMS.cosign.bundle on releases up to v0.4.10. Same bytes either way; substitute the name you actually downloaded.

# 1. the checksums file is authentic (keyless cosign — needs cosign >= 2.0)
#    The signer is the *reusable* build workflow (release-build.yml), not the
#    thin release.yml caller: a workflow_call job's OIDC identity is its own
#    job_workflow_ref, so that is what the Fulcio cert's SAN carries.
cosign verify-blob \
  --bundle SHA256SUMS.sigstore.json \
  --certificate-identity-regexp '^https://github\.com/TheMaxMur/RS-Key/\.github/workflows/release-build\.yml@refs/tags/v.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  SHA256SUMS

# 2. the images match the (now-trusted) checksums
sha256sum -c SHA256SUMS

Both must pass. Step 1 proves SHA256SUMS was produced by this repo’s release workflow; step 2 ties each .uf2 (and the SBOM) to it.

Verify the build is reproducible

The images are bit-for-bit reproducible per platform, per flake.lock, so you can rebuild them yourself and compare (no need to trust the published binary):

git checkout <tag>
nix build .#firmware              # the default flavor (others: .#firmware-fips, …)
sha256sum result/firmware.uf2     # compare against SHA256SUMS for rs-key-<tag>-default.uf2

A match on Linux reproduces the CI-built artifact exactly. (Cross-platform identity, macOS vs Linux, is not guaranteed; the canonical bytes are the Linux ones the workflow publishes.)

Supply chain

How a downloaded RS-Key release proves it came from this source tree, was built by this project’s CI, and pulls in only reviewed dependencies. And how you verify each claim yourself.

No private keys are involved here. The build provenance is keyless (sigstore/Fulcio, signed against this workflow’s GitHub OIDC identity, recorded in the public Rekor transparency log). The only signing key in the project is the secure-boot key. That is a different thing entirely. It seals an image so the RP2350 bootrom will run it. It has nothing to do with the supply chain. See production.md for that.

What every release carries

Verifying a download

1. Reproducible build

Rebuild from the tagged source and compare. This is the strongest check, because it needs no trust in the publisher at all:

git checkout <tag>
nix build .#firmware            # or .#firmware-pqc, .#firmware-fips, …
sha256sum result/firmware.uf2   # compare against SHA256SUMS

CI already enforces this: the release job rebuilds all eleven flavors with nix build --rebuild and fails on any bit-level difference before publishing.

2. Checksum signature (keyless cosign)

cosign verify-blob \
  --bundle SHA256SUMS.sigstore.json \
  --certificate-identity-regexp '^https://github.com/TheMaxMur/RS-Key/\.github/workflows/release-build\.yml@.*$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS
sha256sum -c SHA256SUMS          # then check the artifacts against it

The certificate identity is release-build.yml, not release.yml: cosign runs inside the reusable builder. Sigstore stamps the cert with the reusable workflow’s identity (job_workflow_ref).

3. Build provenance (GitHub attestation)

gh attestation verify rs-key-<tag>-default.uf2 \
  --repo TheMaxMur/RS-Key \
  --signer-workflow TheMaxMur/RS-Key/.github/workflows/release-build.yml

This confirms the .uf2 was built by the release-build.yml reusable workflow in this repo. The attestation records the workflow, commit and runner, so a hand-built upload won’t verify. Pinning --signer-workflow to the reusable builder is the SLSA Build L3 check: it proves a specific, trusted workflow produced the artifact, not merely that something in the repo did. (Dropping --signer-workflow still verifies an attestation exists for this repo, a weaker Build-L2-style check.) The provenance is a GitHub attestation (Sigstore-signed, logged in Rekor) kept in the attestation API rather than as a release asset, so it stays available even though the published release is immutable.

Dependency review — cargo-vet

cargo-deny already blocks bad licenses and known advisories. cargo-vet answers a different question (has anyone actually reviewed this crate’s code?) by requiring every dependency to be covered by a recorded audit.

The audit set lives in supply-chain/: imported audits from Mozilla, Google, ISRG and Zcash, plus our own exemptions for everything they don’t cover. The gate runs in check.sh:

nix develop -c cargo vet --locked

Honest scope. RS-Key is an embedded tree: embassy, the RP2350 HAL, defmt and many RustCrypto crates are not in the big organizations’ audit sets, so they are recorded as exemptions (grandfathered in, not yet line-reviewed). The point isn’t that every line is audited. It’s that a new, unreviewed crate cannot enter the tree silently. It fails cargo vet until it’s audited, imported, or explicitly exempted. To see the current state and shrink the exemption list:

nix develop -c cargo vet              # what's audited vs exempted
nix develop -c cargo vet suggest      # diffs to review next

The host tools/tui workspace is separate and not yet under cargo-vet. It is covered by Dependabot and cargo-deny.

Transparency-log monitoring

The Rekor log that backs every signature above is tamper-evident, not tamper-proof: it records misuse, but only if someone looks. A scheduled workflow, rekor-monitor.yml, does the looking. Every hour it runs sigstore/rekor-monitor and files a GitHub issue listing any Rekor entry signed as an RS-Key GitHub-Actions identity (any …/RS-Key/.github/workflows/* subject under the GitHub OIDC issuer).

This is the detection half that complements the verification above: the attestations prove a legitimate release is genuine, while the monitor surfaces an illegitimate signature, one made with our identity by something we didn’t run (a compromised OIDC token, repo, or runner). Each real release adds a couple of expected entries from release-build.yml, so a known issue or two per release is normal. The alarm is an entry you don’t recognise.

What’s deliberately not here

• No cargo-vet of a fully line-reviewed tree. See the honest scope above.
• No image encryption / signed-for-boot release artifacts. The published .uf2s are unsigned for secure boot by design. You seal them with your own key (production.md). The signatures on this page attest the build, not the boot.

See also: releases.md for the release index, and COMPLIANCE.md for the licensing posture.

Linux host setup

The board enumerates as a composite FIDO HID + CCID device. By default it uses the project’s own RS-Key USB identity 0x1209:0x0001 (pid.codes), with the PC/SC reader name containing RS-Key. The opt-in VIDPID=Yubikey5 interop build instead presents the YubiKey identity 0x1050:0x0407 (other presets: build.md). The two transports have different host requirements on Linux:

flowchart TD
    a["FIDO HID<br/>WebAuthn · ssh-sk · fido2-token"] --> b["hidraw + yubico udev rules<br/>(usually works out of the box)"]
    c["CCID (PC/SC)<br/>ykman · gpg · OpenPGP / PIV / OATH"] --> d["pcscd + polkit rule<br/>(+ disable-ccid for gpg)<br/>— needs both pieces"]

FIDO generally works after installing the standard yubico udev rules. CCID needs three more pieces: the CCID driver’s reader list must contain this device’s USB id at all (next section — on the default identity it does not, and that alone hides every applet), a polkit rule (so a non-root user, including one over SSH, may talk to pcscd), and, if you also use GnuPG, disable-ccid in scdaemon.conf so gpg’s scdaemon goes through pcscd instead of grabbing the raw CCID interface and locking out ykman/pcsc-tools.

Verified on a NixOS 25.11 host (kernel 6.18.x): FIDO getInfo works as a plain user over SSH once the udev rule below is in place, and gpg --card-status works with disable-ccid. ykman info works the same way on the opt-in VIDPID=Yubikey5 build (it gates on the Yubico YubiKey reader name, which the default RS-Key build does not present).

Replace youruser with your login name throughout.

The CCID driver’s reader list (default identity only)

Read this first if the applets are missing. pcscd does not drive readers itself — the ccid driver does, and it binds only USB ids that appear in its own reader list (supported_readers.txt, compiled into ifd-ccid.bundle/Contents/Info.plist). The default RS-Key identity 0x1209:0x0001 is not in that list, so the CCID interface is skipped silently: FIDO keeps working, pcsc_scan shows nothing, and OpenPGP, PIV, OATH and Yubico-OTP all look absent rather than broken. No polkit or udev change fixes this — those govern access to a reader the driver never claimed.

Why it is not simply fixed upstream: 0x1209:0x0001 is pid.codes’ shared prototype id, not an allocation to this project. Listing it in the ccid driver would bind every unrelated prototype using the same id. A dedicated VID/PID is pending, and the upstream submission waits on it.

Until then, pick one:

• Build the interop identity — VIDPID=Yubikey5 (build.md) presents 0x1050:0x0407, which is already in the driver’s list, and the stock yubico udev rules cover it too. Nothing to patch; this is why the applets work out of the box on that build.
• Apply this flake’s ccid overlay (NixOS) — the same driver with that one line already in its reader list, and nothing else changed; the build refuses to produce a bundle the id did not reach.
• Add the id to your local ccid driver. Building from source, a one-line addition to supported_readers.txt before the build; on an FHS distro, edit /usr/lib/pcsc/drivers/ifd-ccid.bundle/Contents/Info.plist, which holds ifdVendorID, ifdProductID and ifdFriendlyName as three parallel arrays — add one entry to each, at the same position, or the mapping shifts. Restart pcscd and re-plug.

Both routes are user reports rather than something CI covers: the source-patch route in #67, the Info.plist route in discussion #58.

NixOS (declarative)

Add to your configuration.nix:

{ pkgs, ... }:
{
  # PC/SC daemon for the CCID applets (OpenPGP / PIV / OATH / OTP).
  services.pcscd.enable = true;

  # udev rules that grant access to the FIDO hidraw node. The stock yubico
  # rules match VID 0x1050 only, so the default RS-Key identity (0x1209) needs
  # its own rule; build VIDPID=Yubikey5 instead if you want to reuse the stock
  # yubico rules unchanged.
  services.udev.packages = [
    pkgs.yubikey-personalization
    pkgs.libfido2
  ];
  services.udev.extraRules = ''
    # RS-Key own identity (pid.codes 0x1209:0x0001) — FIDO HID + CCID access.
    SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="0001", TAG+="uaccess"
    SUBSYSTEM=="usb", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="0001", TAG+="uaccess"
  '';

  # Let a non-root user (e.g. over SSH) talk to pcscd. Without this, CCID works
  # only as root and `ykman`/`gpg --card-status` fail from an SSH session.
  security.polkit.extraConfig = ''
    polkit.addRule(function(action, subject) {
      if ((action.id == "org.debian.pcsc-lite.access_pcsc" ||
           action.id == "org.debian.pcsc-lite.access_card") &&
          subject.user == "youruser") {
        return polkit.Result.YES;
      }
    });
  '';

  # Optional: the host tools (ykman, gpg, openssh with FIDO support).
  environment.systemPackages = with pkgs; [
    yubikey-manager   # ykman
    libfido2          # fido2-token, fido2-assert
    opensc            # opensc-tool -l, pkcs11
    pcsctools         # pcsc_scan
  ];
}

nixos-rebuild switch, then re-plug the board (or restart pcscd).

On the default identity that is not yet enough — the ccid driver still has to know the id (see above). This flake carries an overlay for it; add the repo as an input of your system flake and apply it:

# flake.nix: inputs.rs-key.url = "github:TheMaxMur/RS-Key";
{
  nixpkgs.overlays = [ inputs.rs-key.overlays.ccid-rs-key ];
}

The overlay replaces pkgs.ccid, which is exactly what the pcscd module puts in its plugin list, so there is nothing else to set. If you would rather not override the attribute for the whole system, name the package instead — with lib.mkForce, because the module contributes its own [ pkgs.ccid ] and two ccid bundles collide in the plugin buildEnv:

services.pcscd.plugins = lib.mkForce [
  inputs.rs-key.packages.${pkgs.system}.ccid-rs-key
];

Generic Linux (Debian / Ubuntu / Fedora / Arch)

1. Install the stack. Package names vary by distro:

   • Debian/Ubuntu: pcscd pcsc-tools libfido2-1 yubikey-manager opensc
   • Fedora: pcsc-lite pcsc-tools libfido2 yubikey-manager opensc
   • Arch: pcsclite ccid yubikey-manager libfido2 opensc

2. Enable pcscd: sudo systemctl enable --now pcscd.socket

3. udev rules. The stock yubico rules that ship with libfido2 / yubikey-personalization / libu2f-host match VID 0x1050 only, so they do not cover the default RS-Key identity (0x1209). Add your own rule. Create /etc/udev/rules.d/70-rsk.rules:

   # RS-Key own identity (pid.codes 0x1209:0x0001) — FIDO HID + CCID access.
   SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="0001", TAG+="uaccess", GROUP="plugdev", MODE="0660"
   SUBSYSTEM=="usb", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="0001", TAG+="uaccess", GROUP="plugdev", MODE="0660"
   

   Then sudo udevadm control --reload && sudo udevadm trigger and re-plug. (Alternatively, build VIDPID=Yubikey5 to reuse the stock yubico rules unchanged.) If your user still can’t open the device, confirm you’re in the right group (plugdev on Debian/Ubuntu).

4. polkit rule for non-root pcscd access. Create /etc/polkit-1/rules.d/41-pcsc-rsk.rules:

   polkit.addRule(function(action, subject) {
     if ((action.id == "org.debian.pcsc-lite.access_pcsc" ||
          action.id == "org.debian.pcsc-lite.access_card") &&
         subject.user == "youruser") {
       return polkit.Result.YES;
     }
   });
   

   (Use subject.isInGroup("plugdev") instead of subject.user == … to grant a whole group.) Restart polkit/pcscd or re-plug afterwards.

GnuPG (gpg --card-status, OpenPGP)

scdaemon defaults to grabbing the CCID interface directly, which fights pcscd and locks out ykman/pcsc_scan. Route it through pcscd instead by adding to ~/.gnupg/scdaemon.conf:

disable-ccid
pcsc-shared

Then reload it: gpgconf --kill scdaemon. After this, gpg --card-status and pcsc_scan (and ykman, on the opt-in VIDPID=Yubikey5 build) coexist (they share the one reader through pcscd).

FIDO / SSH (ed25519-sk)

Once the udev rules are in place, OpenSSH with libfido2 support works directly. No pcscd involved (FIDO is HID, not CCID):

ssh-keygen -t ed25519-sk -f ~/.ssh/id_ed25519_sk   # enroll (touch + PIN)
ssh -i ~/.ssh/id_ed25519_sk youruser@host          # login (one touch)

The key file is a handle, copyable between machines. Use lowercase -i (not -I, which is PKCS#11). Most distro OpenSSH builds already link libfido2; if ssh-keygen reports “no FIDO SecurityKeyProvider”, install libfido2 and point SSH_SK_PROVIDER / SecurityKeyProvider at libsk-libfido2.so.

Going further (NixOS quality-of-life)

The FIDO-based YubiKey-on-NixOS recipes (PAM U2F for sudo/login, LUKS FIDO2 unlock, gpg-agent SSH) bind the FIDO HID usage page (or the OpenPGP card via PC/SC), not the VID/PID, so they apply to the default RS-Key build unchanged. (Recipes that gate on ykman or the Yubico YubiKey reader name need the opt-in VIDPID=Yubikey5 build.) A good walkthrough: Improving QoL on NixOS with a YubiKey. Substitute this device wherever it says YubiKey.

Troubleshooting

• pcsc_scan (or ykman, on the VIDPID=Yubikey5 build) says no reader, or “Failed to connect”: scdaemon (from a prior gpg) is holding the reader exclusively. gpgconf --kill scdaemon, then retry. The disable-ccid + pcsc-shared config above prevents the recurrence.
• ykman does not see the device at all: ykman derives the device purely from the PC/SC reader name, which must contain Yubico YubiKey. The default RS-Key build names the reader RS-Key Security Key, so ykman will not recognize it. Build the opt-in VIDPID=Yubikey5 flavor (reader name Yubico YubiKey RSK OTP+FIDO+CCID) to use ykman (see build.md).
• Everything hangs after heavy USB debugging: the pcscd + scdaemon + kernel USB stack can wedge in a way that surviving pcscd/scdaemon restarts or a re-plug do not clear. A full host reboot does. This is a host-stack quirk, not a firmware issue.
• Verify the reader: pcsc_scan (or opensc-tool -l) should list RS-Key Security Key on the default build (or Yubico YubiKey RSK OTP+FIDO+CCID on the opt-in VIDPID=Yubikey5 build). On that opt-in build, ykman info should report 5.7.4 with all six applications enabled.

Windows host setup

The board enumerates as a composite FIDO HID + CCID device. By default it uses the project’s own RS-Key USB identity 0x1209:0x0001 (pid.codes), with the PC/SC reader name containing RS-Key. The opt-in VIDPID=Yubikey5 interop build instead presents the YubiKey identity 0x1050:0x0407 (other presets: build.md). The two transports have different host requirements on Windows:

FIDO needs nothing: WebAuthn talks to the HID interface directly. CCID needs no driver either — the device is a standard CCID smart card — but the whole card is a single reader carrying several applets (OpenPGP, PIV, OATH, OTP), and only one host program can hold that one reader at a time. That is the crux of the Windows friction below.

Not yet hardware-verified on Windows. The Linux remedy in linux.md is confirmed on real hardware; the steps here mirror it and the cross-platform GnuPG behaviour, but have not been checked on a Windows host. Treat them as a starting point and please report corrections via an issue. (The Linux page carries the tested reference config.)

The single-reader contention (issue #44)

RS-Key presents OpenPGP and PIV on one CCID card, exactly as a YubiKey does. On Windows two different stacks then compete for that one card:

• GnuPG’s scdaemon claims it to drive the OpenPGP applet (Kleopatra, gpg --card-status).
• The Windows PIV minidriver (and any PKCS#11 layer such as OpenSC/ykcs11) claims the same card to drive the PIV applet.

Because a smart-card SELECT switches the whole card between applets, two stacks talking at once stomp on each other’s selection. The visible symptoms in issue #44 — Kleopatra showing the device as two cards, a PIV error that then makes the OpenPGP keys look gone, and PicoForge unable to reconnect until you unplug and re-plug — are this host-side arbitration, not a fault on the card. The keys are never lost: OpenPGP clears only its PIN-verified state on an applet switch (spec-required, same as a YubiKey), and re-selecting the card shows them again.

Reducing the contention

There is no driver to install. The fixes are arbitration hygiene:

1. One PC/SC app at a time. Close PicoForge (and any other tool that opened the card) before using Kleopatra/gpg, and vice-versa. If a tool wedges and will not reconnect, unplug and re-plug the board — this clears the held reader handle.

2. Let scdaemon share the reader. By default scdaemon can grab the reader exclusively and lock out other tools. Route it through the Windows Smart Card service and let it share. Edit (create if absent) %APPDATA%\gnupg\scdaemon.conf:

   pcsc-shared
   disable-ccid
   

   Then reload it from a terminal:

   gpgconf --kill scdaemon
   

   pcsc-shared is the key line (share the reader instead of taking it exclusively); disable-ccid forces scdaemon onto the Windows PC/SC stack rather than its own internal CCID driver. Re-plug the board afterwards.

3. Prefer one PIV path. For PIV, either the native Windows minidriver or OpenSC/ykcs11 (PKCS#11) — not both against the card at the same moment. If OpenSC and GnuPG clash, drive PIV through ykcs11 and keep OpenPGP in Kleopatra, one operation at a time.

FIDO / SSH (ed25519-sk)

FIDO uses the HID transport and the built-in webauthn.dll; no PC/SC, no scdaemon, so none of the contention above applies. OpenSSH for Windows enrols and authenticates directly:

ssh-keygen -t ed25519-sk -f %USERPROFILE%\.ssh\id_ed25519_sk
ssh -i %USERPROFILE%\.ssh\id_ed25519_sk user@host

See ssh.md for the WebAuthn/OpenSSH details.

Troubleshooting

• Kleopatra shows two cards / a serial unrelated to the PIV one: expected — one physical card surfaced through two host stacks (OpenPGP via scdaemon, PIV via the minidriver). Recent firmware aligns the OpenPGP card serial with the device serial the other applets report; older firmware showed a divergent OpenPGP serial.
• PIV certificates unusable / signing “pending” under CAPI (CryptoAPI): the Windows PIV minidriver enumerates the card’s containers from its CHUID. Recent firmware serves a default CHUID automatically, so a freshly flashed card is usable; on older firmware, provision one with ykman piv objects generate chuid. (The RSA/EC signing itself is unaffected — it matches a real YubiKey byte-for-byte.)
• PicoForge / a PC/SC tool cannot connect until re-plug: another program is holding the single reader. Close it (PicoForge, Kleopatra, a stray gpg), or unplug and re-plug. gpgconf --kill scdaemon releases a gpg-held handle.
• gpg --card-status and another PC/SC tool cannot coexist: apply the pcsc-shared + disable-ccid config above, then gpgconf --kill scdaemon.
• ykman does not see the device: ykman matches on the PC/SC reader name containing Yubico YubiKey, which the default RS-Key build does not present. Build the opt-in VIDPID=Yubikey5 flavor (reader name Yubico YubiKey RSK OTP+FIDO+CCID) to use ykman (see build.md).

rsk — the device CLI

rsk is the host-side command-line tool for an RS-Key. It consolidates every day-to-day and production task into one command: device status, seed backup, secure-boot provisioning, OTP fuses, FIDO2 management, OpenPGP reset, audit verification, fleet inventory, offboarding. It talks to the device directly: CTAPHID over hidapi for the FIDO interface, and the CCID applets over PC/SC.

It is the canonical interface. The terminal cockpit (rsk-tui) is a read-mostly companion that points you back here for anything irreversible, and PicoForge is a third-party desktop GUI over the same device-config surface (protocol.md §11) for anyone who would rather click than type — it is not part of this repo. Most other guides in this section assume rsk is on your PATH and show the exact rsk <group> … command for the task.

flowchart LR
    cli["rsk (host CLI)"] -->|hidapi / CTAPHID| fido["Device — FIDO<br/>backup · audit · lock · attestation"]
    cli -->|PC/SC / pcscd| ccid["Device — CCID applets<br/>OpenPGP · PIV · OATH · rescue"]
    cli -->|USB BOOTSEL / picotool| boot["Device — bootloader<br/>secure-boot · OTP fuses"]

Running it

In the Nix dev shell, rsk is already on PATH with every dependency pinned:

nix develop
rsk status            # FIDO getInfo + secure-boot + backup state
rsk --help            # all command groups
rsk <group> --help    # a group's subcommands and flags

Without Nix

rsk also runs on any host with Python ≥ 3.9, packaged at tools/. With uv (no install step, an ephemeral environment), from the repo root:

uvx --from ./tools rsk status
uvx --from ./tools rsk --help

Or install it as a persistent tool, so plain rsk is on your PATH:

uv tool install ./tools        # then: rsk status
pipx install ./tools           # or pipx
pip install ./tools            # or a venv + pip

Two dependencies wrap system libraries: hidapi (the CTAPHID transport) and pyscard (PC/SC, for the CCID applets). macOS ships both frameworks and the wheels work out of the box. On Linux install pcsclite and run pcscd for the CCID half, plus udev rules for non-root HID. The full setup and the Apple-Silicon pyscard rebuild note are in tools/README.md and Linux host setup.

The Nix shell stays the primary, reproducible path (it also carries picotool, ykman, gpg, and the test suites). The uv/pip path is for hosts without Nix.

Command groups

Note the two distinct “OTP“s: rsk otp burns the device’s at-rest master key into RP2350 one-time-programmable fuses (a production ritual). The Yubico-style OTP slots feature (touch-to-type codes) is a runtime applet managed with ykman. They share a name, not a mechanism.

Conventions

These hold across the whole CLI, so each group’s guide does not repeat them.

Entering a PIN

Every command that needs the FIDO2 clientPIN accepts it the same way: pass --pin <value> for scripting, or omit it and rsk prompts interactively (hidden input). You never have to remember which form a given command supports.

rsk backup export --pin 1234     # explicit, for scripts / CI
rsk backup export                # prompts:  FIDO2 PIN:

The prompt is only shown when the device actually has a clientPIN set. A touch-only key is never asked, so the plug-and-touch flow is unchanged. If stdin is not a terminal (a pipe) and no --pin was given, rsk skips the prompt and lets the device report device requires a PIN rather than hanging. The PIN-gated commands are:

• backup export / backup restore
• audit log / audit verify
• lock enable / lock disable
• inventory verify
• fido list-passkeys, fido attestation import / clear
• fido set-pin: --pin is the current PIN when changing. --new-pin sets the new one (prompted, with confirmation, if omitted)

This is always the FIDO2 clientPIN (the one rsk fido set-pin manages), never an OpenPGP PW1/PW3 or a PIV PIN. Those are entered only in their own tools (gpg, ykman).

Touch

Operations that release or sign over a secret require a physical touch: a press of the BOOTSEL button while the LED blinks, within a 30-second window. rsk prints touch the device … to stderr before blocking. Touch-gated commands include backup export/restore/finalize, audit verify, inventory verify, lock enable/disable, and fido attestation import/ clear. Read-only commands (status, inventory list, */status) need no touch. audit log needs one only on a device with no PIN (the PIN token gates it otherwise).

One press approves one operation. Consent is per-operation, so a press is spent the moment the ceremony it approved returns. Holding the button through a second prompt does nothing: lift your finger and press again. This matters because requests from every transport are serialised, so a browser, gpg and ykman can queue behind each other — without the rule, one long hold would approve whatever ran next. The touch window is 30 seconds by default and never shorter than 10, even if the device config asks for less.

Machine-readable output

status and inventory list take --json for scripting: a stable object you can pipe to jq. Everything else is human-formatted text.

rsk status --json | jq '.serial, .secure_boot, .fido.clientPin'
rsk inventory list --json        # one JSON object per connected key, per line

Irreversible actions

Destructive or fuse-burning commands (offboard, secure-boot, otp, lock enable, openpgp reset) require a typed confirmation: you type an exact token (e.g. LOCK-SEED) rather than pressing a single key. Anything else aborts. The OTP and secure-boot rituals burn one-time-programmable fuses and cannot be undone. Read Production setup before running them.

Errors and exit codes

On failure rsk prints error: <message> to stderr and exits non-zero (1), so it composes in scripts. A device-reported status is surfaced with its CTAP code where it helps (e.g. a wrong PIN, a sealed export window, a missing OTP DEVK) instead of a bare stack trace.

Where next

• A linear first-run walkthrough: Quick start.
• The read-mostly TUI companion: Terminal cockpit.
• Each task in depth via the Command groups table above.

For contributors

The CLI lives in tools/rsk/: one module per group, each exposing a register(sub) that adds its argparse subparser, wired together in __main__.py. Shared helpers (error exit, the --pin flag + PIN resolution, the picotool runner, the FIDO HID connect) live in common.py. The raw CTAPHID transport and CBOR codec are in ctaphid.py.

PIN entry goes through one chokepoint, common.resolve_pin (flag-or-prompt) and common.add_pin_arg (the shared flag), so consistency is structural, not per-command discipline. The pure-logic unit tests need no device:

# from tools/ (or: uv run --extra test python -m pytest …)
nix develop -c bash -c 'cd tools && python -m pytest rsk/'

Host-tool changes like these do not bump the firmware bcdDevice. See Versions.

FIDO2 / WebAuthn / U2F

The FIDO half of the device: passkeys, two-factor security-key logins, and legacy U2F. It speaks CTAP2 (FIDO_2_0) and CTAP1 (U2F_V2) over the HID interface, so standard WebAuthn browsers and OS dialogs drive it without extra software. It passes the FIDO Alliance Conformance Tools clean (CTAP2.3 235/0, U2F 55/0, a self-run pass, not a paid certification; see testing). What has been checked against real client software is in the interop matrix.

The default build enumerates as “RS-Key”, its own USB identity (0x1209:0x0001, the pid.codes FOSS VID), not a YubiKey one (build.md). FIDO clients don’t care: browsers, python-fido2, and libfido2 bind the FIDO HID usage page, not the VID/PID, so everything on this page works regardless of USB identity. The one exception is ykman, which gates on a “Yubico YubiKey” reader name and so needs the opt-in VIDPID=Yubikey5 interop build (build.md). The reported firmware version is 5.7.4, which is what FIDO tooling reads back. It is a build constant, not the RS-Key release.

Touch is always required

On the default (touch) build every FIDO operation needs a press of the BOOTSEL button: both registration (makeCredential) and login (getAssertion). The firmware’s user-presence bit is implicitly true and it does not honour a request to skip it. WebAuthn userVerification/up cannot turn the touch off, and OpenSSH’s -O no-touch-required is silently ignored on this device. A “no-touch” SSH key still asks for the touch at login. The LED tells you when the device is waiting. See led.md for the colours. A request times out after no touch (the browser shows its own timeout UI). No button wired on a custom board means presence confirms instantly.

Set a PIN first

rsk fido set-pin            # set, or change once one exists
ykman fido access change-pin   # the same operation via ykman (needs the VIDPID=Yubikey5 build)

The clientPIN gates credential creation once it exists. It unlocks anything a site requests user verification (UV) for. Rules from the firmware:

After 3 wrong attempts in a single power cycle the device returns PIN_AUTH_BLOCKED (0x34) and refuses more PIN entry until you unplug and re-insert it. The 8-attempt budget is the across-power-cycle hard limit.

“Power cycle” means a real one. Both the block and the count of wrong attempts that arms it are held in a register a warm reset preserves and only a power-on reset clears, so a host that reboots the device — which it can do without any credential — cannot restart the batch and walk through the 8-attempt budget unattended.

The retry counter resets on a correct PIN. There is no PUK or admin override: once it is locked, the only way back is ykman fido reset, which wipes everything and has to run within ten seconds of a replug (see Factory reset). rsk fido set-pin asks for the current PIN when changing, the new one twice, and prints the resulting clientPin state.

Once a PIN is set, registering a passkey refuses to run without it (CTAP PUAT_REQUIRED, 0x36). The browser collects the PIN and retries. That is expected, not a fault.

Registering a plain second-factor credential (non-discoverable, what a site asks for with userVerification: "discouraged") needs only a touch, PIN or no PIN — the CTAP 2.1 makeCredUvNotRqd option, as on a YubiKey. Sites that want the PIN on every registration ask for UV, and ykman fido config toggle-always-uv (or the always-uv build) forces it device-wide.

Passkeys (resident / discoverable credentials)

Register on any site offering a passkey or “security key” method. The browser drives the device. You touch the button when the LED pulses. These are stored on the device and surface at login without the site sending an allow-list.

Capacity: 256 resident passkeys (and 256 relying parties), flash-bound. When the store is full, makeCredential returns KEY_STORE_FULL (0x28) and the browser reports the key is out of space. Delete some first.

Inspect and clean up (PIN required, credentialManagement is PIN-gated):

rsk fido list-passkeys              # relying parties + user handles + free slots
ykman fido credentials list        # same, via ykman (needs the VIDPID=Yubikey5 build)
ykman fido credentials delete <id>  # remove one (same build; browsers expose this too)

rsk fido list-passkeys prints the existing count and remaining slots, then each relying party with its user names and a credential-id prefix. There is no rsk-native delete yet. Use ykman or the browser/OS passkey manager for that.

credProtect. A site can mark a passkey UV-required (credProtect level 3). The firmware then hides it from discovery and from exclude-list checks until you verify with the PIN, so it never leaks its existence to an unauthenticated caller. RS-Key applies a credProtect level only when the relying party asks for one. It does not silently force a default.

Second-factor registrations (non-resident)

The classic security-key flow (GitHub, Google, GitLab, …) stores nothing on the device. The credential is derived deterministically from the master seed and handed back as an opaque id the site presents at login. This path is effectively unlimited (it costs no flash). The registrations survive a seed backup → restore onto a new board: the same derivation on the same seed reproduces the same keys.

Legacy U2F (CTAP1, U2F_V2) works the same way for older 2FA setups: the register/authenticate pair is non-resident, with a monotonic signature counter, attested by the device’s end-entity certificate.

Signature counters

Every assertion carries a signature counter, the tripwire a relying party watches for a cloned key. RS-Key keeps one per resident credential: a passkey starts at 0 and only its own logins advance it, so colluding sites can’t read a shared global counter to gauge how much you use the key elsewhere (WebAuthn §6.1.1). A non-resident second-factor credential stores nothing on the device, so it reports 0. Legacy U2F keeps the single monotonic counter that protocol expects.

Upgrading an existing key is forward-safe for passkeys: each seeds its counter from the old global value on first use, so the reported number never counts backwards.

Advertised algorithms

getInfo advertises these COSE algorithms. A relying party picks one in its pubKeyCredParams:

RS-Key selects the first supported algorithm a site offers, so put your preferred curve first in the list.

The curve-explicit COSE ids (-9 ESP256, -19 Ed25519, -51 ESP384, -52 ESP512) are accepted too, and a credential comes back stamped with the id the site asked for — offer only -9 and the attested key says -9, not -7. They name the same curves and the same keys as the classic spellings; only the label differs. They are not advertised in getInfo, like -8, -47 and the ML-DSA ids: a host that knows to ask gets them, and one that reads the advertisement offers a classic spelling instead. A YubiKey refuses all four — we are deliberately wider here.

Post-quantum credentials

The device implements all three FIPS 204 parameter sets — ML-DSA-44 (COSE -48), ML-DSA-65 (-49) and ML-DSA-87 (-50) — for makeCredential and getAssertion. They obey the same first-supported rule as everything else, so a site that wants one lists it before its classic fallback. Nothing mainstream requests them yet. A client that does (e.g. a python-fido2 script offering -50) gets a PQC credential today. All three are backed by the in-tree, stack-optimized rsk-mldsa implementation, which streams the FIPS 204 matrix A on the fly so even ML-DSA-87’s 2592-byte key and 4627-byte signature fit the RP2350 stack.

The getInfo advertisement is build-gated behind advertise-pqc (build.md) because shipped Firefoxes (authenticator-rs before 2026-06-02) hard-fail the whole getInfo parse on an unknown COSE id. The capability is always on. Only the advertisement is opt-in, and it lists the three sets in descending security order: ML-DSA-87 (-50), ML-DSA-65 (-49), ML-DSA-44 (-48).

Extensions supported

getInfo advertises seven extensions:

Enterprise attestation is supported but off until enabled. The ep option flips to true once an org key is installed. See attestation.md.

Factory reset

ykman fido reset            # needs the VIDPID=Yubikey5 build; or any WebAuthn "reset security key" UI

Wipes all FIDO state: resident passkeys, the PIN, and the master seed (so all derived non-resident credentials and U2F registrations die too). It regenerates a fresh identity and signature counter. The OpenPGP / PIV / OATH applets are untouched: each applet’s reset wipes only its own files, and a FIDO reset deliberately steps around them even where the file ids interleave.

Replug the key first. The wipe is gated by a physical touch and by the CTAP 2.1 §6.6 power-up window: the firmware accepts authenticatorReset only within 10 seconds of the key attaching to USB. Later than that it answers CTAP2_ERR_NOT_ALLOWED (0x30) straight away, before asking for the touch, and the host tool reports the reset as failed. So the flow is: unplug, plug back in, run the reset, touch within ten seconds.

Two details that catch people out:

• A software reboot does not reopen the window — it closes it. A host can ask the device to reboot without any credential (rsk reboot, a phy config write), so a window a host could restart at will would be no protection. Pull the key out.
• Trusted-display builds are exempt. There the prompt names the operation on screen, so the window is not what stands between you and an accidental wipe; the reset works whenever you confirm it on the panel.

The flash wipe is bounded: if storage keeps reporting a record after a successful delete, reset returns CTAP2_ERR_OTHER instead of staying in the processing state indefinitely.

rsk offboard handles this for you: it sends the reset, and only if the device refuses does it prompt for the replug and retry.

Troubleshooting

• “device not eligible / already registered”. Expected: the site sent an exclude-list matching a credential already on the device.
• “PIN required” / repeated PIN prompts at registration. A PIN is set and the site is registering a passkey, so makeCredential needs it (PUAT_REQUIRED 0x36). Enter it. If you have forgotten it, only a reset clears it — replug first.
• The reset fails immediately with CTAP2_ERR_NOT_ALLOWED (0x30), without ever asking for a touch. The key was plugged in more than ten seconds ago. Unplug it, plug it back in, re-run. A rsk reboot does not count: only a real power cycle opens the window.
• A site demands UV but you have no PIN. Set one (rsk fido set-pin); UV on this device means the FIDO PIN.
• “no space” / store-full at registration. 256 resident passkeys is the cap (KEY_STORE_FULL 0x28). Delete some with ykman fido credentials delete (needs the VIDPID=Yubikey5 build) or your browser/OS passkey manager.
• rsk fido … says “missing dependency: python-fido2”. Run rsk from inside nix develop. The management commands need the python-fido2 library.
• A “no-touch” SSH key still asks for a touch. By design: the firmware always polls the button (see the top of this page). For the ssh-keygen PIN / touch / resident flags, see ssh.md.
• Linux permissions / the device is invisible to the browser. Udev rules in linux.md.

SSH with FIDO keys (ed25519-sk / ecdsa-sk)

Hardware-backed SSH keys. The private key is generated on the device and never leaves it. The file on disk is only a handle that points at it. Logging in takes one touch (and a PIN, if you ask for one). This is the OpenSSH “security key” (-sk) feature. The device is a FIDO2 authenticator, and RS-Key supports both key types it can use:

Requirements

• OpenSSH 8.2+ for -sk keys (8.3+ to download resident keys with -K).
• A FIDO middleware: distro OpenSSH links libfido2; check with ssh -Q key | grep sk.
• macOS: Apple’s /usr/bin/ssh ships without FIDO support and fails with Permission denied before touching the device. Use Homebrew OpenSSH:

  brew install openssh
  export PATH="/opt/homebrew/opt/openssh/bin:$PATH"   # ahead of /usr/bin
  

• Linux: OpenSSH links libfido2 almost everywhere; you only need the FIDO udev rules (see linux.md). FIDO is local to wherever ssh runs, so logging in to a remote box needs nothing special there.
• Windows: OpenSSH for Windows routes -sk keys through the Windows WebAuthn API (webauthn.dll), which only offers algorithms the device advertises in its FIDO getInfo. ed25519-sk needs firmware that advertises EdDSA: RS-Key bcdDevice 0x077D or newer (see rsk status). On older firmware ed25519-sk fails at create with a generic error while ecdsa-sk still works, so either reflash or use ecdsa-sk. macOS and Linux talk to libfido2 directly and send the algorithm regardless, so they are unaffected.

Enroll

ssh-keygen -t ed25519-sk -f ~/.ssh/id_ed25519_sk -C "you@laptop"
# → enter the FIDO PIN if one is set, then touch the button

The -C comment is free text that ends up in the .pub and on the server. It is handy for telling keys apart. Two files appear:

• id_ed25519_sk: the handle. Not a private key; useless without the physical device. Copy it (and the .pub) to every machine you ssh from. The device is the second factor, the file is just a pointer.
• id_ed25519_sk.pub: the public key, for authorized_keys.

Then install it on a server:

ssh-copy-id -i ~/.ssh/id_ed25519_sk.pub you@server
ssh -i ~/.ssh/id_ed25519_sk you@server      # one touch

Enrollment options (-O)

Pass -O flags at ssh-keygen time to shape the credential:

# PIN on every login, and store the key on the device:
ssh-keygen -t ed25519-sk -O resident -O verify-required \
    -O application=ssh:work -f ~/.ssh/id_work_sk

no-touch-required does nothing useful on RS-Key. The default (touch) build always polls the button on every assertion. The firmware does not honor up:false. The flag still marks the credential, but you will be asked to touch regardless. The touch is the point; enroll without it.

PIN and touch: what to expect

RS-Key follows the standard FIDO2 flow, the same as a YubiKey: the PIN unlocks a session token silently (no touch for the PIN itself), and then each operation takes one touch.

* You only touch twice at enrollment when several FIDO devices are plugged in at once: the first touch is a CTAP “selection” gesture (which key did you mean?), the second authorizes the key creation. With one device connected it is a single touch.

So a single login asks for the PIN at most once. If you ever see the PIN prompt twice in one action, two separate operations are running. Usually the key is offered by both ssh-agent and an IdentityFile (add IdentitiesOnly yes), or git push opened two SSH channels (use ControlMaster / ControlPersist, see the git guide). A real YubiKey behaves identically in those setups. It is the client, not the device.

Resident (discoverable) keys

-O resident stores the key handle on the device itself, so you can recover it onto any machine later instead of carrying the file:

ssh-keygen -K                      # download handles into the current dir (PIN)
# → writes id_ed25519_sk_rk[...]  and the matching .pub
ssh-add -K                         # load resident keys straight into the agent
rsk fido list-passkeys             # see what's stored on the device

Resident keys cost one of the device’s 256 discoverable-credential slots. For most people the non-resident default plus a seed backup is better: non-resident keys are re-derivable from the seed, so a restored board logs in with the same handle files. No slot used, nothing to download. Reach for resident keys when you want to walk up to a fresh machine with only the device in your pocket.

ssh-agent and ~/.ssh/config

Add the key to the agent so you are not retyping -i:

ssh-add ~/.ssh/id_ed25519_sk       # non-resident: add the handle file
ssh-add -K                         # resident: pull from the device
ssh-add -l                         # list loaded keys

A config block makes plain ssh host use the right key (and the Homebrew binary on macOS):

# ~/.ssh/config
Host server
    HostName server.example.com
    User you
    IdentityFile ~/.ssh/id_ed25519_sk
    IdentitiesOnly yes

IdentitiesOnly yes stops the agent from offering every other key first. Worth it so each connection prompts for exactly one touch.

Server side

The .pub goes in ~/.ssh/authorized_keys like any key. You can also pin requirements there, independent of how the key was enrolled:

# authorized_keys — require the FIDO PIN for this key (touch is omitted = required)
verify-required sk-ssh-ed25519@openssh.com AAAA... you@laptop

sshd enforces verify-required from OpenSSH 8.4+; older servers accept the key but skip the check. A key enrolled verify-required always asks for the PIN on the client regardless of the server. (Adding no-touch-required here would relax the touch requirement, but RS-Key touches anyway, as above.)

Signing git commits

The same key signs git commits and tags (no GPG needed). See the git guide. The short version:

git config gpg.format ssh
git config user.signingkey ~/.ssh/id_ed25519_sk.pub
git config commit.gpgsign true     # one touch per commit

Using the OpenPGP AUT slot instead

If you already run an OpenPGP key on the card, its authentication subkey doubles as an SSH key via gpg-agent, a different path that needs no -sk support in the client. See openpgp.md (gpg --export-ssh-key, enable-ssh-support).

Troubleshooting

• Permission denied instantly on macOS → you are on /usr/bin/ssh; use the Homebrew binary (above).
• Key enrollment failed: requested feature not supported → the client lacks ed25519-sk middleware; install libfido2 / Homebrew OpenSSH, or fall back to -t ecdsa-sk.
• device not found / no prompt → FIDO udev rules missing (linux.md), or a browser / gpg-agent is holding the device; close it and retry.
• Asks for a PIN you never set → some client builds require a PIN to enroll; set one with rsk fido set-pin and retry.
• sign_and_send_pubkey: signing failed on login → the wrong device is plugged in, or the key is resident on a device you reset. Re-plug the right key, or ssh-add -K again.
• After a factory FIDO reset, old id_*_sk files stop working. The seed they derive from is gone. Re-enroll, or restore the seed first so the same handles work again.

Git with the device

Two jobs you do with git and a hardware key: sign your commits and tags, and authenticate to push, pull, and clear the forge’s 2FA / “confirm access” challenges. The same RS-Key handles both. They are just different credentials on it. Signing comes first. Authentication and 2FA are at the end.

Signing keeps the key off the disk and takes a touch per signature. It has two flavours. RS-Key supports both:

If you have no GPG setup and just want verified commits, use SSH signing. It is the smaller path. If you already keep a GPG identity, use OpenPGP.

SSH signing

Point git at your -sk public key and turn signing on:

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519_sk.pub
git config --global commit.gpgsign true     # sign every commit
git config --global tag.gpgsign true        # sign every tag

Now git commit asks for one touch. Drop --global to scope it to a single repo (handy if only some repos should be signed by the device).

git commit -m "…"          # touch the device when the LED blinks
git log --show-signature   # see the signature on each commit

Verify locally

Verification needs an allowed_signers file mapping identities to public keys:

mkdir -p ~/.config/git
echo "you@example.com namespaces=\"git\" $(cat ~/.ssh/id_ed25519_sk.pub)" \
    >> ~/.config/git/allowed_signers
git config --global gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers

git verify-commit HEAD              # "Good \"git\" signature for you@example.com"
git log --show-signature -1

Without that file git can make signatures but reports every commit as “No signature” on verify. That means the file is missing, not a bad signature.

On GitHub / GitLab

Add the same .pub as a Signing key. On GitHub this is a separate entry from an authentication key (Settings → SSH and GPG keys → New SSH key → Key type: Signing Key). Commits then show as Verified. Turn on vigilant mode (GitHub) to flag any unsigned commit on your account as Unverified.

OpenPGP signing

First put a signing-capable key on the card and learn its key id. See openpgp.md. Then:

git config --global gpg.format openpgp        # the git default; set it explicitly
git config --global user.signingkey 0xLONGKEYID
git config --global commit.gpgsign true
git config --global tag.gpgsign true
# if gpg isn't found by name on your platform:
git config --global gpg.program $(command -v gpg)

git commit now goes through gpg → scdaemon → the card: the User PIN once per session, then a touch per signature if the SIG slot’s UIF touch policy is on (openpgp.md).

git commit -m "…"
git log --show-signature        # "Good signature from …" via your gpg keyring
git verify-tag v1.0

On GitHub / GitLab

Export the public key and add it as a GPG key (Settings → SSH and GPG keys → New GPG key):

gpg --armor --export 0xLONGKEYID    # paste the block into the forge

The email on a signing UID must match your commit email for the forge to mark it Verified.

Authenticating: push, pull, and 2FA

Signing proves who wrote a commit. Authenticating is how you push, pull, and get past the forge’s security-key prompts. The device does this too, with separate credentials from the signing key.

Push / pull over SSH

The cleanest path: use the device’s -sk SSH key (or the OpenPGP AUT subkey via gpg-agent) as your transport. Add the public key to the forge as an Authentication key. On GitHub this is a separate entry from the signing key (Settings → SSH and GPG keys → New SSH key → Key type: Authentication). Point the remote at SSH, and each connection is a challenge the key answers with a touch:

git remote set-url origin git@github.com:you/repo.git
git push                     # touch when the LED blinks

That is one touch per connection, not per command. To keep a burst of pushes under a single touch, reuse the SSH channel:

# ~/.ssh/config
Host github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_sk
    IdentitiesOnly yes
    ControlMaster auto
    ControlPath ~/.ssh/cm-%r@%h:%p
    ControlPersist 10m         # one touch covers everything in the window

The key setup itself is the SSH guide. Here it just doubles as the git transport.

Push / pull over HTTPS

Over HTTPS git authenticates with a token, not the key. The device isn’t in that path. But it protects the account the token comes from: gh auth login, or signing in to mint a token, triggers the 2FA challenge below, which a tap clears.

Account 2FA and “confirm access” challenges

The forges require 2FA and re-challenge for sensitive actions: signing in on a new machine, changing keys, deleting a repo (GitHub calls this sudo mode). Register the device once and a tap answers every such prompt:

• GitHub: Settings → Password and authentication → add a Passkey (one tap, no password) or a Security key (second factor).
• GitLab: Settings → Account → enable a WebAuthn Device.

A passkey is a resident credential. It costs one of the device’s 256 discoverable slots (ssh.md). A security key 2FA credential is non-resident. Either way the browser shows “use your security key”, you touch, and the challenge clears.

One device, three jobs: a signing key for commits, an SSH auth key for push/pull, and a passkey / 2FA credential for the account. Three independent credentials on the same RS-Key, each its own touch.

Living with the touch

Every signature is one touch. That is the security benefit (malware can’t sign in the background), but it adds up on a rebase that re-signs many commits.

• SSH signing always touches. There is no caching. For a big rebase, sign the final result rather than every intermediate commit, or temporarily set commit.gpgsign false for the rebase and re-sign at the end.
• OpenPGP caches the PIN (via gpg-agent, default-cache-ttl), but the touch still happens per signature when UIF is on. Turn UIF off on the SIG slot if you want PIN-only signing (weaker: any process with the cached PIN can then sign).
• git commit --no-gpg-sign skips signing for a one-off commit.

Troubleshooting

• error: gpg failed to sign the data (SSH mode) → gpg.format isn’t ssh, or user.signingkey points at a missing file. Re-check both.
• git verify-commit says “No signature” but the commit is signed → the allowed_signers file isn’t configured (above).
• OpenPGP: No secret key / selecting card failed → scdaemon lost the reader (often after ykman/another tool grabbed it): gpgconf --kill scdaemon and retry. On Linux apply the linux.md scdaemon settings.
• Commits show Unverified on the forge → the signing key/GPG key isn’t added to your account, or the commit email doesn’t match the key’s identity.
• git push says Permission denied (publickey) → the authentication key isn’t on the forge (it is a separate entry from the signing key), or the remote is HTTPS not SSH. Check with git remote -v and ssh -T git@github.com.
• The device never prompts for a touch → another process is holding it (a browser, gpg-agent, the TUI). Close it and retry.

OpenPGP card

A full OpenPGP card 3.4 over CCID: three key slots (signature, decryption, authentication), works with stock GnuPG. The same slots cover commit signing, SSH login (via gpg-agent), and end-to-end mail/file encryption.

Prereqs: on Linux, pcscd + the scdaemon.conf lines from linux.md. Check the card is visible:

gpg --card-status            # reader: RS-Key Security Key …, OpenPGP v3.4

gpg works regardless of the reader name. scdaemon identifies the card by its ATR and applet SELECT, not the USB identity. The default build reports the reader as “RS-Key”; the opt-in VIDPID=Yubikey5 flavor reports it as “Yubico YubiKey” (build.md).

PINs

Those columns are exclusive: the admin PIN authorises no key operation. It cannot sign, decrypt or authenticate, however recently it was entered — that is the card spec’s rule and what a YubiKey does. (Earlier RS-Key builds let PW3 stand in for PW1 here. If you have a script that unlocks signing with the admin PIN, it needs the user PIN now.)

The same split governs the four private-use data objects: 0101 and 0103 are the cardholder’s and open to the user PIN, 0102 and 0104 are the admin’s. There is no admin override on the cardholder’s pair — 0101 and 0103 answer 6982 to PW3, as a YubiKey does. (Earlier RS-Key builds took the admin PIN on those two as well; a script that stashes data there needs the user PIN now.)

The card enforces those lengths itself: a CHANGE REFERENCE DATA or RESET RETRY COUNTER carrying a new value outside the range is refused with 6985, whatever the host’s own policy is. gpg applies the same ≥ 6 / ≥ 8 minima before it ever reaches the card. A shorter reference stored by an older firmware keeps verifying; only new ones are checked.

A verify of a value outside the range is refused the same way, with 6A80 — and it costs no retry and leaves an already-entered PIN standing, because a password the reference could not be is a malformed request rather than a wrong guess. On a card still holding a legacy out-of-range reference the check is off, so that reference stays verifiable.

A fresh card has no Reset Code. It stays deactivated until an admin sets one (passwd option 4, below), so RESET RETRY COUNTER in its RC form cannot run against a known default.

Each PIN has its own retry counter, default 3. Every attempt is charged against it before the card compares anything, and a correct entry gives the charge back; a wrong one keeps it. The one visible consequence: pulling the key out mid-VERIFY can cost a try the holder never used. That is the safe direction — charging afterwards would mean an interrupted write leaves a wrong guess free, and this counter is the only limit the card has. gpg --card-status prints them as PIN retry counter : 3 3 3 (PW1, RC, PW3: all three default to 3).

Change them first:

gpg --card-edit
gpg/card> admin
gpg/card> passwd            # menu: 1 change PW1 · 3 change PW3 · 4 set Reset Code

The same menu sets the Reset Code (option 4, under admin), which lets a holder who has forgotten PW1 reset it without the admin PIN. Useful when the admin PIN lives somewhere offline.

Two ways admin operations lock:

• Three wrong PW3 blocks the admin PIN. Unlike PW1, the admin PIN has no higher authority to unblock it. Recovery is a factory reset of the applet (below). Plan to keep PW3 written down somewhere offline.
• Three wrong PW1 blocks the user PIN. This one is recoverable: unblock it with the admin PIN or the Reset Code (see Unblocking PW1).

Generate keys on-card

gpg --card-edit
gpg/card> admin
gpg/card> key-attr           # per slot, pick the algorithm (table below)
gpg/card> generate           # makes all three keys + a gpg keyring entry

key-attr is asked once per slot (signature, then encryption, then authentication), so you can mix: e.g. Ed25519 for signing and authentication, Cv25519 for encryption (gpg’s default modern pair), or RSA across the board.

Supported per-slot attributes (advertised via DO 0xFA, the list ykman and gpg read back):

Changing a slot’s algorithm after a key exists invalidates that slot’s old private/public key pair. Re-select the intended attribute before generating or importing the replacement; writing the same attribute leaves the key intact.

RSA-1024 is advertised and it works — a YubiKey does not offer it at all. It is below every current guidance (NIST SP 800-131A retired it in 2013) and it is here only so a key generated under an older build keeps working. Do not pick it for a new key.

Not supported: X448, Ed448 and brainpoolP512r1. gpg will offer them; the card advertises none of the three in DO 0xFA and refuses the key-attr write with 0x6A80, so a slot cannot end up announcing a curve it will not use. No mature no_std Rust arithmetic exists for those yet, so shipping them would mean unaudited curve math.

On-card generation means the private keys never existed anywhere else, and cannot be backed up. gpg’s “make an off-card backup” prompt covers the encryption key only, and only if you say yes. (A lost signing or authentication key is regenerated, not recovered.) RSA generation is slow on this hardware. The firmware races both RP2350 cores for the two primes and streams CCID keepalives while gpg waits:

The spread is wide because the prime search is random. RSA-4096 has been seen anywhere from ~17 s to ~120 s on the same board. See ../limitations.md for the measured dual-core numbers. EC is the pragmatic default unless a peer needs RSA.

Or import existing keys

If you already have a GnuPG key (and want a recoverable off-card copy), import the subkeys instead of generating:

gpg --expert --edit-key YOURKEY
gpg> toggle                  # show secret subkeys (ssb)
gpg> key 1                   # select the subkey to move (repeat per subkey)
gpg> keytocard               # pick the matching slot: 1 sig · 2 enc · 3 auth
gpg> save

keytocard moves the selected subkey onto the card, replacing the on-disk copy with a stub that points at the device. Set key-attr to match the incoming key’s algorithm before keytocard, or the card refuses the import. The size counts as much as the family: a 2048-bit key offered to a slot announcing RSA-4096 is refused, because the attribute is what gpg --card-status and every other host reads back as the truth about that slot. A mismatched algorithm/curve/size returns “Wrong data” / “Function not supported” and a missing admin (PW3) session returns “Security status not satisfied”. gpg surfaces one of these as a card refusal.

Importing keeps an off-card copy in your keyring until you delete it. Your call which way the trade-off goes. The usual recoverable setup: generate the master key offline, move only the three subkeys to the card, and store the master key material on encrypted offline media.

The card records which way each slot was filled and reports it in DO 0xDE, because that is the difference between a key that can only exist here and one that has a copy somewhere. A slot filled by a build older than this one, or one whose GENERATE lost power partway, reads as imported: the card will not claim on-card generation it cannot prove. Generate into the slot again if you want the stronger claim back.

Daily use

Signing and decryption

echo hi | gpg --clearsign                 # PW1, then a touch if UIF is on
gpg --encrypt -r alice@example.com file    # public-key op, no card needed
gpg --decrypt file.gpg                     # PW1 (PW2), card does the ECDH/RSA

gpg drives the slots automatically: the SIG slot signs, the DEC slot decrypts. Encryption to a recipient is a public-key operation and never touches the card. Only decryption does.

By default PW1 stays valid for the session after the first signature. That session ends when the key is unplugged or another application is selected on the card — a PIV or OATH tool reaching for the same key mid-session does exactly that. Selecting OpenPGP again does not end it (§4.2 spends its rule on “a SELECT to a different DF”), so a tool that re-selects before each command keeps the PIN it already gave. To force a PIN on every signature, flip the PW1 status byte:

gpg/card> admin
gpg/card> forcesig          # toggles "PW1 valid for one signature only"

SSH authentication via gpg-agent

The AUT slot doubles as an SSH key through gpg-agent:

# one-time agent setup
echo enable-ssh-support >> ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

# add the authentication subkey's keygrip to sshcontrol
gpg --list-keys --with-keygrip YOURKEY     # find the [A] subkey's keygrip
echo <KEYGRIP> >> ~/.gnupg/sshcontrol

# export the public key in OpenSSH format and install it
gpg --export-ssh-key YOURKEY > ~/.ssh/id_rsk.pub
ssh-copy-id -f -i ~/.ssh/id_rsk.pub you@server

Then export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket) (in your shell rc) and ssh you@server prompts for PW1 and logs in. This is the standard gpg-agent recipe, nothing device-specific.

For FIDO-backed SSH (ed25519-sk, no gpg) see ssh.md; for signing git commits and tags with the SIG slot see git.md.

Touch policies (UIF)

Each slot has an independent user-interaction flag. When on, every use of that key additionally requires a button press. The firmware polls the BOOTSEL button and fails the operation (0x6600) if it is not pressed in time. PIN alone is no longer enough. A remote attacker holding your unlocked session still cannot sign or decrypt without physical access.

gpg/card> admin
gpg/card> uif 1 on          # 1 sig · 2 enc · 3 auth   (off to disable)
gpg/card> uif 1 permanent   # irreversible: only a factory reset clears it

UIF is per-slot, so you can require a touch for signing but not decryption, or any mix. On a board with no button configured the check is a no-op.

on is revocable with the admin PIN, so it protects against a stolen user PIN, not a stolen admin PIN. permanent (the card’s UIF value 02) cannot be lowered by any command — PUT DATA answers 6985 — so a host that learns PW3 still cannot turn your signatures touchless. Clearing it takes TERMINATE DF + ACTIVATE FILE, which wipes the applet. Set it only when you mean it.

AES encryption (PSO)

The card carries one AES key, in DO D5. It belongs to the card, not to a key slot — the spec names it by the commands it serves, and ENCIPHER uses no key slot at all. The card seeds it as AES-256 the first time you generate an encryption keypair, so the feature works out of the box. Tools that expose the card’s symmetric PSO (e.g. gpg-card) can ENCIPHER / DECIPHER arbitrary block-aligned data with it (raw AES-CBC, zero IV; output is 0x02 || cryptogram). It needs PW1 (PW2). Most users never touch this. Public-key encryption is the normal path.

A host can also supply the key itself, with PUT DATA on DO D5 under the admin PIN: 16 bytes for AES-128 or 32 for AES-256, and no other length.

Once a key is there nothing replaces it but another PUT DATA D5 — generating or importing a keypair leaves it alone, on every slot. There is no way to remove it short of TERMINATE DF + ACTIVATE FILE, which wipes the applet, and the card cannot tell you a key is there: DO D5 is write-only.

Recovery and reset

Unblocking PW1

Three wrong user-PIN tries block PW1 but not the keys. Two ways back:

# with the admin PIN
gpg --card-edit
gpg/card> admin
gpg/card> unblock           # verify PW3, set a new PW1

# or with the Reset Code, if one was set (no admin PIN needed)
gpg/card> passwd            # menu option 2: "unblock PIN" via Reset Code

Both reset PW1’s retry counter and re-seal its key material under the new PIN.

A PIN change interrupted by unplugging the key

Changing a PIN rewrites two things: the PIN’s verifier, and the copy of the key that PIN unwraps. Pull the key out of the port between the two — during gpg --change-pin — and the card reports a memory error.

Since firmware 0x0889 the card finishes the interrupted change itself on the next VERIFY, so there is nothing to do. On an older build the card comes back in a state that looks fatal and is not: the affected PIN verifies, and every operation that needs a key answers “Card error”. Do not factory-reset it.

The card keeps one copy of the key per PIN and only the copy belonging to the PIN you changed was damaged, so the repair is to reach the key through a different PIN. Which one depends on which PIN you were changing, and the two recipes are not interchangeable:

The admin PIN (PW3) was being changed — verify the user PIN first, in the same session, then change PW3 again:

gpg --card-edit
gpg/card> verify            # PW1 — its copy of the key is untouched
gpg/card> admin
gpg/card> passwd            # change PW3 again; the card is repaired

The user PIN (PW1) was being changed — use the admin unblock, and do not verify PW1 anywhere in that session:

gpg --card-edit
gpg/card> admin
gpg/card> passwd            # menu option 1, "unblock PIN" — sets PW1 via PW3

The order matters for a reason worth knowing: the card reaches for PW1’s copy of the key whenever PW1 is verified, ahead of the admin’s. So for a torn PW1 change, verifying PW1 — even with the PIN that now works — puts the damaged copy back in front and the repair fails. unblock never verifies PW1, which is why it is the one that works there.

Factory reset (OpenPGP only)

rsk openpgp reset      # or: gpg --card-edit → admin → factory-reset

rsk openpgp reset blocks both PINs, then drives the spec-compliant TERMINATE (0xE6) + ACTIVATE (0x44) and reseeds factory defaults (PW1 123456, PW3 12345678). It wipes the OpenPGP applet (keys, PINs, DOs, reset code) and nothing else. FIDO / PIV / OATH / OTP survive (the TERMINATE is scoped to the OpenPGP FIDs). This is also the only way out of a PW3 that you have blocked: a blocked admin PIN cannot be unblocked, only reset away, along with the keys it protected. It also works when the admin verifier itself is unusable — a card provisioned by an older firmware with an empty PW3 could otherwise neither verify nor terminate, leaving a device-wide factory reset as the only escape.

It is destructive but idempotent, so it is the clean way to clear non-default PINs a prior gpg session left behind (which otherwise block the test suite at VERIFY).

Troubleshooting

• gpg: selecting card failed: No such device → scdaemon vs pcscd fight; apply linux.md’s disable-ccid, then gpgconf --kill scdaemon.
• ykman stops seeing the device after gpg used it → same fix; gpg’s scdaemon holds the reader. gpgconf --kill scdaemon releases it.
• A card refusal on keytocard / generate (gpg may report “Function not supported”, “Wrong data”, or “Security status not satisfied”) → the slot’s key-attr doesn’t match the key, or you skipped admin (no PW3 session).
• gpg --card-status shows PIN retry counter : 0 … → that PIN is blocked; see Recovery and reset.
• RSA generate seems to hang → it isn’t; on-card RSA keygen takes the times above and gpg shows no progress bar. Wait it out, or use an EC curve.
• ykman openpgp info (needs the opt-in VIDPID=Yubikey5 build: ykman only sees the device when the reader name contains “Yubico YubiKey”) → ERROR: Incorrect TLV length on firmware before 0x0759: the GET DATA 6E reply was missing its constructed-DO wrapper, which ykman’s strict parser requires (gpg tolerated it). Fixed in 0x0759; flash it and re-run. See interop.md.

PIV

A PIV smart-card (NIST SP 800-73-4) over CCID: X.509 client certificates, S/MIME, PIV-aware OS login, SSH and age through PKCS#11. Driven with ykman piv or yubico-piv-tool; the applet also speaks the Yubico extensions (metadata, serial, attestation, move/delete, set-retries) those tools use. ykman piv and yubico-piv-tool gate on the “Yubico YubiKey” reader name, which the default RS-Key build (VID:PID 0x1209:0x0001) does not present. They need the opt-in VIDPID=Yubikey5 interop build (build.md). The PKCS#11 / OpenSC and OS-native (macOS CryptoTokenKit, Windows) routes below identify the card by its applet, not the reader name, so they work on the default build.

Windows note: the card serves a default CHUID automatically — the Windows PIV minidriver needs it to enumerate the certificate containers, so no manual ykman piv objects generate chuid step is required.

Prereqs: on Linux, pcscd plus the polkit rule from linux.md; if you also use GnuPG, the disable-ccid line so scdaemon and pcscd stop fighting over the reader. Check the card is visible (the ykman commands here assume the opt-in VIDPID=Yubikey5 build):

ykman piv info            # PIV version 5.7.4, slot + PIN/PUK/mgmt-key state

Defaults

Change all three before real use:

ykman piv access change-pin
ykman piv access change-puk
ykman piv access change-management-key --generate --protect

--protect stores the new management key on the card, encrypted under the PIN, so ykman can recover it from the PIN alone (no separate hex string to carry). The applet accepts AES-128/192/256 management keys; under the FIPS-style build it refuses to set a new 3DES key, though an existing 3DES key still authenticates so a reflashed device can migrate itself to AES.

PIN protection is per key and does not survive a rotation. Setting a new management key clears the protected flag, so the new key is not PIN-readable unless you opt in again — ykman piv access change-management-key --protect re-writes the flag as part of the same operation, so nothing changes for the command above. It matters if you rotate with anything else (a raw SET MANAGEMENT KEY APDU, yubico-piv-tool): the card then holds a key only the hex string opens, and ykman piv info reports it as not protected. Rotating away from a protected key is also how you revoke that PIN-only access. The flag is cleared only once the new key is stored, so a rotation that fails part-way leaves the escrow describing the key that is still on the card — you are never left holding a PRINTED-only key the card no longer admits to escrowing.

On the panel (trusted-display builds). The PIV PIN and PUK can be changed (and a blocked PIN unblocked with the PUK) on the device, no host needed: Settings → Security → PIV PIN → Change PIN / Change PUK / Unblock PIN. Each verifies the current PIN/PUK against the applet’s own retry counter (shown on the pad) and stores the new value in the 8-byte 0xFF-padded wire form, so a later ykman / yubico-piv-tool VERIFY accepts it.

A 24-byte management key can’t be typed on a numeric pad, so the panel sets a random, PIN-protected one instead: Settings → Security → PIV PIN → Protect mgmt key. The device generates a random AES-256 management key, seals it, and marks it PIN-protected (the ykman --protect scheme), so a host then uses it with just the PIV PIN. ykman piv info shows it as protected and ykman piv operations no longer need the hex key. Security: once protected, the PIV PIN alone grants management access (it unlocks the random key), so treat the PIN accordingly; the panel states this and gates the action behind the device PIN and a hold. (ykman piv access change-management-key --generate --protect installs a random PIN-protected key from the host too.) If you had raised the management key’s touch policy (--touch, below), the panel action keeps it — it replaces the key, not the gate, so admin actions still ask for a press. The host command does not: ykman sends the policy in the command itself and defaults it to off, so re-run it with --touch if you want the gate back.

The panel manages PINs/PUKs that follow the standard PIV convention (6–8 digits, padded to 8 bytes with 0xFF), which is what ykman, yubico-piv-tool and OpenSC all use. Since firmware 0x088A the card refuses to store a value shorter than six bytes at all, so a sub-6-digit reference can no longer be provisioned by any route. A reference stored unpadded by an older build is still possible, and it can’t be verified on the panel; re-set it with ykman first. The factory defaults follow the convention, so the panel works out of the box.

If an older build shortened both the PIN and the PUK, the only way back destroys the keys. Since 0x08D1 a CHANGE REFERENCE DATA / RESET RETRY COUNTER body is sixteen bytes or nothing, so no build can enter this state any more — but a card already in it has no non-destructive exit. A shortened PIN alone is repaired by ykman piv access unblock-pin (the PUK still works), and a shortened PUK alone by ykman piv access set-retries (the PIN still works), both with every key intact. With both shortened, neither repair is presentable: block both counters with wrong guesses and run ykman piv reset, which wipes every PIV key and certificate. The state needed an older build and a host that sent a fourteen-byte reference pair, which no shipped tool emits, so it is unlikely you are here — but if you are, restore the slots from backup after the reset rather than looking for a gentler command.

The defaults are public. Until you change the PIN, PUK and management key, anyone with physical access can generate, import or delete keys. Treat a default-credential card as unprovisioned.

Slots

The signature slot (9c) demands the PIN before every private-key operation; the other slots cache the PIN for the rest of the session after one VERIFY. A session ends when the card loses power or another application is selected on it — an OpenPGP or OATH tool reaching for the same key mid-session does exactly that. Selecting PIV again does not end it (SP 800-73-4 Part 2 §3.1.1), so a tool that re-selects before each command keeps the PIN it already gave. 9e is the exception at the other end: SP 800-73-4 makes the Card Authentication Key the one usable without a PIN, so a default-policy 9e key signs with no VERIFY at all — which is what makes it usable for physical-access and contactless readers. Give it --pin-policy ONCE (or ALWAYS) at generate time if you want it gated like the rest.

Algorithms. On-card generation and import accept RSA-2048 / 3072 / 4096, RSA-1024 (disabled under the FIPS-style build, SP 800-131A), ECC P-256 / P-384, and the Curve25519 pair Ed25519 (signing) and X25519 (key agreement), the Yubico 5.7 PIV algorithm ids 0xE0 / 0xE1, so ykman drives them as --algorithm ED25519 / X25519. An Ed25519 key generates with a self-signed certificate like the other curves; an X25519 key is key-agreement-only and can’t self-sign, so generation writes no auto-certificate (provision one from a CA via ykman piv certificates import). RSA-3072/4096 keygen is slow on this hardware (tens of seconds to a minute-plus).

Generate a key on-card

ykman piv keys generate --algorithm ECCP256 9a pub.pem   # on-card key, public part out
ykman piv certificates generate --subject "CN=me" 9a pub.pem   # self-signed cert into 9a
ykman piv info

Generating in a slot already writes a self-signed certificate into that slot’s certificate object, so a GET DATA serves one immediately even before you run certificates generate. Management-key auth is required to generate.

For a real CA, emit a CSR instead of a self-signed cert:

ykman piv certificates request --subject "CN=me" 9a pub.pem me.csr
# … sign me.csr at your CA, then import the issued cert:
ykman piv certificates import 9a issued.pem

On-card generation means the private key never existed off-device and cannot be exported or backed up. Losing the card loses the key (that is the point). RSA generation is slow on this hardware (RSA-2048 takes 4–6 s on the reference board and about twice that on others, and the prime search is random so run-to-run times vary; the device streams CCID keepalives so the connection stays alive; it is not a hang). See limitations.md for the measured dual-core figures and which board they are from. EC generation is instant.

Or import an existing key

ykman piv keys import 9d existing.pem        # PEM with the private key
ykman piv certificates import 9d existing-cert.pem

Import is management-key gated and also accepts RSA-2048/1024, P-256/P-384 and Ed25519/X25519. An imported key keeps whatever copy you imported it from. Your call which way the trade-off goes. Imported keys cannot be attested (see below): attestation proves on-card generation, which import didn’t do.

PIN and touch policy per key

Both policies are fixed at generate/import time and stored in the slot metadata:

ykman piv keys generate --pin-policy ALWAYS --touch-policy ALWAYS 9a pub.pem

ALWAYS means the VERIFY has to be the last thing before the operation: a private-key operation at any PIN-gated slot uses it up — including one that fails after reaching the key — so VERIFY → sign at 9a → sign at 9c refuses the second signature with 6982. Verify again between them. Nothing else is affected — the PIN itself stays verified, so a 9c signature does not close the ONCE slots, the PIN-protected management key or a plain VERIFY status query, and a NEVER-policy key never uses anything up.

Ask for the press and you get it on every sign / decrypt / ECDH, and a declined touch fails the operation with 6982. Don’t ask, and the key never prompts — which is what makes pkcs11, age-plugin and SSH usable unattended. Raise the management key’s own policy with ykman piv access change-management-key --touch if you want admin actions gated too.

CACHED is treated as ALWAYS. The device has no wall clock, so it cannot honour the 15-second touch cache a real YubiKey offers; it errs strict and asks every time. If you set CACHED, expect ALWAYS behaviour.

Data objects that need the PIN to read

Most PUT DATA objects are readable by anything that can open the reader — that is what SP 800-73-4 pt1 Table 3 says, and a certificate is public anyway. Four are not:

ykman piv objects export 5fc103 - on one of those needs a VERIFY first, or the card answers 6982. The refusal comes before the lookup, so an empty object and a populated one are indistinguishable without the PIN. The management key does not substitute for it: writing these is management-gated, reading them is PIN-gated, and the two are separate conditions.

5FC109 has a second job: it is where a PIN-protected management key is read back from. While protection is on, PRINTED is that escrow and nothing else — the read answers with the key, synthesized from slot 9b, and a write of any other content is refused with 6985 rather than accepted and hidden underneath it. Revoke the protection first (ykman piv access change-management-key without --protect, or set a new key any other way) and it is ordinary storage again. Note that ykman’s own revoke clears PRINTED as its first step, so anything stored there before you turned protection on does not survive the round trip.

The one write the card never keeps is a PivmanProtectedData body — exactly 88 L { 89 L <key> }, what --protect sends — which is acknowledged and dropped, because the key it carries is already sealed in 9b and a second copy would sit in flash in plaintext. The match is on that exact shape, so printed information that merely happens to contain those tags is stored like anything else. One consequence worth knowing: --protect fails on a card that already has other content in PRINTED, because ykman tries to parse it as an escrow record. Clear the object first.

Attestation

ykman piv keys attest 9a attestation.pem

Proves a slot key was generated on-device, not imported. The attestation certificate is signed on-card by the f9 key (a P-384 CA key, self-signed at first boot) and carries the standard Yubico OIDs: firmware version, device serial, and the slot’s pin/touch policy. Subject/issuer names are C=ES, O=RS-Key, CN=RS-Key PIV …. Read the f9 CA cert with:

ykman piv certificates export f9 attestation-ca.pem

Attestation only works for generated keys; an imported key returns 6A80 / WRONG DATA (there is nothing to attest). For the FIDO side of attestation (org-provisioned enterprise attestation) see attestation.md.

An interrupted keys import or keys move fails closed: the target slot’s metadata is dropped before the new key is written, so a power cut between the two leaves a slot that reads as empty (GET METADATA → 6A88) rather than one whose key and its recorded provenance disagree. Re-run the import; the slot works again once it completes. That ordering is what keeps attestation honest — it can never certify an imported key as generated on-device.

Move and delete keys

ykman piv 5.7 can move a key (with its certificate and metadata) between slots, or delete it:

ykman piv keys move 9a 82          # 9a → retired slot 82, cert + metadata follow
ykman piv keys delete 9c           # wipe the signature slot's key

Moves go both ways — a key parked in a retired slot can come back to an active one. Moving a key onto its own slot is refused, because the source-delete would erase what the move just wrote. Both operations require management-key auth.

Use it

The card shows up as a standard PIV token; nothing here is RS-Key-specific.

• PKCS#11 (browsers, VPNs, SSH, age): point the app at OpenSC’s opensc-pkcs11.so, found at /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so on Debian, /usr/lib/opensc-pkcs11.so on many distros, or the Nix store path under NixOS (linux.md).

• SSH via PKCS#11:

  ssh-keygen -D /usr/lib/opensc-pkcs11.so          # print the slot 9a public key
  ssh -I /usr/lib/opensc-pkcs11.so you@host        # log in with it (touch + PIN per policy)
  

  For an ed25519-sk hardware SSH key the FIDO path is simpler (see ssh.md). PIV-over-PKCS#11 is the route when you need an RSA or NIST-curve key, a smart-card-login certificate, or a server that wants a real X.509 chain.

• age encryption: age-plugin-yubikey drives PIV slots directly for identity files but, like ykman, keys off the “Yubico YubiKey” reader name, so it wants the opt-in VIDPID=Yubikey5 build; on the default RS-Key build use any PKCS#11-aware age build against opensc-pkcs11.so.

• ECDH / key agreement (9d and retired slots, P-256/P-384 and X25519): ykman piv ... exposes it (ykman piv keys calculate-secret for X25519); at the wire level it is GENERAL AUTHENTICATE with tag 0x85, the operation yubico-piv-tool and OpenSC use for decryption.

• Windows / macOS native smart-card stacks pick the PIV applet up as-is; macOS CryptoTokenKit binds its pivtoken.appex to the reader (interop.md).

At rest

PIV private keys are stored AES-256-GCM-sealed under the device root (the sealed blob is nonce ‖ ciphertext ‖ tag, authenticated against the device serial). Once the OTP master key is fused, a flash dump does not yield key material; before that burn, the seal’s root derives from on-chip state an attacker with the flash and chip could reconstruct, so at-rest protection is only meaningful after provisioning (see threat-model.md). The seal is bound to the device, not the slot, so a keys move re-homes the blob verbatim (no re-encryption).

Factory reset (PIV only)

ykman piv reset

Wipes PIV keys, certificates and PINs only; the other applets are untouched. The reset is only accepted once both the PIN and the PUK are blocked; ykman blocks them for you first. To wipe every applet at once (PIV included), use rsk offboard, which blocks PIN+PUK then resets PIV as part of a full-device wipe with a signed receipt (see fleet.md).

9000 from the reset means every PIV file is gone — private keys, public-key caches, certificates, the data objects a host wrote through PUT DATA, and the PIN/PUK files, which are then re-seeded to the factory defaults. The sweep runs until the enumeration comes back empty rather than for a fixed number of passes, and its safety budget counts files actually deleted, so neither a card stuffed with PUT DATA objects nor one whose flash holds many superseded copies of them can outrun it.

If the flash refuses a delete — or reports an enumeration it could not finish, so “nothing left” cannot be proven — the command answers 6581 (MEMORY_FAILURE) instead of claiming a wipe it did not complete. Treat that as “the card is still provisioned” and retry: a failed reset still re-creates the PIN, PUK and retry-counter files it deleted first, so the next attempt behaves like the first one instead of answering 6A88 for the rest of the power cycle.

There is no rsk piv command group: PIV is provisioned entirely through ykman piv / yubico-piv-tool / PKCS#11, with rsk only involved for a whole-device offboard.

Troubleshooting

• ykman can’t connect → linux.md (pcscd + polkit + the disable-ccid scdaemon note).
• ykman stops seeing the card after gpg used it → scdaemon grabbed the raw CCID interface; apply disable-ccid and gpgconf --kill scdaemon (openpgp.md).
• PIN blocked → ykman piv access unblock-pin (needs the PUK). PUK blocked too → only ykman piv reset recovers, and it wipes the slots.
• ykman piv keys attest fails with INCORRECT PARAMS → the key in that slot was imported, not generated; attestation is generated-keys-only.
• change-management-key rejects 3DES on the FIPS-style build → expected; set an AES-128/192/256 key instead.
• RSA-2048 generate takes a few seconds (≈ 4–6 s on the reference board, ≈ 10 s on other boards, occasionally longer since the prime search is random) → that’s the prime search on this hardware, not a hang; the device keeps the CCID connection alive with keepalives.

OATH — TOTP / HOTP codes

The device stores authenticator-app secrets and computes the 6/8-digit codes on-card, over Yubico’s YKOATH protocol (CCID). The HMAC secret is written once and never leaves the chip again: every code is derived inside the firmware and only the digits come back. Up to 255 accounts.

Clients are the stock Yubico tooling: ykman oath on the command line and the Yubico Authenticator desktop/mobile app over USB. There is no rsk oath subcommand; OATH is driven entirely through those. Both ykman oath and the Yubico Authenticator gate on a Yubico YubiKey reader name, so they only see the device on the opt-in VIDPID=Yubikey5 build; the default RS-Key build enumerates as RS-Key Security Key (VID:PID 0x1209:0x0001) and stays invisible to them. Build that flavor when you want to drive OATH from the Yubico tools (build.md).

On Linux this needs pcscd running plus the polkit rule from linux.md; if you also use gpg, the disable-ccid line there keeps scdaemon from grabbing the reader and locking ykman out.

ykman oath info        # applet version + whether an access password is set

Add accounts

# Interactive: paste the base32 secret when prompted.
ykman oath accounts add github --issuer GitHub

# Straight from an otpauth:// URI (everything — secret, issuer, digits,
# algorithm, period — is parsed out of the URI):
ykman oath accounts uri 'otpauth://totp/GitHub:me@example.com?secret=BASE32SECRET&issuer=GitHub'

The account name shown in lists is issuer:account (here GitHub:me@example.com). Most sites hand you the secret two ways at enrollment: a QR code and a “can’t scan it?” base32 string. Either works:

• base32 string → accounts add (or accounts uri if they give the full otpauth:// link).
• QR code on screen → ykman oath accounts uri -- reads it from the primary display, or the Yubico Authenticator GUI has a Scan QR code button that grabs whatever QR is visible.

Options that matter:

All three hashes are implemented on-card (SHA-1/256/512); RFC 6238/4226 test vectors for each pass in crates/rsk-oath. Adding a name that already exists overwrites the old secret in place (--force skips the prompt). There is one credential per name.

Get codes

ykman oath accounts code            # every TOTP account at once
ykman oath accounts code github     # one account by name substring

code with no name runs the bulk path (CALCULATE ALL). Two kinds of account are not computed there and show a placeholder instead:

• Touch-required accounts are listed but not calculated. Name them explicitly (ykman oath accounts code github) and the firmware waits for the press, then prints the code. This is deliberate: a bulk read can never make a touch account leak a code without the button.
• HOTP accounts are never computed in bulk either (it would silently burn the counter). Name them to step the counter once.

The Yubico Authenticator GUI shows all TOTP codes live and re-derives them each period. Touch and HOTP entries get a tap-to-reveal button instead.

Touch-required accounts

ykman oath accounts add aws --issuer AWS --touch
# existing account → re-add with --touch --force, or toggle it in the GUI

With --touch, the firmware refuses to compute that account’s code until the BOOTSEL button is pressed; a timeout or a declined press returns “security status not satisfied” and nothing is computed. For HOTP this gate sits before the counter advances, so a denied touch burns no counter. A refused press leaves the account exactly where it was. The button is the same physical press used by FIDO and OpenPGP UIF; only one prompt is outstanding at a time.

Accounts that only go forward

The YKOATH protocol has a second per-account property beside touch, only increasing, and the firmware enforces it the way a YubiKey does. A TOTP account carrying it remembers the highest challenge it has served and refuses anything at or below that, so its codes can only move forward in time. That is worth having against brief physical access: nobody can walk your clock backwards and harvest the windows you already used, and if someone does read a future window, your next legitimate code fails — which is how you find out.

The cost is that the account is only as usable as your clock. If the host’s time jumps backwards (a bad NTP correction, a timezone-confused VM, a dual-boot machine with a local-time RTC), the account stops answering until real time catches up, and there is no way to lower the mark short of re-adding the account. ykman does not expose the property today; a client that does will say so. Ordinary accounts are unaffected — the mark exists only where the property was set at enrollment.

The OATH access password

By default the credential list and codes are readable by anything that can reach the CCID interface. An optional access password gates the applet:

ykman oath access change            # set or change the password
ykman oath access remember          # cache it for this host (keyring)
ykman oath access forget            # drop the cached password

How it works on-card: the password becomes an HMAC key (PBKDF2 over the password, salted with the device serial, done host-side by ykman). On every fresh connection the card issues a random challenge; the host must answer with HMAC(key, challenge) before any account command is allowed. The card answers the host’s challenge with the same key (mutual proof). Selecting the applet again re-locks it. The compare is constant-time and full-length, so a truncated or guessed response can’t brute-force its way in one byte at a time.

Footguns:

• The password gates listing and computing codes over CCID. At rest the secrets are protected separately: every credential record — name, secret, HOTP counter — and the access password’s own validation key are individually AES-256-GCM-sealed before they reach flash, under the device key kbase (accounts enrolled before that landed are re-sealed on the next boot). The password is not part of the sealing key, deliberately: codes have to compute without a separate at-rest unlock, exactly like PIV slot keys. So the seal is device-bound, not password-bound. Once the OTP master key is burned a flash dump on its own no longer yields your secrets (threat-model.md); what it never buys is protection from something that can drive this chip’s firmware — that is what the access password and --touch are for.
• There is no recovery for a forgotten access password short of ykman oath reset, which wipes every account with it.
• --touch per account and the access password are independent hardenings. Use either, both, or neither.

The OTP PIN and the password safe

Alongside the OATH accounts the applet can store a login, a password and a note per credential — the password-safe extension nitropy speaks. Those fields are secrets in a way a TOTP code is not: a code expires, a stored password does not.

They are read by GET CREDENTIAL, and the rule is that an OTP PIN, once set, is always required for it — on a fresh connection, whether or not an access password is also configured, and again after every re-select. VERIFY CODE is gated the same way. Set the PIN with nitropy nk3 secrets set-pin; the card demands a touch when it mints one, so a PIN cannot be planted on a key someone briefly picked up.

With neither a PIN nor an access password the store is open to anything on the CCID interface, exactly as the credential list is — that is the code-less default this applet shares with a YubiKey, not an oversight. If you keep passwords on the key, set one of the two.

A failed PIN attempt shuts the safe again, whether it arrives as a verify or as a PIN change with the wrong old PIN, and either way it spends a retry. So walking away mid-session no longer leaves the safe readable to whoever tries the PIN next: the three failed guesses that lock the card also close what the last correct PIN opened. A malformed request is not an attempt — it costs no retry and changes nothing.

Manage

ykman oath accounts list                       # account names (extended list also flags which need touch)
ykman oath accounts list -P                    # include the period column
ykman oath accounts rename github GitHub:work  # current name → new name
ykman oath accounts delete github              # remove one account
ykman oath reset                               # wipe the OATH applet only

rename rewrites the name in place and keeps the same secret and counter; renaming to a name that already exists is rejected. delete of an unknown name is a no-op error. reset clears all accounts, the access password, and the OTP password-PIN. Nothing outside OATH is affected (FIDO/PIV/OpenPGP survive). To wipe the whole key instead, see rsk offboard.

Notes

• Secrets live in device flash, each record sealed to this chip (see the footgun above). Codes are computed on-card, so the secret never returns to the host after add.
• OATH accounts are not covered by the seed backup and do not come back on a backup key: they are sealed to this chip, not derived from the FIDO seed. Keep your otpauth:// URIs/QRs somewhere safe, or re-enroll on loss. The device cannot export a secret once it is stored.
• HOTP counters are persisted across reboots and continue from where they were. Touch-required HOTP accounts only advance the counter after the touch, so there are no drive-by increments.
• Enrollment is checked before anything is written, the way a YubiKey checks it: the secret is 14–64 bytes, the name 1–64, the code 6/7/8 digits, the hash one of SHA1/SHA256/SHA512. A client that sends anything else gets 6A80 and nothing is stored — in particular, a rejected add over an existing account leaves that account working instead of replacing it with one that can never produce a code. ykman and Yubico Authenticator stay inside these bounds; a client that does not was writing an account no authenticator app could ever use.
• OATH interop (add → list → calculate → delete, plus TOTP crypto-verified against RFC vectors, via both ykman oath and Yubico Authenticator) is tracked in interop.md.

Troubleshooting

• ykman finds no reader / “Failed to connect”: on Linux this is almost always scdaemon holding the CCID interface after a gpg call. Apply the disable-ccid line from linux.md and run gpgconf --kill scdaemon, then retry.
• Codes are rejected by the site: TOTP depends on the host clock. The card has no battery-backed time and trusts the timestamp ykman/the GUI sends. Fix the host’s clock (NTP) and re-read. For HOTP, a code is rejected once the server counter has moved past yours; resync on the server side.
• “Touch” account prints nothing under accounts code: that’s expected. Bulk read skips touch accounts. Name the account so the firmware prompts for the press.
• Forgot the access password: there is no unlock; ykman oath reset is the only way out, and it deletes every account.

OTP slots — Yubico OTP, challenge-response, static passwords

The YubiKey “OTP” feature: four slots, each holding one credential, output by a button press or read over USB. Program slots 1–2 with stock ykman otp. Slots 3–4 are two extra slots reached over the same protocol with a slot offset.

ykman otp needs the opt-in Yubico flavor. ykman gates on the “Yubico YubiKey” reader name. Only the opt-in VIDPID=Yubikey5 build presents it. The default RSKey build (VID:PID 0x1209:0x0001, reader “RS-Key”) is invisible to it. The HID-keyboard typing of a slot’s output is identity-independent and works on either build. Only programming and reading slots over ykman needs the Yubico flavor.

Not the RP2350 fuses. This page is the Yubico one-time-password feature. The chip’s One-Time-Programmable fuses (secure-boot key, master sealing key) are a different thing with the same three letters. See otp-fuses.md.

The device is also a USB keyboard: pressing the button types the selected slot’s output wherever the cursor is. That keyboard is a third USB interface (standard boot keyboard). It sits after the FIDO HID and CCID interfaces. If your OS asks about a new keyboard at first plug, that’s this one.

flowchart LR
    press["button press"] --> kbd["USB HID keyboard"] --> types["types the slot output"]
    ykman["ykman otp"] --> c1["CCID / HID frame"] --> s12["slots 1-2"]
    raw["slot-offset APDU"] --> c2["CCID"] --> s34["slots 3-4"]

Slot selection by clicks

The firmware runs a click counter: clicks landing within 1 second of each other count toward one gesture. The gesture types that slot when the window closes.

A press the key asked for — a touch confirming a signature, a PIN change, a reset — is not a click, even if you keep holding it after the operation finishes: its release belongs to that ceremony. Only a press made while the key is idle counts toward a gesture.

ykman otp only knows slots 1 and 2, the classic short/long-press pair. Slots 3 and 4 use the same wire protocol with a 1- or 2-step slot offset (the firmware addresses all four as one contiguous block). A tool has to send that offset itself. Most setups never need them. Everything below targets 1/2 unless noted.

What each slot type does

Four credential types share the slots. Only some type on a press:

A challenge-response slot types nothing on a press. The button only gates the USB calculate when the slot was programmed touch-required. So a slot can hold a Yubico OTP or a static password or a HOTP secret or a challenge-response secret, not several at once.

Program a slot

ykman otp info                                                   # what's in each slot
ykman otp yubiotp 1 --serial-public-id -g -G                     # classic Yubico OTP (random ids + key)
ykman otp chalresp 2 --generate --touch                          # HMAC-SHA1 challenge-response
ykman otp static 1 --generate --length 38                        # typed static password
ykman otp hotp 2 --digits 6 'base32secret'                       # OATH-HOTP
ykman otp swap                                                   # swap slots 1 and 2
ykman otp delete 2                                               # clear a slot

Notes on the options:

• --touch (chalresp) sets the touch-trigger bit: the USB calculate then waits for a button press and refuses without one. Touch-typing slots (Yubico OTP, static, HOTP) always need the press anyway. That’s the only way to fire them.
• yubiotp: -S/--serial-public-id uses the device serial as the public id, -g/--generate-private-id randomises the private id, -G/--generate-key randomises the AES key. All three together give a self-contained random credential.
• --length on a static slot is the typed-password length, max 38 characters (the slot stores 38 password bytes). --length 38 fills it. By default static only uses the modhex alphabet (cbdefghijklnrtuv) so the password types the same on any keyboard layout. --keyboard-layout us (etc.) widens the character set at the cost of layout-dependence.
• Reprogramming a slot is destructive. The new secret overwrites the old. There is no “read it back.” Yubico OTP and chal-resp secrets are random and exist only on the device once programmed (see Validation below for the exception).
• Access code: set one with ykman otp settings <slot> --new-access-code. The firmware then refuses to overwrite, update, delete, or swap that slot unless the code is presented (ykman otp --access-code <hex> …, given before the sub-command). Lose the code and the only way out is a factory reset of the OTP applet.

ykman otp reaches the device over the HID frame protocol on the keyboard interface (and over CCID). Both work without any PIN. OTP slots are not PIN-protected, only optionally access-code-protected.

Challenge-response from software

ykman otp calculate 2 <hex-challenge>     # HMAC-SHA1, returns the 20-byte HMAC

This is the KeePassXC / LUKS pattern: the database (or disk) key is mixed with the slot’s HMAC of a fixed challenge. --touch slots wait for a press first. The keyboard interface answers the same protocol, so tools written for YubiKeys (“YubiKey challenge-response” in KeePassXC, ykchalresp, the pam_yubico HMAC mode) work unchanged.

Those tools are the ykpers/ykcore family, and on Linux they talk to the key over raw libusb rather than through the kernel HID stack. That path has two requirements a stock YubiKey satisfies implicitly:

• A Yubico VID. KeePassXC filters on Yubico’s (and OnlyKey’s) vendor id and a fixed PID list, so a default 0x1209 build is invisible to it — build the firmware with VIDPID=Yubikey5 (see build.md).
• libusb access to the device. Install Yubico’s udev rules (69-yubikey.rules / 70-yubikey.rules, packaged as yubikey-personalization on most distributions); without them libusb cannot open the device at all.

ykman otp calculate is not affected by either — it goes through hidraw.

Since bcdDevice 0x085A the frame protocol also answers on the FIDO interface, the way a YubiKey does, so a tool that addresses OTP by interface index finds it whatever the enabled interface set looks like. Turning the keyboard interface off in the phy record still takes it away from both.

Two challenge-response modes exist:

• HMAC-SHA1 is the common one. Variable-length challenges (HMAC_LT64) are supported with the classic YubiKey trim quirk: a short challenge is padded by repeating its last byte, and a challenge that ends in its own last byte loses that tail. KeePassXC and ykchalresp -H already account for this.
• Yubico mode is a 6-byte challenge, AES-encrypted with the slot key after mixing in the device serial. Rarely used. HMAC-SHA1 is what tools expect.

Yubico OTP validation

A Yubico-OTP slot types 44-modhex one-time passwords (a 6-byte public id in clear, then an AES-128-ECB block over the private id, a 16-bit usage counter, a session counter, an uptime stamp, two random bytes and a CRC). A validation server decrypts and replay-checks them.

• The usage counter advances every power-up and every session wrap, so a token never repeats across reboots: the standard replay defence.
• Public validation (YubiCloud) requires uploading the slot’s AES key to Yubico. --generate-key prints the key, public id and private id at programming time. Capture them then, because they cannot be read back later.
• Self-hosted validation (yubikey-val, or a custom verifier) keeps the AES key on your own server. Nothing leaves the building.

Static passwords

A static slot types a fixed string on each press. Handy for a long machine password or a prefix you append a moving code to. It is not a secret store: anyone who can press the button gets the password typed out, and a static password is replayable by definition. The string is typed as raw HID scancodes, so it is keyboard-layout independent up to the characters ykman will accept.

OATH-HOTP slots

An OTP-slot HOTP credential types an RFC 4226 code (6 or 8 digits, --digits) and advances its counter on each press. This is the typed HOTP, distinct from the full OATH applet, which stores many TOTP/HOTP accounts and is read by an authenticator app rather than typed. Use a slot when you want one HOTP typed by a button. Use the OATH applet for a list of accounts.

Reading status / serial

ykman otp info               # slot 1/2 programmed? touch? type?
ykman info                   # device serial, firmware version, enabled apps

The serial that OTP reports is the YubiKey-style 8-digit serial derived from the chip id, the same value ykman info shows. A serial derived from the same chip id is mixed into Yubico-mode challenge-response, though it draws on more of the chip-id bytes than the reported 8-digit value, so the two aren’t byte-identical.

Disabling the keyboard interface

If the extra keyboard is unwanted (some KVMs or login screens dislike a button that types), ykman config usb --disable otp now genuinely turns OTP off:

ykman config usb --disable otp        # disables the OTP application (enforced)
ykman config usb --list               # confirm what is on
ykman config usb --enable otp         # reversible — turns it back on

The write persists to the Yubico management capability blob (EF_DEV_CONF) and the firmware enforces it live (no replug): a button press then types nothing, and Yubico / HMAC challenge-response is refused on both the keyboard frame protocol and the CCID OTP applet.

One caveat: the keyboard USB interface still enumerates. Whether the HID interface is present at all is decided at boot by a separate mask in the rescue phy record (EF_PHY / USB_ITF_KB), which a capability-bit change does not touch — so the OS still sees an (now inert) keyboard. To drop the interface itself, clear the USB_ITF_KB bit in the rescue phy mask via the rescue applet (stock ykman can’t do it). If accidental typing was the only worry, --disable otp — or leaving the slots empty / behind an access code — already stops the presses.

Troubleshooting

• ykman otp info hangs or errors right after gpg/ssh used the device → scdaemon is holding the CCID interface. gpgconf --kill scdaemon, then retry. See linux.md and openpgp.md.
• A press types nothing → the slot is empty, or it’s a challenge-response slot (those never type). ykman otp info shows which.
• ykman otp calculate returns CONDITIONS_NOT_SATISFIED / waits forever → the slot is --touch. Press the button.
• Overwrite/delete refused → the slot has an access code. Pass it with ykman otp --access-code <hex> … (before the sub-command), or factory-reset the OTP applet.
• Slots 3/4 don’t show in ykman otp info → expected. ykman otp only enumerates 1 and 2.
• KeePassXC on Linux says Hardware key USB error: Pipe error, or ykchalresp fails while ykman otp calculate works → firmware older than bcdDevice 0x0859 enumerated the FIDO interface first, and these tools address the OTP interface as interface 0 unconditionally. Update the firmware. If the key isn’t listed at all, check the VID and udev requirements above.
• A --touch slot works from ykman but not from KeePassXC, and afterwards even ykinfo fails for half a minute → firmware older than bcdDevice 0x085B stayed in the touch wait once a host had probed the slot and moved on, and answered “would block” to every command until it timed out. Update the firmware. A non-touch slot never hit this.

Notes and limits

• OTP slot secrets are not covered by the seed backup and not by a primary/backup-key pair. They’re sealed to this chip. Re-program the slots on a replacement board, or keep the AES keys / HOTP seeds you generated somewhere safe.
• Touch-triggered typing always requires the physical press. Only the challenge-response USB path honours each slot’s touch-trigger flag.
• No PINs here. Anything that can reach the USB interfaces can press-by-proxy a typing slot and can run calculate on a non-touch chal-resp slot. Make the sensitive ones --touch, and put an access code on slots you don’t want silently reprogrammed.

Seed backup — BIP-39 / SLIP-39

Hardware-wallet-style backup of the FIDO master seed. The 32-byte seed is exported once and rendered as words. Later it can resurrect your deterministic FIDO identity on a fresh board. Every non-resident credential (ssh ed25519-sk keys, classic 2FA registrations) derives from the seed. After a restore the same key files and registrations keep working.

Not covered (sealed to the chip, not derivable from the seed): resident passkeys, OpenPGP keys, PIV keys, OATH accounts, OTP slots.

Two ways to stay recoverable

Seed backup is one strategy. A primary + backup device pair is the other. They are complementary:

• Back up the seed (this page): one identity, kept recoverable by its mnemonic. Restore it onto a replacement board to resurrect the same credentials. Simple, but it is a single secret, and resident passkeys / PIV / OpenPGP don’t come back.
• Primary + backup pair (backup-key.md): two independent keys with different seeds, both registered on every account. Lose one and the other already works. No restore, no shared secret to leak. The cost is registering both keys everywhere (and enrolling resident passkeys on each).

Many people do both: two devices and a written mnemonic for each.

Export (once, at setup)

rsk backup export --scheme bip39                       # 24 words
# or Shamir shares — any 2 of 3 reconstruct:
rsk backup export --scheme slip39 --threshold 2 --shares 3

Gates, all enforced by the firmware: an encrypted transport channel, a touch, the FIDO PIN (when set), and the setup window (below). Write the words on paper. The host that runs the export sees the seed, so do this on a machine you trust.

rsk backup finalize        # seals the export window — typed confirmation
rsk backup status

After finalize, export is refused forever (until a factory reset makes a new seed). That’s the anti-exfiltration gate: malware on a later host cannot quietly re-export your seed. Corollary: lost words cannot be re-exported either, so pick a SLIP-39 share count with margin (2-of-3 minimum, 3-of-5 for the paranoid).

Restore (onto any RS-Key board)

rsk backup restore --scheme bip39          # prompts for the 24 words
# or: --scheme slip39                      # prompts for ≥ threshold shares

Touch + PIN gated. The incoming seed is re-sealed under the destination device’s own root. A restored board is cryptographically indistinguishable from the original for every derived credential. Restore overwrites the destination’s auto-generated seed (it warns; a fresh board loses nothing).

After restoring: your ~/.ssh/id_*_sk files log in again, 2FA registrations answer again. Resident passkeys do not come back, so re-enroll those.

The TUI

rsk-tui has the same export/restore/finalize flows interactively (BIP-39 only; SLIP-39 stays in the CLI), with the seed phrase revealed on-screen and zeroized after.

Mechanics (for the curious)

The seed crosses USB only inside an ephemeral encrypted channel: P-256 ECDH → HKDF-SHA256 → ChaCha20-Poly1305, fresh nonce per message. The mnemonic encodings are entirely host-side. BIP-39 (24 words) and SLIP-39 (Shamir T-of-N) both encode the same raw 32 bytes, so either reconstructs the seed. The setup-window flag lives with the seed’s lifecycle: cleared when a seed is generated (first boot, factory reset), set by finalize.

Backup key — a primary + backup pair

A single security key is a single point of failure. Lose it, break it, leave it at the office, or have it stolen, and you are locked out of everything it was your only key for. The fix is the one hardware-key vendors recommend: keep two keys, a primary you carry and a backup you store somewhere safe, and register both with every account. Lose one and the other already works, with no recovery dance.

This page is the why and the how. The seed-backup mnemonic (seed-backup.md) is a different, complementary safety net. The two are compared at the end.

Why two independent keys

The pair are two separate devices with different seeds, not one identity copied onto two sticks. That independence is the point:

• No single point of failure. A primary that is lost, bricked, or left behind doesn’t lock you out. The backup is already enrolled everywhere.
• No shared secret. Because the seeds differ, compromising one key tells an attacker nothing about the other. (Cloning the same seed onto both would make a single leak break both, the opposite of what a backup is for.)
• It is how WebAuthn is meant to be used. Every serious account lets you add more than one security key precisely so you can enroll a backup. You are using the platform’s built-in redundancy, not working around it.
• Resident credentials aren’t seed-portable anyway. Passkeys, PIV, and OpenPGP keys are sealed to the chip, so even with a seed backup you would re-enroll them on a replacement. Two live keys sidestep that entirely.

The model

Both keys are enrolled on every account. Day to day you use the primary. The backup sits in a drawer or a safe. If the primary is gone, the backup logs you in to remove the lost key and enroll a fresh replacement. No downtime, no restore.

Set it up — rsk pair

rsk pair walks you through it. It reads each device in turn (touch-free), confirms they are two different physical keys, and prints the checklist:

rsk pair          # plug in the primary, then the backup, when prompted

Then, working down the checklist:

1. Give each device its own PIN (in your browser / OS security-key settings).
2. Back up each seed separately. Two independent seeds means two different mnemonics (seed-backup.md). Do rsk backup export with each device, then rsk backup finalize.
3. Register both keys on every important account. In each service’s security-key settings, add the primary and the backup. Don’t stop at the accounts you remember. Email and your password manager first, since they gate everything else.
4. Store the backup key somewhere separate from the primary (a different building is ideal, since fire and theft take whatever is in one place).
5. Test the backup by signing in with only it, once, before you rely on it.

Different seeds — on purpose

Each RS-Key generates its own seed on first boot, so two fresh keys are already independent. You don’t have to do anything to make their seeds differ. The one way to accidentally defeat this is to rsk backup restore the same mnemonic onto both, which turns them into clones. Don’t. If you want the same identity on a replacement board, that’s the seed-backup flow, not the pair flow.

rsk pair can’t cryptographically prove the seeds differ. RS-Key credentials are randomized (a fresh key handle per registration), so there is no stable seed-derived value to compare between two devices, and the device attestation key is per-chip, not per-seed. The wizard confirms two distinct physical devices and relies on the self-generated-seed property above. If you want to check by hand, rsk backup export both and compare the phrases (they must differ).

If you lose a key

Losing one of a registered pair is a routine event, not an emergency:

1. Sign in with the surviving key. It is already enrolled everywhere.
2. Remove the lost key from each account. In each service’s security-key settings, delete the missing authenticator so it can no longer be used.
3. Get a new key and make it the new backup. rsk pair again with the survivor as the primary, then enroll the new one across your accounts.

A stolen key is gated by its PIN (a few wrong tries lock it), but removing it from your accounts is what actually retires it. Do that promptly.

This vs. the seed-backup mnemonic

They are complementary. The pair gives you redundancy with zero recovery effort. The mnemonic resurrects an identity onto a replacement when you only had one key. Many people do both: two keys, and a written mnemonic for each.

Soft-lock — at-rest seed lock

Optional hardening: with the lock engaged, the FIDO master seed exists in flash only encrypted to a 32-byte key that you hold (as BIP-39/SLIP-39 words or hex). A stolen board refuses every FIDO operation until that key is presented, even powered up, even running genuine firmware. Your identity becomes device + words, two factors.

This is the same idea as a wallet passphrase. It composes with (does not replace) the silicon protections: once provisioned, the OTP root and secure boot (production.md, otp-fuses.md) stop flash-dump and foreign-firmware attacks. The soft-lock additionally stops your own device in the wrong hands.

Needs firmware with soft-lock support (bcdDevice >= 0x0742). Older builds answer rsk lock status with “firmware too old”. Check with rsk status.

Prerequisite: a FIDO2 PIN

enable and disable ride authenticatorConfig, which the firmware always gates on a pinUvAuthToken with the acfg permission. So a FIDO2 PIN must already be set, and you pass it with --pin. With no PIN configured the command stops with “authenticatorConfig needs the acfg pinUvAuthToken”. Set one first:

rsk fido set-pin           # see fido2.md

unlock is the exception: it needs neither PIN nor touch (below).

Enable

rsk lock enable --pin 1234             # PIN + touch gated; typed confirmation

Generates a random 32-byte lock key, prints it once (default 24-word BIP-39), wraps the seed value with ChaCha20-Poly1305 under it into flash, and deletes the plaintext-sealed copy. Touch the device (BOOTSEL button) when prompted. Treat the key like the backup words: paper, not a file.

Choose how the key is rendered:

rsk lock enable --pin 1234 --scheme slip39 --threshold 2 --shares 3

--key-out FILE also writes the raw key hex to a 0600 file. A test/CI convenience, not for production: it defeats the point of holding the key only on paper.

The wrap is over the seed value, independent of the at-rest format tag and of the kbase the plain file was sealed under. So locking and the OTP re-sealing (otp-fuses.md) stay orthogonal.

Daily use — unlock at power-up

rsk lock status            # locked? unlocked this session?
rsk lock unlock            # prompts for the 24 words; seed goes to RAM only

status prints four flags read straight from the device:

The lock re-engages at every power cycle: the unlocked seed lives only in RAM and is zeroized on unplug. While locked with no unlock this session, the seed loader fails and the firmware errors out of every credential operation: registration (makeCredential) and assertion (getAssertion/U2F) alike. Browsers show a generic failure and ssh says the key refused, until you unlock.

Unlock takes the key the same three ways and can run headless in a script:

rsk lock unlock --scheme bip39 --mnemonic "word1 word2 … word24"
rsk lock unlock --key-hex 0011…  # 64 hex chars
rsk lock unlock --scheme slip39  # prompts for shares, one per line, blank to finish

Unlock needs no PIN and no touch. Knowledge of the 256-bit key is the authorization (it is verified by the AEAD decrypt succeeding). A wrong key fails closed with unlock failed: 0x… (wrong key?) and leaves the device locked. Unlocking a device that isn’t locked reports device is not locked.

Disable

rsk lock disable --pin 1234            # needs an unlocked session + PIN + touch

Disable proves you hold the key by requiring the seed already unlocked this power cycle, then writes it back plaintext-sealed (device-root-sealed) and deletes the wrapped blob. If you haven’t unlocked yet, pass the key and disable unlocks first:

rsk lock disable --pin 1234 --mnemonic "word1 … word24"
rsk lock disable --pin 1234 --key-hex 0011…

Calling disable without an unlock prompts for the lock key (or pass --mnemonic/--key-hex). Supply nothing valid and it fails with the lock still engaged.

How it composes with seed backup

The soft-lock and the seed backup are independent (backup exports/imports the seed value, the lock wraps that same value), but their ordering matters:

• Back up before you lock. A mnemonic taken before ENABLE still restores the original identity onto a fresh board later.
• Restore is refused while locked. rsk backup restore (firmware BACKUP_LOAD) returns “not allowed” on a locked device. A restore next to a live wrapped blob would leave two competing seeds. disable (or a reset) first.
• Export works once unlocked. With the seed unlocked this session, rsk backup export serves the in-RAM copy normally (subject to the one-time export window).

Lost the lock key?

Unrecoverable by design. The way forward is a FIDO factory reset, which deletes the locked blob and generates a fresh identity (ykman fido reset, which needs the opt-in VIDPID=Yubikey5 build, or any WebAuthn “reset security key” UI on the default build). Replug the key first: a screenless build accepts the reset only within ten seconds of a power-up (see fido2.md). Your seed backup, if you made one before locking, still restores the old identity afterwards. Without it the old credentials (ssh ed25519-sk keys, U2F registrations) are gone.

Honest caveats

• The flash log keeps the superseded plaintext-sealed record until natural compaction overwrites it. The at-rest guarantee hardens over time after ENABLE rather than instantly. (That lingering record is still sealed to the device root, so this only matters against an attacker who has also defeated the OTP tier; see threat-model.md.)
• A compromised host at unlock time cannot read the key from the wire (the channel is an ephemeral ChaCha20-Poly1305 tunnel) or the seed (never leaves the device). But while the device sits unlocked and plugged in, it can drive normal FIDO operations, like any session. Unplug when done.
• The lock protects the FIDO seed only. OpenPGP, PIV, and OATH keys are sealed to the chip independently and are not gated by it. To gate those, rely on their own PINs and on the OTP/secure-boot tier.

LED

The status LED is the device’s only display. On the reference board (the Waveshare RP2350-One), it’s a WS2812 addressable RGB on GPIO16.

Build-time knobs

Three hardware properties of the indicator are compile-time knobs set by build flags. A fourth, MAX_LEDS, sets the upper bound for the PIO buffer. The actual number of connected LEDs is configured at runtime via rsk hw --led-num (or PicoForge) and must be ≤ MAX_LEDS.

# example: build for a 4-LED board with standard GRB order
env MAX_LEDS=4 LED_ORDER=grb cargo build --release -p firmware
# then set the runtime count (persists across reboots):
rsk hw --led-num 4

Once built, a non-none build compiles all backends, so the pin, driver, wire order, and LED count are runtime-changeable (no reflash) with rsk hw (build.md). The build knobs set the boot defaults.

What the LED shows (colour, brightness, and the visual effect) is runtime-configurable separately, covered next.

Effects

Each of the four states can run one of several animated effects. The effect determines how the LED(s) display the state’s colour and brightness. All effects work with any number of LEDs. vapor and sparkle shine on a single LED too. bounce and flow naturally reduce to a static colour or a single pixel when there is only one LED.

Effects only render on the ws2812 backend (addressable RGB). The gpio and pimoroni backends always use the classic on/off blink, regardless of the effect setting. They lack per-LED control and pixel-level colour.

Default mapping (multiple LEDs)

A few honest details:

• No dedicated error colour. The firmware does not light a distinct “error” state. A failed operation just drops back to idle. Read the host tool’s exit code, not the LED, for success or failure.
• The touch state needs the touch build. It is only ever shown on the default touch build. A no-touch build (--features no-touch) never enters it. The processing state still flashes during the operation either way (build.md).
• Default brightness is gentle. 16 of 255 per channel, so the indicator is visible without being a flashlight. Turn it up if you want.
• Boot is brief. You normally see it only for the moment between power-up and the first idle, so don’t tune your eye to it.

This is not the BOOTSEL / picotool state. Holding the button while plugging in puts the RP2350 in its ROM bootloader, where this firmware (and therefore this LED engine) isn’t running, so the LED is dark or shows whatever the ROM does. That mode is for flashing firmware and OTP, covered in build.md and otp-fuses.md.

Customize

Colour & brightness

Per-state colour and per-channel brightness are configurable. The values persist in flash (EF_LED_CONF) and apply live, no reboot:

rsk led --get                                  # print the current config
rsk led --status idle --color blue             # recolor a state
rsk led --status idle --brightness 64          # 0–255; 0 = that state goes dark
rsk led --status idle --color blue --brightness 64

touch cannot be switched off, and its colour is reserved. On a build without the trusted display the touch state is the only signal that the key is waiting for your consent. You can restyle it — colour, effect, speed, brighter — but the firmware normalizes four things on every write, whatever transport it came in on (rsk led, rsk led --transport fido, or a boot reload of the stored record):

• --color off on --status touch becomes the default yellow.
• --brightness 0 on --status touch is raised to 8.
• --speed 1 is raised to 2. At 1 the breathing effect renders an all-black frame every tick while the brightness byte still reads fine.
• no other state may wear the touch state’s colour. One that does is reset to its own factory look, whatever its effect, brightness or speed. The rule keys on colour alone because a brightness or speed one unit off is identical to the eye, and the effect is no signal at all in --steady mode or on a one-LED board.

Every other state still goes fully dark on --brightness 0. rsk led --get shows what the device is actually rendering, so read it back after a write that hits one of these rules.

There is one case where touch gives way instead. If the state wearing the touch colour has that colour as its own factory colour, resetting it would not resolve the clash, so touch reverts to its factory look (yellow, bounce). Only boot (red) and idle/processing (green) can trigger that:

rsk led --status touch --color red      # sticks — unless boot is red
rsk led --status touch --color green    # sticks — unless idle or processing is green
rsk led --status boot  --color blue     # …then a red touch is legitimate and kept

What this does not promise. Two states in different colours can still be hard to tell apart. On a single-colour (gpio) build hue collapses to lit or unlit; red, green and yellow are mutually confusable under red-green colour blindness; and on a one-LED board bounce, flow and steady mode all render the same solid frame. What separates the states there is the per-state blink timing (touch 1000/100 ms vs idle 500/500 ms), which no host write can change — but --steady suppresses blinking altogether, so on a single-colour build it leaves nothing to distinguish them. If the consent signal has to be unambiguous, use a trusted-display build, which names the operation on screen.

Effect & speed

Each state’s effect and animation speed are configurable the same way:

rsk led --status idle --effect vapor          # change the effect
rsk led --status touch --effect bounce --speed 15  # custom speed (ticks per step)
rsk led --status processing --effect legacy   # revert to classic on/off blink

--speed 0 (or omitting --speed) uses the effect’s built-in default.

Steady / blink

--steady and --blink are global, not per-state: the firmware keeps each state’s timing internally, but a single flag decides whether any of them blink. --steady makes the whole indicator a solid lamp whose colour tracks the current state. --blink brings the blink patterns back.

rsk led --status idle --color cyan --steady    # solid cyan at idle, no pulse
rsk led --blink                                # back to the blink patterns

rsk-tui has a “cycle idle color” action that steps the idle state through the palette, plus “Read LED state”. For per-state colour, brightness, or the steady toggle, use rsk led.

Identify (CTAPHID wink)

A host can ask the key to point at itself — CTAPHID_WINK — which is how you tell two identical keys apart when both are plugged in. The indicator answers with four fast blinks over about half a second in the touch colour, then goes back to whatever it was showing.

rsk identify              # wink every attached key in turn, naming each
rsk identify --repeat 3   # three bursts each, if you looked away

rsk-tui has the same thing as “Identify this key” in Overview — that one winks the device the dashboard is showing, rather than walking them all.

The burst deliberately overrides the configured effect and --steady: the command is only useful if the key visibly flashes. It also uses the touch colour because that is the one state rsk led keeps above a visibility floor, so a key dimmed everywhere else still answers something you can see.

Two bounds follow from borrowing that colour. Repeated WINKs do not extend a burst already running — it always ends 600 ms after the first one — and a WINK arriving while the key is waiting for a touch shows the real prompt, not the burst. Without both, a host could hold the awaiting-touch indicator lit and forge the one consent signal a build without the display has.

A build with no indicator (LED_KIND=none, which includes the display build) does not advertise the wink capability at all, rather than accepting the command and doing nothing.

Selectors and values

Hardware wiring (rsk hw)

See the phy record spec for the full reference. The LED wiring (pin, driver, wire order) lives in the phy record, shared with PicoForge:

rsk hw --led-pin 22                     # move the WS2812/gpio data pin to GPIO22
rsk hw --led-driver gpio                # switch to a plain on/off LED
rsk hw --led-order grb                  # fix a red/green swap on a GRB part

By default rsk hw speaks CCID (PC/SC). On a host where pcscd can’t read or write the card, add --transport fido to do the same read-modify-write over the FIDO HID transport instead. It is gated by a device touch and, if a PIN is set, --pin (a pinUvAuthToken). rsk led takes the same flag. Wiring (rsk hw) applies on the next boot, so re-plug the device. Colours (rsk led) apply live:

rsk hw  --transport fido --touch-timeout 45   # wiring; approve with a touch
rsk led --transport fido --status idle --color blue   # colours, applied live

--touch-timeout has a floor of 10 seconds. A shorter window can expire while your finger is still on the button, and the next queued request would then inherit that same press as its consent. rsk hw refuses anything below 10, and the firmware raises it anyway if some other host writes the record directly.

It bounds the whole ceremony, not just the wait for a press: a key that confirms and then waits for the finger to lift stops waiting at the same deadline, so no one request occupies a button key for longer than the window. (A trusted-display key may add up to 3 s absorbing a finger already on the panel.)

Reset to defaults

rsk led --status idle       --color green  --brightness 16 --effect vapor
rsk led --status processing --color green  --brightness 16 --effect flow
rsk led --status touch      --color yellow --brightness 16 --effect bounce
rsk led --status boot       --color red    --brightness 16 --effect sparkle
rsk led --blink

Under the hood

rsk led talks to the firmware’s vendor applet over CCID (tools/rsk/led.py, firmware/src/vendor.rs):

• SET LED (INS 0x10) packs brightness into P1 and colour + the steady bit + the target state into P2. When the caller sends 1–2 data bytes, they set the effect and speed for that state.
• GET LED (INS 0x11) returns the whole config block: [steady:1, (effect:1, color:1, brightness:1, speed:1) × 4] (17 bytes).

The firmware writes the block to EF_LED_CONF and reloads it on every boot, so your settings survive a power cycle but not an OpenPGP/FIDO factory reset (those don’t touch this file). The led.rs module keeps per-status atomics that the render task reads live. SET LED updates them immediately, then persists the full block to flash — unless the record already holds exactly that block, in which case it answers 9000 and leaves the flash alone.

The touch rules above live in the block codec (crates/rsk-led), not in any one command handler, so they apply wherever a block is decoded: the CCID setter, the FIDO CONFIG_WRITE LED target, and the boot reload. The CCID path persists the normalized block; a FIDO CONFIG_WRITE stores your bytes as sent and normalizes them on the way to the pixels, so CONFIG_READ can echo a record the device is not rendering. rsk led --get (GET LED) always reports the rendered values.

For the wiring half (rsk hw), see the phy record spec. It writes to EF_PHY via the rescue applet and applies at next boot.

Troubleshooting

• LED is dark and stays dark. Either the board has no addressable LED, or the data pin / driver is wrong for your wiring. Fix it live with rsk hw --led-pin N / --led-driver … (or rebuild with the right LED_PIN / LED_KIND, build.md). If a known-good board goes dark mid-session, the firmware task is likely wedged, not the LED.
• Red and green look swapped. Wrong wire order for your LED part. Flip it with rsk hw --led-order grb (or build with LED_ORDER=grb). See the RGB-vs-GRB note above.
• Only the first LED lights up; the rest stay dark. The board has multiple daisy-chained addressable LEDs, but the runtime LED count was never set. Run rsk hw --led-num <your count> to configure it (persists across reboots; the change applies after a warm reboot). If you need a higher buffer ceiling, rebuild with MAX_LEDS=<n>.
• rsk led can’t reach the device. It needs the CCID interface up (pcscd on Linux). If gpg --card-status / rsk status also fail, fix that first (linux.md).
• An app looks frozen. Check for the long-on yellow touch state and tap the button. If the LED is idle-green and the app is still stuck, it isn’t waiting on the device.

Trusted display

Experimental. An RS-Key variant for a screen-and-touch RP2350 board (the reference target is the Waveshare RP2350-Touch-LCD-2.8). The screen turns the key into a trusted display: the operations that matter (approving a sign-in, typing a PIN) happen on the device’s own glass, not on the host. A compromised or phishing host cannot fake what you see or capture what you type. Concretely:

• An Approve / Deny prompt paints the real relying party for every signature. A signature cannot be obtained without a physical tap on a screen showing the true rpId.
• PINs are entered on-screen (a FIDO clientPIN/UV, a device PIN, and the OpenPGP / PIV PINs over CCID) and never cross USB.
• An on-device browser lets you inspect and prune credentials (delete a passkey, read the applet state) without a host.

The whole feature is dep:-gated. A standard key without a screen compiles none of the UI or driver code (the gate asserts the rsk-ui crate is absent from the default firmware image), so an ordinary build is byte-for-byte unaffected.

The full GUI uses always-on antialiasing. Text uses four-bit IBM Plex Sans and Mono coverage data. Icons, circles, status rings, rounded cards, and controls blend their edges into the surface below them. The device does this with integer math and retained panel writes. It does not use a framebuffer or a heap. A full page is recorded once as compact drawing commands. The firmware compares keyed 128-bit tags for 32×32 visual-state tiles and merges the changed tiles. Typed UI components can provide smaller exact damage before composition. Each changed rectangle uses two 8-row RGB565 buffers while PIO DMA sends the other buffer. Common background rows are copied from raster templates in flash instead of being generated for every band. The buffers use the active stack and do not reduce permanent RAM. RLE checkpoints and a vertical command index let each band start at its own data. One panel address window stays open for each rectangle. Small animations still use direct partial redraws, and there is no antialiasing setting to manage. A scene or SPI failure stops UI input before an incomplete prompt can stay active.

The display build runs the RP2350 at 160 MHz. A TX-only PIO program emits one serial bit every two cycles, for an 80 MHz panel clock. A complete 240×320 RGB565 transfer has a 15.36 ms wire-time floor.

Try it without a board

The screens on this page are not photographs — they are what rsk_ui::render draws, at the panel’s own 240×320. The same renderer runs in a window:

cargo run --manifest-path tools/emu/Cargo.toml --target "$HOST" -- --display

That is the whole flow, not a viewer. The ambient loop, the Approve/Deny hold, the on-screen PIN pad and the Settings menu are the code the board runs (crates/rsk-display); a mouse held on a button enters it through the same TouchPad a finger does, and the power button is the space bar. So the ceremony this page is about — a signature cannot be had without a tap on a screen naming the true relying party — can be tried before deciding whether to buy the hardware.

--taps <file> replaces the mouse with a script — one contact per line, x,y[,hold_ms[,gap_ms]] in panel pixels, # for a comment — so a sequence that takes six taps to reach can be replayed instead of performed:

# Settings → Security → FIDO PIN
209,301
119,123
119,123

The images themselves are regenerated with rsk-emu --screenshots docs/images when a screen changes.

Building and flashing

The panel takes over the addressable-LED pin, so the display flavor is built LED_KIND=none (a compile-time guard enforces this) with the larger flash the UI assets want:

env LED_KIND=none FLASH_SIZE=16M cargo build --release -p firmware --features display
# or the hermetic package:
nix build .#firmware-display        # → result/firmware.uf2

GPIO16 (the WS2812 pin on a standard board) drives the backlight here. WAKE_PIN (default 25, the board’s BAT_PWR button) both wakes the panel from display sleep and, while awake, sleeps it on demand from any screen. A press blanks the panel and (when a device PIN is set) locks the on-device UI, aborting any host prompt it interrupts. See the full knob table in build.md; the display-only knobs are WAKE_PIN / WAKE_ACTIVE_HIGH.

Flash it like any other image (BOOTSEL → picotool load, hardware.md). Two notes:

• The build output is unsigned. On a secure-boot device you still picotool seal --sign it before loading (signing-keys.md, anti-rollback.md). The RP2350 boot ROM verifies the signature on boot.
• You can reach BOOTSEL from the panel itself: Settings → Firmware → reboot to BOOTSEL (a deliberate hold). The reboot routes through the worker so live RAM secrets are scrubbed first.

What’s on screen

A bottom navigation bar carries four peer tabs, each captioned:

Approve / Deny — the anti-phishing core

Any operation that needs user presence paints a trusted prompt naming the operation and the real relying party, and waits for a deliberate action:

• A WebAuthn registration shows a Save new passkey? card (relying party + account, Cancel / Save).
• A sign-in and the generic OpenPGP / PIV touch prompts share an approve screen (shield + relying party + a hold-to-approve button). Deny refuses with OPERATION_DENIED.

Every prompt waits for the previous finger to lift before it will accept a tap, and a prompt that runs out of time is denied rather than approved — a finger resting on Save when the window expires cancels the registration, it does not confirm it. The release wait has a floor of its own, so shortening the presence timeout in the device config cannot shrink it away.

Because the device only knows the relying-party string (and its hash), it shows that string verbatim, never a host-supplied brand logo. A relying-party id too long for the box is clipped with a truncation marker, and the clip keeps the registrable-domain suffix (a leading … ellipsis) rather than the head. So a padded look-alike such as accounts.google.com.attacker.com can never hide its real domain (…attacker.com) behind the cut.

This holds on every screen that shows an attacker-chosen rpId: the approve and enrollment prompts and the Passkeys manager’s list, service-detail title and Confirm-Delete card. A device-local nickname (which you set, not the host) keeps its head instead.

Entering a PIN on the trusted screen

The panel has an on-screen numeric PIN pad: digits are masked, an eye toggle reveals them briefly so you can check before committing, and the minimum length shows as placeholder dots. Every PIN screen names which credential it is collecting in the header (Device PIN, FIDO PIN, PIV PIN / PIV PUK, or the OpenPGP PINs), so the independent PINs are never confused. The New / Confirm / current step rides in the caption beneath. The PIN never leaves the device.

Whichever way the PIN arrives — typed on the pad or sent by the host — the panel asks before a pinUvAuthToken is issued (CTAP 2.1 §6.5.5.7 requires the consent on any authenticator with a display). Declining ends the operation with OPERATION_DENIED and costs no PIN retry, since the question comes before the PIN is checked. So ykman fido and anything else needing a token waits on a tap here.

This backs four things:

• Built-in user verification. getInfo advertises options.uv. A PIN typed on the pad mints a pinUvAuthToken via clientPIN (getPinUvAuthTokenUsingUvWithPermissions), checked against the same EF_PIN the host clientPIN path uses. A platform can also skip the token: makeCredential / getAssertion carrying options: {uv: true} collect the PIN on the pad directly (CTAP 2.1 §6.1.2 step 11.2), and that entry counts as the ceremony’s user presence, so the response sets up without the spec requiring a second gesture. The panel still asks: pad first, then the Approve / Deny card, because that card is the only screen naming the relying party — the pad carries a trusted, firmware-supplied title and never relying-party text. With alwaysUv on, a request that brings no pinUvAuthParam takes the same route instead of being refused with PUAT_REQUIRED. Declining on the pad ends the operation with OPERATION_DENIED — deliberately, since the code CTAP would have the device send instead (PUAT_REQUIRED) asks the host to prompt for the same PIN, which would make the refusal meaningless. A wrong PIN still falls back to the host path.
• CCID secure PIN entry (pinpad). A display build advertises bPINSupport and handles PC_to_RDR_Secure, so GnuPG (OpenPGP PW1/PW3) and OpenSC (PIV PIN) collect the PIN on the trusted screen. The PIN never crosses USB in pinpad mode. Details and host-driver caveats: protocol.md §1.3.
• U2F under alwaysUv. A screenless key has to switch CTAP1/U2F off once alwaysUv is on, since a touch proves no verification. A pad with a PIN set is the exception CTAP 2.1 §7.2.4 allows, so U2F keeps working here — each register and authenticate names itself on screen (Register key? / Sign in?) and then collects the PIN on the panel. Turning alwaysUv on before setting a PIN still disables it; there would be nothing to verify against.
• First-run onboarding. A fresh, PIN-less device offers a Set a PIN? screen at first run. Declining is remembered (a flag in EF_DISPLAY) so the offer isn’t repeated until a factory reset.

Passkeys

The Passkeys tab lists resident credentials by relying party (real rpId + account count) and drills into a per-account detail where a passkey can be deleted on-device (gated by the device PIN, then a hold), decrypted on the device, never on the host. The detail’s pencil opens a character-wheel rename that sets a short device-local nickname for the relying party, shown in place of its rpId. The nickname is sealed at rest (a dedicated EF_RPNICK region), wiped by a reset, and (unlike a host updateUserInformation) never re-seals the credential, so the passkey keeps working. The trade-off: the nickname is device-local and not seen by host credential managers.

Apps — a read-only credential browser

The Apps tab reads applet state without a PIN. No key material, PIN or public point is ever shown, and no OATH code is computed (the device has no clock).

• OpenPGP: the Signature / Encryption / Authentication slots with each one’s algorithm, the signature counter and PW1/PW3 attempts; a per-slot detail with the SHA-1 fingerprint and touch policy; and a Card holder row (name / login / URL / language).
• PIV: the 9A/9C/9D/9E slots with algorithm and PIN/PUK attempts, a per-slot detail (PIN/touch policy, key origin, cert presence), and a Retired & F9 row listing the populated retired key-management slots (82–95) and F9. From it, Generate key creates a key (EC P-256/P-384, Ed25519, X25519, or RSA 2048/3072/4096) into the next free retired slot, gated by the device PIN and a hold, restricted to empty slots (add-only, never overwrite). There is no management-key auth: physical presence at the panel is the authorisation.
• OATH: the stored credentials (label, TOTP/HOTP, a padlock when touch-gated), each with a detail (type, HMAC algorithm, digits, TOTP step).

Settings

Grouped into three domains, plus the journal / backup / reset actions:

• Display: backlight brightness (PWM), the display-sleep timeout, and the touch timeout, each adjusted live. All three persist across reboots: brightness and sleep in an EF_DISPLAY flash record; the touch timeout in EF_PHY’s PresenceTimeout, the same field rsk hw --touch-timeout writes, so the panel and the host tool stay in sync.
• Security: set / change the device PIN and the FIDO clientPIN (each chosen entirely on the panel). Changing the clientPIN asks for the current one first, and that prompt is the card’s changePIN check: a wrong entry spends a retry and ends any pinUvAuthToken a plugged-in platform holds, exactly as a wrong old PIN sent over USB does — the platform just asks for the PIN again. Then a PIV PIN sub-menu: change the PIV PIN, change the PUK, unblock a blocked PIN with the PUK, or protect the management key. Protect mgmt key generates a random AES-256 management key, seals it and marks it PIN-protected, the ykman --protect scheme, so a host then uses the management key with just the PIV PIN (which alone grants management access, a trade-off the panel states and gates behind the device PIN and a hold). Any existing host PivmanData (its PIN-change timestamp and other flags) is preserved (the obsolete derived-key salt is dropped, exactly as ykman does). Last on the page, Scramble PIN pad — a toggle, off by default. On, the ten digit keys are laid out afresh at random for every PIN entry (and again between the “New PIN” and “Confirm PIN” steps), so a fingerprint trail, a worn patch of glass, or an onlooker who sees your hand but not the panel learns nothing from where you tapped. It buys nothing against anyone who can see the screen — they read the digits off it — and it costs muscle memory: entry is slower and mistyping is likelier, against a limit of three wrong PINs per power cycle. That trade is the owner’s to make, which is why it ships off.
• Firmware: the installed bcdDevice build and chip serial, the real OTP secure-boot fuse state (it warns when secure boot is off rather than claiming a check it isn’t doing), and the hold-to-reboot into BOOTSEL for an over-USB update.

• Audit log: the most recent device-journal events (sign-ins, passkeys added, PIN changes, lockouts, resets, power cycles), colour-coded, newest first.

• Backup. An honest view of the recovery-seed export window: whether a seed is present and whether its one-time export has been sealed. While the window is open, Show recovery (gated by the device PIN) paints a 24-word BIP-39 phrase or a T-of-N SLIP-39 share set on the trusted screen, derived on the device, never crossing USB, behind a hold + warning, wiped the instant they’re shown. Seal backup closes the window for good (until a factory reset). See seed-backup.md.

• Factory reset: erases every applet’s data (FIDO, PIV, OpenPGP, OATH), scrubs the flash, and reboots to a blank device (gated by the device PIN, then a hold). Only the org attestation and the fused OTP / secure-boot state survive.

A display build is also exempt from the power-up window that makes a screenless key refuse a host authenticatorReset more than ten seconds after it was plugged in. That window exists to stop a wipe being approved by a press collected under some other pretext; here the panel names the operation, so a host reset is accepted whenever you confirm it on screen — no replug.

Security model

The device PIN (EF_DEVICE_PIN, its own sealed record + retry counter) gates the on-device UI (unlock, on-device delete, factory reset) independently of FIDO. The device boot-locks when a device PIN is set. A forgotten device PIN is cleared only by a host authenticatorReset (the sole recovery, since the lock gates on-device Settings). Every device-driven ceremony (a granted Approve, an on-device delete, a factory wipe) ends on a brief success confirmation.

This is an experimental variant. Read threat-model.md and limitations.md for what the trusted display does and does not defend against.

See also

• Build options: the display feature and its knobs.
• Hardware: boards and flashing.
• Host protocol §1.3: CCID pinpad secure PIN entry.
• FIDO2 / WebAuthn · PIV · OpenPGP · Seed backup.

rsk-tui — the terminal cockpit

rsk-tui is a host-side dashboard for an RS-Key. It talks to the device directly (CTAPHID over hidapi and the CCID applets over PC/SC), so it does not shell out to rsk or any other process. It lives in its own workspace (tools/tui), separate from the firmware, and links the host PC/SC and HID stacks.

It is a companion to the rsk CLI, not a replacement: the cockpit covers the safe, day-to-day reads and a few in-band actions (LED, seed backup, reboot, audit, identity verify). Irreversible production rituals (secure-boot staging, OTP fuses, factory resets, soft-lock, attestation import) stay in the CLI on purpose. The cockpit points you at the exact command instead of doing them.

flowchart LR
    tui["rsk-tui (host process)"] -->|hidapi / CTAPHID| fido["Device — FIDO"]
    tui -->|PC/SC / pcscd| ccid["Device — CCID applets<br/>OpenPGP · PIV · OATH · OTP"]

Running it

In the dev shell rsk-tui is on PATH:

nix develop
rsk-tui              # interactive cockpit

Without Nix, run it from its workspace (the repo defaults to the firmware target, so name the host target explicitly; this is what the launcher does):

cargo run --release --manifest-path tools/tui/Cargo.toml \
  --target "$(rustc -vV | sed -n 's/host: //p')"

On Linux the CCID half needs pcscd + a polkit rule; see linux.md. FIDO works as soon as the udev rules are in place. If PC/SC is down, the cockpit still starts: the FIDO sections work and every CCID field shows CCID unavailable rather than a fabricated value.

Flags

--demo is handy for screenshots, docs, and trying the navigation without a key plugged in. Demo data is clearly labelled [DEMO] and every simulated action is prefixed [demo]; it never pretends to touch hardware.

--json and --once are the scriptable paths. Both gather one snapshot and exit, so they fit a health check or a CI probe. --json emits a stable, explicit object (identity, fido, backup, secure_boot, rollback, applets, led, pgp, piv_meta, errors, …); --once is the same data formatted for a human. Either honours --demo, so you can shape a pipeline against the mock first:

rsk-tui --json | jq '.secure_boot, .rollback'
rsk-tui --once --demo            # see the field layout without a key

--selftest drives the native MSE channel + clientPIN token + BIP-39 path end-to-end: export a seed, re-derive its fingerprint, restore it, confirm the fingerprint is stable, all without revealing the seed. It needs a no-touch firmware build (the touch build would block waiting for a button press), and takes the FIDO2 PIN as an optional positional argument if one is set.

It talks to real hardware, so it refuses two invocations that would otherwise mislead: a flag where the PIN should be (--selftest --demo would have sent the literal string --demo as the PIN, spending a real retry), and --demo in any position (it does not apply — there is no simulated round-trip).

A non-interactive snapshot of the simulated device (rsk-tui --once --demo) gives a sense of what the cockpit reads:

[DEMO — simulated device]
device     : serial 37bebfdca282 · fw 5.7.4 · bcd 0x0759
transports : HID present  PC/SC present  CCID present
serial     : 37bebfdca282523b
firmware   : 5.7.4  bcdDevice 0x0759  sdk 3.4
fido       : U2F_V2, FIDO_2_0, FIDO_2_1  clientPin=true
backup     : sealed=false  has_seed=true
seed lock  : off
secure boot: ENABLED (not locked)  (enabled=true locked=false bootkey=0x1)
rollback   : not required  boot version 0/48
org attest : not installed
applets    : OpenPGP present  PIV present  OATH present  OTP present
openpgp    : 2 keys  serial 2a1b3c4d  retries PW1 3 RC 0 PW3 3
piv        : PIN 3/3 tries (default)
led        : steady  idle cyan  processing blue  touch green  boot white

Layout

┌ header: app · health · device identity · refreshed ─────────────┐
│ sections │ selected section: status fields + action menu        │
│  …       │                                                      │
├──────────┴──────────────────────────────────────────────────────┤
│ events: recent operations and errors                            │
├─────────────────────────────────────────────────────────────────┤
│ last result · key bindings                                      │
└─────────────────────────────────────────────────────────────────┘

The sidebar narrows and the event panel drops away on small terminals; the UI keeps working down to a few rows. Status uses an OK / WARN / ERR / UNK / N/A word plus a colored glyph, so it reads on a monochrome or color-blind terminal. N/A is reserved for things the device supports but the TUI deliberately leaves to the CLI. It is never a faked or unknown value. Set RSK_TUI_ASCII=1 (or run in a non-UTF-8 locale) to force ASCII glyphs ([+] [!] [x] [?] [-] instead of ● ▲ ✖ ○ –); a UTF-8 LANG/LC_* is auto-detected otherwise.

Key bindings

The status also auto-refreshes every few seconds while you are in the normal view, never while a modal is open, so a read can’t redraw over a PIN prompt or hammer the CCID bus mid-task.

Inside a modal the keys narrow to that modal: a text/PIN input takes characters + Backspace, Enter submits, Esc cancels (and wipes the buffer); a yes/no prompt takes y/n or Enter/Esc; a reveal panel dismisses on any key (a shoulder-surfed secret clears fast); a message panel (audit output, LED state, a verify report) scrolls with the arrows / j k / PgUp / PgDn / Home / End and closes on Enter, Esc, q, or space. The / palette filters by a case-insensitive substring of the action label as you type, ↑/↓ pick, Enter jumps to that action’s section and starts it.

Sections and what they do

OpenPGP and PIV show a little more than presence, from unauthenticated reads in the same gather: OpenPGP parses its 6E application-related data (card serial, the PW1/RC/PW3 retry counters, and how many of the three key slots hold a key); PIV reads the PIN’s GET METADATA (retries left, and whether the PIN is still the factory default). OATH and OTP stay presence only. The full card contents (individual keys, accounts) still need the applet’s own tooling, so those rows point you at it: gpg --card-status (openpgp.md), ykman piv info, ykman oath accounts, and so on.

Verify identity issues a fresh 16-byte challenge, has the device sign it with its DEVK-derived P-256 attestation key (vendor AUDIT_CHECKPOINT), and verifies the ECDSA signature locally over tag‖head‖seq‖challenge. This is a real cryptographic check, not a display of device-asserted bytes. On success it prints an 8-byte fingerprint of the attestation public key. Record that fingerprint: a later rsk inventory verify --expect-key <hex> (or rsk audit verify --expect-key …) pins it, so a swapped or cloned board fails the check instead of quietly verifying. Verify needs a touch, the FIDO2 PIN if one is set, and a provisioned OTP DEVK. Without the DEVK it says no OTP DEVK provisioned — attestation unavailable rather than guessing.

Read journal dumps the tamper-evident audit log (vendor AUDIT_READ): a hash-chained sequence of events (BOOT, MAKE_CREDENTIAL, GET_ASSERTION, PIN_SET, BACKUP_EXPORT, CHECKPOINT, …) folded into an epoch, with the running chain head. It is read-only (the device never lets the host rewrite it) and asks for the FIDO2 PIN if one is set, or a physical touch if not. The full cross-check against the signed head lives in rsk audit verify.

LED reads the four LED states the firmware drives (idle, processing, touch, boot), each with a color and brightness, plus whether the idle LED is steady or blinking. The section paints a colour swatch beside each state — a background-filled block, so it shows with no block-glyph support, and the colour name is printed too — refreshed live with the status. Cycle idle color steps the idle color through the palette (red → green → blue → yellow → magenta → cyan → white, then wraps) and writes it back; it is a cosmetic, unauthenticated setting, not a security control.

PINs in the cockpit

Every PIN the TUI asks for is the FIDO2 clientPIN (the same one rsk fido set-pin manages), not an OpenPGP PW1/PW3 or a PIV PIN. It gates the in-band actions that need it: Verify, Read journal, and seed Export/Restore (when a PIN is set). If no clientPIN is set, those actions skip the prompt. OpenPGP and PIV PINs are only ever entered in their own tools (gpg, ykman), never here.

CLI-only / unsupported in the TUI

These are surfaced as menu entries that, when selected, print the exact command to run. They are never performed from the cockpit:

• FIDO: set/change PIN (rsk fido set-pin), list resident passkeys (rsk fido list-passkeys --pin …), factory reset (ykman fido reset)
• OpenPGP / PIV / OATH / OTP: full card data and factory resets (gpg --card-status, ykman piv info, ykman oath accounts, rsk openpgp reset, ykman piv reset, …). The ykman commands gate on the “Yubico YubiKey” reader name, so they only see the device on the opt-in VIDPID=Yubikey5 build; gpg and rsk work on the default RS-Key build.
• Backup: SLIP-39 restore (recombining shares): rsk backup restore --scheme slip39. SLIP-39 export is now in the cockpit (2-of-3 shares, via the in-tree rsk-slip39 crate); other T-of-N splits stay in the CLI (seed-backup.md)
• Maintenance (Reboot section): seed soft-lock (rsk lock enable | unlock | disable), org-attestation import/clear (rsk fido attestation import | clear), secure-boot staging, OTP fuses. See production.md and otp-fuses.md

The FIDO section’s Count resident passkeys action reads the count over credMgmt getCredsMetadata. It needs the FIDO2 PIN — there is no unauthenticated way to read it — and reports how many passkeys are stored plus roughly how many slots remain. Enumerating the passkeys themselves stays in the CLI: rsk fido list-passkeys --pin ….

Safety model — what is and is not logged

• Destructive or irreversible operations require a typed confirmation, not a single keypress: export (EXPORT), restore (RESTORE), finalize/seal (SEAL), reboot to BOOTSEL (BOOTSEL). The typed word must match exactly (case-sensitive); anything else cancels the action. Reboot to app uses a yes/no prompt. Finalize is refused outright once the window is already sealed. It explains rather than re-confirming.
• PINs are masked on entry and never written to the event log. The log additionally redacts any live PIN/phrase substring as a backstop, and it is a bounded ring (the last 200 lines), so nothing accumulates on disk. It is only ever in memory.
• The seed is shown only after you confirm export. It appears once, in a modal, is zeroized from memory when you press a key, and never reaches the event log or any file. The same goes for a restore phrase you type in.
• Sensitive buffers (PIN, phrase, revealed seed) are wiped (zeroize) on cancel, on submit, and on Ctrl-C. Ctrl-C wipes the in-flight buffer before it quits, from any modal.
• The terminal is restored on every exit path: q, Ctrl-C, an I/O error, or a panic (device I/O can panic, so a panic hook leaves the alternate screen and raw mode first).

The seed backup flows here are exactly the BIP-39 export/restore/finalize of rsk backup, just interactive: same touch + PIN + setup-window gates, same forever-sealed semantics after finalize. Read seed-backup.md for what a backup does and does not recover before you rely on it.

Architecture (for contributors)

tools/tui/src is split so rendering, state, and I/O stay separate and the UI is testable without hardware:

• model.rs: typed state (DeviceSnapshot, TransportStatus, Section, Action, ActionResult, EventLog, …) and --json serialization. No I/O.
• device.rs: native CTAPHID + PC/SC I/O behind a DeviceProvider trait, with HardwareProvider (real) and MockProvider (--demo). Holds the native seed backup crypto: the MSE channel (P-256 ECDH → HKDF → ChaCha20-Poly1305) and the clientPIN protocol-two token (ECDH + HKDF + AES-CBC + HMAC).
• app.rs: app state, navigation, and the modal/confirmation flow.
• actions.rs: action dispatch + result handling (the one place that blocks on device I/O; it paints a “working — touch the device…” line and redraws before the blocking call so the prompt is visible).
• input.rs: key handling → state change + Flow.
• ui.rs: rendering only.
• theme.rs: styles, colors, ASCII fallback.

Because the UI is driven by a DeviceProvider, the whole cockpit (navigation, confirmation flows, secret redaction, rendering) is unit-tested against the mock with no device attached.

# fmt / clippy / test / build, host target (the merge gate runs these too):
H="$(rustc -vV | sed -n 's/host: //p')"
cargo fmt   --manifest-path tools/tui/Cargo.toml --check
cargo clippy --manifest-path tools/tui/Cargo.toml --target "$H" --all-targets -- -D warnings
cargo test   --manifest-path tools/tui/Cargo.toml --target "$H"
cargo build --release --manifest-path tools/tui/Cargo.toml --target "$H"

The --target "$H" is load-bearing: the repo’s .cargo/config.toml defaults to the thumbv8m firmware target, and tools/tui is a detached workspace (note the empty [workspace] table in its Cargo.toml) precisely so it builds for the host instead. See build.md for the workspace layout.

Audit journal

A tamper-evident, on-device log of security events: boots, FIDO registrations and logins, factory resets, PIN set/change/lockouts, policy changes, seed backup and soft-lock activity.

rsk audit log              # export + print (add --pin if a PIN is set)
rsk audit verify           # log + DEVK-signed checkpoint (touch)
rsk audit verify --expect-key <hex>   # also pin the enrolled attestation key

log is a plain read. It pretty-prints the live window and the recomputed chain head, no signature. It takes --pin on a device with a PIN, and a touch on one with none (the read is never fully open). verify does the same read and asks the device to sign the head. It is the command that actually proves the log is real. Use log for a quick glance, verify when the answer matters.

What it records

Each entry is a fixed 20 bytes: seq(4) ‖ uptime_ms(4) ‖ event(1) ‖ aux(1) ‖ detail(8) ‖ repeats(2 LE). There is no wall clock on the device. uptime_ms counts from the moment the key attached to USB, not from power-on — boot spends seconds before that on TRNG seeding and flash migrations, and none of it is time a host could have used. Every power cycle opens with a BOOT entry, and the sequence number gives total order. Wall-clock attribution is the host’s job (e.g. record when you ran rsk audit verify).

For the FIDO operations — MAKE_CREDENTIAL, GET_ASSERTION, U2F_REGISTER, U2F_AUTH — the detail field carries the first 8 bytes of the rpIdHash and nothing else: no RP names, user handles, or credential IDs. That is deliberate: the log answers “how was this key used and how often” without revealing which sites. See gating below. Other events use detail for their own small payload (CFG_MIN_PIN’s forceChangePin flag, CONFIG_WRITE’s run counters); none of them records a site.

Events a silent host can drive cost one slot per run

The journal is append-only with one bounded exception. Three events can be driven on demand with no touch and no PIN, so 128 of any one of them would otherwise evict every other entry from the 128-slot window:

• CONFIG_WRITE, ungated on the default build;
• GET_ASSERTION from a getAssertion carrying up:false — the spec-mandated silent pre-flight, which needs a credential but no gesture;
• U2F_AUTH from an AUTHENTICATE with P1=0x08 (don’t-enforce-user-presence), for the same reason.

Each folds a run into a single entry that keeps the seq and the timestamp of the first occurrence. The two shapes differ in where the count lives. CONFIG_WRITE carries its own inside detail — repeats(2 LE) ‖ targets(1), where targets is a 1 << target mask of every record the run touched — and folds only into the newest entry. The two silent FIDO events instead keep the detail of the first occurrence (so the rpIdHash shown is the first site of the run) and count the rest in the entry’s trailing repeats(2 LE), scanning the whole window rather than only the newest entry, so interleaving two of them does not defeat the fold. A gestured assertion always earns its own slot. rsk audit log renders both:

   seq      uptime  event              aux  detail
   201       8.2s  CONFIG_WRITE         1  300× write (phy+led)
   202       9.1s  GET_ASSERTION        0  a3f1c2...  ×128

Two consequences worth knowing:

• A run never folds across a power cycle, so the BOOT entry between two runs is never swallowed.
• A fold moves the chain head without advancing seq_next. Seeing the same seq_next with a different head is legitimate, not a tamper signal; verify re-folds the exported window and still matches.

This bounds the flood, it does not remove it: a phy write latches a reboot, so a host willing to make the key re-enumerate can still spend two slots per cycle (a fresh BOOT plus a fresh run). Each cycle is a visible re-enumeration, and building --features strict-config — which puts the write behind a touch and a PIN token — is the complete answer.

A log run prints a header, the chain state, then the window:

window [72, 200)  —  128 entries, 72 folded into the epoch
epoch : 4f1c…           (the accumulator for evicted history)
head  : a93b…  (chain over the window — OK)

   seq      uptime  event              aux  detail
    72       3.4s  GET_ASSERTION        0  1a2b3c4d5e6f7081
    73     120.9s  MAKE_CREDENTIAL      0  9f8e7d6c5b4a3928
   …

How the tamper evidence works

The journal is a 128-entry flash ring. Each entry extends a SHA-256 hash chain; when the ring is full, the oldest entry is folded into an epoch accumulator (epoch' = SHA-256(epoch ‖ entry)) before its slot is reused, so evicted history stays attested in aggregate even though its per-event details are gone. The chain head is fold(epoch, window): the epoch run forward through every entry still in the ring.

The chain is anchored, on an empty journal, at SHA-256("RSK-AUDIT-GENESIS-v1" ‖ serial_hash), bound to the device so two boards’ empty journals never share a head.

flowchart TD
    e["new event"] --> chain["SHA-256 hash chain (window)"]
    chain -->|ring full| fold["fold oldest into epoch accumulator"]
    fold --> reuse["slot reused"]
    chain --> head["chain head = fold(epoch, window)"]

rsk audit verify sends a fresh 16-byte random challenge. The device signs "RSK-AUDIT-CKPT-v1" ‖ head ‖ seq_next ‖ challenge with an ECDSA P-256 key derived (HKDF) from the OTP DEVK (production.md stage 1) and returns the signature plus its 65-byte SEC1 public key. The host refolds the exported window, verifies the signature over the message it reconstructs, and checks that the signed head matches the refold. The challenge is what makes the verdict fresh. A replayed old checkpoint signs a stale challenge and fails.

A successful verify prints the window, the head, and the attestation key with a short fingerprint. The verdict depends on whether you pinned the key:

chain   : OK — head a93b…
sig     : OK — checkpoint over seq_next=201, fresh challenge
att key : 04a1b2…   (65-byte SEC1)
          fingerprint 9c4e7f12ab… — record this; pin later runs with --expect-key
verdict : chain + signature OK — the key is NOT pinned, so this does not prove
          which device signed it

With --expect-key the last line becomes journal authentic ✓ (signed by the pinned key).

Meta updates are ordered so that a power cut at any point loses at most the newest event and never produces a false tamper verdict: when the ring is full the fold-and-advance meta is committed before the slot is reused.

Pinning the attestation key — --expect-key

The checkpoint key is deterministic and reset-stable (HKDF of the DEVK), so a given device always signs with the same public key. Record it once at provisioning, then pass it back on every later run:

rsk audit verify                         # first run: copy the printed "att key" hex
rsk audit verify --expect-key 04a1b2…    # afterwards: fail loudly on any mismatch
rsk audit verify --expect-key 9c4e7f12ab…   # the short fingerprint works too

A mismatch means the public key changed, which can only happen if the DEVK changed. That means you are talking to a different device, or a clone that was flashed without burning the same OTP. --expect-key takes either the full 65-byte SEC1 point (04 ‖ x ‖ y) or the 16-hex fingerprint, lower-case, and the comparison is exact. The full key is the stronger pin. Stash it in your provisioning record alongside the device serial.

Without a pin, verify proves nothing about identity. The public key it checks against arrives in the same response it is checking, so an unpinned run establishes only that the journal is internally consistent and self-signed — a counterfeit signing with a key of its own passes it. The device refuses to sign without an OTP DEVK, but a host cannot tell a DEVK-derived key from any other P-256 point. Pinning is what turns “some key” into “your device”.

Reset semantics (privacy by design)

authenticatorReset does not erase the journal. It folds the whole window into the epoch and deletes the per-event details, then logs the RESET. A handed-over device therefore proves “N events happened, then a reset” without revealing where it had been used. The chain (and the checkpoint key, which is DEVK-derived) continue uninterrupted across resets, so verify keeps working and the head still validates against the same --expect-key.

Gating

• AUDIT_READ (export). With a PIN set it needs a pinUvAuthToken carrying the acfg (authenticator-config) permission. With no PIN it needs a physical touch. The entries are only weakly pseudonymous. A detail is a 64-bit rpIdHash prefix, never an RP name or user handle, but short enough to be dictionary-matched back to a domain. So the touch is what stops a silent host from harvesting a no-PIN device’s RP-usage history.
• AUDIT_CHECKPOINT. The same PIN gate plus a physical touch, and it refuses entirely without a provisioned OTP DEVK. An attestation that anyone could re-derive would be theatre. The signing step is what the touch protects. The read that precedes it is AUDIT_READ-gated as above.

If a PIN is set, both subcommands take --pin. The PIN is exchanged over the standard CTAP pinUvAuth protocol (it is not sent in clear), and a wrong PIN counts against the FIDO retry counter. Do not guess.

Troubleshooting

The two “rerun first” verdicts are different. A head mismatch can happen benignly if an event landed between the read and the checkpoint (a login on another host, say). One rerun usually clears it. A signature failure or a key mismatch never has a benign cause. Do not retry your way past those.

What it does and does not prove

The log is written by the firmware, so its honesty is rooted in the boot chain: with secure boot + the OTP master key (production.md, otp-fuses.md) only your signed firmware can append to the journal or wield the checkpoint key, and a flash dump cannot forge it. On an unprovisioned dev board the journal still works as a debugging aid, but verify is refused. There is no device-bound key to sign with, and a checkpoint without one would prove nothing.

Two honest limits worth stating:

• The window is 128 entries. Older events are folded into the epoch and their details are gone. You can prove they happened (the head still covers them) but not read them back. verify regularly if you want a per-event record. The host transcript is your archive, the device is not.
• There is no wall clock. The device cannot tell you when in calendar time something happened, only the order and the milliseconds since that power cycle’s USB attach. Pair the seq and BOOT markers with your own host-side timestamps.

Enterprise attestation (org provisioning)

Out of the box, ordinary makeCredential returns packed basic attestation: an ES256 signature by the device key over authData ‖ clientDataHash, with the device’s own certificate as the x5c leaf. That certificate is a per-device P-256 X.509 leaf (subject C=XX, O=RS-Key, OU=Authenticator Attestation, CN=RS-Key FIDO2) built over the seed at first boot, and U2F registration presents the same one.

The two alternatives were both tried and both break clients. fmt:"none" with an empty statement is rejected by OpenSSH below 10.0, which hands every credential without a certificate to libfido2’s fido_cred_verify_self() regardless of format. Packed self-attestation signs with the credential key and so inherits its algorithm, and an Ed25519 statement fails on Windows WinHello, which broke ed25519-sk enrollment (issue #26). Basic attestation signs with ES256 whatever the credential algorithm is, so neither path is reached.

Because the leaf is per-device it is a stable identifier: every relying party that asks for attestation sees the same certificate, and two of them can tell they met the same key. Browsers strip it unless the site explicitly requests attestation: "direct" (WebAuthn §5.1.3 replaces the statement otherwise), but native CTAP clients do not. There is also no root to publish — a per-device self-signed leaf chains to nothing, so attestationRootCertificates in the metadata statement stays empty and a relying party that requires a trusted anchor will treat the attestation as untrusted.

An organization can replace that device cert with its own attestation key and certificate chain, so its relying parties can verify “this credential was created on one of our keys”. This is the CTAP 2.1 enterprise-attestation (EA) feature.

This page is for the team that provisions fleet keys. If you do not work for an org that has provisioned yours, it is a no-op: nothing here changes how an unprovisioned key behaves, and EA is never served unless a managed platform explicitly asks for it.

The key + chain model

Two pieces of state make up an org attestation, stored separately on the device:

The key signs each attestation; the chain is what relying parties walk back to your CA. The leaf’s public key must match the imported scalar. The device does not check this (framing only), so a key/chain mismatch surfaces as your own relying party’s first signature-verification failure, not an import error.

Provisioning

Generate an attestation CA and a leaf however your PKI does it. The leaf’s subject public key must be the P-256 point of the private key you import; only P-256 (secp256r1) keys are accepted. rsk rejects any other curve before it touches the device.

# host-side, with your PKI:
#   org-att.pem    P-256 private key (PEM)
#   org-chain.pem  leaf cert first, then intermediates, then (optionally) the CA
rsk fido attestation import --key org-att.pem --chain org-chain.pem [--pin …]
rsk fido attestation status

--chain takes a PEM bundle (concatenated -----BEGIN CERTIFICATE----- blocks) or already-concatenated DER. Limits, enforced host-side and again in firmware:

status is ungated and prints whether a chain is installed plus the SHA-256 of the packed chain (so you can confirm a fleet is on the right CA without moving any secret):

$ rsk fido attestation status
org attestation : installed
chain hash      : 9f2c…

To roll back to the factory self-signed cert:

rsk fido attestation clear [--pin …]

What changes once a chain is installed

• makeCredential with enterpriseAttestation 2 (platform-managed, sent by managed platforms) returns a full attestation: signature by the org key, x5c = your chain (leaf first), and the ep response flag (true). Level 1 (vendor-facilitated) does the same, but only for a relying party on the device’s enterprise RP list — which is empty until you write it, so a level-1 request from an unlisted RP gets the ordinary per-device attestation and no ep.
• U2F / CTAP1 registration attests with the chain’s leaf instead of the self-signed device cert (classic batch attestation: a U2F response carries exactly one certificate, so only the leaf travels).
• Ordinary makeCredential is untouched: packed basic attestation under the device’s own certificate, no org chain. EA fires only when the platform sets the enterpriseAttestation request field and enableEnterpriseAttestation is on (below).

Without an org chain (the default)

If no org key is provisioned, the request field still has an effect, per the spec:

Without an org key every level answers with the same per-device basic attestation; what an EA request adds is the org chain and the ep response flag. The device key and that self-signed cert are the same pair U2F register uses.

Enabling EA on the device (enableEnterpriseAttestation)

Importing the key is not enough. A makeCredential with the EA field is honored only after enableEnterpriseAttestation (CTAP 2.1 authenticatorConfig, subcommand 0x01) has been issued. RS-Key has no rsk command for this. It is the managed platform’s job (the OS/MDM/browser stack that drives EA), and it requires an acfg pinUvAuthToken, i.e. a FIDO PIN must be set. getInfo reports the current state in the ep option, which the firmware mirrors straight from EF_EA_ENABLED:

# python-fido2, the same library `rsk` uses:
python3 - <<'PY'
from fido2.hid import CtapHidDevice
from fido2.ctap2 import Ctap2
info = Ctap2(next(CtapHidDevice.list_devices())).info
print("ep =", info.options.get("ep"))   # True once enableEnterpriseAttestation ran
PY

enableEnterpriseAttestation persists across power cycles. It is written to flash (EF_EA_ENABLED), as CTAP 2.1 specifies. It is cleared only by authenticatorReset (see below).

Who gets vendor-facilitated (type 1) EA

Level 2 applies to every relying party the moment EA is enabled. Level 1 is narrower by design: the spec leaves it to the vendor to say which RPs qualify, so RS-Key keeps a list of relying parties on the device and honors a level-1 request only for one of them. The list holds up to 8 entries, is stored as sha256(rpId) (EF_EA_RPIDS), and is empty on a device that has never been told otherwise — including one upgraded from an older firmware. Until you write it, level 1 qualifies nobody, which is exactly how RS-Key behaved before the list existed.

rsk fido attestation set-rpids sso.corp.example vpn.corp.example
rsk fido attestation set-rpids --clear

Each write replaces the whole list — there is no add or remove, and no read path: the device never hands the list back, so keep your own copy of what you sent. More than 8 ids is refused outright (CTAP2_ERR_KEY_STORE_FULL) and the previous list stays in place; nothing is ever silently truncated. The ids travel as text and are hashed on the device, so the stored form cannot disagree with what makeCredential compares against.

Authorization is the same as enableEnterpriseAttestation: an acfg pinUvAuthToken, i.e. a FIDO PIN, and no touch. The list alone grants nothing — with EA disabled, every level-1 request is still rejected outright — so the touch that guards the seed would buy nothing here. Each write lands in the audit journal as CFG_EA_RPIDS, with the new entry count as its aux.

Under the hood it is authenticatorConfig (0x0D) subCommand vendorPrototype (0xFF), vendorCommandId 0x0e6841934e719be7, rpIds at subCommandParams key 4 — specified in protocol.md for third-party tools.

Transport and gating

The P-256 private scalar crosses USB ChaCha20-Poly1305-wrapped on the same ephemeral-ECDH channel (MSE handshake: P-256 ECDH → HKDF-SHA256 → ChaCha20-Poly1305) the seed backup uses. The chain is public certificate material and travels in the clear, MAC-covered by the PIN token like every subcommand parameter.

Import (0x09) and clear (0x0A) are gated exactly like a seed move: channel + PIN (when one is set) + physical touch. On this board the touch is the BOOTSEL button (build.md). On a device with no PIN the import asks for a second, named confirmation first (“Replace attestation identity?”): the PIN half of the gate is waived in that state, and one generic touch should not hand over the identity every later U2F registration signs with. status (0x0B) is ungated; the chain it returns is public. Both mutations land in the audit journal (ATT_IMPORT / ATT_CLEAR), and so does an enableEnterpriseAttestation (CFG_EA).

rsk fido attestation import …    # → "touch the device (BOOTSEL) to authorise…"
rsk fido attestation clear …     # → "touch the device (BOOTSEL) to remove…"

On the device the key is sealed under the same kbase arms as the master seed. The seal tag records which arm wrapped it, so importing before or after the OTP burn both stay loadable. Burn the OTP master key before importing and the sealed attestation key is rooted in fuses, not just flash (otp-fuses.md).

Reset semantics

authenticatorReset wipes FIDO user state, but the org provisioning splits across that line:

So a factory reset leaves the org attestation installed but switches EA off and forgets who qualified for level 1: the managed platform must re-issue enableEnterpriseAttestation, and an administrator must re-send the RP list, before level-1 EA fires again. The reset itself is recorded in the audit journal. Removing the key and chain is the explicit, gated attestation clear. Nothing else clears them.

Privacy note

A shared org chain makes credentials linkable to the organization across its relying parties. That is the entire point of EA, and why the spec gates it behind both an explicit per-request field and a device-wide enable. Ordinary (non-EA) makeCredential still carries the per-device certificate, which is linkable to the device but not to the organization; the org chain is served only on explicit EA requests.

Troubleshooting

• attestation key must be P-256 (got …): the --key PEM is the wrong curve. RS-Key attests with ECDSA P-256 only. Re-issue the org key on secp256r1.
• chain too large (… B, max 2048): trim the bundle. You rarely need the root CA in x5c; leaf + one intermediate is usually enough, and the leaf alone is all U2F can carry.
• device requires a PIN — pass --pin (status 0x36): import/clear are gated; set a FIDO PIN first (rsk fido set-pin) and pass it.
• An EA makeCredential comes back self-attested (no x5c, no ep). Either enableEnterpriseAttestation was never issued (check options.ep), or it was cleared by a factory reset. Have the managed platform re-enable it.
• import failed: 0x33 (PIN_AUTH_INVALID): the PIN was wrong, or its token lacked the acfg permission. Re-run with the correct --pin (do not guess, wrong attempts burn PIN retries).
• The import hangs at “touch the device…”: the physical touch never arrived. Press the BOOTSEL button while the prompt is up, then it completes.

AAGUID & metadata

Every FIDO2 authenticator model carries an AAGUID, a 128-bit identifier that says “this is a Model X authenticator.” It rides inside the attested credential data of every makeCredential. A relying party (RP) uses it to look up the model’s Metadata Statement: a machine-readable description of what the model can do and how it attests.

This page explains RS-Key’s AAGUID, the self-published Metadata Statement that ships in the repo, and (importantly) the line between what that buys you for free and what is gated behind FIDO certification.

RS-Key’s AAGUID

2479c7bf-6b30-5683-9ec8-0e8171a918b7

It is a UUIDv5, derived reproducibly so its provenance is self-evident:

python -c 'import uuid; print(uuid.uuid5(uuid.NAMESPACE_URL, "https://github.com/TheMaxMur/RS-Key"))'
# -> 2479c7bf-6b30-5683-9ec8-0e8171a918b7

An AAGUID is self-assigned. No central registration is required to pick one. Earlier RS-Key builds inherited an upstream AAGUID (the bytes of SHA-256("Pico FIDO2")), which meant the device claimed another project’s model identity. As of firmware bcdDevice 0x075F it carries its own.

A few consequences worth knowing:

• One AAGUID for every flavor. It identifies the firmware model, not the USB branding, so the default pid.codes identity and the opt-in YubiKey-identity interop build report the same AAGUID. The YubiKey-identity build deliberately does not claim a real YubiKey AAGUID. That would be a forgery and would fail attestation anyway (it cannot chain to Yubico’s roots).
• Existing credentials keep working. The AAGUID only appears in attestation at registration time. Resident keys made on an older build still assert fine. Only new registrations report the new AAGUID. An RP that pinned the old AAGUID for attestation matching would need a re-enroll.
• Build-time override. AAGUID=<uuid-or-32-hex> cargo build bakes a custom AAGUID (build.rs validates it, consts.rs const-parses it); omit the flag to keep the default above. A non-default build makes the checked-in Metadata Statement (and the drift guard below) no longer match — reserve it for a fork that ships its own metadata, not a cosmetic tweak.

The Metadata Statement

metadata/rs-key.metadata.json is a FIDO Metadata Statement v3.1.1 describing the default build profile. It declares the AAGUID, the supported authentication algorithms, the attestation type, key/matcher protection, and an embedded authenticatorGetInfo that mirrors exactly what the device returns to authenticatorGetInfo (CTAP 0x04).

A drift guard, tests/62_metadata_statement.py, checks the statement against both the firmware source (the default AAGUID in build.rs) and a live device (the embedded authenticatorGetInfo vs the real one). Run it by hand. It is not in the hardware gate.

Two caveats baked into the statement

• ML-DSA is not expressible. RS-Key implements post-quantum credential types (COSE -48 / -49, ML-DSA-44 / ML-DSA-65), but the FIDO Metadata Statement registry has no enum value for ML-DSA/Dilithium, so they cannot appear in authenticationAlgorithms. They are visible only inside the embedded authenticatorGetInfo (and only on the advertise-pqc build). A strict MDS consumer will not see the PQC capability.
• One profile per statement. The build features advertise-pqc (adds COSE -48 to the algorithm list), fips-profile (drops secp256k1, raises the PIN floor to 6) and largeblob-ext (swaps the largeBlobKey extension, the largeBlobs option and maxSerializedLargeBlobArray for the CTAP 2.3 largeBlob extension) change getInfo. The shipped statement describes the default build. A different profile needs its own statement.

What this does — and does not — get you

RS-Key works as a passkey/security key with the overwhelming majority of relying parties without any of this. Self-attestation is accepted by GitHub, Google, Microsoft consumer accounts, browsers, ssh, and any RP that does not enforce attestation. The AAGUID and statement add a stable, honest identity and a machine-readable capability description for tooling that wants one.

The hard boundary is attestation enforcement. Taking Microsoft Entra ID as the strict reference:

That second row is a deliberate non-goal here: official MDS listing and FIDO certification require FIDO Alliance membership, a certification lab, and money, none of which is a code change. The self-published statement is the part that is actionable: an RP or library that can import a local metadata file (rather than only trusting the MDS BLOB) can consume it directly. If RS-Key is ever certified, the statement is already authored and ready to submit.

See also: Enterprise attestation for the org-provisioned cert-chain path, and the interop matrix for what has actually been observed working on hardware.

Fleet tooling

Inventory, identity verification, and offboarding for a fleet of RS-Keys. Three commands cover the lifecycle:

list reads only ungated state, so it is safe against a whole hub of keys. verify is the enrollment anchor. offboard is destructive and is the only one of the three that changes the device.

Inventory

rsk inventory list          # human-readable, one block per key
rsk inventory list --json   # one JSON object per line, for scripting

Walks every connected key over both transports. Prints one record per device with serial, firmware version, bcdDevice (the build counter), secure-boot state, flash usage, FIDO options, backup/soft-lock state, org-attestation state:

device 37bebfdca282523b  (ccid+hid)
  firmware   : 5.7.4  bcdDevice 0x0748  sdk 8.6
  secure boot: LOCKED  (bootkey 0x0)
  flash      : 16711/1572864 B used, 469 files
  fido       : U2F_V2, FIDO_2_0  clientPin=True
  backup     : sealed=False has_seed=True  seed lock: off
  org attest : installed  chain sha256 74d9f98c3fb0bb5c…

The serial is the RP2350’s OTP chip id, read from the rescue applet’s SELECT response. It is unique per chip, unlike the USB descriptor serial (identical across devices). Everything list reads is gate-free: no PIN, no touch, safe to run against a hub full of keys.

secure boot decodes to one of three states: not enabled (a blank dev board), ENABLED (the SECURE_BOOT_ENABLE fuse is set but the key pages are not yet locked), LOCKED (fully sealed). The bootkey index is the active key slot. See otp-fuses.md for what those fuses mean and production.md for how they get burned.

With several keys connected the CCID and HID transports cannot be matched to one another, so the records stay separate (tagged ccid / hid). The output ends with a note: saying so. Plug keys in one at a time when you want a single merged ccid+hid record per device.

The --json records

--json prints one object per line (JSON Lines, pipe it to jq, not json.load). The fields present depend on which applets answered. A merged record carries all of them:

A foreign PC/SC reader that does not answer the rescue SELECT is skipped, not reported. list only emits records for things that identify as RS-Keys.

Dump a fleet sweep to a ledger keyed by serial:

rsk inventory list --json | jq -s '
  map(select(.serial)) | INDEX(.serial)' > fleet-$(date +%F).json

Flag any key not on the current firmware (replace with your floor):

rsk inventory list --json \
  | jq -r 'select(.bcd_device and (.bcd_device < "0x0759"))
           | "\(.serial // .product)\tstale \(.bcd_device)"'

Identity verification

rsk inventory verify                            # print the fingerprint (touch)
rsk inventory verify --expect-key 66573f74ca06359a   # pin it (--pin if set)
rsk inventory verify --expect-key 04ab…   # or the full 65-byte SEC1 pubkey

Challenge-response against the device’s attestation key: the host sends a fresh 16-byte challenge, the device signs it (vendor AUDIT_CHECKPOINT) with the ECDSA P-256 key derived from its OTP DEVK, and the host verifies the signature. The printed fingerprint (SHA-256 of the public key, first 16 hex digits) is the same one rsk audit verify prints. One identity anchor for both workflows.

sequenceDiagram
    participant H as Host
    participant D as Device
    H->>D: fresh 16-byte challenge
    D-->>H: ECDSA-P256 signature (OTP-DEVK key) + public key
    H->>H: verify signature, match fingerprint vs record

--expect-key accepts either form printed by a prior run: the 16-hex fingerprint or the full hex att key (65-byte uncompressed SEC1 point). Either matches. The full key is the stronger pin since the fingerprint is a truncated hash.

This only proves identity once the device has a provisioned OTP DEVK. On an unprovisioned dev board there is no device-bound key and verify is refused. The error messages map to the vendor status:

Enrollment: when you hand a key out, run rsk inventory verify once and record serial + fingerprint (or the full att key). Any later verify with --expect-key <fingerprint> (or the full SEC1 public key) proves you are talking to that physical chip. A clone without the OTP DEVK cannot answer. Every verify is itself journaled as a CHECKPOINT event, so the device’s audit log shows each time it was checked.

verify has no --json (only inventory list does), so at provisioning time capture the two lines from its plain output, or just paste them into your record by hand:

rsk inventory verify | sed -n 's/^\(serial\|fingerprint\) *: //p'

Offboarding

rsk offboard                       # guided, typed confirmation, a replug, ~3 touches
rsk offboard --report ret-42.json  # choose the receipt path
rsk offboard --no-receipt          # wipe only — no preflight, no receipt file
rsk offboard --verify ret-42.json  # re-check a saved receipt, no device

Decommissions a returned key: wipes the OTP slots, OATH credentials, PIV (block PIN+PUK, then factory reset), OpenPGP (block PWs, then factory reset), the FIDO seed/passkeys/PIN, and the org attestation, then signs a final audit checkpoint over the post-wipe journal window and saves it as a JSON receipt. It needs both interfaces (CCID for the applet wipes, FIDO HID for the reset and the signature). If either is missing it refuses before touching anything.

The receipt needs the audit journal, which is off by default. The RESET event that makes the receipt mean anything is a journal entry, so on a device where journalling was never enabled there is nothing to sign — and after the wipe there is no way back. rsk offboard therefore probes the journal state before the confirmation prompt and refuses, pointing at rsk audit enable. Enable it at provisioning time, or pass --no-receipt to wipe with no attestation at all — that flag skips the preflight, the checkpoint touch and the receipt file, so the run leaves no record of any kind.

The wipe is interrupted once, on purpose. The FIDO reset is only accepted within ten seconds of a power-up (fido2.md), and by the time the four CCID applets are wiped the key has been plugged in for far longer. So rsk offboard sends the reset, and when the device refuses it prints an unplug/replug prompt and retries in the fresh window:

the key refuses a reset this long after power-up (CTAP 2.1 §6.6):
UNPLUG it now and plug it straight back in — it must be the only
FIDO key attached, and the reset lands within 10s of
power-up. Waiting up to 60s…

Plug the same key back in and nothing else. rsk offboard refuses to start with more than one FIDO device attached, because the USB serial is a constant and it cannot tell two RS-Keys apart: the applet wipes go to the card it picked by reader name, and the FIDO reset would go to whichever HID device enumerated first. A trusted-display key never sees the replug prompt — it is exempt from the window — and neither does firmware older than 0x0854.

The order is fixed and each step reports its own result:

The PIV step blocks the PIN and PUK with two different wrong values (00000000 then 11111111, eight tries each) before the reset, so even a device whose real PIN happened to be one of those still ends up with a dead retry counter. The reset then always succeeds regardless of the original credentials.

The receipt is a cryptographic statement that this device (attestation fingerprint) had its FIDO applet factory-reset (the signed window contains the RESET event). It is split along that trust boundary: attested is what the device signed plus the inputs needed to re-derive it, host_observations is what the tool saw and the device never vouched for.

{
  "receipt_version": 2,
  "signed": true,
  "reset_attested": true,
  "notes": [],
  "attested": {
    "signed_head": "…", "seq": 414, "signature": "…",
    "attestation_pubkey": "04…", "fingerprint": "66573f74ca06359a",
    "challenge": "…", "epoch": "…", "entries": "…"
  },
  "host_observations": {
    "device": "37bebfdca282523b",
    "timestamp": "2026-06-13T14:22:09-04:00",
    "steps": {"otp": "ok", "oath": "ok", "piv": "ok", "openpgp": "ok",
              "fido_reset": "ok", "org_attestation": "cleared"},
    "journal_window": [{"seq": 412, "event": "RESET", "...": "..."}]
  }
}

attested.epoch and attested.entries are the raw journal window the signature covers. Without them a reader can check the signature but cannot tie it to any particular window, so the RESET claim would rest on a decoded list anyone could hand-edit. Receipts written before this format (receipt_version absent) dropped them, which is why --verify refuses those outright rather than pretending to check them.

The default receipt path is offboard-<serial>-<YYYYMMDD-HHMMSS>.json in the working directory. --report overrides it. The file is always written, even on a partial failure or when a post-wipe check fails: a failed step leaves its error string in steps, a failed check appends a {"code", "detail"} entry to notes and clears reset_attested, the report still saves, and rsk offboard then exits non-zero so a script notices.

Re-checking a receipt

rsk offboard --verify ret-42.json --expect-key <fingerprint-from-enrollment>

Offline, no device: it re-folds entries from epoch, requires the result to equal the signed head, requires that bound window to contain the RESET event, then checks the ECDSA P-256 signature over "RSK-AUDIT-CKPT-v1" ‖ signed_head ‖ seq (LE32) ‖ challenge. --expect-key takes the 16-hex fingerprint or the full SEC1 point; without it the run still verifies the chain and the signature but says so — the key comes from the receipt itself, so an unpinned check cannot tell you which device signed.

Pin the fingerprint you recorded at enrollment, from your inventory record — not the one printed in the receipt you are checking. Pinning a receipt’s own attested.fingerprint compares it against itself and proves nothing. rsk offboard says as much when it prints the re-check line at the end of a wipe.

The steps are host observations. The journal has no event type for PIV, OATH, OpenPGP or OTP, so four of the five wipe steps are not attestable in principle; only the FIDO reset is. --verify prints that caveat on every run.

Why it needs no PIN

No PIN is needed anywhere in the flow. Every wipe path is deliberately reachable without credentials (the PIV/OpenPGP paths block the PINs first, which is the spec’s own anyone-can-reset design; OATH and FIDO have resetting paths of their own), so a key that comes back with unknown PINs can still be offboarded. What it cannot do is impersonate: nothing in the wipe path can read or export secrets, and the receipt’s signature still requires the device’s own OTP DEVK. A wipe tool cannot forge it.

Footguns and partial wipes

• OTP slots protected by an access code are the one exception. They refuse the PIN-free delete (SW 6982), and the receipt’s host_observations.steps.otp records exactly which slots stayed (e.g. slots [2] protected by access codes — NOT wiped). A follow-up rsk offboard after recovering the code, or a full rsk-wipe flash nuke, covers that case.
• The CCID wipes are idempotent. A failed FIDO reset is recorded in steps and the run still writes the receipt for what was destroyed, then exits non-zero. Re-run rsk offboard; the applet wipes already done are harmless to repeat.
• no-session in notes means the key was never replugged (or never came back) within the timeout, so there was no FIDO session left to sign with. The receipt is written anyway, unsigned, with the CCID steps that did complete and fido_reset recording the abort — the applets are gone either way, and an irreversible step must not end with no artifact. Re-run to finish the FIDO half.
• Unsigned receipt. On a board with no OTP DEVK the wipes still happen but the checkpoint is refused (0x30). The report saves with "signed": false and a no-devk note. That is expected on dev boards, not a fault.
• no-reset-event in notes means the signed window did not contain the RESET, so the receipt does not certify a wipe (reset_attested is false and the command exits non-zero). The wipe still happened and re-running cannot produce the missing event. The usual cause is journalling being off, which the preflight now catches before anything is destroyed; the other is the journal ring having evicted the RESET past the export window.
• head-mismatch in notes means the signed head did not fold from the window the device exported. Treat that as tampering or a broken device, not as a retryable error.

See also

• audit.md: the journal and rsk audit verify; same attestation key and fingerprint as inventory verify.
• attestation.md: the org-attestation chain that offboard clears and list reports.
• seed-backup.md / backup-key.md: back up before you offboard if the key holds a recoverable seed.
• production.md, otp-fuses.md: burning the OTP DEVK that makes verify and the signed receipt possible.
• linux.md: pcscd / scdaemon setup so the CCID interface is visible to the inventory and offboard flows.

FIPS-style profile (fips-profile)

An opt-in build flavor that bakes a locked, FIPS-style algorithm policy into the image. Nothing is removed from the codebase or from the default build. Without the flag the firmware is byte-for-byte the usual one. With it, the policy is part of the signed image. Once secure boot is enabled the device runs nothing but that signed image: a policy you cannot toggle off at runtime, because there is no runtime knob to toggle.

cargo build --release -p firmware --features fips-profile
# or the reproducible Nix target (same flag):
nix build .#firmware-fips
# then sign + flash as usual (production.md)

A profile, not a validation. Nothing here is FIPS 140-3 validated: no CMVP certificate, no validated module boundary, no tested entropy source. This profile restricts the device to FIPS-approved algorithms and documents exactly where the line is drawn. If your compliance regime needs a certificate number, this is not it. If it needs “the device will not negotiate a non-approved algorithm,” this is exactly it.

What the profile locks

The flag wires through to two crates only: the FIDO applet (rsk-fido/fips-profile) and the PIV applet (rsk-piv/fips-profile). Every gate below is a compile-time cfg, so the restricted path is the only path compiled into the image.

Two things worth reading carefully:

• ES256K leaves on both sides. getInfo’s algorithms list no longer carries -47, so a relying party never offers it. Even if a client asks for -47 anyway, makeCredential maps it to “unsupported” and declines. There is no path to a new secp256k1 FIDO credential.
• RSA-1024 is blocked on two independent gates: the generation template parser (crates/rsk-piv/src/keygen.rs:47-50) and the separate import path (crates/rsk-piv/src/keygen.rs:596-598), which does not go through that parser. So neither ykman piv keys generate ... RSA1024 nor importing an external 1024-bit key onto a slot succeeds. Both return 6A 80 (incorrect data).

What deliberately stays

• Ed25519 / X25519: approved by FIPS 186-5 (EdDSA) and SP 800-186. ssh ed25519-sk keeps working, and so do Ed25519/cv25519 OpenPGP keys.
• NIST P-256 / P-384 / P-521 FIDO and PIV keys. The whole point of the profile is to keep these and drop the curve that was never on the list.
• ML-DSA-44 / ML-DSA-65: FIPS 204. The post-quantum path is the point, and the profile does not touch it. (Whether they are advertised in getInfo is the separate advertise-pqc flag. Capability is on either way; see build.md.)
• HMAC-SHA-1 in OATH HOTP/TOTP: RFC 4226 mandates it, and HMAC-SHA-1 (unlike bare SHA-1 signatures) remains approved.
• The whole OpenPGP applet, unchanged. The profile is FIDO + PIV. It does not narrow OpenPGP key attributes. If you want only approved curves there, that is a card-edit policy choice (openpgp.md), not something this flag enforces. State it honestly to anyone relying on the profile.
• Existing credentials still work. A secp256k1 credential created by a default build still asserts after you reflash with the profile. The gate is on makeCredential (creation), not on getAssertion (login). Same shape everywhere: an existing 3DES management key still authenticates (you can use it to set an AES one), existing RSA-1024 PIV keys still sign and decrypt. The profile gates creation and import, never your ability to keep using what is already on the device.

Migrating a device into the profile

Because the profile blocks creation but not use, an in-place migration is mechanical:

# 1. flash the profile image (signed, per production.md)
# 2. replace any non-approved long-lived keys:
ykman piv access change-management-key --algorithm AES256 --generate --protect
ykman piv keys generate 9a pub.pem            # re-issue any RSA-1024 slots as
                                              # ECC P-256 or RSA-2048
# 3. FIDO: re-register any sites that hold a secp256k1 credential with an
#    ES256 / EdDSA passkey; the old credential keeps working until you do.

ykman needs the opt-in VIDPID=Yubikey5 build. It gates on the “Yubico YubiKey” reader name, which the default RS-Key build (0x1209:0x0001) does not present. Build that flavor for the ykman commands here and under Verifying below, or drive the device with rsk / rsk-tui on the default build.

There is no “convert” command. You generate a new approved key and retire the old one through normal applet flows. The old 3DES/RSA-1024/secp256k1 material lingers only as long as you let it.

Verifying a device runs the profile

ykman fido info        # Minimum PIN length: 6
ykman info             # firmware version, applet capabilities

A profile build shows Minimum PIN length: 6. The absence of -47 (ES256K) is not something ykman fido info prints. It lists the AAGUID, options, PIN retries and minimum PIN length, but not the COSE algorithms array. To confirm secp256k1 is gone you need a raw getInfo dump (e.g. fido2-token -I or python-fido2): read the 0x0A array and confirm -47 is absent.

That advertisement is evidence, not proof on its own. A default build can have its minimum PIN raised to 6 by hand, which makes the PIN field alone ambiguous. The proof is the image signature. Combined with secure boot, the firmware’s own signature is the policy attestation: the fuses boot only your signed profile image, and that image is the only code present, so “the device enforces the profile” reduces to “the device booted, and your signature is the only one it accepts.”

flowchart TD
    src["Source (one tree)"] --> def["Default image"]
    src --> fips["fips-profile image"]
    fips --> sign["Sign + flash"]
    sign --> sb["Secure boot fuses<br/>boot only your key"]
    sb --> dev["Device runs only<br/>the signed profile"]
    dev --> att["getInfo + signature<br/>= the attestation"]

Why compile-time, not a runtime switch

A runtime “FIPS mode” toggle is one admin command away from not being FIPS mode, and one malware-driven APDU away from being turned off without you noticing. A compile-time profile under secure boot is a different object: the restricted menu is the only code in the image, the image is signed, and the fuses only boot your signatures. Changing the policy means signing and flashing a different image. That is exactly the auditable, physical event you want a policy change to be, rather than a silent state flip.

This mirrors how the rest of RS-Key’s hardening works: every knob is compile-time, and the irreversible posture lives in OTP fuses, not in mutable runtime state.

Honest limits

• No CMVP certificate, no validated boundary. Read the first callout again: this is an algorithm policy, not a validation. The limitations and threat model pages apply unchanged.
• The entropy source is the RP2350’s, untested against SP 800-90B. A validated module needs a validated RNG. This profile does not provide one.
• OpenPGP and OATH are not narrowed by the flag. If your policy needs approved-only algorithms there too, you enforce that through the applets’ own configuration, not through fips-profile.
• “Approved algorithm” ≠ “approved usage.” The profile keeps you from negotiating a disapproved primitive. It does not audit key sizes, rotation, or how you use the device. That part is on you.

Related

• build.md: all compile-time flags, including the .#firmware-fips Nix target.
• production.md: signing and the secure-boot fuse sequence that seals the profile in place.
• seed-backup.md: the seed export/finalize flow on a default build (and why the profile refuses it).
• piv.md, fido2.md, openpgp.md: the applets the profile narrows (and the one it leaves alone).

Production setup — signed boot + OTP master key

⚠️ EXPERIMENTAL. IRREVERSIBLE. BRICK RISK. Everything on this page burns one-time-programmable fuses or changes what the chip will ever boot again. A mistake can permanently brick the board or permanently lose your enrolled credentials. Read the whole page before running anything. The tools refuse to act without typed confirmations and support --dry-run. Use it.

Out of the box, RS-Key’s at-rest encryption roots in a key derived on the device and stored sealed in flash. That stops casual key extraction. But a motivated attacker who steals the board can dump flash over BOOTSEL and grind offline. The production path closes that in two independent stages:

1. OTP master key (MKEK): fuse a random 32-byte key into RP2350 OTP page 58 and re-root all at-rest sealing in it, then hard-lock the page so neither BOOTSEL nor non-secure code can ever read it. A flash dump alone is now worthless.
2. Secure boot: fuse your public-key fingerprint and the SECURE_BOOT_ENABLE bit so the bootrom runs only images you signed. Attacker-flashed firmware (the remaining way to read the OTP key) no longer runs.

A third, optional stage builds on those: anti-rollback, so that old images you signed (with bugs you have since fixed) stop booting too. It has its own page: anti-rollback.md.

Each stage is usable alone. Together they are the full story. All are driven from the host. The firmware never burns a fuse behind your back. The two exceptions are rows that physically cannot be written from BOOTSEL (bootloader-read-only OTP pages): the page-58 lock and the ROLLBACK_REQUIRED flag, each applied by the firmware on explicit command. The fuses these stages write are explained in otp-fuses.md.

flowchart TD
    d["Default<br/>flash-derived root · any image boots"]
    d --> s1["Stage 1 — OTP master key<br/>burn page 58 · migrate · lock"]
    s1 --> s2a["Stage 2 — secure boot<br/>load-key · harden (non-enforcing)"]
    s2a --> s2b{{"ENABLE<br/>the one irreversible bit"}}
    s2b --> s2c["lock key slots + fuse pages"]
    s2c --> s3["Stage 3 — anti-rollback<br/>(optional)"]
    s2b -. "a correctly-signed UF2 can always be re-flashed over BOOTSEL" .-> rec["BOOTSEL recovery"]

Every command on this page, in order

The CLI groups by fuse family — rsk otp owns the OTP master key and the rollback flag, rsk secure-boot owns the boot-key and enforcement fuses — while this page groups by goal. The two cuts cross, which is why rsk otp shows up in stage 1 and again in stage 3. Nothing is out of order; they are different axes. The stages themselves are independent and usable alone, and this is the order to run them in if you are doing all three.

rsk secure-boot status reads the whole fuse state and is safe at any point. Every burning command takes --dry-run and a typed confirmation.

Before you start

• Make a seed backup first if you haven’t: rsk backup export (guides/seed-backup.md). It is the only thing that survives a board swap. The production path is exactly when you start caring about that.
• Plan for the signing key. Stage 2 generates an ECDSA key. Losing it bricks the board for new firmware. Decide now where you’ll keep it durably.
• Understand the substrate. These stages write OTP fuses. otp-fuses.md explains what is irreversible and why.
• Rehearse. Every step supports --dry-run, which prints the exact picotool commands without touching anything.

Stage 1 — OTP master key

What it does: writes a random DEVK (device attestation key) and MKEK (master sealing key) plus anti-imaging chaff into OTP page 58, ECC-verified, then locks the page. On the next boot the firmware notices the provisioned key and migrates everything already on the device (FIDO seed, PIV keys, OpenPGP key wraps, PIN verifiers) under the new root. Your enrolled credentials survive. That is the point of the migration layer.

At-rest hardening pass. The migration re-seals each secret under the new root. But the flash store is append-only, so the old chip-serial-sealed copies linger until their page is reclaimed. To stop a flash dump from recovering them, that same first post-burn boot runs a one-shot compaction that physically scrubs the credential partition. It is a multi-second stall that runs before the device re-attaches to USB, so on that one boot the device stays dark a little longer than usual. Don’t cut power during it. It runs once (a flash marker gates it) and re-runs if interrupted.

New deployments: burn OTP before you enroll. A seed generated after the burn is sealed under the fused root from birth, so no chip-serial-sealed copy ever exists and the hardening pass has nothing to scrub. The migrate-in-place path above is for hardening a device you have already been using.

rsk reboot bootsel               # picotool needs the chip in BOOTSEL
rsk otp burn --dry-run           # preview every step
rsk otp burn                     # typed confirmation; keys are generated and FORGOTTEN
picotool reboot -a               # back to the app; migration runs at boot
rsk otp lock-page58              # firmware applies the page-58 hard lock (typed confirm)

Facts to internalize first:

• The burn tool generates MKEK/DEVK randomly and forgets them. There is no copy to lose, and none to back up. The fuses are the key.
• After the burn, the device attestation public key changes (it now derives from the fused DEVK). FIDO/PIV identities survive. The rescue attestation key does not. That is expected, not data loss. If you use audit or fleet verification, re-record the device’s fingerprint afterward (guides/fleet.md).
• The lock is the half that matters for at-rest. Burning the MKEK without lock-page58 leaves the key fused but still readable over BOOTSEL. The flash dump is not yet worthless. Run lock-page58 to actually close it.
• After lock-page58, picotool otp get on page 58 fails with a permission error forever. Only the secure-mode firmware can read the keys. That failure is the lock working.
• A seed backup (rsk backup) made before or after is unaffected. Backups carry the seed value, which gets re-sealed under whatever root the device has.
• Never flash a FAKE_MKEK test build onto a provisioned board. It migrates the data under a fake, greppable key and orphans it (build.md).

Stage 2 — secure boot

What it does: the RP2350 bootrom verifies an ECDSA (secp256k1 + SHA-256) signature on every image against a fingerprint fused into OTP. Unsigned or foreign-signed images do not boot. The chip falls back to BOOTSEL, where you can always drag a correctly-signed UF2 (recovery path).

The permanent consequences:

• Every future flash must be signed with your key. The dev loop becomes build → picotool seal --sign → flash.
• Losing the signing key bricks the board for new firmware (the current signed image keeps booting). Back the key up before enabling enforcement.
• DEBUG_DISABLE is burned along the way. SWD is gone (flashing is BOOTSEL anyway).

2a. Generate a signing key (once, off-repo)

mkdir -p ~/.rs-key-secrets && cd ~/.rs-key-secrets
openssl ecparam -genkey -name secp256k1 -noout -out secure_boot_key.pem
openssl ec -in secure_boot_key.pem -pubout -out secure_boot_pub.pem
chmod 600 secure_boot_key.pem
# BACK IT UP somewhere that survives this machine.

That is the whole of what you create by hand. The otp_secureboot.json the next step passes around is produced by seal, not written here — see 2b.

This key is the root of trust for the board’s whole life. Treat it like the most important secret you have here: if you lose it after enable, you can never flash new firmware to that board (the running image keeps booting). It is also what makes key rotation possible later, so a single, well-kept key with a backup is the goal. The full key lifecycle is in signing-keys.md: passphrase protection (and the decrypt-for-seal step it implies), backup, one fresh key per board, rotation, and recovery.

2b. Sign and prove a signed image boots (before any fuse)

# 1. an image to sign. The partition table has to be in it BEFORE sealing, or
#    the signature does not cover the fence (build.md#the-partition-table).
cargo build --release -p firmware
scripts/pt.sh target/thumbv8m.main-none-eabihf/release/firmware firmware-pt.elf
#    (or a single `nix build .#firmware`, whose result/firmware.elf already has it)

# 2. sign the ELF — NOT the UF2, and convert afterwards. `seal` retires the
#    image's own IMAGE_DEF (the linker's, carrying no signature and no rollback
#    version) only when handed an ELF; given a UF2 it appends its signed block and
#    leaves that one live and FIRST, which a SECURE_BOOT_ENABLE + ROLLBACK_REQUIRED
#    device meets first and refuses — while the host still prints
#    "signature: verified". otp_secureboot.json does NOT exist yet: you pick the
#    path, and `seal` creates the file there. It is the artifact stage 2c fuses.
picotool seal --sign --hash firmware-pt.elf -t elf firmware-signed.elf -t elf \
    ~/.rs-key-secrets/secure_boot_key.pem ~/.rs-key-secrets/otp_secureboot.json \
    --major 1 --minor 0 --rollback 1
picotool uf2 convert firmware-signed.elf -t elf firmware-signed.uf2
picotool info -a firmware-signed.elf   # "signature: verified", and block 1 "ignored"
ls -l ~/.rs-key-secrets/otp_secureboot.json    # seal wrote this; 2c needs it

# 3. BOOTSEL, then flash + confirm the device works:
picotool load -v firmware-signed.uf2 && picotool reboot   # or drag it onto the RP2350 drive

What otp_secureboot.json is for

The one part of this page with no obvious purpose until you see both ends of it.

The bootrom’s check is: does SHA-256(the public key inside this image) equal a fingerprint fused in OTP? So that fingerprint has to get into the fuses. But signing happens on your host, with a private key that must never go near the device, while fusing happens against the board — two separate operations, possibly on different machines and months apart. Nothing in the signed image can carry the value across: the device is exactly what you don’t trust yet.

That file is the courier, and its whole job:

You do not back it up, and losing it costs nothing. It is a pure function of your signing key — sealing any image with the same .pem regenerates it byte-for-byte, and --major / --minor / --rollback do not change a byte of it. It holds no private material, so it is not a secret either. The .pem is the thing to protect; this is a derived artifact you can recreate in one command.

It is per-key, so with one key per board (recommended — signing-keys.md) keep each next to the .pem that produced it, under names you can tell apart.

The other arguments:

• secure_boot_key.pem: your signing key. It signs the image.
• --major / --minor: an image version (major.minor) stamped into the RP2350 boot metadata. It is a plain version label, distinct from the firmware version RS-Key reports (5.7.x, build.md) and from the rollback version. The bootrom can use it to prefer the newer of two images in an A/B setup. RS-Key ships a single image, so here it is effectively a label. Keep 1 0.
• --rollback: the anti-rollback version, a separate counter (not the image version). It is harmless before anti-rollback is enabled, and having a version in every sealed image from day one makes that stage cheap. What it means and how to choose it: anti-rollback.md.

picotool info firmware-signed.uf2 must report signature: verified. The firmware’s image definition is already secure-boot compatible. The sealed UF2 carries the signature block.

Sealing also covers the image’s partition table, the fence that keeps the USB bootloader out of the KV store (build.md). That is the whole reason the fence is worth anything: on an unsigned board an attacker simply flashes an image carrying a permissive table, while a sealed table cannot be replaced without this key. It closes the one snapshot/restore gap secure boot does not close by itself — writing the data region is not code execution (threat-model.md). Prove it, don’t assume it: picotool info -a firmware-signed.uf2 must show the store partition as NSBOOT(-), and a byte flipped anywhere in the table must turn hash: verified into hash: incorrect.

2c. Burn, staged

rsk secure-boot splits provisioning so every irreversible write is proven by a real boot before the next. The only true point of no return is one bit:

rsk secure-boot status      # read the current fuse state any time
rsk secure-boot load-key ~/.rs-key-secrets/otp_secureboot.json   # 1. boot-key fingerprint + KEY_VALID (non-enforcing)
rsk secure-boot harden      # 2. DEBUG_DISABLE + glitch detectors   (non-enforcing)
rsk secure-boot enable      # 3. SECURE_BOOT_ENABLE = 1  ← the brick bit
rsk secure-boot lock        # 4. revoke unused key slots + lock the fuse pages

Each step has --dry-run and a typed confirmation. Between steps, reboot and confirm the device still works. After enable, verify the negative case: drag an unsigned UF2. The bootrom must reject it and fall back to BOOTSEL. Re-drag the signed one to recover.

lock and key rotation: a decision to make now. The lock stage revokes the three unused boot-key slots (KEY_INVALID), maximizing hardening against an attacker who tries to inject their own key. It also forecloses key rotation, the escape valve if you ever exhaust the 48-step anti-rollback budget (you rotate to a new signing key and revoke the old one). If you want to keep that valve, don’t run the full lock. Leave a slot. The trade-off is in anti-rollback.md. Most users should run the full lock. You will almost certainly never reach the ceiling.

The new flash workflow (forever)

cargo build --release -p firmware
scripts/pt.sh target/thumbv8m.main-none-eabihf/release/firmware firmware-pt.elf
# seal the ELF, convert after — a UF2 in leaves the unsigned IMAGE_DEF first (2b)
picotool seal --sign --hash firmware-pt.elf -t elf firmware-signed.elf -t elf \
    ~/.rs-key-secrets/secure_boot_key.pem ~/.rs-key-secrets/otp_secureboot.json \
    --major 1 --minor 0 --rollback 1
picotool uf2 convert firmware-signed.elf -t elf firmware-signed.uf2
# BOOTSEL (hands-free: rsk reboot bootsel), then:
picotool load -v firmware-signed.uf2 && picotool reboot   # or drag it onto the RP2350 drive

The pt.sh line is not optional here, and its position is the point. It embeds the partition table that fences the KV store off from the bootloader (build.md); cargo build alone never produces one. Running it before seal is what puts the table under the signature — which is the only thing that stops an attacker flashing a permissive table of their own. Seal a table-less image and you have signed away the fence without any error telling you so.

The --rollback value is your board’s current floor (see anti-rollback.md). 1 is the usual starting value.

To seal an image others can independently verify, build it with nix build .#firmware instead of the dev-shell cargo build. That path is bit-for-bit reproducible from the source tree (build.md), so anyone can rebuild at your release commit and confirm the payload you signed.

Stage 3 — anti-rollback (optional)

This stage stops your own older signed images from booting, so a bug you have since fixed can’t be re-introduced by downgrading. Read anti-rollback.md first. It is the full model: how the floor works, the 48-burn budget, when (and whether) to raise it, what to do at the ceiling, and the new-board case. This section is only the steps to turn it on.

The mechanism is two RP2350-native pieces: a per-image rollback version (--rollback N at seal time) checked against a 48-bit OTP thermometer, and the ROLLBACK_REQUIRED fuse that makes that check mandatory. Until the fuse is burned, versionless images boot and the feature is off.

Turning it on

1. Seal and flash firmware with a rollback version (start at --rollback 1), reboot, and confirm rsk secure-boot status reports boot version 1/48. If it still reads 0/48, stop and investigate. Never burn the fuse on an unproven setup.
2. Re-seal rsk-wipe at the same version. The recovery escape hatch must stay bootable.
3. From the running firmware: rsk otp rollback-require (typed confirmation; --dry-run reports state without burning). The firmware refuses unless secure boot is enabled, so it can only run from an image that itself passed the rollback check, and the “fuse before a versioned image” footgun can’t happen.
4. Negative-test: drag any versionless signed UF2. The bootrom must refuse it and fall back to BOOTSEL. Re-drag the current image to recover.

After it’s on

• Every picotool seal must include --rollback <your floor>. A versionless sealed image no longer boots (fail-closed). You find out at flash time and recover by re-sealing.
• To raise the floor and close a downgrade-fix, seal one step higher (--rollback <floor + 1>). The default is not to raise it. When, why, and the budget math are all in anti-rollback.md.
• A board that has burned to floor N never boots an image below N again. No undo.

Everything about whether to bump, the 48-budget, the ceiling, key rotation, and moving to a new board lives in anti-rollback.md.

Recovery and failure cases

Deliberate choices

• USB BOOTSEL stays enabled. It is the only reflash and the only recovery path (no debugger). It cannot bypass signature enforcement, and after the page-58 lock it cannot read the OTP keys. Disabling it (the datasheet’s full checklist) would turn every bad flash into a permanent brick.
• No image encryption. The code is open source. There is nothing secret in the image (secrets live sealed in flash, rooted in OTP). The RP2350 also has no transparent XIP decryption. Encrypted boot requires fitting the image in SRAM, which a ~1.7 MB image does not.

Residual risks (still open after all stages)

• XIP TOCTOU: the image executes from external QSPI flash. Hardware that swaps or emulates the flash chip between the bootrom’s signature check and execution can subvert it. Decap/side-channel-class attack, out of scope.
• A host compromised while the device is plugged in can drive normal operations (as with any security key). See threat-model.md.
• An older signed image of yours re-opens the store fence. The partition table travels inside the image, so anything you signed before 0x0871 carries none, and flashing it makes the KV store bootloader-writable again — the snapshot/restore rollback is back. This is an ordinary downgrade attack, so the version axis is what answers it: raise your rollback floor past your pre-table builds (anti-rollback.md). Until you do, the fence is worth exactly as much as your oldest signed artifact.

Signing keys (secure boot)

Once secure boot is enabled, a single key you hold is the root of trust for the board’s whole life: it signs every image the board will run. This page is the full key lifecycle: what the key is, how it relates to the other on-chip keys, and the correct flow to generate, back up, provision, use, rotate, and (if it comes to it) recover it.

⚠️ This key is the most important secret in the production path. Lose it after enable and you can never flash new firmware to that board again. Read the backup section before you generate anything.

The keys on an RS-Key, and which one this is

Three different key concepts live on a provisioned board. Don’t conflate them:

The signing key is the only one you generate, hold, and must keep. The MKEK/DEVK are random and unrecoverable by design. The signing key is the opposite: you keep it, and keeping it is the whole job here.

Architecture — the trust chain

You sign images with the private key. The board never sees it; OTP holds only a fingerprint (SHA-256 of the matching public key). The signed image carries its public key plus an ECDSA signature. The bootrom checks both at every boot:

flowchart TD
    priv["Private key<br/>(offline, backed up)"] -->|signs| seal["picotool seal --sign"]
    seal --> img["Signed image<br/>public key + ECDSA signature"]
    img -->|BOOTSEL flash| board["Board"]
    board --> rom{"bootrom: SHA-256(image's public key)<br/>matches a fused, valid slot?"}
    rom -->|no| reject["refuse → BOOTSEL"]
    rom -->|yes| verify["verify the ECDSA signature"]
    verify --> boot["boot the image"]
    slots["OTP boot-key slots (4)<br/>fingerprints + KEY_VALID / KEY_INVALID"] -. anchors .-> rom

Two consequences fall out of this shape and explain everything below:

• The board only ever holds the public fingerprint, so a stolen board can’t yield your signing key, but the board also can’t help you recover it.
• The bootrom matches against any valid slot and ignores which key signed, beyond the fingerprint. That is what makes key revocation a downgrade defense (see anti-rollback.md).

1. Generate (one fresh key per board, off-repo, ideally offline)

The RP2350 bootrom verifies secp256k1 + SHA-256, so the key must be secp256k1. Protect it with a passphrase. That is the difference between a stolen backup being your signing key and being ciphertext:

mkdir -p ~/.rs-key-secrets && cd ~/.rs-key-secrets
# generate, then encrypt at rest with a passphrase (openssl prompts you to set one):
openssl ecparam -genkey -name secp256k1 -noout \
  | openssl ec -aes256 -out secure_boot_key.pem
# derive the public key (prompts for the passphrase to read the private key):
openssl ec -in secure_boot_key.pem -pubout -out secure_boot_pub.pem
chmod 600 secure_boot_key.pem

Use a long, unique passphrase and back it up separately. Losing the passphrase loses the key as surely as losing the file. If you would rather not use one, drop the | openssl ec -aes256 … pipe and write the key straight out (-out secure_boot_key.pem): simpler, but then any copy of the file is the key. Either way, generate it on a machine you trust (ideally offline/air-gapped) and never commit it. The hermetic nix build path deliberately keeps the key out of the build sandbox (build.md); signing is always a separate, local step.

One key per board, one board per key. Generate a brand-new key for every chip you provision and trust only it on that board. A new device is signed with a new key. Never carry an old board’s key onto a new one. That rule is also what keeps a replacement board’s rollback floor safe: the old images are signed by the old key, which the new board does not trust (anti-rollback.md).

2. Back it up — before you fuse anything

This is the step people skip and regret. After enable, the fused fingerprint is permanent and only this key can sign images the board will boot. So:

• Make at least two durable copies, on media that survive this machine (and each other), e.g. an encrypted USB stick kept offline, plus a printout of the PEM in a safe.
• Encrypt it at rest. A passphrase-protected copy, or a copy held on a separate hardware token, is worth the friction.
• Keep it off networked machines. The host that signs only needs the key for the few seconds of picotool seal.
• There is no recovery from the device. It holds only the public fingerprint. If every copy of the private key is gone, the board’s current signed image keeps booting but you can never flash it again.

If you reserve a slot for rotation you get one escape hatch later. Even so, treat the key as un-loseable.

3. Provision — fuse the fingerprint (slot 0)

picotool seal writes the fingerprint into the otp_secureboot.json it produces. rsk secure-boot load-key fuses it into boot-key slot 0 without enabling enforcement yet:

# seal once to produce the otp.json (also see production.md, stage 2b):
picotool seal --sign --hash firmware-pt.elf -t elf firmware-signed.elf -t elf \
    ~/.rs-key-secrets/secure_boot_key.pem ~/.rs-key-secrets/otp_secureboot.json \
    --major 1 --minor 0 --rollback 1
rsk secure-boot status                          # bootkey present: False
rsk secure-boot load-key ~/.rs-key-secrets/otp_secureboot.json   # fuses slot 0

load-key is non-enforcing: unsigned images still boot until enable. It refuses if a key is already present, so it is a one-shot for slot 0. (If your key is passphrase-protected, decrypt it to a temp file for this seal too, exactly as in step 4.) The rest of the staged ritual (harden → enable → lock) is in production.md.

4. Daily use — sign every flash

After enable, every image must be sealed with this key. picotool reads only an unencrypted PEM (it has no passphrase prompt), so a passphrase-protected key (recommended) is decrypted to a temporary file just for the seal and removed straight after:

# decrypt for the seal only — best on a RAM-backed dir so the plaintext never
# touches disk; openssl prompts for the passphrase:
( umask 077; openssl ec -in ~/.rs-key-secrets/secure_boot_key.pem -out /tmp/sk.pem )
picotool seal --sign --hash firmware-pt.elf -t elf firmware-signed.elf -t elf \
    /tmp/sk.pem ~/.rs-key-secrets/otp_secureboot.json --major 1 --minor 0 --rollback 1
picotool uf2 convert firmware-signed.elf -t elf firmware-signed.uf2
rm -P /tmp/sk.pem        # overwrite + delete (Linux: shred -u /tmp/sk.pem)
# BOOTSEL, then:
picotool load -v firmware-signed.uf2 && picotool reboot   # or drag it onto the RP2350 drive

If your key has no passphrase, pass ~/.rs-key-secrets/secure_boot_key.pem straight in as the <key> argument and skip the decrypt / rm lines.

The rsk-wipe recovery image must be sealed with a currently valid key too, or it won’t boot on a secure-boot board. After a rotation it must be re-signed with the new key. The full flag meaning is in production.md; if anti-rollback is on, add --rollback (anti-rollback.md).

Key slots and validity

The RP2350 has four boot-key slots, each holding one fingerprint, plus KEY_VALID / KEY_INVALID masks that say which slots the bootrom trusts:

• The bootrom accepts an image whose public key matches any valid, non-revoked slot.
• The lock stage (production.md) sets KEY_INVALID on every slot the bootrom does not already trust, keeping the one the board actually boots from. Maximum hardening, but it also removes any room to add a key later. On a board mid-rotation — a new key provisioned but the old slot not yet revoked — two slots are trusted and lock refuses rather than guess: run revoke <old slot> first.
• Reserving a slot vs. full lock-down is a decision you make at provisioning time. It is the same trade-off as the anti-rollback escape valve, laid out in anti-rollback.md. Most users should take the full lock. Reserve a slot only if you specifically want a future rotation path.

5. Rotate a key

You rotate when you want a new signing key to take over and the old one to stop being trusted. The two real reasons: a suspected key compromise or the anti-rollback budget ceiling (a new key revokes the old, killing old signed images by signature; see anti-rollback.md).

The flow, in order (never revoke the old key until the new one is proven):

1. Generate a new key K2 (section 1) and back it up (section 2).
2. Provision K2’s fingerprint into a free, un-revoked slot: rsk secure-boot load-key --slot <free> K2-otp.json.
3. Re-sign the current firmware with K2, flash it, and confirm it boots (the board now validates it via K2).
4. Revoke the old key K1: rsk secure-boot revoke <K1-slot>. Old images signed only by K1 now fail secure boot.

rsk secure-boot rotate K2-otp.json runs steps 2–4 as a guided flow: it provisions the next free slot, then stops and tells you to flash and prove K2 before you revoke K1. It never revokes for you while only one key is proven.

Tooling. Rotation is driven by rsk secure-boot, not hand-rolled picotool otp writes: load-key --slot N provisions any of the four slots, revoke <slot> retires one (refusing to revoke your last valid key), and rotate <new.json> walks the whole flow: provision a free slot, then it tells you to flash and prove the new key before revoking the old one. It only works if you reserved a slot (didn’t run the full lock, which leaves the key pages bootloader-writable); on a fully-locked board the commands refuse, and a fresh board is the only path. With four slots you can rotate roughly three times before they’re spent.

Loss and recovery — the cases

Best practices, in one place

• secp256k1, generated offline, passphrase-protected at rest, never in the repo or a build sandbox.
• ≥2 durable, encrypted, offline backups (before you fuse anything).
• One fresh key per board for its life: a new board gets a new key, never the old one. Rotate only on compromise or the rollback ceiling, and only if you reserved a slot.
• Sign rsk-wipe with the same key as your firmware (keep the recovery hatch bootable).
• Decide lock-down vs. a reserved rotation slot up front. It can’t be changed after lock.

OTP fuses (RP2350)

The “production” hardening in RS-Key comes down to writing the RP2350’s OTP: the OTP master key, secure boot, and anti-rollback. This page explains what OTP is, why it is irreversible, how RS-Key writes it, and exactly which rows it touches. Read it before production.md. It is the substrate everything else stands on.

“OTP” here means One-Time-Programmable fuses on the chip, not the Yubico one-time-password feature (guides/otp.md). Different thing, same three letters.

What OTP is

OTP is a block of on-chip memory made of antifuses: writing a bit physically and permanently changes the silicon. A bit goes 0 → 1 and never back. There is no erase, no reset, no “factory default”. For OTP, factory is wherever you left it. Every chip has its own OTP. Nothing about it is shared between boards.

This is the whole point. The value of OTP for a security key is exactly that it cannot be undone: a key fused here can’t be un-fused, a secure-boot bit can’t be cleared, a rollback floor can’t be lowered. Hardening that you could reverse would be hardening an attacker could reverse too.

⚠️ Every write on this page is permanent. A mistake can lock you out of reading a value forever, or brick the board for new firmware. The tools refuse to act without typed confirmations and support --dry-run. Use it.

Layout: pages, rows, and reliability copies

OTP is addressed in rows (24 bits each), grouped into pages of 64 rows (so page N starts at row N × 0x40; page 58 begins at row 0xE80). Page granularity matters because read/write locks are applied per page, not per row.

A single antifuse can be marginal, so the values that the bootrom and firmware depend on are stored redundantly:

• RBIT-3: the value is written into three consecutive rows, and the reader takes the bitwise 2-of-3 majority. An interrupted burn that set only one copy doesn’t count. Two copies do. The secure-boot flags, the boot-key fingerprints, and the rollback rows are all RBIT-3.
• ECC: other pages store an error-correcting code alongside the data.

Who can write OTP, and when

Two paths write OTP, and the difference is central to how RS-Key stays safe:

• BOOTSEL / picotool: with the board in BOOTSEL you can read and write OTP directly from the host. This is how the bulk of provisioning happens (the master key, the secure-boot key, the enable bits).
• Secure firmware (the rescue applet): a handful of rows must be written by the running, secure-boot-validated firmware, not from BOOTSEL. Two cases:
  • rows that are made bootloader-read-only by a page lock (so BOOTSEL can no longer write them) but stay secure-writable. The page-58 lock and the ROLLBACK_REQUIRED flag are applied this way, by rsk otp lock-page58 / rsk otp rollback-require, each guarded by an exact magic payload so a stray APDU can never trigger them.

Each OTP page lock is a byte encoding three independent levels: LOCK_BL (bootloader), LOCK_NS (non-secure), LOCK_S (secure), each of read-write / read-only / inaccessible. That three-way split is what lets a page be unreadable to BOOTSEL but still readable/writable by secure firmware (see page 58 below).

What RS-Key burns

These are the rows RS-Key provisions, grouped by the stage that writes them. The authoritative source is the code (tools/rsk/otp.py, tools/rsk/secureboot.py, crates/rsk-rescue/src/rollback.rs). The table is the map.

A few notes that matter:

• Page 58 is read-write to secure firmware even after the lock. The lock value (0x3C3C3C) sets BL and NS to inaccessible but leaves S read-write. So only secure-mode firmware can ever read the MKEK/DEVK again, and a BOOTSEL flash dump cannot.
• The MKEK/DEVK are generated randomly and forgotten. rsk otp burn does not keep a copy. The fuses are the key. There is nothing to back up and nothing to lose.
• The rollback thermometer is advanced by the bootrom, not by a host write, when a higher-version image boots. See anti-rollback.md.
• Pages 1 and 2 stay bootloader-read-only after lock (0x141414), not inaccessible. The bootrom must read the keys and flags on every boot. They remain secure-writable, which is how the firmware applies ROLLBACK_REQUIRED after the pages are otherwise locked down.

Anti-imaging chaff

Page 58 stores the keys in its low half and the bitwise complement of every key row in its high half: DEVK at 0xE80…0xE8F with its complement at 0xEA0, MKEK at 0xE90…0xE9F with its complement at 0xEB0 (offset 0x20 = half a page). The firmware never reads the high half. It plays no part in key reconstruction (firmware/src/otp_keys.rs reads only the key rows). It exists for one reason.

The cheapest invasive OTP read demonstrated against this antifuse family (IOActive, RP2350 Challenge 1, see threat-model.md) recovers the bitwise OR of two physically paired bitcell rows, not the rows individually. Raspberry Pi’s mitigation is to put the key in one half of a page and its complement in the opposite half, so each physical pair reads OR(b, ¬b) = 1, a uniform all-ones pattern that carries no key bits. The low-half / high-half placement here is exactly that scheme, and it neutralises the demonstrated readout.

This defeats the demonstrated OR-read. IOActive note that a more advanced attack might separate the paired (even/odd) rows with additional effort, which would read the key half directly, and a plain complement does not stop that. Raspberry Pi have said a forthcoming application note will describe a storage scheme mitigating both the current attack and that hypothetical one. If it prescribes more than complement-in-opposite-half, revisit this.

Reading OTP

OTP is readable until a lock says otherwise:

rsk secure-boot status        # decodes the secure-boot + rollback rows for you
picotool otp get -r -n 0x48   # raw row read (BOOTSEL), if you want the bytes

rsk inventory list / rsk status surface the human-readable state. Once page 58 is locked, picotool otp get on it fails with a permission error forever. That failure is the lock working, not a fault.

Honest limits

• OTP is not a secure element. It hardens against software- and BOOTSEL-level attacks, and the anti-imaging chaff above neutralises the demonstrated passive-voltage-contrast OTP readout. But the antifuses are still on a general-purpose die: a funded lab with a focused ion beam can image them, and that (like laser fault injection and power/EM analysis) is out of scope (threat-model.md). The antifuse readout is not fixed by any silicon stepping. Use A4 for the fault and boot-ROM fixes (our own boards are A2, the stepping broken in the public challenge).
• It is finite. The rollback thermometer is 48 bits for the board’s life. There are 4 key slots. Neither resets. See anti-rollback.md.
• It is per-chip. None of this carries to another board. A new board is a fresh, blank OTP.

Anti-rollback

Secure boot (production.md) refuses foreign images. Every image you signed stays valid forever. The first time a release fixes an exploitable bug, your previous signed image becomes a hole: an attacker with the device drags your old, signed UF2 over BOOTSEL and attacks the bug you already fixed. Anti-rollback closes that downgrade path.

Scope: this page is about rolling back the image. Rolling back the data — snapshotting flash over BOOTSEL and restoring it later to reset a wrong-PIN counter — is a separate attack with separate defenses, in threat-model.md. Neither mechanism sees the other’s rollback.

This page is the model and every case. The operational steps to turn it on are in production.md, stage 3; the fuses it touches are in otp-fuses.md. It is optional. Until you enable it, nothing here applies.

Read this whole page before enabling it. Anti-rollback burns one-time fuses. Once enforced, it changes which images your board will boot. None of it is reversible.

Two independent axes

The single most important idea: an old, vulnerable image can be refused by two different mechanisms. They do not depend on each other.

While you have version budget, the first axis does the work. When it runs out, the second takes over. A fresh chip with a fresh key resets both. The rest of this page is those two axes and what happens at their limits.

Axis 1 — version (the rollback floor)

Two different numbers

• Firmware version (v0.3.1, semver): “which build is this”, changes every release.
• Rollback floor: a number on your board. It refuses to boot anything below it. You move it, rarely, by hand.

RS-Key does not assign project-wide “epoch” numbers. There is only your own floor, on each board, and you manage it.

How it works in hardware

The floor lives in RP2350 OTP as a 48-bit thermometer (its value is the number of burned bits). At boot the bootrom (not our firmware) compares the image’s rollback version against your board’s floor:

• image version below the floor → refused, fall back to BOOTSEL;
• equal → boots;
• above → boots and immediately burns the thermometer up to the image’s version.

The whole mechanism has an on/off fuse, ROLLBACK_REQUIRED. Until it is burned, images carrying no rollback version boot regardless (anti-rollback has no teeth). You burn it from firmware:

rsk secure-boot status      # shows ROLLBACK_REQUIRED and the boot version N/48
rsk otp rollback-require     # fuse ROLLBACK_REQUIRED (requires secure boot enabled)

⚠️ Burning the thermometer is irreversible. OTP is one-time-programmable: a bit goes 0→1 and never back. See otp-fuses.md.

Budget: 48 steps per chip, for the board’s whole life

The thermometer is 48 bits, so the floor can advance 48 times over the entire life of that board, and never again. That is not “48 releases”. It is 48 burns. Treat each advance as spending an irreversible, finite resource.

The project flags downgrade-fixes; you decide

Because secure boot is rooted in your own signing key, there are no project-signed images. Every owner signs and chooses their own floor. So the project’s only job is to mark, in the changelog, which releases fix a downgrade-exploitable bug:

When you build firmware, you check: were there downgrade-fix releases since my last build? If so, it is your call:

• Raise the floor (close those bugs): seal with --rollback <your counter + 1>. The board burns up to it. Your older images below it stop booting.
• Leave it (you accept the risk): seal with --rollback <your current counter>. Everything still boots, nothing burns.

The default is not to burn. Raising the floor is a deliberate act tied to a specific security release, not routine.

If you don’t burn, the downgrade attack stays possible. Your old signed image will still boot. That is a fine, conscious trade-off (you keep your 48-budget and don’t orphan working images), but it is your choice of risk, not a default-protected state.

Why +1 is enough

The floor only needs to sit above your own vulnerable builds. Every build you made was sealed at a version ≤ your current counter. So raising the floor to counter + 1 cuts off your entire build history below it in a single bit. There is no absolute number to “catch up” to.

A bonus falls out of this: “decline, decline, then raise once when you decide to care” spends fewer bits than raising the floor on every release, for the same protection, because all your older builds sit below the one bump.

Concretely:

rsk secure-boot status         # read your floor, say "boot version 2/48"
# build the fixed firmware, then seal it one step higher:
picotool seal --sign --hash firmware-pt.elf -t elf firmware-signed.elf -t elf \
    ~/.rs-key-secrets/secure_boot_key.pem ~/.rs-key-secrets/otp_secureboot.json \
    --major 1 --minor 0 --rollback 3        # 3 = counter (2) + 1
picotool uf2 convert firmware-signed.elf -t elf firmware-signed.uf2
# flash it; on boot the floor burns 2 → 3, and every image sealed ≤ 2 is now refused

One caveat for correctness: you must seal the fixed firmware strictly above the version you used for the vulnerable build. In practice that is counter + 1. If you accidentally seal the fixed image at the same version as a vulnerable one, the floor didn’t rise and you are not protected.

Your floor is per-board

The floor is private to each board. It equals the highest version that that board has booted. It depends only on your burns, not on how many releases exist. Different boards carry different floors. This is normal and needs no coordination. The one rule: a board will not boot an image below its own floor. You cannot go back down past a floor you’ve burned.

At the ceiling (floor = 48)

The thermometer is full, but you can still update forever. You seal every future image at version 48 and it boots. You lose only the growth of version-based downgrade protection: a new release can no longer out-version a previous one (there is no 49th step). The device works. Secure boot still holds. From here, downgrade protection moves to axis 2.

Axis 2 — key (the signature)

How the bootrom checks a signature

• OTP holds not the key but a fingerprint (SHA-256(public key)) in a boot-key slot.
• A signed image carries, inside it, the full public key plus an ECDSA signature (secp256k1 + SHA-256) over the image hash.
• At boot the bootrom hashes the public key from the image and compares it to the fused fingerprints. No match → refused, before it even checks the signature. Match → it verifies the ECDSA signature with that key → boots.

This can’t be forged: an attacker can’t sign for a key they don’t hold, and they can’t make a different public key hash to a fused fingerprint (SHA-256).

Key revocation = downgrade defense without the thermometer

When the version budget is spent, you switch axes. For each new downgrade-fix:

1. sign the fixed firmware with a new key K2;
2. confirm it boots;
3. revoke the old key K1 (KEY_INVALID).

The old vulnerable image, signed by K1, now fails secure boot by signature. The version counter is not involved. RP2350 has 4 key slots, so this buys roughly 3 more rounds on top of the 48.

A decision you must make before the ceiling

Key revocation needs a free key slot reserved at provisioning time. Today rsk secure-boot lock (stage D) revokes all three unused slots. After that there is nowhere to rotate to. So this is a genuine trade-off, made up front:

Detail: after lock, the key pages stay secure-writable (the firmware must still write ROLLBACK_REQUIRED and the page-58 lock), so a future firmware command could in principle provision a key into a free, un-revoked slot even after lock. That command does not exist yet.

When the 48 budget is exhausted — the ladder

1. Rotate the key on the same board (~3 rounds, if you reserved a slot). Old images die by signature.
2. New board + new key (next section): a fresh 48, and the whole old history is dead by signature.
3. Accept the residual: secure boot still holds. A downgrade is then only possible to an attacker with physical access and one of your old signed artifacts. Document it; for most threat models this is acceptable.

This is the RP2350’s hard limit, not an RS-Key flaw. Any firmware on this chip has the same ceiling (48 versions + 4 keys). There is no software trick around it: a software rollback counter in the firmware would be weaker. It runs after the bootrom already booted the (possibly vulnerable) image, and its store would live in flash — which the same attacker can rewrite, by first flashing a partition table that permits it (threat-model.md: the table we ship fences BOOTSEL out, and only secure boot stops it being replaced).