RS-Key

RS-Key (RSK) is open-source security-key firmware for the Raspberry Pi RP2350. It turns an RP2350 board into a USB authenticator: FIDO2/WebAuthn/U2F, OpenPGP card, PIV, OATH, Yubico-style OTP. It ships the host-side tooling to drive and provision it.

Written in Rust (no_std, embassy). For development, research, and controlled experiments.

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.

flowchart TD
    user["You"] --> tools["Host tools<br/>browser · ssh · gpg · ykman · rsk"]
    tools -->|USB| dev["RS-Key firmware (applets)"]
    dev --> hw["RP2350 board<br/>flash · TRNG · OTP"]

Start here

• Quick start: build, flash, set a PIN, enroll something
• 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["nix develop · cargo build"] --> b["firmware.uf2"]
    b --> 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
• Nix with flakes enabled (the dev shell provides everything: toolchain, picotool, host tools). Without Nix: rustup + rustup target add thumbv8m.main-none-eabihf + picotool ≥ 2.0, and the Python deps from flake.nix for the host tools.

1. Build

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

This is the touch build: FIDO operations (registering, logging in) require a press of the presence button (BOOTSEL by default; set PRESENCE_PIN=<gpio> for a dedicated GPIO button). For a no-touch build (needed by the automated test suites, or if your board is hard to reach) add --features no-touch. All build knobs: build.md.

2. Flash

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:

   • 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:

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.

3. Set a PIN (recommended)

rsk fido set-pin

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

The two Printables designs 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 the MakerWorld design’s own license on its page before reusing it. 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 ...]
picotool uf2 convert target/thumbv8m.main-none-eabihf/release/firmware -t elf firmware.uf2

flowchart TD
    knobs["env knobs + cargo features"] --> build["cargo build (or nix build)"]
    build --> elf["firmware.elf"]
    elf --> conv["picotool uf2 convert"]
    conv --> uf2["firmware.uf2"]
    uf2 --> flash["BOOTSEL flash"]
    uf2 -. "secure boot only" .-> seal["picotool seal --sign<br/>signing key (host-only)"]
    seal -.-> 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).

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.

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:

  picotool seal --sign --hash result/firmware.uf2 firmware-signed.uf2 \
      ~/.rs-key-secrets/secure_boot_key.pem ~/.rs-key-secrets/otp_secureboot.json \
      --major 1 --minor 0
  

  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 ML-DSA-65 and ML-DSA-44 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.cosign.bundle: 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).

• 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 SHA256SUMS.cosign.bundle.

# 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.cosign.bundle \
  --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.cosign.bundle \
  --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 the extra two pieces below: 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.

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

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

The curve-explicit COSE ids (-9 ESP256, -19 Ed25519, -51 ESP384, -52 ESP512) are also accepted in pubKeyCredParams. RS-Key selects the first supported algorithm a site offers, so put your preferred curve first in the list.

Post-quantum credentials

The device implements ML-DSA-44 (FIPS 204, COSE -48) and ML-DSA-65 (COSE -49) makeCredential / 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 -49) gets a PQC credential today. Both are backed by the in-tree, stack-optimized rsk-mldsa implementation, which streams the FIPS 204 matrix A on the fly so ML-DSA-65’s larger keys still 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. ML-DSA-87 (-50) is recognised but unsupported: its makeCredential response overruns the CTAPHID message ceiling.

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.

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

The card enforces those lengths itself: a CHANGE REFERENCE DATA or RESET RETRY COUNTER carrying a new value outside the range is refused with 6700, 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 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. A correct entry resets that PIN’s counter. A wrong one decrements it. 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):

Not supported. gpg will offer them, and the card even accepts the key-attr write, but GENERATE / keytocard then refuses with 0x6A81 “Function not supported”: X448, Ed448, and brainpoolP512r1. (X448 and Ed448 still appear in the 0xFA advertisement but are non-functional; brainpoolP512r1 is not advertised.) 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. A mismatched algorithm/curve 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.

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. 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 DEC slot carries an on-card AES-256 key, minted automatically whenever the encryption keypair is generated. 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.

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.

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 does the same thing from the host.)

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. A PIN or PUK provisioned outside that convention (e.g. hand-crafted raw CHANGE REFERENCE DATA / RESET RETRY APDUs that store an unpadded or sub-6-digit value) 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.

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. 9e carries no special default on this firmware. Like the other non-signature slots it defaults to PIN once per session, so a default-policy 9e key still needs one VERIFY before use. For true card-auth / contactless no-PIN behaviour, generate the 9e key with an explicit --pin-policy NEVER.

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 roughly 4–6 s, 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. 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

Generated slot keys default to touch ALWAYS: each sign / decrypt / ECDH needs a button press. A declined touch fails the operation with 6982. The management key ships touch NEVER so admin provisioning isn’t gated; raise it with ykman piv access change-management-key --touch if you want admin actions to require a press 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.

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 / INCORRECT PARAMS (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

A key in a retired slot cannot be moved back into an active slot. 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, 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.

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, not the secrets at rest. OATH blobs sit in plaintext flash. Unlike PIV and OpenPGP keys, they are not individually sealed. This password protects the live applet, not a flash image; at-rest confidentiality for OATH rests only on the RP2350 device-level protections (secure boot / BOOTSEL lockout, see threat-model.md), not on per-credential sealing.
• 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.

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 (in plaintext: OATH blobs are not individually sealed, unlike PIV/OpenPGP). 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.
• 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.

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.

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.

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.

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.

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), and 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).
• 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.

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) ‖ rsvd(2). 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.

Config writes cost one slot per run

The journal is append-only with one bounded exception. CONFIG_WRITE is ungated on the default build and is the only event a silent host can drive on demand, so 128 of them would otherwise evict every other entry from the 128-slot window. Instead a run of config writes folds into a single entry: it keeps the seq and the timestamp of the first write of the run, and its detail counts the rest — repeats(2 LE) ‖ targets(1), where targets is a 1 << target mask of every record the run touched. rsk audit log renders it:

   seq      uptime  event              aux  detail
   201       8.2s  CONFIG_WRITE         1  300× write (phy+led)

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 fmt:"none" attestation. Self-attestation conveys no trust beyond “none” per WebAuthn §6.5.2, and a packed EdDSA self-attestation breaks ed25519-sk enrollment on Windows / OpenSSH 10 (issue #26). The fido-conformance build keeps packed self-attestation for the conformance suite. RS-Key does carry a per-device self-signed certificate (a P-256 X.509 leaf with CN RSK FIDO2, built over the seed at first boot), but it presents that only on U2F registration and EA-level-2 requests. 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 1 or 2 (sent by managed platforms) returns a full attestation: signature by the org key, x5c = your chain (leaf first), and the ep response flag (true). With an org key installed, both EA levels emit the org attestation.
• 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: fmt:"none", no chain, no cross-site trackable identifier. 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:

So a stock key already answers an EA-level-2 request with a real “basic” attestation, just under its own per-device cert rather than a shared chain. 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).

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: the managed platform must re-issue enableEnterpriseAttestation before 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 returns fmt:"none" and is unlinkable; 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) and fips-profile (drops secp256k1, raises the PIN floor to 6) 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: the tool takes the first FIDO device it finds, and the USB serial is a constant, so it cannot tell two RS-Keys apart. With a second key attached the wait simply times out and the run aborts cleanly rather than resetting the wrong device. A trusted-display key never sees the 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 (piv/keygen.rs:48) and the separate import path (piv/keygen.rs:242), 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"]

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.

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)

picotool seal --sign --hash firmware.uf2 firmware-signed.uf2 \
    ~/.rs-key-secrets/secure_boot_key.pem ~/.rs-key-secrets/otp_secureboot.json \
    --major 1 --minor 0 --rollback 1
picotool info firmware-signed.uf2        # must say "signature: verified"
# BOOTSEL, then flash + confirm the device works:
picotool load -v firmware-signed.uf2 && picotool reboot   # or drag it onto the RP2350 drive

The arguments:

• secure_boot_key.pem: your signing key. It signs the image.
• otp_secureboot.json: seal writes the boot-key fingerprint here. You fuse it into OTP with load-key below.
• --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.

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    # 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
picotool uf2 convert target/thumbv8m.main-none-eabihf/release/firmware -t elf firmware.uf2
picotool seal --sign --hash firmware.uf2 firmware-signed.uf2 \
    ~/.rs-key-secrets/secure_boot_key.pem ~/.rs-key-secrets/otp_secureboot.json \
    --major 1 --minor 0 --rollback 1
# BOOTSEL (hands-free: rsk reboot bootsel), then:
picotool load -v firmware-signed.uf2 && picotool reboot   # or drag it onto the RP2350 drive

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.

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.uf2 firmware-signed.uf2 \
    ~/.rs-key-secrets/secure_boot_key.pem ~/.rs-key-secrets/otp_secureboot.json \
    --major 1 --minor 0
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.uf2 firmware-signed.uf2 \
    /tmp/sk.pem ~/.rs-key-secrets/otp_secureboot.json --major 1 --minor 0
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 the three unused slots. Maximum hardening, but it also removes any room to add a key later.
• 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.

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.uf2 firmware-signed.uf2 \
    ~/.rs-key-secrets/secure_boot_key.pem ~/.rs-key-secrets/otp_secureboot.json \
    --major 1 --minor 0 --rollback 3        # 3 = counter (2) + 1
# 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.

Prevention beats cure. 48 genuine downgrade-exploitable fixes on a single chip is beyond even commercial keys over a decade. If you are approaching the limit, you are almost certainly flagging as “downgrade-fix” releases where booting the old image gains the attacker nothing. The real discipline is: floor +1 only when the old image is a working exploit.

Moving to a new board

A fresh chip gives a fresh 48 and fresh 4 slots. You provision a new signing key (yours, backed up) and trust only it on the new board.

Why the new board’s floor is 1, not a repeat of every old risk

This is the subtle part. Starting a new board at floor 1 can look like you are re-accepting every downgrade risk you defended against on the old board. You are not. The protection didn’t disappear. It moved from the version axis to the key axis:

• the old vulnerable images are signed with the old key;
• the new board trusts only the new key, so those images are refused by signature;
• and there are no vulnerable images signed with the new key. You signed only the current, fixed firmware with it.

So there is nothing below floor 1 (on the new key) to block. Floor 1 is safe precisely because no image exists that is both (a) vulnerable and (b) signed by a trusted key.

The rule that makes this work: an image is dangerous only if it is both signed by a trusted key and exists as a file. On the new board, old vulnerable images are signed by an untrusted key, and the new key has signed only the fixed firmware.

⚠️ Required condition: the new board trusts only the new key. If you also provision the old key on the new board, the old vulnerable images pass the signature check again and floor 1 will not stop them. New board ⇒ fresh key, old key not carried over.

What migrates, what doesn’t

• Migrates: your FIDO identity, via seed backup (ssh ed25519-sk, 2FA registrations), with rsk backup restore.
• Does not migrate: resident passkeys, OpenPGP and PIV keys, sealed to the old chip, not derivable from the seed. Re-enroll those.

How to verify all of this

rsk secure-boot status              # fused boot-key fingerprint, ROLLBACK_REQUIRED, boot version N/48
picotool info firmware-signed.uf2   # the image's key fingerprint — compare to the fused one

Negative tests are the real proof:

• an unsigned UF2 → bootrom refuses it, falls back to BOOTSEL;
• an image below your floor → refused (the version axis works);
• an image signed by the old / a foreign key → refused by signature (the key axis works).

Cheat sheet

• Firmware version ≠ rollback floor. The project assigns no epochs. The floor is on your board and you control it.
• The project only flags a release as a downgrade-fix; you decide and you burn.
• Raise = your board’s current counter + 1. Default: don’t burn.
• Don’t burn ⇒ downgrade is possible (your conscious risk).
• Budget is 48 per chip; burning is irreversible.
• At the ceiling, updates still work; protection moves to key revocation.
• A new chip + new key is a clean restart at floor 1; the old history is dead by signature, not by version.

Threat model

What RS-Key defends against, what it deliberately does not, and the honest residuals in between. The defenses compose in tiers: each one assumes the ones before it.

Assets

The FIDO master seed (every non-resident credential derives from it), resident passkeys, OpenPGP private keys and their DEK chain, PIV private keys, OATH secrets, OTP slot secrets, PINs.

Attackers, strongest defense first

1. A hostile host (malware on the computer)

Everything arriving over USB is attacker-controlled: CTAPHID frames, the CCID bulk stream, ISO-7816 APDUs, CTAP2 CBOR. Defenses:

• Memory safety. no_std Rust end to end. The parsers and applet dispatch are safe code. The handful of unsafe sites are enumerated and justified in unsafe.md.
• Fuzzing. Every parser and every applet’s full dispatch path has a cargo-fuzz target (30+). See testing.md.
• Protocol gates. PINs/UV with retry counters and lockout, physical-touch requirements on FIDO operations and OpenPGP UIF, OATH access codes, PIV management-key auth.
• What a hostile host can do: drive any operation you have authorized while the device is plugged in and unlocked (sign, decrypt, assert). A security key authenticates presence and possession, not the intent of every byte the host sends. Touch requirements bound the rate.
• Device config is UNGATED on the default build. The shipped default is the full-ykman/YubiKey-compatible admin surface: a hostile USB host can silently rewrite the DeviceInfo / enabled-applications / USB identity — over CCID Management WRITE CONFIG, the FIDO vendor CONFIG_WRITE, and the CTAPHID (0x43) and OTP-HID (0x15) transport writes — with no touch or PIN, and can trigger a device-wide factory reset (that one keeps a presence gate). The USB identity (serial, strings) is cosmetic — never proof a device is genuine, attestation is (§3). The enabled-applications mask is enforced, though: a disabled application’s applet stops answering (PIV/OpenPGP/OATH/OTP over CCID, FIDO2/U2F over CTAPHID, the OTP keyboard), so a hostile host can turn one off. That is a reversible denial-of-service, not a confidentiality or integrity break — the Management applet, the FIDO vendor command, and the OTP-HID identify/config slots are never gated, so any single transport can re-enable it, and no secret is exposed. If you need config writes gated on the operator, build/flash firmware-strict-config, which restores the presence/PIN gates and refuses the ungated transport writes (build.md). It is not the runtime flash flag EF_HARDENED.
• The residual gap is intent. The trusted-display flavor closes it. Because a standard key attests presence and possession, a malicious page can silently drive an authorized key over WebUSB to phish a real sign-in (demonstrated against YubiKeys in Chrome). The trusted-display flavor paints the true rpId on the device’s own screen and gates each signature on a tap there, so a compromised host cannot fake what you approve. Qubes OS’s CTAP proxy tackles the same gap in software, mediating CTAP through a trusted VM.

2. A thief with the powered-off device (at-rest)

• All key material is sealed in flash: FIDO seed and PIV keys under AES-256-CBC/GCM keyed by a device key (kbase = HKDF of the chip serial and the OTP master key once provisioned), OpenPGP keys under the PIN-wrapped DEK chain.
• OTP master key (production.md stage 1): with the MKEK fused and page-58 hard-locked, a flash dump (even with BOOTSEL access and the chip id) does not reproduce the sealing key. Without the burn, the sealing key derives from on-chip state an attacker with full flash + chip access could reconstruct. The burn is what makes at-rest real.
• The seals give confidentiality, not authenticity. Records written before the burn are keyed from the public chip serial alone, and those pre-OTP arms stay readable afterwards so a provisioned device keeps working across the upgrade. So an attacker who can write flash (BOOTSEL) can forge a record that opens under one, and the boot migration then re-seals it under the fused root. Reading the flash still tells them nothing. Closing this needs a fuse-rooted latch on the migration window; audit run-27 #8 has the analysis.
• Soft-lock (guides/soft-lock.md): optionally, the seed at rest is additionally wrapped with ChaCha20-Poly1305 under a 32-byte key only you hold (BIP-39/SLIP-39 words). A stolen device (even running genuine firmware) refuses every FIDO operation until that key is presented over an encrypted channel at power-up. Device + words, two factors.
• Caveat: superseded records linger. The flash log is append-only, so re-sealing or deleting a secret leaves the old copy on flash until its page is reclaimed. Two cases differ in how much that matters:
  • The OTP-burn migration supersedes the pre-OTP seed, which was sealed under the chip-serial-only root (no fuse secret). Left alone, a flash dump plus the chip id would recover it, bypassing the burn. So it is not left to lazy healing: the first boot after provisioning runs a one-shot compaction (Fs::compact, gated by the EF_HARDENED marker, crash-safe) that drives a full GC lap over the credential partition and physically erases every superseded pre-OTP record before the device re-attaches to USB.
  • The soft-lock transition leaves the same kind of lingering record, but on a provisioned device it is already sealed under the fused root (moot against anything short of a fused-key compromise), so soft-lock’s at-rest guarantee simply hardens over time as natural compaction overwrites it.
• The FIDO seed is never PIN-wrapped at rest (a deliberate design decision). UP-only operations (ssh ed25519-sk, U2F, no-PIN assertions) must work from a cold boot with no PIN presented. So a PIN-keyed at-rest copy adds no protection an attacker couldn’t bypass via the always-loadable copy, while breaking those flows. At-rest strength is the kbase (tier above), not the PIN.

3. An attacker who can flash their own firmware

• Secure boot (production.md stage 2): the bootrom refuses unsigned images, so no foreign code ever runs to read the OTP key in secure mode. Glitch detectors are fused on along the way.
• Anti-rollback (anti-rollback.md, optional): with ROLLBACK_REQUIRED fused, images below your board’s rollback floor (or carrying no version at all, i.e. anything sealed before the feature) no longer boot. A kept copy of an old signed release with a since-fixed bug stops being a downgrade path.
• Before secure boot is enabled, this attacker wins against the OTP tier: their firmware reads the MKEK exactly like ours does. That is why the production page calls the two stages one story.
• The USB/smartcard identity (VID/PID, manufacturer, product, OpenPGP AID vendor) is fully host-configurable at runtime via the phy record and is not an authenticity signal: a phy write that sets the Yubico VID makes a stock key present a full Yubico identity, and the manufacturer/product strings are also settable outright (phy tags 0x0F / 0x09), so any VID can carry any vendor name. On the default build these config writes are ungated (no touch, no PIN — see §1); firmware-strict-config re-gates them. Treat the identity as cosmetic, never as proof a device is genuine — attestation (device-key / org cert) is the authenticity mechanism, and it is unaffected by any config write.

4. Physical / lab attacks — OUT OF SCOPE

Decapping, microprobing, advanced fault injection beyond the RP2350’s glitch detectors, power/EM side channels, and the XIP TOCTOU: interposing on the QSPI bus to serve the genuine image to secure boot’s verifier and a tampered one to the CPU, since nothing binds checked bytes to executed bytes and the image is too large to verify-in-place from SRAM. An in-package-flash part (RP2354) leaves no discrete flash chip to tap, raising a reliable swap to decap-class effort. The RP2350 is not a secure element and RS-Key does not pretend otherwise. If your threat model includes a funded lab, buy a certified key.

5. Network

None. The device speaks USB only. There is no radio and no IP stack.

Flash snapshot rollback (the PIN-counter reset)

Reported by Token2 (issue #37, advisory PDF). An attacker with brief physical access and BOOTSEL runs picotool save to snapshot the whole flash, guesses PINs until the wrong-PIN counter locks, then picotool loads the old snapshot to reset the counter and repeats. That is unlimited offline PIN guessing. It defeats every applet’s retry counter — FIDO clientPIN, PIV PIN/PUK, OpenPGP PW1/PW3, OATH — since all are ordinary flash records with no external freshness binding.

The gap is freshness, not confidentiality or authenticity. Secure boot accepts the restored image (it is genuine and signed); the at-rest seal decrypts it (same chip). Neither notices a rollback. RS-Key’s firmware anti-rollback (anti-rollback.md) versions the firmware image, not the flash data, so it is blind to the swap too. The clean fix is a monotonic counter in tamper-resistant NVM that the firmware checks on boot — exactly what a secure element has and the RP2350 lacks. Its OTP is write-once antifuse (a few dozen one-way bits for the board’s whole life), so it cannot back a retry counter that must reset to eight on every correct PIN. We cannot close the rollback itself on this silicon; we raise its cost:

• OTP-seeded PIN verifier (always on after the OTP burn). The stored verifier is HKDF(serial_hash, HMAC(kbase, pin)), with kbase rooted in the fused OTP master key (production.md stage 1). A flash dump does not contain that key, so it cannot brute-force the PIN offline — the guessing must run on the device, one try at a time.
• strong-pin / fips-profile builds (opt-in). Raise the clientPIN floor to six code points and refuse the most guessable PINs (a repeated digit, a 123456-style run), so the on-device search space is at least a million. By Token2’s estimate an automated attack runs ~34 days at six digits and ~10 years at eight, against ~8 hours at four (build.md).
• Soft-lock (opt-in). The FIDO seed is wrapped under a key only you hold (guides/soft-lock.md), so a brute-forced PIN yields nothing until you present it. It covers the FIDO seed; the PIV, OpenPGP and OATH counters stay rollback-resettable.

The durable defense on a general-purpose MCU is PIN entropy, plus the soft-lock second factor for the FIDO seed. A device left in an attacker’s hands, protected only by a short PIN, is not safe here. This is the same boundary as “anyone with the device and your PIN is you”.

Platform silicon: the RP2350 security challenges

Raspberry Pi has publicly stress-tested the RP2350 die. The results bound RS-Key’s physical-attack posture.

Challenge 1 broke the A2 stepping (results). The task was to extract an OTP secret from a board running secure boot. The winning attacks:

• Aedan Cullen: voltage glitch on the USB_OTP_VDD rail, reading OTP secrets out of the guarded path (erratum E16) (writeup, talk).
• Marius Muench: a glitch plus a boot-ROM flaw, bypassing secure boot to run unsigned code.
• Kévin Courdesses: laser fault injection corrupting the boot-time signature check (erratum E24) (writeup).
• IOActive: focused-ion-beam (FIB) plus passive voltage contrast (PVC), reading the antifuse array directly: the bitwise OR of two physically paired bitcell rows (writeup).

The first three are comparatively cheap fault / boot-ROM attacks. The IOActive readout needs FIB-class lab equipment (a tool worth hundreds of thousands of dollars, one to two days per target) and applies to every device built on the Synopsys dwc_nvm_ts40* antifuse IP on TSMC’s 40 nm node, an antifuse property, not an RP2350-specific defect.

The A4 stepping fixes the fault and boot-ROM attacks in silicon, but not the antifuse readout (announcement). A4 closes the boot-ROM errata (E20/E21/E24, including the laser signature bypass) in a new boot ROM, the OTP power-glitch (E16) through changes to the wrapper circuitry around the OTP macro, and the GPIO errata (E9, E3). The antifuse-array PVC readout is explicitly not fixed in A4. Raspberry Pi’s guidance is to mitigate it by how secrets are stored in OTP, the chaffing RS-Key applies (see otp-fuses.md). A third challenge (power side-channel analysis of the secure-boot AES) is open with no break reported (challenge 2).

What this means for RS-Key. Our development boards are A2: the broken stepping, kept as the conservative worst case. The firmware is A4-compatible, and A4 is recommended for the fault / boot-ROM attacks above. Against the antifuse readout (which no stepping fixes), RS-Key applies the chaffing mitigation directly (otp-fuses.md). What remains out of scope is unchanged: a funded lab with FIB/PVC, laser fault injection, or power/EM analysis against a device in hand. No software or provisioning choice on a general-purpose die closes those. That is what a dedicated secure element is for (limitations.md).

Seed backup (the deliberate exception)

A FIDO authenticator’s pitch is non-exportable keys. The wallet-style backup is a conscious trade for recoverability, gated accordingly. Export moves the seed over an ephemeral encrypted channel (P-256 ECDH → HKDF → ChaCha20-Poly1305), and requires (all at once) physical touch, the FIDO PIN/UV token when a PIN is set, and the one-time setup window: after an explicit finalize, export is refused until a full reset regenerates a new seed. Malware cannot exfiltrate the seed silently or later. Restore re-seals the seed under the destination chip’s root. The host driving a backup necessarily sees the seed plaintext. Do it on a machine you trust. Scope: the deterministic identity only (resident passkeys, OpenPGP, PIV are not covered).

On the trusted-display flavor the host need not be in that trust path: the device can render its BIP-39 recovery phrase on its own screen (the seed is turned into words on-device and never crosses USB), so a backup can be taken without trusting any host. That trades the host-observation surface for a physical/visual one. The words are briefly on the panel (shoulder-surf, camera). It is gated to keep that surface small: it requires a device PIN set and re-entered, a deliberate hold past an explicit “no one watching” warning, runs only inside the same one-time window (and seal closes it), is disabled on the fips-profile (non-exportable) build, zeroizes the seed/words from RAM on exit, and auto-clears the panel after a short idle.

sequenceDiagram
    participant U as You
    participant H as Host
    participant D as Device
    U->>D: touch + PIN/UV (when set)
    H->>D: ephemeral P-256 ECDH
    D-->>H: seed over HKDF → ChaCha20-Poly1305 channel
    Note over H: the host necessarily sees the seed in the clear
    H-->>U: BIP-39 / SLIP-39 words
    U->>D: finalize → export refused until a full reset

Zeroization

Key-grade material in RAM is wiped (zeroize, volatile writes) when its use ends: session state and PIN/UV tokens on drop, transient key copies at end of scope including error paths, and the transport/exchange buffers as soon as a message completes (requests carry PINs and imported keys). Accepted residuals: Copy temporaries inside RustCrypto curve arithmetic, digest internals, and heap temporaries inside the rsa crate. Short-lived, library-internal, not wipeable without forking the crates.

Supply chain & process

• cargo audit + cargo deny (advisories, license allow-list, source policy) and gitleaks run in scripts/check.sh and the pre-commit hook.
• Dependencies are pinned (Cargo.lock). The git dependencies are restricted to the embassy organization.
• One known-unfixed advisory is accepted deliberately: RUSTSEC-2023-0071 (Marvin timing side channel in rsa), the OpenPGP RSA backend. It is mitigated by per-operation base blinding on every private-key path (PKCS#1 v1.5 sign, decipher, and the raw fallback rsa_raw). Rationale in deny.toml. The constant-time audit verified that this blinding leaves no unblinded private-exponent path.

Post-quantum notes

ML-DSA-44 (COSE −48) and ML-DSA-65 (COSE −49) FIDO2 credentials (both the in-tree rsk-mldsa crate) with hedged signing (32 fresh DRBG bytes per signature; the hedge and expanded keys are zeroized). rsk-mldsa streams the FIPS 204 matrix A on the fly so ML-DSA-65’s keygen+sign fit the RP2350 stack. It is hand-written, so its constant-time posture is a source-level claim (branch-free reductions, masked norm checks, no secret division), not proven at machine code. It is checked byte-for-byte against NIST ACVP KATs, with Kani proofs over the reductions and rounding. ML-DSA-87 (−50) is out of reach on this chip (keygen overflows the stack; its makeCredential response also overruns the CTAPHID message ceiling). ML-KEM-768 is compiled in as scaffolding but nothing calls it until a CTAP PQC PIN/UV protocol exists. None of these has a third-party audit yet, the same standing as the rest of the RustCrypto stack, tracked via cargo-audit/deny.

Reporting

This is an experimental hobby project. If you find a security issue, please report it privately to the maintainer rather than opening a public issue.

Limitations — what RS-Key does not do, and why

Each gap below comes with its reasoning. “Not yet” and “never” are marked. The project as a whole is experimental and unaudited. The threat model covers the security boundary. This page covers feature and hardware gaps.

Cryptography

• brainpoolP512r1 (OpenPGP): not offered. brainpoolP256r1 and P384r1 are supported (advertised in DO 0xFA, generate / keytocard / sign / decrypt), but no Rust arithmetic for the 512-bit brainpool curve exists yet, so the applet neither advertises nor generates it. Status: until a crate exists.

• X448 / Ed448 (OpenPGP): not offered, same reason. RustCrypto coverage of Curve448 is thin and unaudited. Cv25519/Ed25519 plus the NIST curves and secp256k1 cover practical use. Status: until a serious crate exists.

• RSA-3072/4096 on-card generation is slow. The prime search dominates the cost: rejecting hundreds of composite candidates, each one asm-modexp-bound. Both cores run the search with the modexp hot path in SRAM (architecture). Typical timings, measured on the reference board (single-core → dual-core):

  key	before	after
  RSA-2048	~8.9 s	~4–6 s
  RSA-3072	~35 s	~22 s
  RSA-4096	~65 s	~50 s

  The total is set by how many candidates a given draw happens to need, which is random. The per-keygen spread is wide (17 s to 124 s seen at 4096) because that count varies, not because the silicon does. Per candidate the throughput is ~6.9 ms across both cores.

  The lever is fewer candidates reaching the modexp: a deeper small-prime sieve. (The Baillie–PSW that confirms a survivor, asm strong Miller–Rabin plus a software Lucas test, runs only a handful of times per keygen, so it doesn’t move the total.) Depth is set by the measured cost ratio: one strong-MR modexp is ~35 ms (1024-bit) / ~239 ms (2048-bit) against ~11 µs / ~23 µs for one trial division, so it pays to sieve by every prime up to ~3.1k / ~10.5k, far past the old flat 256-prime (≤1619) sieve. Depth now scales with key size (448 primes at RSA-2048 … 1280 at RSA-4096), and the sieve runs incrementally: a candidate stream n, n+2, n+4, … from a random odd start, each residue n mod pᵢ stepped by one add instead of re-derived by a Horner pass (OpenSSL/GMP do the same). The primality decision is untouched, so key strength is unchanged. Same-device A/B (per-candidate cost, which divides out the prime-search-luck variance): depth-scaling took RSA-2048 7.84 → 6.48 ms/candidate and RSA-4096 36.0 → 26.2 ms versus the old flat 256-prime sieve, and the incremental step took those a further 6.48 → 5.28 ms (−18.5%) and 26.2 → 20.9 ms (−20.4%). The device streams keepalives throughout, so tools wait it out. Import is fast. Status: inherent to the hardware class; the parallel-scan share is at the two-core limit, the sieve at the measured modexp:division ratio and now incremental.

• ML-KEM is scaffolding: compiled, tested, unused. No CTAP PIN/UV protocol number for PQC key agreement exists yet to implement. Status: waiting on standards.

• PQC interop is limited by client support: ML-DSA-44 (COSE −48) and ML-DSA-65 (−49) credentials work and verify on-device. Their signatures verify under OpenSSL and Yubico’s python-fido2, but no browser or mainstream WebAuthn library negotiates these COSE ids against security keys yet. Released Firefox versions abort getInfo if the algorithm is advertised (hence the advertise-pqc build flag, default off; capability stays on regardless). ML-DSA-87 (−50) does not fit the RP2350 (stack + CTAPHID message size). These are the ML-DSA schemes, not a FIPS-validated module.

Backup & migration

• The seed backup covers the deterministic identity only. Non-resident credentials (ssh ed25519-sk, most 2FA registrations) derive from the master seed and survive a restore onto a new board. Not covered: resident passkeys (stored records, not derivable), OpenPGP private keys, PIV private keys, OATH secrets, OTP slots, all sealed to the source chip. A board swap means re-enrolling those. Status: by design; a full at-rest export would gut the at-rest story.
• A finalized backup window stays closed until a factory reset regenerates the seed. Lost words cannot be re-exported. Pick a generous SLIP-39 share count. Status: by design (anti-exfiltration gate).

Hardware / physical

• No secure element. The RP2350’s OTP fuses, glitch detectors and secure boot are real, and RS-Key adds anti-imaging OTP chaffing on top. But decap, microprobing, FIB imaging, advanced fault injection and power/EM side channels remain out of scope. The public RP2350 hacking challenge broke the A2 stepping. The A4 stepping fixes the boot-ROM and OTP power-glitch attacks in silicon, but not the antifuse-array readout (mitigated only by how secrets are stored: the chaffing RS-Key applies). Our development boards are A2. The firmware is A4-compatible and A4 is recommended. Status: never. These are silicon properties, not firmware ones; closing them fully is what a dedicated secure element is for.
• The at-rest seals are not authenticated against a flash writer. They keep a flash dump from yielding key material, which is what the OTP burn buys. They do not stop someone who can write flash over BOOTSEL from planting a record: the pre-OTP key base derives from the public chip serial, and those arms stay readable after the burn so an already-provisioned device survives the upgrade. The boot migration then re-seals the planted record under the fused root. Status: needs a fuse-rooted latch that closes the migration window once the device is provisioned; the analysis is audit run-27 #8, the decision is the maintainer’s because it makes lock-page58 load-bearing for boot correctness.
• XIP TOCTOU residual: secure boot verifies the image in external QSPI flash, then executes from it. Nothing binds the bytes that were hashed to the bytes later fetched, so hardware interposing on the QSPI bus can serve the genuine image to the verifier and a tampered one to the CPU. The clean fix (copy the image into SRAM, verify, run verified-in-place) does not fit: the ~1.7 MB image plus working RAM far exceeds the 520 KB SRAM. There is also no runtime flash authentication in hardware. Part selection is the real lever: an in-package-flash device (RP2354) stacks the flash die on the QSPI bus inside the package, so there is no discrete flash chip to clip an emulator onto and a reliable interposer needs decap-class access. RS-Key is developed and tested on external-flash RP2350 boards, so RP2354 is a recommendation here, not a configuration the project has validated. Status: never on an external-flash board; decap-class effort on RP2354.
• No TrustZone-M secure/non-secure split. Considered and rejected: the embassy ecosystem has no TrustZone support, so it would mean hand-rolling SAU/IDAU configuration, NSC veneers and dual images (the project’s single biggest item) to defend mainly against parser memory corruption, which safe Rust plus fuzzing already address. Physical attacks are orthogonal to TrustZone. Status: revisit only with ecosystem support.
• Anti-rollback is opt-in and coarse: picotool seal --rollback plus the ROLLBACK_REQUIRED fuse (anti-rollback.md). The OTP thermometer has 48 steps for the board’s life, so the rollback floor is raised for security-relevant releases only. Until the fuse is set, any previously-signed image still boots. Status: shipped (optional).
• No image encryption: pointless for open-source code (no secrets in the image; secrets live sealed in flash), and the RP2350 has no transparent XIP decryption anyway. Status: never.

Protocol / compatibility

• The default USB identity is RS-Key’s own (0x1209:0x0001 on the pid.codes FOSS VID, manufacturer RS-Key, product RS-Key Security Key, reported firmware 5.7.4), not a YubiKey masquerade. We no longer ship Yubico’s identifiers by default. A YubiKey identity (0x1050:0x0407, reader name Yubico YubiKey …) exists only as the opt-in VIDPID=Yubikey5 build flavor (build.md), built for local interop testing and never distributed. Distributing hardware with Yubico’s identifiers is not OK. The trade-off: ykman, Yubico Authenticator and the stock Yubico udev rules gate on the Yubico YubiKey reader name / VID 0x1050, so on the default RS-Key build they do not see the device. Use them against the VIDPID=Yubikey5 flavor, or add a udev rule matching VID 0x1209. FIDO2/WebAuthn, ssh -sk, gpg/OpenPGP, OpenSC/PKCS#11 and the project’s own rsk/rsk-tui tools are identity-independent and work on the default build.
• OpenPGP secure messaging is not implemented (rarely used by clients; PINs gate everything in practice).
• One physical button on the base build. Touch = the BOOTSEL button, and there is no fingerprint reader, so UV is the PIN and “number matching” style UV is impossible. The trusted-display flavor (guides/display.md) adds a screen for on-device PIN entry and per-signature relying-party approval, but still no biometric UV.

Operational

• The flash log heals lazily: deleting/superseding a record (e.g. enabling the soft-lock) leaves the old record in the log until compaction naturally overwrites it, so most at-rest guarantees harden over time rather than instantly. (On a provisioned device the superseded copy is sealed to the fused root.) The one record that is not left to lazy healing is the pre-OTP seed superseded by the OTP-burn migration. It is sealed under the chip-serial-only root, so the first boot after provisioning scrubs it eagerly with a one-shot full-GC-lap compaction.
• The board is the security boundary: anyone with the device and your PIN is you. Same as every security key.

unsafe audit

The firmware is no_std Rust. Safety of the parsers and applet logic is the core defensive property, so every unsafe is enumerated here: its justification, why a safe alternative does not work, and how the risk is contained. Adding a new unsafe requires updating this page. (Safe Rust rules out memory-corruption bugs in this code. It is not a security audit; see the threat model.)

Runtime sites: 15. Eight in the firmware proper (main.rs + presence.rs): the interrupt-handler pair (2), the Send impl, the heap init, and the four GPIO-pin steals (the presence button, the LED power-enable rail, the nuisance USR LED, and the display build’s wake button). Two for the per-core prime sieves, three in the RSA assembly FFI, two in the standalone flash-wipe tool.

flowchart TB
    subgraph fw["firmware/src/main.rs + firmware/src/presence.rs"]
      a["interrupt executor (×2)"]
      b["Send for SendUsb"]
      c["heap init"]
      d["GPIO pin steal ×4 (presence, LED power, USR LED, display wake)"]
    end
    subgraph kg["firmware/src/core1.rs"]
      e["per-core prime sieves (×2)"]
    end
    subgraph asm["rsk-rsa-asm"]
      f["modexp / sign_crt / modexp_pub FFI (×3)"]
    end
    subgraph wipe["rsk-wipe"]
      g["raw flash erase/program (×2)"]
    end

The unsafe lives only in plumbing. None of it is in a parser, applet, crypto wrapper, or the filesystem.

Firmware (firmware/src/main.rs, firmware/src/presence.rs)

1–2. The high-priority interrupt executor

#![allow(unused)]
fn main() {
#[interrupt]
unsafe fn SWI_IRQ_1() {
    unsafe { EXECUTOR_HIGH.on_interrupt() }
}
}

USB and the transports run on an embassy InterruptExecutor so they preempt long synchronous work (RSA keygen, flash GC) and keep the bus alive. The handler itself is unsafe fn (hardware interrupt ABI). The on_interrupt() contract (call only from the interrupt the executor was started on) is upheld by construction: EXECUTOR_HIGH.start(SWI_IRQ_1) is the only starter and this is the only caller. Safe alternative: none; this is embassy’s documented pattern for a second executor. Containment: two lines, no data touched.

3. unsafe impl Send for SendUsb

embassy_usb::UsbDevice is !Send only because it holds a list of &mut dyn Handler control-request handlers. Our only stateful handler is a zero-sized type whose state is Sync (critical-section-guarded statics). The device is moved into exactly one task on the interrupt executor and never touched from anywhere else: exclusive ownership after the move. Safe alternative: none while the USB device must live on the interrupt executor and embassy keeps the trait object !Send. Containment: the wrapper is private, constructed once, and the invariant (single task, single executor) is structural.

4. Heap initialization

#![allow(unused)]
fn main() {
unsafe { HEAP.init(core::ptr::addr_of_mut!(HEAP_MEM) as usize, HEAP_SIZE) }
}

A 64 KiB heap exists solely for the rsa crate’s big integers (the only allocating dependency). init’s contract (call once, with exclusive access to the region) is met: it runs once at the top of main, on a dedicated static buffer used by nothing else. Safe alternative: none; every embedded allocator initializes this way. Containment: one call, before any allocation can happen.

5–8. GPIO pin type-erasure (presence button, LED power rail, USR-LED-off, display wake, ×4)

#![allow(unused)]
fn main() {
let any = unsafe { AnyPin::steal(pin) };
}

Four build-configurable GPIOs are chosen by number at build time rather than as a concrete PIN_n type, so each must be converted to embassy’s type-erased AnyPin: the optional PRESENCE_PIN=<gpio> presence button (ButtonPresence::new_gpio, presence.rs), the optional LED_POWER_PIN enable pin driven high to power a gated LED rail (the LED block in main.rs), the optional USR_LED_PIN driven to a nuisance onboard LED’s OFF level and held (the boot block in main.rs), and — display builds only — the optional WAKE_PIN button that wakes the panel from display sleep (the panel block in main.rs). AnyPin::steal is unsafe because the caller must guarantee unique ownership of that hardware pin — a match over p.PIN_0..=PIN_29 (as the LED data pin uses) is impossible here, since it would double-move the peripheral set the LED block already claims. Safe alternative: none for a runtime/number-selected GPIO; the safe constructors require a statically known pin type. Containment: each is gated by pin-range validation and the single-owner invariant from main — none of the presence pin, the LED-power pin, the USR-LED pin, nor the wake pin is ever handed to another driver, and compile-time assert!s reject a build that collides LED_POWER_PIN or USR_LED_PIN with the LED data pin or a GPIO PRESENCE_PIN (and refuse USR_LED_PIN outright on a display build, whose panel owns those pads) or a WAKE_PIN in the LCD/touch range (10..=18), as an LED/presence collision already panics at boot.

Firmware dual-core keygen (firmware/src/core1.rs)

9–10. The per-core prime sieves

#![allow(unused)]
fn main() {
static mut CORE0_SIEVE: IncrementalSieve = IncrementalSieve::new();
static mut CORE1_SIEVE: IncrementalSieve = IncrementalSieve::new();
// …
let sieve = unsafe { &mut *core::ptr::addr_of_mut!(CORE1_SIEVE) }; // core1
let sieve = unsafe { &mut *core::ptr::addr_of_mut!(CORE0_SIEVE) }; // core0
}

The dual-core keygen runs one running small-prime sieve per core (each ~5 KiB of residues, too large to live on core1’s stack beside the Baillie-PSW bignum frames, so they are static). Each is single-core-exclusive: CORE0_SIEVE is taken &mut only inside run_rsa_search (core0), CORE1_SIEVE only inside search (core1), and the two cores never touch the same sieve. So the &mut never aliases and there is no cross-core race. Each keygen calls scrub() through the reference before use, forcing a fresh window and wiping any prime left from the previous job. Safe alternative: none that is free. A Mutex/critical-section cell would add a lock on a provably-uncontended access, and the sieve is reused across jobs so it cannot be a stack local. (Edition-2024 forbids implicit &mut to a static mut, hence the explicit addr_of_mut!.) Containment: two call sites, one per core; the partition (which core touches which sieve) is structural, and the data is non-secret (small-prime residues of a candidate, scrubbed at the top of every keygen). A wrong residue can only let a composite through to the strong-MR/Lucas test, which still rejects it.

RSA assembly FFI (crates/rsk-rsa-asm/src/lib.rs)

11–13. The modexp / CRT-sign calls

On-card RSA key generation needs hundreds of modular exponentiations over 1024–2048-bit candidates. The pure-Rust path was ~7× too slow on the Cortex-M33 (minutes per key, CCID timeouts). The crate wraps the vendored C+ARM-assembly routines behind three unsafe FFI calls — modexp_priv (keygen), sign_crt (the CRT private-key operation) and modexp_pub (the public-exponent side of blinding and the fault check) — each with fully owned, length-checked buffers on both sides. Safe alternative: tried (num-bigint). Functionally correct, unusably slow. Containment: both ends fail closed. Key generation is KAT-gated — a power-on known-answer self-test must pass or it refuses to run — and every signature is Bellcore-fault-checked (out^e == base) by the caller, so a miscompiled or corrupt routine cannot emit one. Inputs/outputs are fixed-size stack buffers zeroized after use. On the host the crate substitutes a pure-Rust fallback, so all host tests exercise the same API safely.

Flash wiper (rsk-wipe/src/main.rs)

14–15. Raw flash erase/program in a critical section

The wiper’s entire job is to erase the flash the firmware lives on, from a RAM-resident image. It calls the ROM flash-erase/program routines inside critical_section::with(|_| unsafe { ... }): interrupts off, XIP disabled, nothing else running. Safe alternative: none; erasing the chip out from under yourself is inherently unsafe and is the tool’s purpose. Containment: rsk-wipe is a separate opt-in UF2 you flash deliberately; it never ships inside the firmware.

Build-time (not runtime)

• crates/rsk-rsa-asm/build.rs: unsafe { env::set_var(...) } forces the ARM cross-compiler for the vendored C. Build scripts are single-threaded at that point (the call is host-side, never in the image).
• Edition-2024 declarations: #[unsafe(link_section = ".start_block")] on the two bootrom image-definition statics and unsafe extern "C" on the linker-symbol/FFI declaration blocks. These mark declarations the compiler cannot check. The symbols are addresses read via addr_of!, never dereferenced as data.

What is not here

No unsafe in any parser, applet, crypto wrapper, or the flash filesystem. The attacker-facing surface is entirely safe Rust, and cargo clippy -D warnings plus the fuzz targets (testing.md) keep it that way.

Constant-time / timing side-channel audit

This is a source-level constant-time and timing side-channel audit of the RS-Key firmware (Rust, no_std, RP2350 / Cortex-M33). Its scope is every secret-dependent comparison, branch, memory access, and private-key arithmetic operation that an attacker holding the device can probe over USB (CCID / ISO-7816 APDUs and CTAPHID / CTAP2): PIN/PUK/password verifiers, the FIDO pinUvAuthToken MAC, OATH and OTP access codes, RSA private operations, and the hand-written rsk-rsa-asm keygen primitives.

What this is and isn’t. This is a source/disassembly audit: it establishes that the generated machine code has no secret-dependent branch / early-exit / index on the audited paths. It is not a measured timing study and does not replace an instrumented hardware harness (TVLA / Welch t-test). See Coverage & limits.

Summary

42 candidate sites were examined. 3 were real findings, all fixed (no high/critical). The core authentication surface is sound. The project’s hand-rolled constant-time comparison is genuinely constant-time as compiled for the production target. The PIN/MAC/verifier paths compare one-way derived verifiers, not raw secrets. The defects were concentrated in two places the canonical helper did not reach: an unblinded RSA private-exponent exponentiation on an OpenPGP fallback path, and two raw short-circuiting comparisons of the OTP slot access code with no rate limit.

Methodology

Six analysis lenses were applied across the workspace. Each candidate was then put through adversarial verification (default-to-false; a finding survives only if a concrete secret → observable path is demonstrated at exact file:line with the exploitation model stated), and a completeness critic pass caught sites a single lens would miss. Several constant-time refutations were corroborated by disassembling the actual on-device LTO firmware ELF and by standalone thumbv8m compiles at the production opt-level=s and at opt-level=3.

1. Hand-rolled constant-time comparator definitions.
2. Secret-vs-attacker comparisons that bypass the comparator.
3. Secret-dependent control flow / variable work between match and mismatch.
4. Secret-indexed memory access / data-dependent arithmetic.
5. Crypto-primitive usage (are the CT-by-design RustCrypto primitives wrapped non-CT? is the hand-written modexp safe?).
6. Status-word / error-path / response-latency oracles.

Findings (fixed)

Constant-time confirmed

The assurance result. Sites checked and found correct:

• The canonical comparator rsk_crypto::ct_eq is constant-time. Public length-equality early-return, then a full-width OR-accumulate with no in-loop branch on the accumulator. Verified in the on-device LTO ELF: the inlined copies lower to a loop whose only branch is governed by the public length counter. The secret accumulator is reduced branchlessly. Reproduced from source at opt-level=s and opt-level=3.
• PIN/PUK/password verifier compares are CT and structurally non-amplifiable. Every verifier site compares 32-byte HKDF/HMAC-derived verifiers, not raw secret bytes. Even a hypothetical position oracle would reveal avalanche-hash bytes, not PIN digits, and the “10ᵏ → k·10” counter-defeat does not apply.
• The pinUvAuthToken MAC verify, OATH access-code/HOTP verifies, and PIV mutual-auth all route through the constant-time comparator (PIV against a single-use per-session challenge, not the persistent management key).
• The RSA sign/decipher mainline is blinded (verified through rsa 0.9.10’s blind/unblind around the secret-exponent CRT modexp), and with the fix above, so is the raw fallback.
• RustCrypto primitives are CT-by-library and not wrapped non-CT: k256, ed25519-dalek, x25519-dalek, ML-KEM/ML-DSA, and the HMAC/HKDF/SHA-2 KDF.
• Keygen primality primitives are not an attacker oracle: they operate on RNG-generated, single-use, never-disclosed candidates. Production keygen uses the branchless incremental sieve.

Defense-in-depth applied

The five hand-rolled comparators (one canonical plus four byte-identical duplicates across the applet crates) were consolidated onto the single rsk_crypto::ct_eq, and a core::hint::black_box barrier was added before its final reduction. The comparator was already constant-time on the audited toolchain. The barrier pins that property so a future LLVM/rustc cannot fold the accumulate into an early-exit branch. It does not change the code generated today.

Documented residuals

• RUSTSEC-2023-0071 “Marvin” timing channel in the rsa crate, accepted as mitigated by per-operation base blinding on all private-key paths (the finding above closed the one path the blinding did not previously cover). See threat-model.md.
• rsk-rsa-asm keygen modexp secret-indexed window lookup: a genuine secret-dependent memory-access pattern over bits of the generated prime, but it is keygen-only, one-shot, and not USB-timing-observable. On the cacheless Cortex-M33 there is no microarchitectural channel. Exploitable only via physical EM/power capture of a single keygen event, already out of scope (threat-model.md). Optional hardening: build the asm with a constant memory-access pattern.

Coverage & limits

Covered: all hand-rolled comparator definitions and call sites; every PIN/PUK/password/MAC/verifier comparison across FIDO, PIV, OpenPGP, OATH; OTP slot access-code compares; HOTP/TOTP; RSA private sign/decrypt/raw paths; the rsk-rsa-asm C/asm modexp, sieve, and primality primitives; secret-indexed lookups; and status-word/error-path oracles.

What a source/disassembly audit cannot prove:

• No measured timing distributions. This shows the code has no secret-dependent branch/early-exit/index. It cannot rule out a microarchitectural channel (e.g. XIP-flash stall variance, data-dependent multiplier latency). A definitive statement needs an instrumented timing harness on hardware with a statistical leakage test (TVLA / Welch t-test).
• Compiler stability is empirical, not contractual. The comparator is constant-time under the audited toolchain. The black_box barrier pins it, but the guarantee remains “verified on this build.”
• Physical side channels (power/EM/fault) are explicitly out of scope and unverified here, including the keygen access pattern and any DPA on the secure-boot AES, both already noted in the threat model.
• Third-party crate internals (RustCrypto, rsa/num-bigint-dig) were audited only at the usage boundary. Their own CT properties are inherited from upstream and the documented RUSTSEC residual.

Architecture

How the firmware is put together, for contributors and the curious. For what the design does and does not defend against, see the threat model.

The big picture

A composite USB device with three interfaces, seven smart-card applets and one storage layer. Day to day everything runs on one RP2350 core. The second wakes only to parallelize RSA keygen (below):

flowchart TD
    subgraph irq["Interrupt executor"]
      fido["FIDO HID<br/>(0xF1D0, CTAPHID)"]
      ccid["CCID<br/>(class 0x0B, APDU)"]
      kbd["Boot keyboard<br/>(OTP typing)"]
    end
    fido --> worker
    ccid --> worker
    kbd --> worker
    subgraph thread["Thread executor"]
      worker["worker task<br/>owns flash + TRNG"]
      worker --> applets["Applets<br/>FIDO2/U2F · OpenPGP · PIV · OATH<br/>OTP · mgmt · vendor + rescue"]
    end
    applets --> fs["flash KV store<br/>(rsk-fs over sequential-storage)"]

Two executors. USB and the transports live on a high-priority InterruptExecutor. The applet dispatch lives on the low-priority thread executor, in a single worker task that owns the flash and the TRNG outright. Long synchronous work (on-card RSA generation, flash compaction, a touch wait) blocks only the worker, while the interrupt executor keeps the bus enumerated, streams CCID/CTAPHID keepalives, and animates the LED. No mutexes: ownership does the synchronization.

Why (mostly) one core. The async executor provides the concurrency that the upstream design used a second core and hand-rolled queues for. Core 1 is kept out of the transport path and has exactly one job: during on-card RSA generation both cores race the prime search. Independent random candidates, each core with its own DRBG stream, feed one shared two-prime pool (firmware/src/core1.rs). Measured, RSA-2048 generation drops from ~8.9 s to ~4.3 s mean (2.07×).

Three details make that work:

• The Fermat-filter modexp (C + asm) executes from SRAM. Two cores running it from XIP throttle each other on the shared flash cache (~40% per core, measured).
• The key returns the moment the pool completes; core1’s last candidate finishes in the background.
• A core1 that ever stops answering latches the engine into single-core mode rather than stalling the worker (INS 0x12 on the vendor applet reads the engine’s counters and flags).

Outside keygen, core1 parks in WFE, and embassy-rp pauses it around every flash erase/program, so its XIP fetches never collide with flash writes.

Boot sequence

Getting to that runtime state has a strict order. The bootrom verifies the signed image, then the firmware provisions and recovers all persistent state (OTP keys, the KV store, the phy record, the TRNG, the seal migrations and the one-shot at-rest scrub) before it asserts the USB pull-up. That ordering is load-bearing: builder.build() starts host enumeration, and the task that answers control transfers must be spawned with no blocking work in between, or the host enumerates a mute device and times out. That is the “blink red / not recognised until several replugs” report that motivated attaching to the bus only after everything else is ready.