Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

RS-Key

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

What this isFirmware. A .uf2 file you drop onto a board. Nothing here is for sale.
What you needAny RP2350 board (from about $5) and a USB cable. No soldering, no programmer, no toolchain.
What you getA USB authenticator your browser, ssh, gpg and ykman already know how to talk to.

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

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

Start here

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 report.
  • 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 0xF1D2, from pid.codes), presenting as “RS-Key Security Key”. An opt-in VIDPID=Yubikey5 build instead borrows a YubiKey’s identity (VID 0x1050 / PID 0x0407) so that ykman and Yubico Authenticator (which key off the “Yubico YubiKey” reader name) work without custom rules. That flavor is for interop only and is never distributed. See limitations. RS-Key is not affiliated with or endorsed by Yubico, Nitrokey, or Raspberry Pi.

License

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

Quick start

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

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

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

What you need

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

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

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

0. Easy way: use the web flasher

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

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

1. Get the firmware

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

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

Or build it yourself

You need Nix with flakes enabled; the dev shell provides the toolchain, picotool and the host tools. Without Nix: rustup + rustup target add thumbv8m.main-none-eabihf + picotool ≥ 2.0, and the Python deps from flake.nix.

nix develop                                  # first run downloads the toolchain
bash scripts/build.sh
cp target/trustzone/combined.uf2 firmware.uf2

The builder embeds the partition table that keeps the USB bootloader out of the key’s storage. nix build .#firmware includes the same step (build.md).

Set PRESENCE_PIN=<gpio> for a dedicated presence button instead of BOOTSEL. 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

To flash the firmware manually:

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

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

    • Drag-and-drop: cp firmware.uf2 /Volumes/RP2350/ (macOS) or copy it to the mounted drive on Linux.

    • picotool (more reliable: it verifies and skips the mass-storage layer): picotool load -v firmware.uf2 && picotool reboot.

    • rsk flash (checks a release image first): put SHA256SUMS and SHA256SUMS.sigstore.json from the same release next to the image, and run

      rsk flash rs-key-<version>-default.uf2
      

      It checks the signature (it needs cosign), the checksum and, with the GitHub CLI installed, the build provenance. Only then does it run the picotool command above. What each check proves is in supply-chain.md.

    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:0xF1D2 from pid.codes; the PC/SC reader name contains “RS-Key”. For a build that presents the YubiKey USB identity so ykman/Yubico Authenticator auto-recognize it, build the opt-in VIDPID=Yubikey5 flavor; see build.md.)

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

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

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

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

This screenshot predates the allocated 1209:F1D2 identity and shows the former 1209:0001 test PID. No PIN is set yet (that is step 3), and the boot mode is still Development. production.md is what turns the last one into a locked-down key — irreversibly, so read it first.

rsk fido set-pin

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

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

4. Enroll something

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

An SSH key:

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

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

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

5. Back up your identity (optional but wise)

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

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

Where next

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

Hardware

RS-Key targets the Arm cores of the RP2350 family. That includes RP2354, which puts 2 MiB of flash in the same package. The flash size, presence input and status indicator depend on the board design. RP2350 datasheet

Tested boards

These are examples of boards that have run RS-Key. To use another board, match the build to its wiring and flash size.

Waveshare RP2350-One — a blue USB-A stick board Waveshare RP2350-Zero — a small blue USB-C stick board TenStar RP2350-USB — a black USB-A stick board Waveshare RP2350-Touch-LCD-2.8 — a board with a 2.8-inch touch screen
RP2350-One
reference · USB-A
WS2812 on GPIO16
RP2350-Zero
4 MiB flash · 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).

The Waveshare RP2350-One is the reference board. The default image matches its 4 MiB flash, WS2812 on GPIO16 and BOOTSEL button for presence.

Bitmerse tested FIDO2 on Romu (RP2354A) with its RS-Key fork. Their build uses the 2 MiB layout, reads the active-high capacitive touch sensor on GPIO20, and adds an rgb_gpio driver for Romu’s common-anode RGB LED. Romu on Crowd Supply · Bitmerse’s RS-Key build guide

Trusted display

The display build currently supports one board, the Waveshare RP2350-Touch-LCD-2.8. Both revisions use a 240×320 ST7789 panel. V1 uses a CST328 touch controller, and V2 uses a CST3530. The similarly named RP2350-Touch-LCD-2.8C uses a round ST7701 panel and needs its own port. Waveshare 2.8 specifications · Waveshare 2.8C specifications

nix build .#firmware-display     # V1
nix build .#firmware-display-v2  # V2

The preset selects 16 MiB of flash and LED_KIND=none. The screen handles presence and status. See the Trusted display guide.

Defaults and the knobs to change them

Current builds assume a 12 MHz crystal and use the RP2350’s native USB port. USB BOOTSEL lets you load the firmware without a programmer. Board settings cover GPIO 0–29. Using GPIO 30–47 on an RP2350B or RP2354B requires firmware changes.

Start with a preset under firmware/boards/ if one matches your board. Pass its filename without .toml as BOARD. For example, seeed-xiao sets up the 2 MiB flash, powers the WS2812 through GPIO23 and holds the separate user LED off. For a custom board, set the flash size and match the presence input and LED to the wiring. See Build options for the full list.

KnobDefaultWhen to change it
FLASH_SIZE4MMatch the flash capacity, up to 16 MiB. The linker derives the firmware and storage layout from it.
KVMAIN1408KUse 896K with FLASH_SIZE=2M on boards such as the Seeed XIAO RP2350, Waveshare RP2350-Zero-CM or Romu. Leave at least 1 MiB for firmware. Keep both settings when updating a provisioned key.
LED_KINDws2812ws2812 for addressable RGB, gpio for a plain on/off LED, pimoroni for the fixed Pimoroni PWM wiring, or none to omit the status LED.
LED_PIN16Data GPIO for ws2812 or output GPIO for gpio.
LED_ORDERrgbSet grb if the addressable LED’s red and green are swapped.
LED_POWER_PINnoneGPIO to hold high for an LED power gate, such as GPIO23 on the Seeed XIAO RP2350.
USR_LED_PINnoneGPIO of a separate onboard LED to hold off, such as GPIO25 on the Seeed XIAO RP2350. Set USR_LED_ACTIVE_HIGH=1 for an active-high LED.
MAX_LEDS1Compiled capacity of the addressable LED chain, up to 64. Set the active count at runtime.
PRESENCE_PINbootselUse BOOTSEL or set the GPIO of a dedicated button or touch sensor. A GPIO input defaults to active-low with a pull-up.
PRESENCE_ACTIVE_HIGH0Set 1 for a GPIO button or touch sensor that goes high when pressed.
# Seeed XIAO RP2350 and TenStar RP2350-USB presets
nix develop -c env BOARD=seeed-xiao bash scripts/build.sh
nix develop -c env BOARD=tenstar-usb bash scripts/build.sh

# Custom board with 8 MiB flash, a plain LED and an active-high touch sensor
nix develop -c env FLASH_SIZE=8M LED_KIND=gpio LED_PIN=25 \
  PRESENCE_PIN=0 PRESENCE_ACTIVE_HIGH=1 bash scripts/build.sh

With LED support compiled in, rsk hw can change the pin, driver, wire order and active LED count. The settings take effect on reboot. The compiled MAX_LEDS caps the active count. See the LED guide.

Adding a board

If the peripherals already have drivers, add a board preset with the flash size and pin assignments. A peripheral that uses a different protocol or wiring may need a driver change. Romu’s RGB LED is one example. The status LED is optional, so you can use LED_KIND=none while bringing up the rest of the board.

We welcome pull requests for board presets and drivers. Include a pinout or schematic reference and what you tested on the board, such as USB boot, FIDO2 registration and login, presence, and the LED or display.

Enclosures

Community designs for 3D-printed enclosures are available for several boards.

See each model page for its license.

What the hardware does not give you

RS-Key uses the microcontroller’s own OTP and Secure Boot for production hardening. The threat model excludes lab attacks such as decapping, microprobing, advanced fault injection and power or EM side channels. See Production setup, the threat model and limitations.

Build options

Every authenticator build combines Secure and Non-secure firmware for the RP2350. The default output is an unsigned ELF and UF2 with the storage partition table. For a Secure Boot device, follow the production signing procedure.

Local build

From the repository root:

nix develop -c bash scripts/build.sh

The builder links Secure first to export its CMSE gateways. It links Non-secure against that import library, then embeds the Non-secure payload in the final Secure link. It checks that the gateways stayed at the same addresses, embeds the partition table and converts the resulting ELF to UF2. Bare Cargo builds require the builder’s link-stage inputs.

flowchart TD
    options["Board settings and firmware features"] --> builder["TrustZone builder<br/>Link Secure and Non-secure<br/>Embed partition table by default<br/>Convert ELF to UF2"]
    builder --> elf["Combined UF2"]
    builder --> uf2["Combined UF2"]
    elf --> sign["Secure Boot signing"]
    sign --> signed["Signed UF2"]

Environment and Cargo arguments

Use --features a,b, --features=a,b, -F a,b, -Fa,b or FEATURES=a,b. These forms compose, including repeated flags and whitespace-separated feature lists. Both Secure links use the same features. The builder resolves Cargo’s dependency graph and forwards the effective strict-config policy to Non-secure. --no-default-features applies to both worlds.

ArgumentEffect
--config KEY=VALUE or --config PATHMerge Cargo configuration. Options can repeat, and file paths are relative to the calling directory.
--jobs N, -j N, --offline, --frozen, --lockedCargo concurrency and dependency resolution. The builder always passes --locked.
--verbose, -v, -vv, --quiet, -q, --color, --message-format, --timings, --keep-going, --future-incompat-reportCargo output and build controls
--release, -rAccepted for compatibility. The builder always uses the release profile.
--target-dir DIRSet the output directory as described below
--no-partition-tableBuild both artifacts without the BOOTSEL storage fence
--help, -hPrint usage

Long options with a value also accept --option=value. The short -jN form works for the job count.

The target is thumbv8m.main-none-eabihf. The builder rejects package, manifest, target and profile selectors, --all-features and unknown options.

Exported values reach Cargo without shell expansion. The builder sets a separate Cargo target directory for each world and owns its link-stage variables. RSK_TZ_CARGO_CONFIG can supply one extra --config value. The remaining RSK_TZ_* controls outside the output settings below are used by the builder or the image test harness.

Cargo’s CARGO_ENCODED_RUSTFLAGS and RUSTFLAGS override the flags from .cargo/config.toml, including required linker flags. To add target flags, merge the target configuration instead.

nix develop -c env BOARD=waveshare-one USB_PRODUCT="RS-Key local build" \
  FEATURES=strong-pin bash scripts/build.sh -F strict-config --offline --jobs 4

nix develop -c bash scripts/build.sh \
  --config 'target.thumbv8m.main-none-eabihf.rustflags=["--cfg=local_build"]'

Output directories

The builder writes combined.elf and combined.uf2 to the first applicable directory in this list.

  1. DIR/trustzone if you pass --target-dir DIR.
  2. RSK_TZ_OUT if set.
  3. CARGO_TARGET_DIR/trustzone if set.
  4. target/trustzone in the repository.

Paths supplied by the caller are resolved from the calling directory. Cargo artifacts go under secure/ and nonsecure/ within the output. Use a separate output directory for each concurrent build or experiment.

Cargo features

Physical presence is enabled by default. The features below are opt-in. Several features are available as Nix presets.

FeatureEffect
advertise-pqcAdvertises ML-DSA-87, -65 and -44 in FIDO getInfo. makeCredential can negotiate the algorithms with the flag off.
strong-pinRaises the FIDO PIN minimum from four to six code points and rejects common patterns. Also applies to the FIDO PIN policy on the display.
fips-profileApplies the strong PIN policy, removes FIDO secp256k1, refuses seed export, and restricts PIV management keys and algorithms. See FIPS-style profile for scope.
always-uvCompiles with CTAP alwaysUv enabled by default. A runtime override survives reboot, and authenticator reset restores the compiled default. With no configured PIN, CTAP2 requests that need verification return PUAT_REQUIRED. U2F is unavailable while alwaysUv is active unless configured built-in UV can protect it.
strict-upRequests presence even for a silent up:false getAssertion probe. The reply still leaves the UP flag clear for that probe. An allowList login can require a press for the probe and another for the assertion.
strict-configRequires authorization for configuration writes on the gated paths and disables ungated CTAPHID and OTP HID config writes. With the flag off, those writes are available for YubiKey interoperability.
largeblob-extSelects the CTAP 2.3 per-credential largeBlob extension. It replaces largeBlobKey and authenticatorLargeBlobs and stores up to 4046 bytes per discoverable credential. Client support depends on the extension the client speaks.
displayEnables the trusted display, on-device PIN entry and local screens. Use a compatible display board and LED_KIND=none. See Trusted display.
preview-signEnables the experimental previewSign extension.
no-touchAuto-confirms button-based presence for automated tests. Use a presence-enabled build for deployment.
fido-conformanceEnables the conformance profile, including strict-up, and suppresses EdDSA advertisement.
ea-conformance-rpidAdds the conformance RP ID to the vendor-facilitated enterprise attestation list and enables fido-conformance.
bench, keygen-bench, core1-statsTest-only vendor commands for primitive timing, keygen timing, stack diagnostics or core1 counters.

Environment variables

BOARD loads defaults from a named TOML file under firmware/boards/. An explicitly exported knob wins over a board value. A board selects hardware settings. Enable the display feature separately. With no board selected, the build uses the defaults below.

VariableDefaultAccepted values and effect
BOARDunsetabrobot-4m, abrobot-16m, waveshare-one, waveshare-touch-lcd, tenstar-usb, seeed-xiao. Use the file stem, without .toml.
VIDPIDRSKeyUSB identity preset. RSKey is 0x1209:0xF1D2. Other presets are Pico, Dev, Yubikey5, YubikeyNeo, YubiHSM, NitroHSM, NitroFIDO2, NitroStart, NitroPro, Nitro3, Gnuk and GnuPG. Use vendor presets for local interop.
USB_VID, USB_PIDfrom preset16-bit IDs in decimal or 0xHHHH form. Either half can override the preset independently.
USB_MANUFACTURER, USB_PRODUCTRS-Key, RS-Key Security Key for the default identityDescriptor strings. An effective Yubico VID uses the built-in Yubico reader strings unless EF_PHY supplies a string override.
FW_VERSION5.8.0X, X.Y or X.Y.Z, with components from 0 to 255. Sets the reported applet firmware version.
XOSC_DELAY_MULT1281..=1024. Crystal oscillator startup delay multiplier.
FLASH_SIZE4MPhysical flash size, in bytes, hex, or with a K or M suffix. Must be 4 KiB aligned and at most 16 MiB.
KVMAIN1408KMain-store capacity. Same size syntax as FLASH_SIZE, 4 KiB aligned, at least 128 KiB. Preserve the layout when updating a provisioned device.
LED_KINDws2812ws2812, gpio, pimoroni or none. Sets the boot default. none omits the status LED support and is required by the display build.
LED_PIN16GPIO 0–29 for the WS2812 data line or GPIO status LED. Pimoroni PWM uses its fixed pins.
LED_ORDERrgbrgb or grb wire order for addressable LEDs
LED_POWER_PINnonenone or GPIO 0–29, held high to power a gated LED rail. Use a pin distinct from the status LED and presence input.
MAX_LEDS11..=64. Compiled addressable LED capacity. The runtime LED count must fit it.
USR_LED_PINnonenone or GPIO 0–29. Holds a separate onboard LED off. Must avoid the status LED, LED power and presence pins. Display builds require it unset.
USR_LED_ACTIVE_HIGH01 for an active-high user LED. 0 holds an active-low LED off.
PRESENCE_PINbootselbootsel or GPIO 0–29. Display builds use touchscreen presence and reject a GPIO presence pin.
PRESENCE_ACTIVE_HIGH01 for an active-high GPIO presence button. 0 selects an active-low button with a pull-up.
WAKE_PIN25Display wake button. Use none for touch-only wake or a free GPIO 0–29.
WAKE_ACTIVE_HIGH01 for an active-high wake button. 0 selects active-low.
FAKE_MKEK, FAKE_DEVKunsetTest-only OTP substitutes, each 64 hex digits. They are embedded in the binary. Use disposable test storage.

Boolean GPIO settings also accept true/false, yes/no and on/off. For display boards, the PK_DISPLAY_* overrides below take precedence over the corresponding [display] TOML settings. DISPLAY_TP_CHIP overrides [display].tp_chip.

VariableFallbackSetting
PK_DISPLAY_SPI_FREQ_HZ80000000Panel PIO serial clock. The firmware requires half its fixed 160 MHz system clock.
PK_DISPLAY_CS, PK_DISPLAY_DC, PK_DISPLAY_RST13, 14, 15Panel control GPIOs
PK_DISPLAY_BL_PIN, PK_DISPLAY_BL_PWM_SLICE, PK_DISPLAY_BL_PWM_CHANNEL16, 0, 0Backlight GPIO, PWM slice and channel. Use a supported tuple from the board wiring.
DISPLAY_TP_CHIPcst328Use cst328 for Waveshare V1 or cst3530 for V2.
PK_DISPLAY_TP_RST, PK_DISPLAY_I2C_FREQ_HZ17, 400000Touch controller reset GPIO and I²C clock
PK_DISPLAY_INVERT_COLORS, PK_DISPLAY_COLOR_ORDER1, 0Panel color inversion and RGB/BGR selection. 1 selects inversion or BGR, respectively.

Flash size and the memory map

The linker places the firmware region below KVMAIN and the fixed 128 KiB KVCNT. The builder requires at least 1 MiB for firmware. The last 64 KiB of that region holds Non-secure, with the 4 KiB CMSE gateway window immediately below it. See the Architecture flash map for the addresses on the 4 MiB board.

GeometryFirmware regionKVMAINKVCNT
FLASH_SIZE=2M KVMAIN=896K1024 KiB896 KiB128 KiB
FLASH_SIZE=4M KVMAIN=1408K2560 KiB1408 KiB128 KiB
FLASH_SIZE=16M KVMAIN=1408K14844 KiB1408 KiB128 KiB

At 16 MiB, the linker leaves the final 4 KiB sector unpartitioned for the RP2350-E10 workaround at 0x10FFFF00. Smaller devices end below that sector. The 2 MiB profile constructs its storage backend at runtime to save space in the ELF.

check.sh checks the combined image’s flash budget of 1024 KiB, which counts the embedded NS payload once. Its Secure stack floors are 120 KiB for the ordinary image and 116 KiB for display. Both require 20 KiB of Non-secure stack. The embedded linker uses flip-link, with rust-lld available in the development shell.

The partition table

The TrustZone builder embeds the table in the final ELF before UF2 conversion. It reads __kvmain_start and __kvcnt_end from the linked image. The firmware partition permits BOOTSEL updates. The store partition allows Secure reads and writes and denies Non-secure and BOOTSEL access. The gate compares the resulting table with the same linker symbols.

Secure Boot authenticates the table as part of the signed image. See Flash snapshot rollback for the fence’s scope.

For a diagnostic build that omits the table from both artifacts:

nix develop -c bash scripts/build.sh --no-partition-table --target-dir /tmp/rsk-unpartitioned

The flag preserves the Secure/Non-secure memory layout and omits the BOOTSEL storage fence. The named Nix packages and release workflow use the default partitioned build.

Examples

# Default 4 MiB image with physical presence
nix develop -c bash scripts/build.sh

# 2 MiB Seeed XIAO RP2350
nix develop -c env BOARD=seeed-xiao bash scripts/build.sh

# Waveshare touch display
nix develop -c env BOARD=waveshare-touch-lcd bash scripts/build.sh --features display

# YubiKey-compatible identity for local interop
nix develop -c env VIDPID=Yubikey5 bash scripts/build.sh

# Automated tests
nix develop -c bash scripts/build.sh --features no-touch

# Require authorization for gated configuration writes
nix develop -c bash scripts/build.sh --features strict-config

Inspect an ELF or UF2 without flashing with picotool info -a. The default build writes target/trustzone/combined.elf and target/trustzone/combined.uf2.

nix build (hermetic, no dev shell)

nix build .#firmware
# result/firmware.elf and result/firmware.uf2

Nix pins the toolchain and dependencies and uses the TrustZone builder. The derivation remaps build and toolchain paths so they do not enter the artifact under their local names. The release workflow rebuilds each published flavor and compares its UF2 bytes. See Supply chain for reproducibility and verification.

Package suffix after firmwareSettings
noneDefault configuration
-2mb, -16mb2 MiB with KVMAIN=896K, or 16 MiB with the default KV size
-display, -display-v2Trusted display on Waveshare V1 (CST328) or V2 (CST3530). Both use 16 MiB flash and LED_KIND=none.
-picoVIDPID=Pico
-pqcadvertise-pqc
-fips, -strong-pin, -always-uv, -strict-upCorresponding feature, also available with an added -pqc suffix
-strict-configstrict-config
-no-touch, -no-touch-pqc, -no-touch-fips, -no-touch-fips-pqcTest images with the named feature combinations

The packages emit unsigned ELF and UF2 files. To sign a Secure Boot update, seal the partitioned ELF and convert the signed ELF to UF2. See Production setup and Anti-rollback for the required image metadata.

nix run — host tools without the dev shell

nix run .#rsk -- --help
nix run .#rsk-tui
nix run .#flash -- --help

nix run .#flash signs the default Nix ELF or a supplied partitioned combined ELF and flashes it. It expects a board provisioned for the matching signing key. RS_KEY_SECRETS selects the directory containing secure_boot_key.pem and otp_secureboot.json (default ~/.rs-key-secrets). RSK_ROLLBACK selects the rollback version (default 1). It prompts before flashing. -y skips the prompt.

Runtime overrides (phy record)

EF_PHY stores board settings in flash. At boot its valid VID/PID and USB strings override the build defaults, and its interface mask selects which USB classes to expose. It can also set the presence timeout and supported LED settings. Use the CLI for runtime settings.

flowchart TD
    preset["VIDPID preset"] --> env["Explicit build VID/PID and strings"]
    env --> phy["EF_PHY overrides at boot"]
    phy --> usb["Effective USB identity and interfaces"]

An ordinary firmware update preserves EF_PHY with the rest of the store. To change a stored override, update the record through a reachable interface. If storage cannot mount, the boot path selects CCID for recovery.

Notes

  • USB bcdDevice, the applet firmware version (FW_VERSION) and the Secure Boot rollback version are separate values. See Versions.
  • The effective Yubico VID uses Yubico-style reader strings and ATR by default. The Yubikey5 preset is intended for clients such as ykman that use the Yubico reader name.
  • The TUI has its own development shell, nix develop .#tui.

TrustZone boundary

Architecture describes the resource split, USB lifecycle and gateway checks. Both development and production builds use that boundary.

Reproducible configuration and environment overrides

For a custom Nix image, call mkFirmware. It accepts features as a string, cargoFlags as a list of builder arguments, and env for the firmware knobs listed above. Unknown env keys are rejected. Named arguments also exist for board, vidpid, usbVid, usbPid, fwVersion, xoscDelayMult, flashSize, kvmain, ledPin, ledKind, presencePin, fakeMkek, fakeDevk and tpChip.

nix build --impure --expr \
  '(builtins.getFlake (toString ./.)).lib.${builtins.currentSystem}.mkFirmware {
     name = "fw";
     board = "waveshare-one";
     features = "strong-pin,strict-config";
     env = { USB_PRODUCT = "RS-Key local build"; };
   }'

Named arguments override env, which overrides ambient values read during impure evaluation. FEATURES is the ambient fallback for features. A pure build ignores ambient knobs. For a local impure build you can use BOARD=waveshare-one FEATURES=strong-pin nix build --impure .#firmware. Signing keys and the builder’s internal TrustZone controls stay outside the derivation.

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. It runs only at the tag it releases: a run started by hand from a branch, or from another tag, stops before it builds anything. A run started by hand uses the workflow file at the ref it starts from, though, and the tags published up to v0.4.11 carry one without that test. A run started at one of them can still build another tag, signed under the old tag’s name; the tag pin in step 1 below refuses it, and so does gh attestation verify --source-ref (supply-chain.md, step 3).

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

    flavorflagsuse
    defaulttouchthe normal build; start here
    pqc+ advertise-pqcadvertises all three ML-DSA sets in getInfo (breaks old Firefox)
    fips+ fips-profilethe locked FIPS-style policy (guides/fips.md)
    fips-pqc+ both
    strong-pin+ strong-pin6-code-point PIN floor + trivial-PIN block (build.md, threat-model.md)
    strong-pin-pqc+ both
    always-uv+ always-uvbakes 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-upnot 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+ displayexperimental trusted-display build (Waveshare RP2350-Touch-LCD-2.8, guides/display.md)
    2mbFLASH_SIZE=2M KVMAIN=896K2 MB boards (Seeed XIAO RP2350, Waveshare RP2350-Zero-CM)
    16mbFLASH_SIZE=16M16 MB boards (e.g. TenStar RP2350-USB)
    strict-config+ strict-configthe 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:0xF1D2 from build 0x0A8A; older images use the test PID 0x1209:0x0001. For the YubiKey-interop identity, build VIDPID=Yubikey5 yourself (build.md).

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

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

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

  • rs-key-<tag>-sbom.cdx.json and rs-key-<tag>-sbom-nonsecure.cdx.json: CycloneDX bills of materials for the Secure and Non-secure dependency trees.

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

Verify a download

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

# 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. The ref
#    flag pins the release's own tag; any repository can call the workflow, so
#    the last flag pins the repository of the run.
cosign verify-blob \
  --bundle SHA256SUMS.sigstore.json \
  --certificate-identity-regexp '^https://github\.com/TheMaxMur/RS-Key/\.github/workflows/release-build\.yml@refs/tags/v.*$' \
  --certificate-github-workflow-ref refs/tags/<tag> \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  --certificate-github-workflow-repository TheMaxMur/RS-Key \
  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.

rsk flash runs these checks and flashes only when they pass. Keep SHA256SUMS and SHA256SUMS.sigstore.json in the folder with the image, put the board in BOOTSEL, and:

rsk flash rs-key-<tag>-default.uf2    # --dry-run checks and writes nothing

It also runs gh attestation verify, pinned to the release’s own tag, when the GitHub CLI is installed, and says so when it is not (supply-chain.md, step 3).

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

LayerArtifactWhat it proves
Reproducible buildthe 14 .uf2 flavorsthe binary is a pure function of the source at the tag. Anyone can rebuild it — which says the BUILD is deterministic, not that the machine code preserves what the source proves
Repro gate(CI, blocking)the release job fails if any flavor doesn’t rebuild bit-identical, so a non-reproducible image is never published
Checksums + signatureSHA256SUMS + SHA256SUMS.sigstore.jsonthe hashes were signed by this repo’s release workflow (keyless cosign). Up to v0.4.10 the same file is named SHA256SUMS.cosign.bundle
Build provenancea GitHub attestation, plus rs-key-<tag>.intoto.jsonl on the releasewhich reusable workflow, at which commit, on which runner built each .uf2. SLSA v1 Build L3, keyless via attest-build-provenance. The API copy is authoritative; the file is for offline checking
SBOMrs-key-<tag>-sbom.cdx.jsonthe CycloneDX bill of materials for the firmware crate
Dependency auditsupply-chain/ (in-repo)every dependency is covered by an imported audit or a recorded exemption (cargo-vet)

The toolchain that builds it

A reproducible build says the binary is a pure function of the source and the toolchain. This is the toolchain half: every tool a shipped byte passes through, and every tool whose word a published verification result rests on, with the file that pins each one. The table is generated from assurance/toolchain.toml and re-read out of flake.lock, Cargo.lock, .github/workflows/ and assurance/platform.toml on every check-assurance.sh run.

Generated by scripts/toolchain_gate.py from assurance/toolchain.toml and the files that pin it. Each pin below was re-read out of its provenance on the run that wrote this table; a row whose file no longer says the same thing fails check-assurance.sh.

ToolRolePinned byPin
arm-none-eabi-asassemblerflake.lock:nixpkgs31ecbaca1bdefa45dffc409f0250bd8039ea0010
arm-none-eabi-gcccompilerflake.lock:nixpkgs31ecbaca1bdefa45dffc409f0250bd8039ea0010
arm-none-eabi-nmpackagerflake.lock:nixpkgs31ecbaca1bdefa45dffc409f0250bd8039ea0010
cargopackagerflake.lock:fenixcf57f8966c3c129e31caaf29790caf8a6a93e0a6
cargo-kaniproverworkflow:.github/workflows/ci.yml:KANI_VERSION0.67.0
cbmccheckernothingopen obligation PLAT-TOOL-003
cortex-massemblerCargo.lock:cortex-m8ec610d8f49840a5b376c69663b6369e71f4b34484b9b2eb29fb918d92516cb9
flip-linklinkerflake.lock:nixpkgs31ecbaca1bdefa45dffc409f0250bd8039ea0010
jre8runtimeflake.lock:nixpkgs31ecbaca1bdefa45dffc409f0250bd8039ea0010
picotoolpackagerflake.lock:nixpkgs31ecbaca1bdefa45dffc409f0250bd8039ea0010
rust-lldlinkerflake.lock:fenixcf57f8966c3c129e31caaf29790caf8a6a93e0a6
rustccompilerflake.lock:fenixcf57f8966c3c129e31caaf29790caf8a6a93e0a6
tlapluscheckerflake.lock:nixpkgs31ecbaca1bdefa45dffc409f0250bd8039ea0010

Root inputs of flake.lock deliberately outside this TCB:

  • flake-utils — eachDefaultSystem plumbing (flake.nix:36). It emits no binary into any build; it decides which systems the outputs are instantiated for.
  • nixpkgs-sdl2 — SDL2 alone, for the tools/emu –display window (flake.nix:9-15). Nothing from this pin enters a firmware build, a Kani run or a TLC run; it exists because unstable’s sdl2-compat emits SDL3 window events the Rust crate aborts on.

The FFI boundaries. Every place a name in this tree binds to a symbol Rust does not define, read out of the tree on the run that wrote this table: an item an extern block declares (import), an item defined here for a foreign caller (export), and a foreign translation unit a build.rs compiles into the image (unit). The set is held both ways — a crossing no [[boundary]] row claims fails check-assurance.sh, and so does a row for a crossing that is no longer there.

BoundaryKindDerived fromForeign side produced by
rsk_tz_fault_stopexportfirmware/src/trustzone/fault.rs, #[unsafe(no_mangle symbol, unconditionalrustc
rsk_tz_readable_implexportfirmware/src/trustzone/mod.rs, #[unsafe(no_mangle symbol, unconditionalarm-none-eabi-gcc
rsk_tz_writable_implexportfirmware/src/trustzone/mod.rs, #[unsafe(no_mangle symbol, unconditionalarm-none-eabi-gcc
rsk_tz_usb_implexportfirmware/src/trustzone/usb.rs, #[unsafe(no_mangle symbol, unconditionalarm-none-eabi-gcc
rsk_tz_control_implexportfirmware/src/worker.rs, #[unsafe(no_mangle symbol, unconditionalarm-none-eabi-gcc
rsk_tz_poll_implexportfirmware/src/worker.rs, #[unsafe(no_mangle symbol, unconditionalarm-none-eabi-gcc
rsk_tz_submit_implexportfirmware/src/worker.rs, #[unsafe(no_mangle symbol, unconditionalarm-none-eabi-gcc
SWI_IRQ_1exportfirmware/trustzone/nonsecure/src/main.rs, #[unsafe(no_mangle symbol, unconditionalrustc
SWI_IRQ_4exportfirmware/trustzone/nonsecure/src/notify.rs, #[unsafe(no_mangle symbol, unconditionalrustc
RSK_NS_PROBE_PROGRESSexportfirmware/trustzone/nonsecure/src/probe.rs, #[unsafe(no_mangle symbol, unconditionalrustc
RSK_NS_PROBE_TARGETexportfirmware/trustzone/nonsecure/src/probe.rs, #[unsafe(no_mangle symbol, unconditionalrustc
TIMER1_IRQ_0exportfirmware/trustzone/nonsecure/src/time.rs, #[unsafe(no_mangle symbol, unconditionalrustc
__kvcnt_endimportfirmware/src/main.rs, extern "C", unconditionalrust-lld
__kvcnt_startimportfirmware/src/main.rs, extern "C", unconditionalrust-lld
__kvmain_endimportfirmware/src/main.rs, extern "C", unconditionalrust-lld
__kvmain_startimportfirmware/src/main.rs, extern "C", unconditionalrust-lld
_stack_endimportfirmware/src/main.rs, extern "C", unconditionalflip-link
__rsk_ns_image_lenimportfirmware/src/trustzone/mod.rs, extern "C", unconditionalrust-lld
__rsk_scratch_exec_endimportfirmware/src/trustzone/mod.rs, extern "C", unconditionalrust-lld
__rsk_scratch_exec_loadimportfirmware/src/trustzone/mod.rs, extern "C", unconditionalrust-lld
__rsk_scratch_exec_startimportfirmware/src/trustzone/mod.rs, extern "C", unconditionalrust-lld
rsk_tz_enter_nsimportfirmware/src/trustzone/mod.rs, extern "C", unconditionalarm-none-eabi-gcc
__rsk_exec_endimportfirmware/src/trustzone/mpu.rs, extern "C", unconditionalrust-lld
__rsk_exec_startimportfirmware/src/trustzone/mpu.rs, extern "C", unconditionalrust-lld
__rsk_scratch_exec_startimportfirmware/src/trustzone/mpu.rs, extern "C", unconditionalrust-lld
rsk_tz_controlimportfirmware/trustzone/nonsecure/src/main.rs, extern "C", unconditionalarm-none-eabi-gcc
rsk_tz_pollimportfirmware/trustzone/nonsecure/src/main.rs, extern "C", unconditionalarm-none-eabi-gcc
rsk_tz_submitimportfirmware/trustzone/nonsecure/src/main.rs, extern "C", unconditionalarm-none-eabi-gcc
rsk_tz_usbimportfirmware/trustzone/nonsecure/src/usb.rs, extern "C", unconditionalarm-none-eabi-gcc
__rsk_scratch_exec_endimporttests/tz_hardware/secure.rs, extern "C", unconditionalrust-lld
__rsk_scratch_exec_loadimporttests/tz_hardware/secure.rs, extern "C", unconditionalrust-lld
__rsk_scratch_exec_startimporttests/tz_hardware/secure.rs, extern "C", unconditionalrust-lld

Coverage against the six TCB categories. Enumerated here, each with a pin held against its source file:

  • assembler — arm-none-eabi-as, cortex-m
  • compiler — arm-none-eabi-gcc, rustc
  • ffi — the 32 boundary(s) in the table above, each joined to the pinned tool that produces its foreign half
  • linker — flip-link, rust-lld

Not enumerated by this generator at all, and not by any other:

  • bootrom — burned into the RP2350; no file here records a version or a hash for it (assurance/platform.toml’s PLAT-ROM-001 stands in its place)
  • llvm-passes — rustc’s LLVM version is written in no file of this tree and its pass pipeline in none anywhere; rustc -vV would answer for one machine

What the table proves is that each tool it names carries a pin equal to the value in the file that pins it. It does not prove that the tool which actually ran was that version, that a contributor’s PATH holds it, or that a /nix/store path still matches its narHash.

And the boundaries are the boundaries of this tree. A dependency declares its own, in its own source, where no reader of this checkout can see them: 25 of Cargo.lock’s 276 checksummed crates carry extern "C" or #[no_mangle], cortex-m and cortex-m-rt among them. For those, what is recorded here is the pin that fixes the crate, not the symbols it crosses on.

The release procedure, command by command

The table above pins the tools. This one records the procedure: every command a release runs, the inputs each one consumes, and — one column at a time — what that command actually settles. It is generated from release.yml, release-build.yml and firmware.nix on every check-assurance.sh run: every command, flavor, action pin and asset name below is read out of those three files rather than typed here.

Deriving the commands is not the same as holding the pipeline, and the earlier wording claimed it was. A key beside the commands decides whether the steps run at all, on which machine, and with which token — and a derivation that reads commands never sees one. Sixteen such edits were measured past the first version of this row, from if: false on the job to a set +e inside the reproducibility gate. They are refused by the same row now, by rule rather than by derivation: the job’s own keys, its runner and its scopes are pinned, a step that may not run or whose block is not bash is refused, and so is a caller that runs steps of its own or releases a tag outside v*. What is neither derived nor pinned is listed under What this table does not read, at the end.

Generated by scripts/release_gate.py from .github/workflows/release.yml, .github/workflows/release-build.yml, nix/firmware.nix and scripts/build.sh. Every command and every input below was read out of those files on the run that wrote this table; a file that no longer says the same thing fails check-assurance.sh.

This is a recipe, not a record. It says what a release runs, over which inputs. It is bound to no tag, no commit and no artifact — see the open obligations at the end.

Two words that are not each other.

  • bit-for-bit — the same inputs produce the same output bytes. A property of the build, established below.
  • source->binary — the emitted machine code does what the source says. A property of the compiler, established by nothing here. PLAT-TOOLCHAIN-001 in assurance/platform.toml owns it and is pending; it writes the same gap source-to-binary in prose.

A miscompilation reproduces exactly as well as a correct compilation does, so no rebuild can settle the second word. The subject column is held against the shape of each step’s own command, and the second word is not a value that column can take.

What a subject means

The closed vocabulary the Subject column below is drawn from. Printed here because a gloss nothing reads is a gloss anything can be written into: rewriting one to say what source->binary says, under a key this gate was comparing and never opening, was the third way past the rule above.

SubjectWhat claiming it means
admissionwhich commits may become a release at all
bit-for-bitthe same inputs produce the same output bytes
integritythe bytes you have are the bytes that were published
inventorywhat went into the artifact
noneproduces or publishes an artifact; establishes nothing on its own
originwhich workflow, at which commit, on which runner built it

The steps a release runs

#StepSubjectWhat it settles
1actions/checkoutnoneFetches the tagged tree, deep enough that the tag gate below can read origin/main out of it.
2DeterminateSystems/nix-installer-actionnoneInstalls Nix. The build’s determinism rests on the sandbox this provides, not on the runner image.
3nix-community/cache-nix-actionnoneA cache keyed on flake.lock. A cache hit and a cache miss must produce the same bytes; the rebuild step is what says they do.
4actions/cachenoneThe cargo registry cache. Outside the Nix sandbox, so it feeds no shipped byte — nix build vendors from Cargo.lock.
5sigstore/cosign-installernoneInstalls the signer. Its pin is part of the trust base: this is the code that holds the OIDC token.
6resolve tagadmissionShape, charset, the run’s own ref, and an ancestor-of-main test. The ref test makes the published identity the release’s: a run anywhere but at the tag it releases stops here. The rest is defence in depth: an actor who can push a tag also controls this file at that ref, so the primary control is a repository tag ruleset.
7build the 14 reproducible firmware flavorsnoneProduces the images. A build alone establishes nothing — it is the rebuild below that turns it into evidence.
8reproducibility gate — rebuild all 14, require bit-identicalbit-for-bitRecompiles every flavor already in the store and fails on a hash mismatch, so a non-reproducible image is never published. Says the BUILD is a function of its inputs; says nothing about what the machine code means.
9generate the CycloneDX SBOMinventoryThe firmware crate’s dependency tree, scoped to the shipped target.
10checksumsintegrityA digest of every .uf2 and of the SBOM. It does not cover itself, its own signature or the provenance bundle — the last two are written after this step, and the attestation is what stands behind them.
11attest build provenanceoriginGitHub build provenance for the .uf2 files this step is handed, bound to THIS reusable workflow’s identity — the difference between SLSA Build L3 and L2.
12attach the provenance bundle as a release assetnoneAn offline copy of the attestation. The API and Rekor stay authoritative; immutable releases forbid adding it later, so it is attached at create time.
13sign SHA256SUMS (keyless cosign)integrityKeyless cosign over the checksum file. No private key exists: the signer is this workflow’s OIDC identity.
14extract release notes from CHANGELOGnoneExtracts the version’s CHANGELOG section. Cosmetic, and capped because an oversized body fails the job after the tag is already pushed.
15create the GitHub ReleasenonePublishes dist/*. Refuses to publish a no-touch asset, which would ship a build with the physical-consent gate removed.

The commands those steps run, as this gate reads them: \ continuations joined, and a comment cut where a shell would cut one — a # inside a quoted string is part of the command, so an awk '…' program’s own text stays whole and nothing hides behind a quote.

# 1. uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
# 2. uses: DeterminateSystems/nix-installer-action@3138316df39ed29be04236d7ffc686fa525866aa # v23
# 3. uses: nix-community/cache-nix-action@7df957e333c1e5da7721f60227dbba6d06080569 # v7.0.2
# 4. uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
# 5. uses: sigstore/cosign-installer@756fe2d284c7292c4e9b62c8a28f1e5629c59532 # v4.1.3
# 6. resolve tag
case "$TAG" in
v[0-9]*.[0-9]*.[0-9]*) ;;
*) echo "refusing: tag is not vMAJOR.MINOR.PATCH" >&2; exit 1 ;;
esac
case "$TAG" in
*[!0-9A-Za-z.+-]*)
echo "refusing: tag has characters not allowed in a release tag" >&2
exit 1 ;;
esac
if [ "$GITHUB_REF" != "refs/tags/$TAG" ]; then
echo "refusing: this run is at $GITHUB_REF, not refs/tags/$TAG; start it at the tag" >&2
exit 1
fi
git fetch --no-tags --quiet origin +refs/heads/main:refs/remotes/origin/main
if ! git merge-base --is-ancestor "$TAG^{commit}" origin/main; then
echo "refusing: $TAG does not point at a commit on main" >&2
exit 1
fi
echo "tag=$TAG" >> "$GITHUB_OUTPUT"
echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
# 7. build the 14 reproducible firmware flavors
tag="${{ steps.tag.outputs.tag }}"
mkdir -p dist
for pkg in firmware firmware-pqc firmware-fips firmware-fips-pqc firmware-strong-pin firmware-strong-pin-pqc firmware-always-uv firmware-always-uv-pqc firmware-strict-up firmware-strict-up-pqc firmware-display firmware-2mb firmware-16mb firmware-strict-config; do
echo "::group::nix build .#$pkg"
out="$(nix build ".#$pkg" --no-link --print-out-paths)"
label="${pkg#firmware}"; label="${label#-}"
[ -z "$label" ] && label="default"
cp "$out/$pkg.uf2" "dist/rs-key-${tag}-${label}.uf2"
echo "::endgroup::"
done
ls -l dist
# 8. reproducibility gate — rebuild all 14, require bit-identical
for pkg in firmware firmware-pqc firmware-fips firmware-fips-pqc firmware-strong-pin firmware-strong-pin-pqc firmware-always-uv firmware-always-uv-pqc firmware-strict-up firmware-strict-up-pqc firmware-display firmware-2mb firmware-16mb firmware-strict-config; do
echo "::group::nix build .#$pkg --rebuild"
nix build ".#$pkg" --rebuild --no-link
echo "::endgroup::"
done
echo "all 14 flavors rebuilt bit-identical"
# 9. generate the CycloneDX SBOM
tag="${{ steps.tag.outputs.tag }}"
nix develop -c cargo cyclonedx --manifest-path firmware/Cargo.toml --target thumbv8m.main-none-eabihf --format json
sbom="firmware/firmware.cdx.json"
if [ ! -f "$sbom" ]; then
for f in firmware/*.cdx.json; do
[ -e "$f" ] || continue
sbom="$f"
break
done
fi
if [ ! -f "$sbom" ]; then echo "no SBOM produced" >&2; exit 1; fi
cp "$sbom" "dist/rs-key-${tag}-sbom.cdx.json"
nix develop -c cargo cyclonedx --manifest-path firmware/trustzone/nonsecure/Cargo.toml --target thumbv8m.main-none-eabihf --format json
cp firmware/trustzone/nonsecure/firmware-ns.cdx.json "dist/rs-key-${tag}-sbom-nonsecure.cdx.json"
# 10. checksums
cd dist
sha256sum ./*.uf2 ./*.cdx.json > SHA256SUMS
cat SHA256SUMS
# 11. uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
# 12. attach the provenance bundle as a release asset
cp "${{ steps.attest.outputs.bundle-path }}" "dist/rs-key-${{ steps.tag.outputs.tag }}.intoto.jsonl"
# 13. sign SHA256SUMS (keyless cosign)
cosign sign-blob --bundle dist/SHA256SUMS.sigstore.json dist/SHA256SUMS
# 14. extract release notes from CHANGELOG
ver="${{ steps.tag.outputs.version }}"
awk -v v="$ver" '
$0 ~ "^## \\[" v "\\]" { f = 1; print; next }
/^## \[/ { if (f) exit }
f { print }
' CHANGELOG.md > release-notes-full.md
cp release-notes-full.md release-notes.md
if [ ! -s release-notes.md ]; then
echo "RS-Key ${{ steps.tag.outputs.tag }}" > release-notes.md
fi
if [ "$(wc -c < release-notes.md)" -gt 118000 ]; then
awk '
/^### / && $0 !~ /^### TL;DR/ { exit }
{ print }
' release-notes.md > release-notes.short
if [ "$(wc -c < release-notes.short)" -lt 200 ]; then
awk '
{ total += length($0) + 1 }
total > 115000 { exit }
/^- \*\*/ { last = NR }
{ line[NR] = $0; kept = NR }
END {
stop = (last > 1) ? last - 1 : kept
for (i = 1; i <= stop; i++) print line[i]
}
' release-notes.md > release-notes.short
fi
mv release-notes.short release-notes.md
{
echo
echo "_Shortened to fit GitHub's release-body limit._"
echo "_Every entry is in [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/${{ steps.tag.outputs.tag }}/CHANGELOG.md) at this tag._"
} >> release-notes.md
fi
if grep -qE '<!-- @increase-anti-rollback-epoch([^>]*)-->' release-notes-full.md; then
marker="$(grep -oE '<!-- @increase-anti-rollback-epoch([^>]*)-->' release-notes-full.md | head -n1)"
if ! grep -qF "$marker" release-notes.md; then
printf '\n%s\n' "$marker" >> release-notes.md
fi
fi
{
echo
echo "---"
echo "Verify a download: https://github.com/${{ github.repository }}/blob/${{ steps.tag.outputs.tag }}/docs/supply-chain.md"
} >> release-notes.md
cat release-notes.md
# 15. create the GitHub Release
tag="${{ steps.tag.outputs.tag }}"
if ls dist/*no-touch* >/dev/null 2>&1; then
echo "refusing to publish a no-touch firmware asset" >&2
exit 1
fi
gh release create "$tag" --title "RS-Key $tag" --notes-file release-notes.md dist/*

The image each flavor is

The build step and the reproducibility gate iterate the same list, and a difference between them is a check-assurance.sh failure. Every published image is nix/firmware.nix’s package of the same name.

FlavorPublished asBuild selection
firmwarers-key-<tag>-default.uf2no flags, no knobs
firmware-pqcrs-key-<tag>-pqc.uf2--features advertise-pqc
firmware-fipsrs-key-<tag>-fips.uf2--features fips-profile
firmware-fips-pqcrs-key-<tag>-fips-pqc.uf2--features fips-profile,advertise-pqc
firmware-strong-pinrs-key-<tag>-strong-pin.uf2--features strong-pin
firmware-strong-pin-pqcrs-key-<tag>-strong-pin-pqc.uf2--features strong-pin,advertise-pqc
firmware-always-uvrs-key-<tag>-always-uv.uf2--features always-uv
firmware-always-uv-pqcrs-key-<tag>-always-uv-pqc.uf2--features always-uv,advertise-pqc
firmware-strict-uprs-key-<tag>-strict-up.uf2--features strict-up
firmware-strict-up-pqcrs-key-<tag>-strict-up-pqc.uf2--features strict-up,advertise-pqc
firmware-displayrs-key-<tag>-display.uf2--features display, flashSize = "16M", ledKind = "none"
firmware-2mbrs-key-<tag>-2mb.uf2flashSize = "2M", kvmain = "896K"
firmware-16mbrs-key-<tag>-16mb.uf2flashSize = "16M"
firmware-strict-configrs-key-<tag>-strict-config.uf2--features strict-config

Inside the sandbox

What nix build .#<flavor> runs, out of nix/firmware.nix:

# buildPhase
export PATH="${toolchain}/lib/rustlib/$(rustc -vV | sed -n 's/^host: //p')/bin:$PATH"
export CARGO_NET_OFFLINE=true
export RSK_TZ_OUT="$PWD/target/trustzone"
remap_config="target.${target}.rustflags=[\"--remap-path-prefix=$NIX_BUILD_TOP=/build\",\"--remap-path-prefix=${toolchain}=/toolchain\"]"
bash scripts/build.sh --config "$remap_config" ${lib.escapeShellArgs buildFlags}
# installPhase
mkdir -p "$out"
cp "target/trustzone/combined.elf" "$out/${name}.elf"
picotool uf2 convert "$out/${name}.elf" -t elf "$out/${name}.uf2"

Inputs

The files that decide what a release is. A digest here covers the parts the tables above do not print, and it moves when its file moves and at no other time.

Filesha256
.github/workflows/release.yml9f4218cfb9869bc458be8076f2185af6bdb734598db9b49167557dca30324a05
.github/workflows/release-build.ymldfe836938a828195cbf05b84d963d2cea735b9acbcdb616dfd30f91ef3a9da2a
nix/firmware.nix24ade38891f82bdc18bffc560affc3666f45b9cf7b1c148c1535c8c883fd9e7c
scripts/build.sh48059de27f8d63748ab2aeb23cca71e84e93d281330be219e7b7a7130f923db4

The CI code that runs them, pinned by commit:

ActionPinRelease
actions/checkout3d3c42e5aac5ba805825da76410c181273ba90b1v7.0.1
DeterminateSystems/nix-installer-action3138316df39ed29be04236d7ffc686fa525866aav23
nix-community/cache-nix-action7df957e333c1e5da7721f60227dbba6d06080569v7.0.2
actions/cache55cc8345863c7cc4c66a329aec7e433d2d1c52a9v6.1.0
sigstore/cosign-installer756fe2d284c7292c4e9b62c8a28f1e5629c59532v4.1.3
actions/attest-build-provenance4d101475d8b20a2381f78447822ac1eab6504dd8v4.2.2

The toolchain closure — flake.lock, Cargo.lock and the tools they pin — is the table above this section, and is deliberately not restated here: one copy, one place it can rot.

Published assets: SHA256SUMS, SHA256SUMS.sigstore.json, rs-key-<tag>-16mb.uf2, rs-key-<tag>-2mb.uf2, rs-key-<tag>-always-uv-pqc.uf2, rs-key-<tag>-always-uv.uf2, rs-key-<tag>-default.uf2, rs-key-<tag>-display.uf2, rs-key-<tag>-fips-pqc.uf2, rs-key-<tag>-fips.uf2, rs-key-<tag>-pqc.uf2, rs-key-<tag>-sbom-nonsecure.cdx.json, rs-key-<tag>-sbom.cdx.json, rs-key-<tag>-strict-config.uf2, rs-key-<tag>-strict-up-pqc.uf2, rs-key-<tag>-strict-up.uf2, rs-key-<tag>-strong-pin-pqc.uf2, rs-key-<tag>-strong-pin.uf2, rs-key-<tag>.intoto.jsonl.

What this table does not read

  • a step’s with: and env: blocks. They are inside the digest above and are printed nowhere, so a statement in the table must not rest on one — subject-path, fetch-depth and COSIGN_YES are settings this page describes only in the round.
  • the workflow’s own header comments. They are prose about the procedure, not the procedure.
  • what a pinned action DOES. The uses: steps run code out of another repository; the table above records which commit of it a release runs, and nothing whatsoever about what that commit does.
  • what a command MEANS. The subject column is decided by a command’s shape; a step that is present, spelled right and wrong about the world is outside every rule here.

Open obligations

  • no entry on this page is bound to a release artifact. Binding one needs a v* tag and a release-build.yml run: the tag, the commit, the runner, the per-.uf2 sha256 and the Rekor entry all come into existence there and in no checkout. Cost: one tagged release, by the maintainer, plus a manifest field per bound value and a gate rule holding it against the attestation API. Until then this page is a recipe: what a release runs, not what one ran.
  • source->binary is established by nothing here. PLAT-TOOLCHAIN-001 in assurance/platform.toml owns it and is still pending. A reproducible build is a statement about determinism; a miscompilation reproduces exactly as well as a correct compilation does.

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 fourteen flavors with nix build --rebuild and fails on any bit-level difference before publishing.

2. Checksum signature (keyless cosign)

cosign verify-blob \
  --bundle SHA256SUMS.sigstore.json \
  --certificate-identity-regexp '^https://github\.com/TheMaxMur/RS-Key/\.github/workflows/release-build\.yml@refs/tags/v.*$' \
  --certificate-github-workflow-ref refs/tags/<tag> \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-github-workflow-repository TheMaxMur/RS-Key \
  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), which ends in the ref the run started from. The regexp accepts a v* tag only, because releases are cut from tags. A reusable workflow can be called from any repository, and a run elsewhere that calls this one signs with the same identity, so --certificate-github-workflow-repository pins the repository the run belonged to, which the certificate records beside it. The release job stops a run started at any ref but the tag it releases (its resolve tag step, in the table above). A dispatched run uses the workflow file at the ref it starts from, though, and the tags published up to v0.4.11 carry one without that test: a dispatch at one of them can build another tag and sign it under the old tag’s name, which the regexp alone accepts. --certificate-github-workflow-ref refs/tags/<tag>, with <tag> the one in the file names, refuses it, and so does step 3’s --source-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 \
  --source-ref refs/tags/<tag>

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.) --signer-workflow takes that workflow at any ref, so --source-ref pins the run to the release’s own tag, the one in the file names. 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.

Steps 2 and 3 before flashing: rsk flash

rsk flash rs-key-<tag>-default.uf2    # the board in BOOTSEL

rsk flash takes a release image with SHA256SUMS and SHA256SUMS.sigstore.json beside it. It reads the release’s tag from the SBOM’s name in SHA256SUMS, rs-key-<tag>-sbom.cdx.json: the signature covers that file, so a changed name fails step 2. It runs step 2’s cosign verify-blob with the identity, tag, issuer and repository above, character for character, so the certificate and the bundle’s Rekor entry are checked as they are there. It then matches the image’s sha256 to the one SHA256SUMS lists under its name, and runs step 3’s gh attestation verify with the same --signer-workflow and --source-ref. Only then does it run picotool load -v and picotool reboot.

It stops, with nothing written, when a file is missing, when cosign is not installed, when SHA256SUMS names no single release tag, or when any check fails. When gh is not installed it skips step 3 and says so; the tag pin in step 2 still holds. A gh too old for --source-ref stops it, with a message to upgrade. Step 1 is yours to run. --dry-run runs the checks and writes nothing, which is the route for a secure-boot board: the image it boots is one you seal with your own key first (nix run .#flash, production.md). An image you built yourself has no release signature, so it flashes only with --local-build, which checks nothing and warns.

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. Each real release adds a couple of expected entries from release-build.yml, so a known issue or two per release is normal.

An entry you don’t recognise is not by itself a compromise. The monitor matches the certificate’s subject, the workflow that signed, and release-build.yml is a public reusable workflow: a run in any repository that calls it signs with the same subject. The certificate also records the repository and the ref of the run, the two values the verify commands above pin. openssl x509 -noout -text on the entry’s certificate prints them: the repository under 1.3.6.1.4.1.57264.1.5 (and as a URL under .1.12), the ref under .1.6.

  • TheMaxMur/RS-Key at a release tag that was pushed: a release, expected.
  • TheMaxMur/RS-Key at any other ref: the alarm. A run of ours signed that nobody meant to, or an OIDC token, repository access or runner leaked.
  • Any other repository: someone else called the builder. The pins keep it from verifying as any of our releases, so there is nothing to rotate.

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:0xF1D2 (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:

TransportUsed byOut of the box?
FIDO HID (0xF1D0)WebAuthn, ssh ed25519-sk, fido2-token, python-fido2yes, once the yubico udev rules grant your user access to the hidraw node
CCID (PC/SC)OpenPGP, PIV, OATH, Yubico-OTP, gpg --card-status (ykman only on the opt-in VIDPID=Yubikey5 build)needs pcscd running and a polkit rule to use it as a non-root / SSH-session user
flowchart TD
    a["FIDO HID<br/>WebAuthn · ssh-sk · fido2-token"] --> b["hidraw + yubico udev rules<br/>(usually works out of the box)"]
    c["CCID (PC/SC)<br/>ykman · gpg · OpenPGP / PIV / OATH"] --> d["pcscd + polkit rule<br/>(+ disable-ccid for gpg)<br/>— needs both pieces"]

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

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

Replace youruser with your login name throughout.

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

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

pid.codes allocated 1209:F1D2 to RS-Key. The upstream ccid submission is still pending; allocation alone does not add a reader to an installed driver. Older firmware uses 1209:0001, the shared test PID. The opt-in overlay below keeps that id for existing keys as well; it must not be submitted upstream because it also matches unrelated prototypes.

Until then, pick one:

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

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

NixOS (declarative)

Add to your configuration.nix:

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

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

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

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

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

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

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

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

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

Generic Linux (Debian / Ubuntu / Fedora / Arch)

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

    • Debian/Ubuntu: pcscd pcsc-tools libfido2-1 yubikey-manager opensc
    • Fedora: pcsc-lite pcsc-tools libfido2 yubikey-manager opensc
    • Arch: pcsclite ccid yubikey-manager libfido2 opensc
  2. Enable pcscd: sudo systemctl enable --now pcscd.socket

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

    # RS-Key allocated identity (pid.codes 0x1209:0xF1D2).
    SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="f1d2", TAG+="uaccess", GROUP="plugdev", MODE="0660"
    SUBSYSTEM=="usb", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="f1d2", TAG+="uaccess", GROUP="plugdev", MODE="0660"
    # Compatibility with older RS-Key firmware using the shared test PID.
    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.8.0 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:0xF1D2 (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:

TransportUsed byOut of the box?
FIDO HID (0xF1D0)WebAuthn, ssh ed25519-sk (see ssh.md), browser passkeysyes — Windows drives it through the built-in webauthn.dll, no driver install
CCID (PC/SC)OpenPGP (gpg / Kleopatra), PIV, OATH, Yubico-OTPyes — the Windows Smart Card service binds the standard CCID class; the friction is arbitration, not drivers

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), or a certificate login failing with NTE_BAD_KEYSET (“the keyset does not exist”): the Windows inbox PIV minidriver enumerates the card’s containers from its CHUID and reads the mandatory Card Capability Container (5FC107) while opening one. RS-Key serves both objects automatically. If either is missing on an older image, use ykman piv objects generate chuid or ykman piv objects generate ccc to provision it.
  • PicoForge / a PC/SC tool cannot connect until re-plug: another program is holding the single reader. Close it (PicoForge, Kleopatra, a stray gpg), or unplug and re-plug. gpgconf --kill scdaemon releases a gpg-held handle.
  • gpg --card-status and another PC/SC tool cannot coexist: apply the pcsc-shared + disable-ccid config above, then gpgconf --kill scdaemon.
  • ykman does not see the device: ykman matches on the PC/SC reader name containing Yubico YubiKey, which the default RS-Key build does not present. Build the opt-in VIDPID=Yubikey5 flavor (reader name Yubico YubiKey RSK OTP+FIDO+CCID) to use ykman (see build.md).

rsk — the device CLI

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

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

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

Running it

Storage initialization and upgrades

Storage v2 initializes wholly erased storage and migrates readable legacy storage automatically during boot, before ordinary applets or seed/PIN provisioning run. Firmware upgrades require no storage command or physical confirmation. Use rsk storage status to read the resulting state.

Migration preserves readable routed values and existing keys, needs temporary main-partition space for its manifest and counter backups, and refuses before counter erasure if those backups cannot be verified. An interrupted migration resumes automatically at the next boot. A known SDK E10 padding suffix in an otherwise unused counter sector is ignored by the legacy reader. Other occupied page data still requires a compatible storage layout. Keep an independent backup before an upgrade.

Damaged v2 authority, unreadable storage or a malformed legacy page layout keeps the device in CCID rescue mode. Automatic boot never erases occupied storage to turn it into a fresh device. The attended rsk storage initialize and rsk storage import-legacy commands remain recovery tools, with physical confirmation; normal initialization and upgrades do not need them.

Import trusts the legacy records currently readable. It cannot reconstruct a record already discarded by CRC or identify damage that already formed a valid legacy record. After activation, integrity is checked before codec interpretation; remaining v2 witnesses prevent unavailable authority from falling back to legacy. An activated v2 store requires v2-aware firmware: downgrading to the old backend is unsupported. Preserve the flash image when recovery fails; initialization does not repair occupied media. Endurance costs and remaining freshness limits are described in Limitations.

The software emulator follows the same automatic initialization, migration and recovery rules. Existing images retain their magic and geometry. Authority is bound to the configured serial.

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.

CCID reader selection recognizes RS-Key, RSK, or the firmware’s appended (rs-key-0001) USB serial in the PC/SC reader name. Linux pcscd uses the driver’s friendly name in place of the USB product string on some systems.

Command groups

GroupWhat it doesGuide
statusone-shot device overview (FIDO getInfo + secure-boot + backup)quickstart
inventoryfleet enumeration (list) + identity proof (verify)Fleet tooling
identifyblink a key’s indicator so you can tell it from the others plugged inLED
backupwallet-style seed export / restore / finalize (BIP-39, SLIP-39)Seed backup
pairguided primary + backup (two independent keys) enrollmentBackup key
lockat-rest soft-lock of the FIDO seed (enable/unlock/disable)Soft-lock
flashcheck a release image (signature, checksum, provenance), then write it over BOOTSELSupply chain
secure-bootsecure-boot provisioning + key rotation (irreversible)Production, OTP fuses
otpburn and verify keys, automatically seal at boot; otp status reads the result (burn/seal irreversible)OTP fuses
fidoFIDO2 management: set-pin, list-passkeys, attestationFIDO2, Attestation
ledLED color / brightness per device stateLED
openpgpOpenPGP applet utilities (e.g. reset to factory PINs)OpenPGP card
rebootreboot to the app or to BOOTSEL, over CCID—
auditread + cryptographically verify the tamper-evident journalAudit journal
offboardguided full wipe + signed receipt; prompts for a replug (destructive)Fleet tooling

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

Conventions

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

Entering a PIN

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

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

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

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

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

Touch

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

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

Machine-readable output

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

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

Irreversible actions

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

secure-boot harden programs both DEBUG_DISABLE and SECURE_DEBUG_DISABLE, plus the glitch policy, and verifies all eight CRIT1 copies. Interrupted writes can be retried while page 1 remains writable. secure-boot lock refuses incomplete hardening; cold-boot and debug-denial checks on the board still precede enforcement and page locking.

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

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

Build 0x0BDF discards partial CTAPHID requests when the USB session changes. An old continuation is ignored, and the new session can start on another channel immediately.

Build 0x0BB6 avoids an unused public-point calculation during U2F authentication and attestation signing. Existing credentials work across the upgrade; presence checks and durable U2F counters are unchanged.

Build 0x0B45 sizes the TrustZone CCID reply scratch buffer to the existing CCID response limit, reducing initialization and cleanup work on each APDU. Maximum response sizes and complete buffer cleanup are unchanged.

TrustZone build 0x0ADF further reduces CCID getInfo continuation latency. Existing credentials and records upgrade without a reset.

TrustZone build 0x0ADE reduces CCID getInfo continuation latency. Existing credentials and records remain compatible; the upgrade does not require a reset.

TrustZone build 0x0ADD skips unused zero-length USB packet bookkeeping during CCID transfers. Session and epoch checks and complete buffer/stack cleanup remain unchanged. Existing keys and records upgrade without a reset.

TrustZone build 0x0ADC further reduces authenticated read latency while retaining full record verification and rollback protection. Existing keys and records remain compatible; the upgrade does not require a reset.

Build 0x0AD8 also clears the complete Non-secure gateway reply buffer with volatile word stores, including byte edges, on normal completion and abandonment. The guard also clears it when a pending transport future is dropped.

Build 0x0AD7 clears both complete command response buffers with aligned volatile word stores. Byte edges and remaining words are also cleared; every command retains the same full-buffer cleanup and dead-stack sweep.

The shared flash backend verifies programmed bytes and erased sectors before accepting a mutation. A refused readback reports a storage error even if the new value already landed. Retry from the persistent state rather than assuming rollback; the firmware rebuilds its inventory and reports no spare capacity until an incomplete scan can finish. Record formats are unchanged.

From build 0x0ACF, repeated getInfo requests use the complete authenticated main directory held in protected RAM. Each backend read freshly checks the root and authenticates the full requested value against its expected version. Absence comes from that complete directory. Root keys and plaintext values are not cached.

Build 0x0AD5 retains only metadata and full 32-byte read tags after the original checks succeed. Warm tag hits verify them with a freshly read root, avoiding repeated HKDF, mounted-binding and record MAC work. The tag binds the mounted version and complete requested value, even when the caller requests only its length.

Build 0x0AD0 further shortens warm reads by clearing only the scratch span that the read can fill, including alignment padding. Every borrowed byte is cleared on errors too; recovery retains full-buffer cleanup.

From 0x0AD6, a read-tag miss uses the full wiped scratch so a larger neighboring record does not force a lookup retry. The successful read seeds its tag at once; tag hits still use bounded scratch, with the same fresh root and full value proof.

Before reusing the mounted directory for mutation, the backend checks both full journal banks, selected bank last, including erased tails. Without that ready state, authenticated journal resolution and recovery precede mutation. Errors and remounts retain the mounted version floor, so replaying an older valid snapshot cannot turn a retry into old data or false absence. Damage to unrelated journal bytes or payload-map metadata can remain unnoticed by a warm read that uses only known correct data; it is checked when recovery or mutation consumes that media. The cold-start rollback limitation is unchanged.

Mount can checkpoint obsolete main-journal history when it releases at least half a bank. This authenticates the payloads before erasing and retains files, generations, formats and capacities. Maintenance adds startup work and erases when due. Hardware SHA-256 accelerates public-journal checks; the initial scan and root-key HMACs use software crypto. Shared flash reads retain bounded FIFO, address, mode and final-progress checks, including direct erased-tail checks. Allowlisted Puya chips use Quad continuous reads at the existing clock rate; unknown chips keep the ROM mode, and a failed probe restores the old mode.

TrustZone FIDO uses a 1 ms HID interval. Both encrypted getInfo members share one freshly loaded persistent token per command, with separate keys and IVs; a seed-read failure still leaves the credential-store member available. Secure progress interrupts wake the USB transports; the backup poll runs every 16 ms to reduce interruptions of backend work. A missed notification can add up to 15 ms per wait compared with the earlier 1 ms fallback.

Empty PIN/seed/lock records are damaged state, not a fresh device. Firmware preserves them and refuses the affected operation instead of installing a new PIN or identity. A damaged irreversible backup marker keeps export closed. Malformed global counters refuse advancement; malformed alwaysUv overrides keep user verification required until an authenticated reset clears them.

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 FIDO2 interop results.

When a site has several discoverable passkeys, login returns the newest first. One discovery walk serves up to 16 distinct passkeys, including when creation times coincide; a larger matching set keeps the newest 16. This does not change the device’s 256-passkey storage capacity.

The default build enumerates as “RS-Key”, its own USB identity (0x1209:0xF1D2, 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.8.0, 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:

Value
Length4–63 characters (6–63 on the fips-profile build), counted in Unicode code points — 密码 is two, not six
Per-power-cycle3 wrong attempts → PIN_AUTH_BLOCKED (0x34), re-plug to retry
Retry budget8 wrong attempts (across power cycles)
On exhaustionPIN locks until a factory reset, no separate unblock

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.

From 0x0BA8, persistent retry updates use the mirrored counter journal, bound to the current PIN record. The upgrade preserves the remaining attempts and the per-power-cycle limit. After the first update, earlier v2 firmware refuses the store; reinstall this build or later to resume it without a factory reset.

Build 0x0BB0 combines counter header and value programming. It preserves retry charging before PIN comparison and the existing 0x0BA8 storage format.

When the policy requires a PIN change, the replacement must differ from the current PIN. If its verifier cannot be read, the change returns CTAP2_ERR_OTHER (0x7F) and remains pending; retry with a different PIN once storage is readable.

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. With alwaysUv on, U2F is switched off, since a touch verifies nobody: the device stops announcing it, as a YubiKey does, and refuses its commands. The display build with a PIN set is the exception, where each U2F operation asks for the PIN on the panel.

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, and a U2F registration asserted over CTAP2 (a site’s appid login) reports and advances that same counter, as a YubiKey 5.8.0 does, so the site sees one rising sequence on both paths.

A counter the flash cannot serve is refused rather than reported as 0: an assertion the device could not count is not one it signs, so a read fault costs you the login instead of the tripwire. So is a counter the flash cannot advance: the login fails instead of signing a number the next one would repeat.

Replacing a passkey resets its counter only after its new credential record commits. An interruption can leave the preceding passkey with its preceding counter, or the replacement with that high counter until the owner retries. A completed replacement starts its next assertion at 1.

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:

COSE algCurve / schemeNotes
-7 ES256NIST P-256the universal default
-8 EdDSAEd25519
-35 ES384NIST P-384slow keygen/sign (pure-Rust arithmetic)
-36 ES512NIST P-521slow keygen/sign
-47 ES256Ksecp256k1dropped from new credentials on fips-profile

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

Build 0x0ACA uses compact software SHA-2 rounds for the ECDSA dependency paths on Cortex-M33. This reduces ES384 signing latency while preserving deterministic nonces, signatures and credential keys.

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

Post-quantum credentials

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

The getInfo advertisement is build-gated behind advertise-pqc (build.md) because older versions of Firefox can reject getInfo if it advertises an unknown COSE ID. The capability is always on. Only the advertisement is opt-in, and it lists the three sets in descending security order: ML-DSA-87 (-50), ML-DSA-65 (-49), ML-DSA-44 (-48).

Extensions supported

getInfo advertises nine extensions:

ExtensionWhat it doesLimit
hmac-secretper-credential secret keyed by a salt (the WebAuthn PRF maps onto it)32-byte output
hmac-secret-mcthe same evaluation at registration time
credProtectUV-gated credential visibility (levels 1–3)
credBlobsmall opaque blob stored with the credential128 bytes
largeBlobKey + large blobsper-credential key into a device blob store4 KB store
largeBlob (CTAP 2.3)the blob itself, per credential, inside the assertion4046 B/credential; replaces the row above, largeblob-ext build only
minPinLengththe device hands its PIN-length policy to an authorized RP
pinComplexityPolicytells an authorized RP whether trivial PINs are refusedregistration only
uvmsigned record of the presence and PIN methods usedregistration and authentication
thirdPartyPaymentthe secure-payment-confirmation marker

Read or strengthen the PIN policy with rsk fido pin-policy. For example:

rsk fido pin-policy
rsk fido pin-policy --complexity --min-length 6 --rp-id login.example --force-change

The second command authenticates with the current FIDO PIN. It enables the complexity rule, raises the minimum length, authorizes that RP to read both policy extensions, and requires a new PIN before another token can be issued. Complexity and minimum length cannot be lowered without a factory reset, which also removes credentials. Without --force-change, enabling complexity applies to future PIN changes; it does not evaluate the existing PIN. Repeating --rp-id supplies a replacement list; omitting it preserves the current list. The same complexity rule applies when choosing a FIDO PIN on the key’s display.

hmac-secret has a use outside the browser: it is what lets age encrypt to this device with no smart card involved. See age.md.

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

previewSign (experimental, off by default)

A build option, not part of the default image:

bash scripts/build.sh --features preview-sign

The default image carries none of it, and its getInfo does not list it.

previewSign is Yubico’s draft WebAuthn extension for signing a site’s own data, not a login challenge, with a key the device holds. This build speaks draft v4, the shape python-fido2 2.2.1’s PreviewSignExtension sends. At registration the site asks for ESP256-split-ARKG (COSE -65539). The device then mints an ARKG-P256 seed for the credential and returns its public half inside a second attestation object. The site derives signing keys from that seed on its own, as many as it likes. To sign, it sends the SHA-256 digest of its data plus the derived key’s ARKG arguments. The device derives the matching private key, and the signature verifies as plain ESP256 over the data.

Nothing is stored. The signing key handle ties the seed to its credential with a MAC, so the extension changes no flash record.

On a build with the trusted display, the touch that releases a signature asks Sign data?, not Sign in?: the digest the site asked for is what gets signed, and a compromised host could have put its own there.

The site fixes each key’s presence rule at registration (flags). A require-up key, the default, answers a signature request with up: false with CTAP2_ERR_UP_REQUIRED (0x3B), and a require-uv key wants a verified user as well. An unattended key (0b000) needs no touch: a request with up: false is signed with UP clear and nothing asked, as on a YubiKey 5.8.0.

Deliberate deviations from the draft:

  • The seed’s attestation object is none. The draft attests the signing key in the credential’s own format. A YubiKey 5.8.0 answers fmt: "none" with an empty statement beside a packed credential, and so does this build. Only under enterprise attestation, which that YubiKey was not measured with, is the seed attested, by the credential’s key and chain.
  • Not with an ML-DSA credential. Asking for previewSign on a credential whose algorithm is ML-DSA is refused with CTAP2_ERR_UNSUPPORTED_ALGORITHM (0x26). That response would carry two attestation objects beside a multi-kilobyte key, and it would not fit one CTAPHID message.

Only ESP256-split-ARKG is served. The other algorithms the drafts named (ESP256, ES256, ESP256-split) are refused with 0x26, as the draft says. The COSE ids are the ARKG draft’s placeholders, so expect a later build to change them.

Factory reset

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

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

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

Two details that catch people out:

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

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

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

Troubleshooting

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

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

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

Key typeAlgorithmUse it when
ed25519-skEd25519 (EdDSA)the default: smallest, fastest
ecdsa-skNIST P-256 (ES256)a server or old client rejects ed25519-sk

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:

-O optionEffect
residentstore the key on the device so it can be downloaded later (see below)
verify-requireddemand the FIDO PIN on every login, not just a touch
application=ssh:NAMEtag the credential (default ssh:); a distinct string is a distinct key
user=NAMEuser handle stored with a resident key (for listing/telling them apart)
no-touch-requiredmark the key as not needing a touch; see the note below
write-attestation=FILEsave the enrollment attestation for later verification
challenge=FILEuse a fixed challenge (for reproducible attestation)
# 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.

ActionPINTouch
Enroll (ssh-keygen -t …-sk)onceonce*
Log in, normal key—once
Log in, verify-required keyonceonce

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

SSH signingOpenPGP signing
Keyyour -sk SSH key (ssh.md)a key on the OpenPGP card (openpgp.md)
Needsgit 2.34+, nothing elsegpg + scdaemon
Trust modelan allowed_signers file you curatethe OpenPGP web of trust
Touch / PINtouch per signaturePIN once, then touch per signature (UIF)
Best whenyou only want commit signing, no GPGyou already use GPG, or want WoT

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

Build 0x0BE1 lets the background RSA prime search observe cancellation inside its Lucas test after a key is complete. Prime acceptance, key formats and authorization are unchanged; the abandoned candidate is wiped before core1 idles.

Build 0x0BD6 reduces Brainpool arithmetic and counter-rotation work. Retry charging, durable restoration, migration and key cleanup are unchanged.

Build 0x0B45 sizes the TrustZone CCID reply scratch buffer to the existing CCID response limit, reducing initialization and cleanup work on each APDU. Maximum response sizes and complete buffer cleanup are unchanged.

Build 0x0B44 accelerates P-521 signatures, authentication and ECDH using constant-time point arithmetic and Secure SRAM field routines. P-384 uses a specialized field square on 32-bit targets. Existing keys need no migration; peer validation, deterministic signatures, PIN checks and cleanup are retained.

TrustZone build 0x0ADF further reduces the initial GET DATA 6E response latency. Existing OpenPGP keys and data objects upgrade without a reset.

TrustZone build 0x0ADE reduces latency for the initial GET DATA 6E response. Existing OpenPGP keys and data objects remain compatible; no reset is required.

TrustZone build 0x0ADD skips unused zero-length USB packet bookkeeping during CCID transfers. Session and epoch checks and complete buffer/stack cleanup remain unchanged. Existing keys and records upgrade without a reset.

TrustZone build 0x0ADC further reduces authenticated read latency while retaining full record verification and rollback protection. Existing keys and records remain compatible; the upgrade does not require a reset.

Build 0x0AD8 also clears the complete Non-secure gateway reply buffer with volatile word stores, including byte edges, on normal completion and abandonment. The guard also clears it when a pending transport future is dropped.

Build 0x0AD7 clears both complete command response buffers with aligned volatile word stores. Byte edges and remaining words are also cleared; every command retains the same full-buffer cleanup and dead-stack sweep.

From build 0x0ACF, GET DATA uses the shared backend’s complete authenticated main directory in protected RAM. Each requested value is still freshly read and authenticated under a freshly derived root. The backend retains confirmed publication progress across errors and remounts; it does not cache plaintext. Full journal checks remain before mutations and directory reconstruction. Unrelated journal damage is detected when those journals are consumed, rather than on each warm GET DATA. See shared-storage behavior. Existing objects, capacities and persistent layouts are unchanged. Occasional mount-time history checkpointing still adds startup work and erases when due.

Build 0x0AD0 also avoids clearing unused storage scratch after warm GET DATA. From 0x0AD6, a mounted read-tag miss uses full wiped scratch and seeds its read tag without retrying a small buffer that encountered a larger neighbor. Later tag hits keep bounded scratch and freshly authenticate the complete value. Every byte a read can fill is still cleared on success and failure; recovery retains full-buffer cleanup.

From build 0x0B66, signature-counter reads reuse authenticated journal locations after freshly checking both complete banks, including their erased tails. A change triggers full journal verification and recovery. Signatures still require durable counter publication to both banks before success; existing cards need no migration or reset.

Build 0x0B70 also avoids replaying old journal records after PIN and signature counter writes. Both banks are freshly checked against the exact expected publication before success, including all historical bytes and erased tails. Value MACs, retry ordering and recovery after power loss are unchanged.

Build 0x0B83 reduces repeated directory HMAC setup during the storage checks behind PIN updates. Attempts are still durably charged before comparison, and a successful PIN restores its retry count before authorization is granted.

From 0x0BA8, retry bytes use the mirrored counter journal while the PIN verifiers stay in their original records. Existing remaining attempts migrate on the first update. Earlier v2 firmware then refuses the store; reinstalling this build or later resumes it. No PIN or key reset is needed for the upgrade.

Build 0x0BB0 combines counter header and value programming for PIN retries and signature counters. It preserves the 0x0BA8 format and durability checks.

From build 0x0AD1, key information reads the shared origin record once per response. Later responses read it again; an unreadable or unrecorded slot still reports imported.

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.

Build 0x0ACB accelerates P-384 ECDH decryption with constant-time Jacobian multiplication, retaining peer-point validation and the same shared secret. Build 0x0ACC also accelerates the underlying P-384 field products on 32-bit boards; existing keys and signatures remain compatible.

GET DATA returns 6581 if its output buffer cannot hold the complete data object. An undersized buffer does not produce a successful partial template. GET DATA 7A also returns 6581 when the signature counter is absent, unreadable or not exactly three bytes; it never publishes a partial counter template as a successful response.

Boot preserves present damaged security records rather than provisioning factory PINs or a new DEK over them. A malformed UIF record requires touch. Signing refuses a malformed signature counter without returning a signature; attestation refuses malformed subject fields instead of certifying zero padding.

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

From build 0x0ABF, card-status queries use fewer flash reads on authenticated storage. Each request still reads the current values from the key. Build 0x0AC4 also reads variable children and algorithm attributes once per occurrence. Their lengths come from that same authenticated read; an unreadable child refuses the complete response.

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

DefaultLengthUnlocks
User PIN (PW1)1234566–127signing, decryption, authentication
Admin PIN (PW3)123456788–127key import/generation, card settings
Reset Code (RC)unset8–127unblocking PW1 without PW3

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

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

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

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

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

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

The admin PIN can set how many tries each one gets, with the command a YubiKey takes for it:

ykman openpgp access set-retries 5 3 10   # PW1, Reset Code, PW3; asks for the admin PIN

Each number becomes that PIN’s limit and gives it that many tries at once, a blocked PIN included, which keeps its value. ykman takes 1 to 99; the card takes up to 255, and a 0 in the raw command leaves that PIN as it is. The Reset Code’s number waits until a Reset Code is set, which then starts with it. The limits survive a replug, and a factory reset (below) puts back 3, 3, 3. More tries is more guesses for whoever holds the key: the admin PIN can hand PW1 fresh tries without knowing it.

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 (or as many as set-retries gave it) 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 (likewise) blocks the user PIN. This one is recoverable: unblock it with the admin PIN or the Reset Code (see Unblocking PW1).

KDF (kdf-setup) — hashing the PIN before it leaves the host

The card supports the OpenPGP 3.4 KDF-DO, so gpg can salt-and-hash your PINs on the host and send the hash instead of the passphrase:

gpg --card-edit
gpg/card> admin
gpg/card> kdf-setup          # three salts (PW1, Reset Code, PW3)
gpg/card> kdf-setup single   # or one salt shared by PW1 and PW3
gpg/card> kdf-setup off      # back to sending the passphrase

gpg does not change the PINs afterwards — it just writes the DO and starts sending KDF output. The DO carries the hashes of the factory PINs so the card can follow, so kdf-setup puts both PINs back to their defaults: 123456 and 12345678, hashed. Turning it off does the same thing in reverse. So:

Run kdf-setup first, then change your PINs. In the other order you lose the PINs you chose. This is how a YubiKey and a Gnuk behave too.

Two consequences worth knowing:

  • A card that already holds a key refuses it, with 6985 — gpg: error for setup KDF: Conditions of use not satisfied. Otherwise the DO would hand 123456 to whoever asked next, beside a key that is still there. To change the setting on a provisioned card, factory-reset the applet first.
  • An existing Reset Code is deactivated. The DO has a salt for it but no initial hash, so there is nothing to carry it across; set a new one with passwd option 4 afterwards. (A YubiKey leaves the Reset Code in place here and goes on advertising three tries for it, but the code itself stops working — measured, RESET RETRY then answers 6A80 whatever you send it. RS-Key deactivates it so the counter tells the truth.)

Both PIN retry counters go back to 3 with the PINs, and an admin PIN entered before the command stays valid after it — as on a YubiKey.

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

FamilyChoicesNotes
ECC (sign/auth)Ed25519, NIST P-256 / P-384 / P-521, secp256k1, brainpoolP256r1 / P384r1EdDSA on Ed25519; ECDSA on the Weierstrass curves
ECC (encrypt)Cv25519 (X25519), NIST P-256 / P-384 / P-521, secp256k1, brainpoolP256r1 / P384r1ECDH; the DEC slot only
RSA2048 / 3072 / 4096, plus 1024exponent fixed at 65537 (what gpg imports)

From build 0x0B23, P-521 and Brainpool P-256/P-384 signing and authentication skip the unused public-key derivation before signing. RFC6979 nonce generation, raw signature encoding, PIN and touch requirements remain unchanged; existing keys need no migration. P-384 signing also omits the unused nonce-generator update after success; ECDH uses equivalent coordinate formulas with fewer field additions.

From 0x0BD6, Brainpool signing and public-key generation use constant-time fixed-base tables; ECDH uses Jacobian coordinates with the curve’s original coefficient. Stored keys, deterministic signatures, peer-point validation and PIN/touch requirements are unchanged. Counter rotation writes complete body pages before publishing the checkpoint, reducing flash programs during PIN, HOTP and signature-counter updates without a storage migration.

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

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

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

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

SizeTypical on-card keygen
RSA-2048≈ 4–6 s
RSA-3072≈ 22 s
RSA-4096≈ 50 s
any EC curveinstant

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

Or import existing keys

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

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

keytocard moves the selected subkey onto the card, replacing the on-disk copy with a stub that points at the device. Set key-attr to match the incoming key’s algorithm before keytocard, or the card refuses the import. The size counts as much as the family: a 2048-bit key offered to a slot announcing RSA-4096 is refused, because the attribute is what gpg --card-status and every other host reads back as the truth about that slot. A mismatched algorithm/curve/size returns “Wrong data” / “Function not supported” and a missing admin (PW3) session returns “Security status not satisfied”. An RSA key whose numbers make no working key (p = q, composite primes, a modulus shorter than the attribute) returns “Memory failure”, a YubiKey’s answer there. gpg surfaces each as a card refusal, and a refused import leaves the slot’s key and its 0xDE origin as they were.

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

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

Daily use

Signing and decryption

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

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

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

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

SSH authentication via gpg-agent

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

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

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

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

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

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

Touch policies (UIF)

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

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

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

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

Key attestation

The card can vouch that a key was generated on it, the way a YubiKey does. It signs an X.509 statement about the key with its own attestation key, which it minted at first boot and never lets out (a card an older firmware set up mints it at its first ATTEST). Only keys generated on the card are attested; an imported key is refused.

ykman openpgp keys attest sig sig-att.pem          # PW1; sig · dec · aut
ykman openpgp certificates export att card-att.pem # the card's attestation root
openssl verify -CAfile card-att.pem sig-att.pem

The statement lands in the key’s certificate slot (the one gpg shows as the cardholder certificate) and carries Yubico’s extensions: firmware version, serial, touch policy, form factor, cardholder name, fingerprint and generation time, the signature counter for the signing key, and the key source. Like a YubiKey’s, it names no key usage. With forcesig on, each ATTEST spends the PIN as a signature does. A YubiKey’s chain ends at Yubico’s CA; this card’s attestation certificate is self-signed, so pin the card-att.pem you read off your own device. A factory reset mints a new attestation key, and no host can replace it or its certificate (limitations). The att touch policy gates ATTEST like the others gate their keys: ykman openpgp keys set-touch att on.

AES encryption (PSO)

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

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

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

Recovery and reset

Unblocking PW1

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

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

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

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

A PIN change interrupted by unplugging the key

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

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

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

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

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

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

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

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

ATTEST repairs missing or mismatched root public records from the surviving attestation private key before issuing a statement. Repeating an interrupted repair preserves that key. If the private key itself is absent, ATTEST creates a replacement root after retiring the preceding FC certificate.

A restart also retries removal of a legacy DEK wrapper sealed under the public factory reset code after its verifier was removed. The firmware authenticates that orphan before deleting it; it preserves unidentified wrappers and an owner-set reset code. PW1/PW3 and the keys they open are unchanged.

Factory reset (OpenPGP only)

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

rsk openpgp reset blocks both PINs, however many tries they have, 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).

Between the two commands the applet is terminated, as a YubiKey’s is: every command, SELECT included, answers 6285 until ACTIVATE FILE, across a replug too. An interrupted reset leaves it there rather than half-wiped; run rsk openpgp reset or gpg-card factory-reset again, or send ACTIVATE FILE (00 44 00 00) yourself.

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 the GET DATA reproduction.

PIV

Build 0x0BE1 lets the background RSA prime search observe cancellation inside its Lucas test after a key is complete. Prime acceptance, key formats and authorization are unchanged; the abandoned candidate is wiped before core1 idles.

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:0xF1D2) 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.

SELECT preserves damaged empty PIN, PUK, retry and private-key records rather than provisioning factory credentials over them. A missing or damaged public attestation certificate remains repairable from its unchanged private key. The first SELECT loads each existing management and attestation key once. Build 0x0AC8 accelerates P-384 public-key derivation with four signed fixed-base comb groups and specialized complete doubling. It still checks the attestation private key against its certificate before making the key available. Build 0x0ACA also uses compact SHA-2 rounds for deterministic ECDSA nonces, reducing P-384 signing latency without changing signatures or key validation. Build 0x0ACB accelerates P-384 ECDH with constant-time Jacobian multiplication, retaining peer-point validation and the same shared secret. Build 0x0ACC also accelerates P-384 field arithmetic on 32-bit boards, including signing and the public-key derivation performed during attestation validation. A failed management-key read refuses that SELECT and can be retried; a malformed management-key seal keeps certificate access and recovery available.

Windows. The PIV minidriver uses the CHUID to enumerate the card’s containers and reads the Card Capability Container (5FC107) when opening one. RS-Key supplies defaults for both objects.

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.8.0, slot + PIN/PUK/mgmt-key state

Defaults

DefaultNotes
PIN1234566–8 chars; padded to 8 with 0xFF on the wire
PUK123456786–8 chars; unblocks a blocked PIN
Management key010203040506070801020304050607080102030405060708AES-192, the well-known YubiKey 5.7-era default
PIN / PUK retries3 / 3resets to full on each correct entry

Build 0x0B83 reduces repeated directory HMAC setup in the storage checks behind PIN updates. Each attempt still becomes durable before comparison; successful verification restores the counter before granting authorization.

From 0x0BA8, PIN and PUK retry updates use the mirrored counter journal. Existing PINs and remaining attempts are preserved during the first update. After this migration, earlier v2 firmware opens only recovery mode; reinstalling 0x0BA8 or later resumes the existing store without resetting the key.

Build 0x0BB0 combines counter header and value programming to shorten PIN updates. Retry ordering and the existing 0x0BA8 storage format are unchanged.

Change all three before real use:

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

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

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

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

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

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

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

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

Slots

SlotRoleTypical useDefault PIN policy
9aPIV Authenticationsystem / domain login, SSH, client TLSonce per session
9cDigital Signaturedocument & email signingevery operation
9dKey Managementdecryption, key agreement (ECDH)once per session
9eCard Authenticationphysical-access / contactlessno PIN
82–95Retired Key Management20 slots for old decryption keysonce per session
9bManagement Keyadmin auth (not an asymmetric key)—
f9Attestationsigns slot attestation certs (on-card)—

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

Algorithms. On-card generation and import accept RSA-2048 / 3072 / 4096, RSA-1024 (disabled under the FIPS-style build, SP 800-131A), ECC P-256 / P-384, and the Curve25519 pair Ed25519 (signing) and X25519 (key agreement), the Yubico 5.7 PIV algorithm ids 0xE0 / 0xE1, so ykman drives them as --algorithm ED25519 / X25519. Generation writes no certificate for any of them, as on a YubiKey: make one with ykman piv certificates generate, or import one a CA issued (an X25519 key can’t sign its own). 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 writes the key alone, as on a YubiKey: the slot’s certificate object is left as it was, empty on a fresh slot, until certificates generate or certificates import fills it. A certificate already there stays through a new key, one an older RS-Key build wrote included, so replace it with the new key’s. Management-key auth is required to generate.

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

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

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

Or import an existing key

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

Import is management-key gated and also accepts RSA-2048/1024, P-256/P-384 and Ed25519/X25519. A host sends each prime of an RSA key at exactly half the modulus width, and the key signs one trial block before it replaces anything; a pair that is not a working key (p = q, composite factors) is refused 6A80 and the slot keeps its key, as on a YubiKey. 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
--pin-policyEffect
NEVERno PIN to use the key (default for 9e)
ONCEPIN once per session (default for 9a/9d/retired)
ALWAYSPIN before every operation (default for 9c)

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

--touch-policyEffect
NEVERno button press — the default, for slot keys and the 9b management key alike
ALWAYSa physical touch before every private-key operation
CACHEDtreated as ALWAYS on this device (see below)

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

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

Data objects

ykman piv objects import <id> <file> stores any 5Fxxxx object a YubiKey stores — the standard 5FC1xx set, 5FFF00, and any other id, such as the 5FFF10–5FFF15 the Yubico minidriver keeps its container map in — except the attestation certificate 5FFF01, which no host may replace. An object is up to 3063 bytes, 6700 past that, as on a YubiKey. ykman sends one in a single extended APDU, which carries 3046; a larger one does not fit one CCID frame, so store it with a tool that chains its command. Ids outside the standard set share room for 256 objects and 32 KiB; the next one answers 6A84, as a full YubiKey does, until one is deleted. ykman piv objects export reads any of them back.

Data objects that need the PIN to read

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

ObjectName
5FC103Cardholder Fingerprints
5FC108Cardholder Facial Image
5FC109Printed Information
5FC121Cardholder Iris Images

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

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

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

Attestation

ykman piv keys attest 9a attestation.pem

Proves a slot key was generated on-device, not imported. The attestation certificate is signed on-card by the f9 key (a P-384 CA key, self-signed at first boot) and carries the standard Yubico OIDs: firmware version, device serial, the slot’s pin/touch policy and the form factor. It names no key usage, as a YubiKey’s OpenPGP statement names none: it says where the key came from, not what the key is for. 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

SELECT rebuilds a missing, empty, truncated or preceding-key F9 certificate using the stored key. It also retires a stale public cache left by an older build, retaining a certificate that already names that key. Recreating a missing F9 key removes the preceding certificate before saving the replacement. A storage failure returns 6581; retry after the storage fault is resolved.

An unreadable or non-P-384 F9 key makes PIV SELECT answer 6581. It is preserved, never regenerated. A replug retries boot migration of a key still sealed under the earlier root. The dispatcher retains selection after this refusal; raw APDUs can still reach PIV’s command handlers and their gates.

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

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

Key replacement and MOVE also retire the destination’s old public-point cache before writing the key. If a cache refresh fails, GET METADATA uses the new metadata’s point or derives it from that key. A refused cache retirement stops the operation with 6581; existing key and cache record formats stay readable.

Move and delete keys

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

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

Certificates stay where they are, as on a YubiKey: a move leaves the source slot’s certificate behind and the destination’s in place, and a delete keeps the slot’s certificate. To carry it to the key, export it and import it there, then delete the one left behind:

ykman piv certificates export 9a cert.pem
ykman piv certificates import 82 cert.pem
ykman piv certificates delete 9a

A key generated or imported into the slot later keeps that certificate too. On a display build, the panel’s Generate key skips a retired slot that still holds a certificate: delete it to free the slot.

Moves go both ways — a key parked in a retired slot can come back to an active one. A move onto a slot that already holds a key is refused, as on a YubiKey (ykman says DEST slot is not empty): delete that key first if that is what you mean. Moving a key onto its own slot is refused too, because the source-delete would erase what the move just wrote. Both operations require management-key auth.

Use it

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

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

  • SSH via PKCS#11:

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

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

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

  • 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 (PIV interop results).

At rest

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

Factory reset (PIV only)

ykman piv reset

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

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

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

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

Troubleshooting

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

age encryption + secretspec

Encrypt files — and a project’s secrets — to a key that only opens with the device in your hand. Two layers, and this page is in that order: age on its own, then secretspec on top of it.

RS-Key drives both over FIDO2, not the smart card. The plugin asks for the CTAP hmac-secret extension over CTAPHID, so nothing here wants PKCS#11, OpenSC, or a particular reader name, and the stock build works as shipped. PIV is the other route to age and buys something different — the trade-off is at the end of this page.

What you are trusting. hmac-secret unwraps an age identity into host memory. Whoever lifts it from there decrypts your past and future files with no token at all. The device gates access; it is not a wall the key never crosses. On the PIV route the private key does stay on the card. threat-model.md draws that line, and this page sits on the permissive side of it.

What the token actually does

FIDO2 has no asymmetric decryption to offer, so nothing here is “decrypted by the key”. hmac-secret returns 32 deterministic bytes for a given (credential, salt) pair; the plugin uses them to unwrap an age identity it stored in the recipient, or in the encrypted file’s own stanza.

What it costs on the device: nothing persistent. The credential is non-discoverable, so it takes no slot in the credential store and shows up in no passkey list. Its relying party is age-encryption.org, and the same token mints as many independent recipients as you care to ask for.

Install

nix shell nixpkgs#age nixpkgs#age-plugin-fido2-hmac

Or from source — it is Go plus libfido2:

go install github.com/olastor/age-plugin-fido2-hmac/cmd/age-plugin-fido2-hmac@latest

age finds the plugin by name on PATH; there is nothing to configure. On Linux you need the FIDO udev rules, same as for SSH keys — see linux.md. The plugin is pre-1.0 and ships no Windows build.

Create an identity

age-plugin-fido2-hmac -g > identity.txt

It walks you through, in this order:

  1. finds the token (it waits up to 50 s, so plug in whenever),
  2. asks for the FIDO PIN, but only if one is set on the device,
  3. asks for a touch, and mints the credential,
  4. asks whether to require the PIN for decryption — again only if a PIN is set, otherwise decryption is touch-only,
  5. asks whether you want a separate identity. Yes gives you a file to keep; no is “data-less”, where the credential id travels inside every encrypted file and anyone holding one can read it.

Its yes/no questions want a digit, not a letter — 1 for yes, 2 for no — and it reads them straight from /dev/tty, so the prompts survive redirecting stdout to a file but a pipe on stdin will not answer them.

-g writes the recipients into the file as comment lines. Pull one out and encrypt to it:

grep '^# public key:' identity.txt | sed 's/^.*: //' > recipient.txt
echo 'secret' | age -R recipient.txt -o secret.age
age -d -i identity.txt secret.age          # with an identity file
age -d -j fido2-hmac secret.age            # data-less

An ordinary run prints two of them — a plain age1… X25519 recipient and, because deriving it is nearly free, an age1pq… post-quantum hybrid on a # public key (pq safe): line. Take one or the other, never both: age refuses a roster that mixes post-quantum and classic recipients. The grep above anchors on the colon so it picks the classic one; swap the pattern to '^# public key (pq safe):' for the hybrid.

Do not pattern-match on age1fido2-hmac1 — that prefix appears only in the symmetric mode. To recover a recipient from an identity later, age-plugin-fido2-hmac -y identity.txt derives it, but that one needs the token.

Encryption needs no token. The recipient carries an X25519 public key, so age -R runs on a machine that has never seen the device. Only decryption touches it. (-s/--symmetric is the exception: it re-salts every encryption and wants the token both ways.)

Algorithms RS-Key accepts

-a picks the credential’s signature algorithm. It never signs anything here — hmac-secret is the whole point — but the device still has to accept it at enrollment:

-aCOSEOn RS-Key
es256−7the default, works
eddsa−8works on every shipped build
rs256−257refused. RS-Key advertises ES256, ES384, ES512 and EdDSA — no RSA

If you pick rs256 the enrollment fails with an unsupported-algorithm error before anything is written. Nothing is left behind; just rerun with es256.

PIN and touch

ActionFIDO PINTouch
-g enrollment, no PIN on the device—once
-g enrollment, PIN setonceonce
Encrypt (age -R)——
Decrypt, require-PIN answered no—once
Decrypt, require-PIN answered yesonceonce

On an always-uv build, answer yes. The shipped image leaves alwaysUv off, so the touch-only path above is the default. Build with --features always-uv (or flip it with ykman fido config toggle-always-uv) and a makeCredential carrying no PIN token is refused whatever else it asks for — see tests/16_always_uv_gate.py. So set a FIDO PIN first, then answer yes to the require-PIN question.

RS-Key packs the whole credential into the credential id, because a non-discoverable credential has nowhere else to live. That id rides inside the identity string, and inside each encrypted file’s stanza when you go data-less, so both run long. The recipient does not carry it — an ordinary run hands you a plain X25519 age1…, the same length as any other.

secretspec on top

secretspec separates which secrets a project needs from where they live. The declaration goes in secretspec.toml and gets committed; the values go to a provider. Its age provider keeps them in one age-encrypted blob, which is exactly the file the plugin above can lock.

[project]
name = "my-app"
revision = "1.0"

[providers]
vault = "age://secrets.age?identity=identity.txt&recipients-file=recipient.txt"

[profiles.default]
DATABASE_URL = { description = "PostgreSQL connection string", providers = ["vault"] }
secretspec set DATABASE_URL          # no token — writes to the recipient
secretspec get DATABASE_URL          # touch (and PIN, if required)
secretspec run -- ./my-app           # same, secrets exported as env vars

The asymmetry is the useful part: writing a secret never needs the key, so CI and colleagues can add values against the committed recipient file, and only reading asks for the token. Commit secrets.age and recipient.txt; keep identity.txt off the repo, or drop it entirely and let the stanza carry the credential id.

Two things that will bite you:

  • secretspec can ask for a --reason. Its require_reason policy defaults to "agents", and every command above is refused in an environment it reads as one until you pass --reason "<why>" or set SECRETSPEC_REASON. Put require_reason = false in [project] to switch it off.
  • Everyone on the roster reads the whole blob. age recipients decrypt the file, not individual keys. Split anything with a narrower audience into its own blob with its own recipients file.

Which route

Both end at age; they differ in where the key is when it is used.

FIDO2 hmac-secret (this page)PIV + age-plugin-yubikey
TransportCTAPHIDCCID / PKCS#11
Stock buildworkswants the VIDPID=Yubikey5 build, or opensc-pkcs11.so — the plugin matches on the reader name
Key at decryptionidentity in host RAMprivate key stays on the card
Device statenone — non-discoverable credentialoccupies a PIV slot
Recipients per tokenunlimitedone per slot

Pick hmac-secret for convenience on a stock key and for secrets you would otherwise leave in a .env. Pick PIV when “the key never leaves the card” is the property you actually need.

What was measured

The CTAP exchange below is the plugin’s own, taken from its source at c490421 and replayed call for call.

On a board. RS-Key’s getInfo advertises hmac-secret (and hmac-secret-mc), so the plugin’s device filter accepts it. With alwaysUv turned on and a PIN set, the plugin’s makeCredential carrying no PIN token is refused PUAT_REQUIRED — the warning above, on hardware — while rs256 is refused UNSUPPORTED_ALGORITHM first, so the algorithm check runs ahead of the UV gate. An authenticatorReset brings the shipped image back with alwaysUv off, which is the state the touch-only path assumes.

On the software emulator (tools/emu, see testing.md):

  • makeCredential (relying party age-encryption.org, non-discoverable, hmac-secret) is served for es256 and eddsa and refused for rs256. Credential ids came back at 131 and 135 bytes.
  • getAssertion returns a 32-byte hmac-secret output, identical across calls for one salt and different for another — the contract the plugin checks before it will unwrap anything. tests/24_extensions.py asserts the same thing as part of the suite.
  • secretspec’s age provider round-trips set / get / run / check with a plain identity and the provider declared in secretspec.toml as above, and it spawns age-plugin-fido2-hmac --age-plugin=identity-v1 when the identity is a plugin one — so plugin identities are wired through it.

Still unmeasured: a full round trip driven by the plugin itself — enroll, encrypt, decrypt — and the same through secretspec. Every step of it needs a physical touch, so it takes someone at the device; nothing in the exchange is in doubt, only the end-to-end run.

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.

An existing empty access-code or OTP-PIN record keeps its authentication gate closed. It cannot open the password safe or authorize a replacement PIN. An access-code record without secret key material cannot validate a session.

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:0xF1D2) 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:

OptionEffectDefault
--touchcomputing this account’s code needs a button pressoff
--oath-type {TOTP,HOTP}counter-based vs time-basedTOTP
--algorithm {SHA1,SHA256,SHA512}HMAC hashSHA1
--digits {6,7,8}code length6
--period NTOTP step in seconds30
--counter NHOTP starting counter0
--forceoverwrite an existing account of the same name without asking—

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.

Build 0x0B55 reduces repeated storage checks during HOTP updates. Existing accounts and counters need no reset or migration; each counter advance still becomes durable before its code is returned.

Build 0x0B66 also reduces shared-backend cleanup work during HOTP advances and PIN updates. It skips historical bodies of published files during the read-only orphan walk, while authenticating every published value before cleanup or garbage collection. Both durable publications remain required.

Build 0x0B70 replaces the closing history replay with a fresh check of both complete banks against the exact expected append. HOTP still returns its code only after both publications are durable; payload authentication, erased-tail checks and power-loss recovery retain their existing contracts.

Build 0x0B83 reduces repeated directory HMAC setup during HOTP’s storage update. All payload checks and durable publications remain; existing accounts need no migration or reset.

From 0x0BA8, HOTP advances a separately encrypted counter in the mirrored journal instead of rewriting the credential. Existing counters migrate on their next use; rename preserves the current counter, while replacing or deleting an account starts a new owner. OATH PIN retries use the same journal. After migration, earlier v2 firmware refuses the store. Reinstall this build or later to resume it without resetting accounts.

Build 0x0BB0 combines counter header and value programming to shorten HOTP updates. Both copies remain durable before a code is returned; the 0x0BA8 format and existing accounts need no further migration.

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.

For only-increasing accounts, a bulk read persists the challenge marks before returning codes. A flash read failure refuses the command with 6581 and no codes; marks already saved for earlier accounts stay advanced.

Touch-required accounts

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

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

Accounts that only go forward

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

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

The OATH access password

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

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

How it works on-card: the password becomes an HMAC key (PBKDF2 over the password, salted with the device serial, done host-side by ykman). Selecting the applet issues a random challenge, and 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). The proof then holds, as on a YubiKey, until another application is selected, the card is reset, or the key is unplugged; a SELECT of OATH while it is already selected keeps it. The compare is constant-time and full-length, so a truncated or guessed response can’t brute-force its way in one byte at a time.

Footguns:

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

The OTP PIN and the password safe

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

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

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

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

Manage

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

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

Notes

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

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.
  • Adding an account fails with 6A80 (“incorrect parameters in the command data”): the client sent something the enrollment rules above refuse, most often a secret shorter than 14 bytes that it did not pad. A 16-character base32 secret, which many sites hand out, is 10 bytes, and a YubiKey refuses it the same way. Use a client that pads (ykman does), or pad a 16-character secret yourself: remove the spaces and append AAAAAAA. That is the same key zero-padded to 14 bytes, so the codes do not change. A client that sends the touch property as 78 01 02 instead of the bare 78 02 pair gets the same error.
  • 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:0xF1D2, reader “RS-Key”) is invisible to it. The HID-keyboard typing of a slot’s output is identity-independent and works on either build. Only programming and reading slots over ykman needs the Yubico flavor.

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

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

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

Slot selection by clicks

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

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

ClicksSlotykman otp
1 (short)1yes
22yes
33slot-offset APDU only
44slot-offset APDU only

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:

TypeOn button pressOver USB (ykman otp calculate)
Yubico OTPtypes a 44-char modhex OTP—
Static passwordtypes the stored password—
OATH-HOTPtypes the 6/8-digit code—
Challenge-response (HMAC-SHA1)nothinganswers the challenge
Challenge-response (Yubico mode)nothinganswers the challenge

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 no command clears the slot, as on a YubiKey: only a whole-device wipe does — the trusted display’s factory reset, or rsk-wipe flashed over BOOTSEL.

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 15-bit usage counter advances at the first press after every power-up and at every session wrap, until it stops at 0x7FFF. Before that limit, the persisted advance keeps the (use, session) position moving across reboots. At the ceiling, rebooting or wrapping the session can repeat that position; reprogram the slot with new secrets shared with the verifier before reaching it. This follows Yubico’s counter limit. A host cannot advance the counter without a press.
  • 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 (-L <code> once a lock code is set)

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. A programmed typing slot can also stay silent if the key could not store the counter step that press owed — it will not type a code it cannot move past. Press it again: a Yubico-OTP slot owes that step on its first press and then rarely, an OATH-HOTP slot owes it on every press, so a failing store silences HOTP until it recovers. Do not re-plug to clear it — that starts a new power cycle, and if the store is refusing writes the key cannot advance its counter across one either, so what comes back is the previous cycle’s codes. Free space first (rsk status shows it); a key whose store is genuinely failing needs re-provisioning.
  • 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); a lost code needs a whole-device wipe (see Access code above).
  • Slots 3/4 don’t show in ykman otp info → expected. ykman otp only enumerates 1 and 2.
  • A configure / update / swap / set-scan-map fails where the same command worked a moment ago → the key could not read, or could not write, a slot it had to touch, so it refused rather than treat an unreadable slot as an empty one. Check what actually happened before retrying — the refusal does not tell you. A read refused at the gate stops before anything moves and leaves the slots untouched, but a refusal that comes from the write half does not: a slot DELETE is reported failed if the key still finds the record afterwards, and a swap writes its two slots one after the other, so one refused partway can leave the copy that already landed standing with both slots showing the same public id. ykman otp info shows which case you are in; re-run the command from there.
  • 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

Primary + backup pairSeed-backup mnemonic
What it protectslive access, a second key already enrolledone identity, recoverable later
Recover bygrabbing the backup key (no steps)restoring the phrase onto a new board
Secret exposurenone shared, two independent seedsthe seed passes through the host at export
Covers passkeys / PIV / OpenPGPenroll them on each keyno (sealed to the chip)
Costregister both keys everywherewrite the words down, keep them safe

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:

--schemeWhat it printsReconstruct with
bip39 (default)24 wordsthe same 24 words
slip39Shamir shares (--threshold/--shares, default 2-of-3)any threshold shares
hex64 hex charactersthe same hex
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:

FlagMeaning
sealedthe one-time backup-export window is closed (seed-backup.md)
has_seeda plaintext-sealed seed is on flash (false while locked)
lockedthe wrapped blob is what’s stored — an unlock is required
unlockeda RAM copy from this power cycle’s unlock is live

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.

KnobDefaultWhen to change it
LED_KINDws2812ws2812 (addressable RGB, default), gpio (plain on/off), pimoroni (3-pin PWM RGB), or none (no indicator). See build.md.
LED_PIN16A board whose addressable LED is on a different GPIO (0..=29).
LED_ORDERrgbA WS2812 board with swapped red/green: set grb (the WS2812B standard). The Waveshare RP2350-One is rgb; most other parts are grb.
MAX_LEDS1A board with multiple daisy-chained addressable LEDs: set it to the chain length (max 64). Default 1 is a single onboard LED. The actual connected count is set at runtime with rsk hw --led-num.
# example: build for a 4-LED board with standard GRB order
env MAX_LEDS=4 LED_ORDER=grb bash scripts/build.sh
# 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.

EffectIDWhat you seeSuits
legacy0Classic on/off blink (TIMING table)Original blink behaviour
vapor1All LEDs breathe together, smooth triangle-wave brightnessIdle (default)
bounce2A wide hump of light glides back and forth with half-step interpolationTouch (default)
flow3Yellow→red gradient flowing left to right with a trailing wakeProcessing (default)
sparkle4Each LED flashes an independent random colourBoot (default)

Default mapping (multiple LEDs)

StateDefault effectDefault colourMeans
idlevapor: gentle breathinggreenready, nothing in flight
processingflow: warm-colour flowyellow→red gradienthandling an APDU / crypto op
waiting for touchbounce: smooth bounceyellowpress the button to confirm
bootsparkle: random sparkleredthe brief power-up state

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 ends when USB is configured. The LED switches to idle as soon as the host configures the device, before any applet command is needed.

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

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

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

Identify (CTAPHID wink)

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

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

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

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

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

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

Selectors and values

FlagValues
--statusidle, processing, touch, boot (default idle)
--coloroff, red, green, blue, yellow, magenta, cyan, white
--brightness0–255 per channel (0 = off, except --status touch, see above)
--effectlegacy, vapor, bounce, flow, sparkle
--speed0–255 (0 = effect’s built-in default; 1 is raised to 2 on --status touch)
--steadysolid colour, no blinking, global, affects every state
--blinkthe opposite: restore blinking

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

A configuration lock shuts both commands, on either transport, and no code opens them: clear the lock first. The trusted display’s own settings stay open.

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

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

Reset to defaults

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

Under the hood

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

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

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

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

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

Troubleshooting

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

Trusted display

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

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

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

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

The display build runs the RP2350 at 160 MHz. A TX-only PIO program emits one serial bit every two cycles, for an 80 MHz panel clock. A complete 240×320 RGB565 transfer has a 15.36 ms wire-time floor. Both of those numbers are past what the parts are rated for — the RP2350 is specified to 150 MHz and this project had recorded 62.5 MHz as the ST7789’s write ceiling — so what that costs, and which of this repo’s measurements stop covering this flavor, is written down in limitations.md. A key without a screen sets no clock and is unaffected.

Try it without a board

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

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

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

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

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

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

To run the compiled firmware itself, build the ordinary display image below, then launch it with rsk-emu --image target/trustzone/combined.elf --display. The window shows pixels captured from the firmware’s PIO serial output. Mouse contacts become CST328 or CST3530 I2C reports; Space drives the board’s wake GPIO. Add --headless for scripted runs. In image mode, tap-script hold and gap durations follow the emulated clock, so a slow host cannot turn a short contact into a long approval hold. See display image testing for the runner and its limits.

This exercises firmware instructions, rendering and USB framing against models of the panel and touch controller. Physical display timing, electrical I2C behaviour and touch calibration still require the board.

Building and flashing

Use the package for your board revision. Both use the same ST7789 display, but their touch controllers have different I²C addresses and register maps. With the wrong image the screen draws normally and touches do not register.

Board revisionTouch controllerI²C addressNix package
V1CST3280x1Afirmware-display
V2CST35300x58firmware-display-v2

Check the board silkscreen or the controller address to identify the revision. Waveshare board specifications

nix build .#firmware-display     # V1 → result/firmware-display.uf2
nix build .#firmware-display-v2  # V2 → result/firmware-display-v2.uf2

# Build V2 from source with the TrustZone builder.
nix develop -c env BOARD=waveshare-touch-lcd DISPLAY_TP_CHIP=cst3530 \
  bash scripts/build.sh --features display

The source build writes target/trustzone/combined.uf2. Omit DISPLAY_TP_CHIP=cst3530 for V1. The board preset selects 16 MiB of flash and disables the addressable LED, freeing GPIO16 for the backlight.

The board’s BAT_PWR button (GPIO25 by default) wakes and sleeps the panel. Sleeping blanks the screen, locks the on-device UI when a device PIN is set, and aborts any interrupted host prompt. See Build options for WAKE_PIN and 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:

TabWhat it shows
HomeA calm “Ready” and a status card: USB, whether a device PIN is set, and the resident-passkey count (cached, refreshed only at modal boundaries).
PasskeysThe resident credentials, one row per relying party.
AppsA read-only browser for the OpenPGP / PIV / OATH applets.
SettingsDisplay, Security, Firmware, Audit log, Backup, Factory reset.

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). It writes the key alone, as a host generate does; make its certificate from the host. A slot whose key was moved or deleted still holds its certificate, so it is not free until that certificate is deleted (ykman piv certificates delete 82). 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. A configuration lock shuts the host tool’s write and not the panel’s, which no host can reach.
  • Security: set / change the device PIN and the FIDO clientPIN (each chosen entirely on the panel). Changing the clientPIN asks for the current one first, and that prompt is the card’s changePIN check: a wrong entry spends a retry and ends any pinUvAuthToken a plugged-in platform holds, exactly as a wrong old PIN sent over USB does — the platform just asks for the PIN again. Then a PIV PIN sub-menu: change the PIV PIN, change the PUK, unblock a blocked PIN with the PUK, or protect the management key. Protect mgmt key generates a random AES-256 management key, seals it and marks it PIN-protected, the ykman --protect scheme, so a host then uses the management key with just the PIV PIN (which alone grants management access, a trade-off the panel states and gates behind the device PIN and a hold). Any existing host PivmanData (its PIN-change timestamp and other flags) is preserved (the obsolete derived-key salt is dropped, exactly as ykman does). Last on the page, Scramble PIN pad — a toggle, off by default. On, the ten digit keys are laid out afresh at random for every PIN entry (and again between the “New PIN” and “Confirm PIN” steps), so a fingerprint trail, a worn patch of glass, or an onlooker who sees your hand but not the panel learns nothing from where you tapped. It buys nothing against anyone who can see the screen — they read the digits off it — and it costs muscle memory: entry is slower and mistyping is likelier, against a limit of three wrong PINs per power cycle. That trade is the owner’s to make, which is why it ships off.
  • Firmware: the installed bcdDevice build and chip serial, the real OTP secure-boot fuse state (it warns when secure boot is off rather than claiming a check it isn’t doing), and the hold-to-reboot into BOOTSEL for an over-USB update.

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

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

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

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

Security model

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

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

See also

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

FlagEffect
(none)interactive cockpit
--demo, --mockinteractive cockpit against a simulated device, no hardware needed
--onceprint the gathered status once (human-readable) and exit
--jsonone-shot machine-readable status (JSON) and exit
--identifyblink this key’s indicator and exit (the Overview action, scripted)
--selftest [PIN]native backup export/restore round-trip (needs a no-touch build)
-h, --helpusage

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

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

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

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

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

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

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

Layout

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

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

Key bindings

KeyAction
Tab / Shift-Tab, ← / →switch section
↑ ↓ or j kmove selection in the action list
Enterrun the selected action
rrefresh device status
/search actions across all sections
?jump to Help
Esccancel a modal / input
q or Ctrl-Cquit (terminal restored on exit)

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

SectionReads (safe)In-band actions
Overviewidentity (serial, fw, bcdDevice, sdk, aaguid), transports, backup/lock/secure-boot/rollback/attestation/flashRefresh, Verify identity
FIDOCTAPHID presence, versions, clientPIN, optionsCount resident passkeys (PIN · credMgmt)
OpenPGPapplet presence, card serial, PIN retries, populated key slots (from 6E)—
PIVapplet presence, PIN retries + default-PIN flag (from GET METADATA)—
OATH / OTPapplet presence—
Backupseed / sealed / lock stateExport (BIP-39 · SLIP-39 2-of-3), Restore, Finalize
LEDLED mode + per-state color/brightness, with a live colour swatchRead state, Cycle idle color
Auditjournal head + checkpoint key hintRead journal, Verify identity
Reboot / Maintenancedevice summaryReboot → app, Reboot → BOOTSEL
Helpkey bindings, section guide, safety model—

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 on the VIDPID=Yubikey5 build, or a browser’s “reset security key” on any build)
  • 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

eventdetail
BOOTfirst journal touch of each power cycle
MAKE_CREDENTIAL / GET_ASSERTION / U2F_REGISTER / U2F_AUTHfirst 8 bytes of the rpIdHash (only weakly pseudonymous, see Gating). A run of the two silent variants folds — see below
RESETfactory reset (survives it — see below)
PIN_SET / PIN_CHANGE / PIN_LOCKOUTlockout aux: 0 = retries exhausted, 1 = per-boot block
CFG_MIN_PINaux = new minimum; detail[0] = forceChangePin
CFG_ENTERPRISE_ATTno aux/detail (flag-only)
CFG_EA_RPIDSthe vendor-facilitated enterprise RP list was rewritten; aux = how many RPs it now holds, 0 = cleared
LOCK_ENGAGE / LOCK_RELEASEsoft-lock engage/release
BACKUP_EXPORT / BACKUP_LOAD / BACKUP_FINALIZEseed-backup lifecycle
ATT_IMPORT / ATT_CLEARorg attestation provisioning
CFG_ALWAYS_UValwaysUv toggled; no aux/detail (flag-only)
CONFIG_WRITEa device-config write over the FIDO vendor channel. aux = the target that opened the entry (0 dev-conf, 1 phy, 2 led); detail = repeats(2 LE) ‖ targets(1) (see below)
AUDIT_CFGjournalling itself: aux 1 = turned on, 0 = turned off (that entry is the last one written, so the trail shows when it stopped)
CHECKPOINTevery signed checkpoint is itself logged

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

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

Events a silent host can drive cost one slot per run

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

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

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

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

Two consequences worth knowing:

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

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

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

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

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

How the tamper evidence works

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

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

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

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

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

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

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

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

Pinning the attestation key — --expect-key

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

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

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

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

Reset semantics (privacy by design)

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

Gating

commandopen devicePIN set
audit log / AUDIT_READtouchpinUvAuthToken with the acfg permission
audit verify / AUDIT_CHECKPOINTtouchtouch + acfg pinUvAuthToken
  • 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

symptommeaning / fix
device requires a PIN — pass --pin (status 0x36)a FIDO PIN is set; add --pin <pin>
checkpoint refused — no OTP DEVK provisioned (status 0x30)dev board with no DEVK burned; verify cannot sign. log still works. See production.md
denied — no touch within 30 s (status 0x27)press the button when the LED blinks; rerun
attestation key MISMATCH — this is not the enrolled device--expect-key did not match: wrong device, or a clone flashed without your OTP
signed head differs from the exported windowthe journal changed between the read and the checkpoint. Rerun; if it persists, treat it as TAMPER
checkpoint SIGNATURE INVALID — do not trust this journalthe signature did not verify under the returned key. Do not trust the log
export length does not match the windowthe exported entry bytes don’t match seq_next − start; a corrupt or truncated read

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

What it does and does not prove

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

Two honest limits worth stating:

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

Enterprise attestation (org provisioning)

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

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

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

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

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

The key + chain model

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

Stored asHoldsSealing
EF_ATT_KEY (0xCE10)the org attestation P-256 private scalarkbase-sealed, exactly like the master seed
EF_ATT_CHAIN (0xCE11)the DER certificate chain, leaf first (count ‖ (len ‖ der)*)public material, stored plain

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:

LimitValue
CurveP-256 only
Chain size≤ 2132 bytes total
Certs in chain≤ 4

Give each device its own key. The key is sealed like the master seed, so an attack that reads a device’s OTP (threat model) opens it, and a key the whole fleet shares would then attest any authenticator as one of yours. Issue every device its own leaf under your CA.

status is ungated and prints whether a chain is installed plus the SHA-256 of the packed chain (so you can confirm a device carries the chain you issued it, without moving any secret):

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

A chain the device cannot read back whole has no hash to show. status then says the chain is missing, unreadable or over the cap. Enterprise registrations fall back to the device certificate (below), or fail while the chain cannot be read. Re-import the key and chain, or clear the key, to repair it.

To roll back to the factory self-signed cert:

rsk fido attestation clear [--pin …]

What changes once a chain is installed

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

The chain has to read back whole to be used for enterprise attestation. A build before 0.4.11 could store one past the cap above, and it now reads back cut. An EA request over such a chain gets the per-device basic attestation and no ep flag, since the org attestation is the one the device cannot give. Re-import the chain within the cap to restore it. Up to bcdDevice 0x0A69 that registration failed with CTAP1_ERR_OTHER.

The org key itself is held to the same rule. One that is stored but will not open on this device (sealed on another) gives the same per-device attestation and no ep. A key the flash could not read fails the registration with CTAP1_ERR_OTHER for the host to retry, as an unreadable chain does. Up to bcdDevice 0x0A78 both got the per-device attestation with ep, as if no org key were installed. U2F registration holds its batch attestation to the same rule: an unreadable org key answers 6581 (MEMORY_FAILURE, what an unreadable signature counter answers there) for the host to retry, and one that will not open gives the device certificate. Up to bcdDevice 0x0A87 an unreadable key gave the device certificate too, a registration attested by the wrong key for good.

Without an org chain (the default)

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

EA levelWithout org keyWith org key
(absent / 0)basic, device certbasic, device cert
1 — vendor-facilitated, RP listedbasic, device cert, ep flagfull org attestation
1 — vendor-facilitated, RP not listedbasic, device cert, no ep flagbasic, device cert, no ep flag
2 — platform-managedbasic, device cert, ep flagfull org attestation

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

Enabling EA on the device (enableEnterpriseAttestation)

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

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

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

Who gets vendor-facilitated (type 1) EA

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

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

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

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

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

Transport and gating

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

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

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

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

Reset semantics

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

StateSurvives authenticatorReset?
EF_ATT_KEY (org key)yes: org-provisioned device identity, not user data
EF_ATT_CHAIN (chain)yes
EF_EA_ENABLED (the enable flag)no: wiped with PIN, credentials, counter
EF_EA_RPIDS (the type-1 RP list)no: wiped with the flag it serves

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

Privacy note

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

Troubleshooting

  • attestation key must be P-256 (got …): the --key PEM is the wrong curve. RS-Key attests with ECDSA P-256 only. Re-issue the org key on secp256r1.
  • chain too large (… B, max 2132): 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).

FieldRS-Key value
attestationTypes["basic_full"]: packed attestation with an x5c leaf
attestationRootCertificates[]: the leaf is per-device and self-signed, so there is no shareable root; a relying party requiring a trust anchor treats this attestation as untrusted
legalHeaderStandard MDS3 text, matching the official tool’s Metadata P-36; the statement remains self-published
authenticationAlgorithmssecp256r1 / ed25519 / secp384r1 / secp521r1 / secp256k1 (ECDSA + EdDSA)
keyProtection["hardware"]: RP2350 flash/OTP, not a separate certified secure element
matcherProtection["on_chip"]: the PIN is verified on the device
attachmentHint["external", "wired"]: a USB roaming token
upv1.0, 1.1, 1.3: one per FIDO2 entry the device advertises in versions. MDS 3.1.1 maps CTAP 2.0, 2.1 and 2.3 there and reserves 1.2, because CTAP 2.2 was skipped

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

Two caveats baked into the statement

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

What this does — and does not — get you

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

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

Entra policyWhat RS-Key needs
Attestation not enforced (the common case)Nothing extra: none / packed-surrogate / a custom format ≤ 32 chars is accepted. RS-Key works today.
Attestation enforcedA packed attestation chaining to a root extracted from the FIDO MDS, the model’s metadata uploaded to the FIDO MDS, and a FIDO2 certification (any level).

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 FIDO2 interop results for hardware runs.

Fleet tooling

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

CommandQuestion it answersGates
rsk inventory listwhat is this key?none — touch-free, PIN-free
rsk inventory verifyis this the key we enrolled?touch; --pin if set
rsk offboardwipe a returned key, keep prooftyped confirmation, up to 3 touches

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:

FieldMeaning
transportccid, hid, or ccid+hid (merged)
serialRP2350 OTP chip id (CCID only)
sdkRS-Key rsk-sdk framework version (major.minor) from the rescue SELECT
secure_boot{enabled, locked, bootkey}
flash{free, used, kv_total, files, chip} (bytes)
fw, bcd_devicefirmware version string, build counter (HID)
versions, client_pinFIDO CTAP versions, PIN-set flag
aaguidthe device AAGUID (hex)
backup{sealed, has_seed} — seed-export lifecycle
lock{locked, unlocked} — soft-lock state
org_attestation{installed, chain_unusable, chain_sha256} — chain_unusable is true for an installed key whose chain the device cannot read back whole, which list prints as chain UNUSABLE (repair); chain_sha256 comes only with a usable chain
errorpopulated if an applet threw mid-read

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:

SymptomStatusMeaning
device requires a PIN — pass --pin0x36a FIDO PIN is set; add --pin
refused — no OTP DEVK provisioned0x30blank board, no device key (production.md)
denied — no touch within 30 s0x27press the button when the LED blinks
attestation key MISMATCH—not the enrolled device (or a clone without the OTP DEVK)
SIGNATURE INVALID—the device could not prove identity at all

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

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

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

Offboarding

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

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

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

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

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

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

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

StepWhat it doesRecords on success
OTPwrites an all-zero config to slots 1–4 (the protocol’s “delete”)ok
OATHsends the OATH RESET commandok
PIVexhausts PIN + PUK retry counters with two distinct wrong values, then factory RESETok
OpenPGPrsk openpgp reset (TERMINATE + ACTIVATE)ok
FIDOCTAP authenticatorReset — replug, then touchok
org attestationclears the chain if one was installed — touchcleared / none
receiptsigns a checkpoint over the post-wipe journal — touchsigned

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": "<RFC 3339 timestamp>",
    "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.
  • A configuration lock code stays. Offboarding leaves the enabled-applications set and its lock as they were. Clear the code before the key leaves (ykman config set-lock-code -l <code> --clear), or the next holder cannot change which applications are on without it.

Configuration lock

ykman config set-lock-code works as on a YubiKey 5.8.0. Once a code is set, changing which applications are enabled needs it, on every transport:

ykman config set-lock-code --generate          # prints the code; keep it
ykman config usb --disable otp -L <code>       # later changes pass it
ykman config set-lock-code -l <code> --clear   # remove the lock

Setting a code on a key that has none takes a touch of the key (a YubiKey asks none), so a host cannot set one behind your back; set one at provisioning anyway, since a touch given to the wrong prompt could, and a code you do not hold keeps every later change behind a wipe. Changing a code needs the current one.

ykman info reports “Configured capabilities are protected by a lock code”. The key keeps only a salted hash of the code, and counts no wrong tries, as a YubiKey counts none: --generate gives a code nobody can guess, and a code a person made up can be. A factory reset from the trusted display or an rsk-wipe erase clears a lost code; a YubiKey has no such way back. The lock also shuts RS-Key’s own USB identity and LED records, which no code opens: rsk hw and rsk led are refused until it is cleared. The trusted display’s own settings stay open (protocol.md §6.2).

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.

bash scripts/build.sh --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.

AreaDefault buildfips-profile buildGate
FIDO algorithmsES256, EdDSA, ES384, ES512, ES256K, (ML-DSA-44/-65/-87)drops ES256K (secp256k1 — never NIST-approved) from both the advertised list and credential negotiationgetinfo.rs, makecredential.rs
FIDO minimum PIN46 (and setMinPINLength can only raise it, never lower it), plus trivially guessable PINs refused — a repeated period, a ±1 run, two or fewer distinct code points, or a denylisted keypad shape (the strong-pin policy)consts.rs, clientpin.rs, config.rs
Seed backupone-time export windowexport refused — non-exportable key material; restore (BACKUP_LOAD) still works, so keys may migrate into a profile device, never outvendor.rs
PIV management key3DES or AESno new 3DES keys (SP 800-131A); an existing 3DES key still authenticates so a reflashed device can migrate itself to AESpiv/lib.rs
PIV RSA1024 / 2048no RSA-1024 generation or importpiv/keygen.rs

Two things worth reading carefully:

  • ES256K leaves on both sides. getInfo’s algorithms list no longer carries -47, so a relying party never offers it. Even if a client asks for -47 anyway, makeCredential maps it to “unsupported” and declines. There is no path to a new secp256k1 FIDO credential.
  • RSA-1024 is blocked on two independent gates: the generation template parser (crates/rsk-piv/src/keygen.rs:48-51) and the separate import path (crates/rsk-piv/src/keygen.rs:610-612), 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, then give
ykman piv certificates generate --subject "CN=me" 9a pub.pem  # the new key its
                                              # own certificate (or import a CA's)
# 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:0xF1D2) 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.
  • 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

⚠️ OTP writes are permanent. A wrong boot key, image or lock can leave the board unable to boot or recover enrolled credentials. Keep the signing key and the recovery artifacts before enabling enforcement.

RS-Key always runs a combined TrustZone image. The Secure half owns OTP, storage and the applets. Enforced Secure Boot authenticates the combined image before either half runs. The OTP master key protects device-sealed records at rest. The rollback floor lets the ROM reject older signed images.

Before you start

  • Match the board, flash size and KV layout of the device you are updating. Use the production build with its partition table. Use disposable storage with diagnostic builds and builds with no-touch, FAKE_MKEK or FAKE_DEVK. See Build options.
  • Back up existing credentials before provisioning. A FIDO seed backup restores non-resident credentials. Plan separate recovery or re-enrolment for resident passkeys, OpenPGP, PIV, OATH and OTP slots.
  • Check rsk secure-boot status in BOOTSEL and rsk otp status in the running firmware before working on an existing board. Use the update path for a board that already enforces Secure Boot. Current firmware can finish a pending page-58 seal automatically at startup.
  • Disconnect other RP2350 boards before using the provisioning commands. The commands that explicitly write fuses offer --dry-run and ask for confirmation. Page-58 sealing and a ROM rollback advance happen during boot. See OTP fuses.

Every command on this page, in order

This order establishes which firmware the board trusts before it provisions the device secrets on page 58.

StepWhereAction
PrepareHostGenerate and back up the signing key. Build the combined ELF and rsk-wipe for this board. Seal both ELFs, convert them to UF2 and inspect the files.
Check the imageBOOTSEL, then running firmwareLoad the signed firmware and check that the application starts before changing the boot policy.
Stage ABOOTSELrsk secure-boot load-key writes the signing-key fingerprint and sets KEY_VALID. Reboot and check the signed image again.
Stage BBOOTSELrsk secure-boot harden sets both debug disables and configures glitch detection. Cold-boot and verify debug denial.
Stage CBOOTSEL, then normal flash bootrsk secure-boot enable sets SECURE_BOOT_ENABLE. Boot the signed firmware. With --rollback 1 on a fresh board, the ROM can also set floor 1 and ROLLBACK_REQUIRED on this boot. Verify enforcement.
Stage DBOOTSELrsk secure-boot lock revokes the other slots and makes the boot-policy and key pages read-only from BOOTSEL. Decide about rotation before this step.
Provision storageBOOTSEL, then running firmwarersk otp burn writes DEVK and MKEK. Secure startup migrates storage, scrubs flash and seals page 58. Check rsk otp status.
Change rollback policyHost, then deviceFor later activation or an increase, follow Stage 3. Prepare both signed images at the intended version before booting a higher one.

Stage 1 — Secure Boot

1a. Generate and back up the signing key

Generate a separate secp256k1 signing key for this board. The example paths are for one board. Keep another board’s files in a separate directory.

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

Back up the private PEM off the build machine and check that you can restore it before Stage C. The private key stays on the signing host. The board receives its public-key fingerprint. See Signing keys for storage, passphrases and rotation.

1b. Sign and check both images

Run these commands from the repository root in nix develop. The example uses the 4 MiB Waveshare RP2350-One.

BOARD=waveshare-one bash scripts/build.sh

The TrustZone builder links the Secure firmware and CMSE gateways, embeds the linked Non-secure image and adds the partition table to target/trustzone/combined.elf. Sign that finished ELF as a single image. For a Nix build use result/firmware.elf from nix build .#firmware or the ELF for the matching board or feature variant. For the Waveshare display board use BOARD=waveshare-touch-lcd bash scripts/build.sh --features display or the firmware-display package.

Seal the ELF before converting to UF2. With rollback metadata, the ELF sealing path marks the original unsigned image definition as ignored. Sealing a combined UF2 can leave the original block active. A signature reported as verified on the host is insufficient if the ROM rejects that block first.

The example chooses rollback version 1 on a fresh board. The first normal boot after enabling Secure Boot can then permanently commit floor 1 and require rollback metadata. To start with Secure Boot alone and leave a fresh board at floor 0, omit --rollback 1 from both signing commands below. --major and --minor are separate image version fields.

picotool seal --sign --hash target/trustzone/combined.elf -t elf firmware-signed.elf -t elf \
    ~/.rs-key-secrets/secure_boot_key.pem ~/.rs-key-secrets/otp_secureboot.json \
    --major 1 --minor 0 --rollback 1
picotool uf2 convert firmware-signed.elf -t elf firmware-signed.uf2
picotool info -a firmware-signed.uf2

Check hash: verified, signature: verified and the intended rollback version in the signed block. For a versioned combined image, check that metadata block 1 is ignored. The firmware partition should show NSBOOT(rw); the RS-Key Store partition should show S(rw) NSBOOT(-) NS(-). The signature covers both firmware halves, the gateways and the partition table. File inspection verifies the artifact against its embedded key. The board boot after Stage C tests whether its OTP trusts that key.

Build rsk-wipe for the same hardware and physical flash size, including any explicit FLASH_SIZE override. It is a separate SRAM program for erasing flash. Sign it with the same key and intended rollback version.

BOARD=waveshare-one cargo build --locked --release -p rsk-wipe
picotool seal --sign --hash target/thumbv8m.main-none-eabihf/release/rsk-wipe -t elf \
    rsk-wipe-signed.elf -t elf ~/.rs-key-secrets/secure_boot_key.pem \
    --major 1 --minor 0 --rollback 1
picotool uf2 convert rsk-wipe-signed.elf -t elf rsk-wipe-signed.uf2
picotool info -a rsk-wipe-signed.uf2

Check the signature, hash and intended rollback version. The wipe UF2 should report family rp2350-arm-s and a signed Arm Secure image definition in SRAM (0x2000_0000–0x2007_FFFF). Keep both signed UF2s. Launching the wipe image erases flash, so test it only on a board whose contents you can lose.

Enter BOOTSEL using the board button or rsk reboot bootsel from a running RS-Key. Load the signed firmware, then confirm that it enumerates and responds. At this point you are checking the image can run on this hardware. Stage C checks signature enforcement.

picotool load -v firmware-signed.uf2 && picotool reboot

Wait for RS-Key to enumerate, then run rsk status and check that the expected device responds over FIDO or CCID before moving on.

What otp_secureboot.json is for

picotool seal writes bootkey0, the SHA-256 fingerprint of the public key it embedded in the image, to this host-side file. It also emits provisioning flags. rsk secure-boot load-key takes the fingerprint, writes it to the selected slot and sets that slot’s KEY_VALID bit. It reads both back. The separate enable command sets enforcement. Use the JSON produced by the same seal as the firmware you just checked. You can regenerate the fingerprint by sealing with the same private key.

1c. Program the boot policy in stages

Run each block separately and check its result before continuing. Every rsk secure-boot command below runs in BOOTSEL. From the app, use rsk reboot bootsel and approve on the device, or hold the board’s BOOTSEL button while reconnecting it. Wait for BOOTSEL to enumerate. To preview a fuse write, run its command with --dry-run first.

A. Load the boot-key fingerprint

After the signed firmware has booted in Stage 1b, enter BOOTSEL.

rsk secure-boot load-key ~/.rs-key-secrets/otp_secureboot.json &&
    rsk secure-boot status

Slot 0 should show [0]KV. and SECURE_BOOT_ENABLE should still be False. Run picotool reboot, wait for USB and check that the signed firmware responds. Verify that your debug probe can access the board before you harden it.

B. Harden debug and enable glitch detection

Return to BOOTSEL for hardening.

rsk secure-boot harden && rsk secure-boot status

Check that DEBUG_DISABLE, SECURE_DEBUG_DISABLE and hardening copies complete are True, and GLITCH enable/sens is True / 3. Unplug and reconnect the board normally. Verify that the debug probe is denied and the firmware still runs. Return to BOOTSEL.

C. Enable Secure Boot and verify the first boot

Keep firmware-signed.uf2 and rsk-wipe-signed.uf2 ready. The checked signed firmware should already be in flash. Enable enforcement from BOOTSEL.

rsk secure-boot enable && rsk secure-boot status

Check SECURE_BOOT_ENABLE: True, then run picotool reboot. Wait for USB and run rsk status. Confirm that the expected applets work. On the first normal flash boot the ROM can also advance the rollback floor. Return to BOOTSEL and read the resulting fuse state.

rsk secure-boot status

With the version-1 recipe on a fresh board expect SECURE_BOOT_ENABLE and ROLLBACK_REQUIRED to be True and boot version 1/48. With the versionless recipe expect Secure Boot enabled, ROLLBACK_REQUIRED clear and boot version 0/48. Investigate a mismatch before writing more fuses.

On a disposable test board in BOOTSEL, use the unsigned UF2 from the same build and layout to check rejection. The example uses the local builder’s output path.

picotool load -v target/trustzone/combined.uf2 && picotool reboot

Confirm that the unsigned firmware fails to start after a successful transfer and reboot. Enter BOOTSEL with the board button if needed. Restore the signed image and verify that it starts.

picotool load -v firmware-signed.uf2 && picotool reboot

D. Lock the boot-key policy (optional)

To retain key rotation, leave a free slot and skip this step. For a fixed key, enter BOOTSEL after proving enforcement.

rsk secure-boot lock && rsk secure-boot status

The command requires one trusted slot and completed hardening. It revokes the other slots and makes pages 1 and 2 read-only from BOOTSEL. Secure writes remain available for later rollback advances. Check LOCKED, then run picotool reboot and verify another normal signed boot before Stage 2.

Stage 2 — OTP master key

Provision page 58 before enrolling new credentials. On an existing device, the first boot with the new MKEK migrates eligible records, including the FIDO seed, attestation key, persistent grant, and key-base-sealed PIV, OATH and OTP records. Secure startup waits for the required migration and a fresh flash scrub before it locks page 58. The scrub can delay USB enumeration and successful sealing requests a restart. Leave the device powered through that boot.

Enter BOOTSEL from the running signed firmware with rsk reboot bootsel and approve on the device. Wait for BOOTSEL to enumerate, then check that page 58 is ready for provisioning.

rsk otp burn --dry-run

If preflight succeeds, run the burn in BOOTSEL.

rsk otp burn

The command reboots the device. Wait for RS-Key to enumerate again, then read the result from the running app.

rsk otp status

The burn command generates DEVK (device attestation) and MKEK (storage sealing), programs the keys and chaff, verifies the rows and reboots. The fused keys stay on the chip. DEVK changes the rescue attestation public key. Re-record that identity if you use fleet verification.

rsk otp status reports whether sealing finished. If it reports pending migration, follow the listed actions and restart. A legacy FIDO seed wrapped by a PIN or a legacy OATH OTP PIN can delay the latch. Until the access lock takes effect, BOOTSEL can still read page 58. An already-fused device can finish sealing automatically on an upgrade. For an incomplete burn, a foreign lock or a torn latch, use the status and recovery cases in OTP fuses before attempting any further fuse writes. The normal path completes the latch during startup.

Existing PINs and recovery references

Present each configured reference so its verifier can migrate to the fused root. OpenPGP also rewraps the DEK copy associated with that reference. A successful migration of one reference leaves the others to be migrated separately.

  • FIDO PIN. Use a PIN operation such as rsk fido list-passkeys, or enter the PIN on the device display to unlock it.
  • PIV PIN and PUK. Perform a PIN VERIFY. To migrate the PUK, use ykman piv access change-puk or the panel’s Change PUK and supply the current PUK as both values.
  • OpenPGP. In gpg --card-edit, verify presents PW1. For PW3, use admin and passwd option 3 with the current Admin PIN as both values. If you set a resetting code, set it again with option 4.
  • Legacy OATH OTP PIN. Present it using the client that set it. The rewrite is best-effort. Recheck the migration status after restart.

Replug after these operations to let startup scrub superseded copies from flash. The page-58 latch closes the pre-OTP path for the device-sealed records it covers. Legacy PIN verifier and OpenPGP DEK compatibility have their own limits. See Seals and PINs.

Stage 3 — anti-rollback (optional)

On a secured board the ROM compares an image’s signed rollback version with the board’s OTP floor even when ROLLBACK_REQUIRED is clear. The flag closes the path for versionless images. On normal Secure Boot from flash, the ROM sets it when it advances the floor. With the version-1 recipe in Stage 1, this typically already happened at the first boot after enable. See the RP2350 datasheet, §5.1.11.

Turning it on or raising the floor

Read the current floor and flag in BOOTSEL.

rsk secure-boot status

For floor 0, choose a positive version to start. To block a vulnerable build, choose a version strictly above all affected images still eligible under the board’s trusted keys. Prepare and inspect both signed images at that version using the ELF workflow. In BOOTSEL load the firmware and boot normally. This boot can spend OTP bits.

picotool load -v firmware-signed.uf2 && picotool reboot

Confirm the app starts, then return to BOOTSEL and run rsk secure-boot status again. If the floor differs from the intended version, stop and investigate the image and boot path. If the floor is correct and ROLLBACK_REQUIRED is already set, the policy is active.

If the floor is correct and the flag is still clear, verify that both image files carry the intended rollback version. Use picotool reboot from BOOTSEL and wait for the app. Preview the explicit fuse write.

rsk otp rollback-require --dry-run

If it reports the expected floor with the flag still clear, run the write and confirm on the device.

rsk otp rollback-require

Read back the flag with rsk status or return to BOOTSEL and run rsk secure-boot status. On a test board, check that trusted signed images without a rollback version or below the floor are refused. Restore the known-good image and check that it boots.

After it’s on

Reuse the floor for routine updates. Raising it from 3 to 5 spends two logical bits and excludes signed versioned images below 5. The two standard OTP words hold 48 logical bits, which is the denominator in rsk secure-boot status. 47 is the highest version supported by the pinned picotool with those two words. Version 48 requires a third row. Updates at 47 can still use 47. To exclude vulnerable images also signed at 47, use key rotation or a replacement board as applicable. See Anti-rollback for version selection.

Updating a provisioned board

Use the existing trusted key and preserve the device’s flash geometry and KV layout. Follow the combined ELF sealing sequence in Stage 1b, using the current positive floor for both firmware and the recovery utility. For an intentionally versionless setup, check that the floor is zero and ROLLBACK_REQUIRED is clear, then omit the rollback argument.

picotool load -v firmware-signed.uf2 && picotool reboot

This assumes the board is in BOOTSEL. After reboot, confirm the expected USB identity, applets and access to existing credentials. nix run .#flash signs and flashes in one step. It uses the configured signing key and stamps RSK_ROLLBACK, which defaults to 1. Set it explicitly for the target board or use the manual flow above.

Recovery and failure cases

SituationAction
The new firmware fails to startEnter BOOTSEL with the board button. Load a signed combined UF2 with the correct layout, a trusted key and a rollback version allowed by the board.
The only trusted signing key is lostKeep the accepted signed artifacts. Creating new images requires that private key, or an available rotation path on a board provisioned for it. See Signing keys.
The rollback floor advanced unexpectedlyRead the new floor in BOOTSEL and prepare both signed images at it. OTP keeps the higher floor.
The signed wipe image fails to startCheck its SRAM layout, board geometry, trusted signing key and rollback version against Stage 1b.
BOOTSEL refuses a read of page 58This is expected after the page is sealed. Read rsk otp status from the running firmware for the sealing result.
BOOTSEL denies access to the KV partitionThis is the partition table protecting the store. Use the running applets for data management. Use rsk-wipe only when you intend to erase all flash.
Replacing the boardProvision a fresh signing key and restore each credential type through its recovery path. See Moving to a new board.

⚠️ To erase all flash, enter BOOTSEL and run picotool load -v -x rsk-wipe-signed.uf2. The -x selects the downloaded SRAM image for execution. Reinstall the eligible signed firmware through BOOTSEL after the wipe. The signing fuses, page-58 keys and rollback floor survive the erase.

Residual risks

The production policy leaves USB BOOTSEL available for recovery. Its flash transfers are separate from the ROM’s boot checks. A trusted old image that lacks the partition fence can expose the KV store over BOOTSEL again, so account for such artifacts in your rollback policy. See Flash snapshot rollback.

The firmware executes from QSPI flash. Secure Boot verifies it before execution, leaving a window for lab hardware that can substitute flash contents between check and use. RP2350 encrypted boot uses RAM-loaded images. See the RP2350 datasheet, §10.1 and the threat model.

Completing older debug hardening

rsk secure-boot status shows both effective debug-disable flags and whether all eight hardening copies are complete. If page 1 remains BOOTSEL-writable, rsk secure-boot harden can fill in missing bits and preserves the bits already set. Stop if readback fails. If page 1 is already bootloader-read-only and hardening is incomplete, the CLI cannot finish the write through BOOTSEL. Verify debug denial after a cold power cycle before accepting a production device.

Signing keys (secure boot)

A production board trusts the signing-key fingerprints in its OTP. Keep a backup of the corresponding private key and a signed recovery image before enabling Secure Boot. The full fuse sequence is in Production.

The keys on an RS-Key, and which one this is

KeyWhere it livesPurpose
Secure Boot signing keyPrivate PEM on the signing host. Public-key fingerprint in OTP page 2.Authorizes firmware and recovery images
MKEK and DEVKGenerated by the host provisioning tool and written to OTP page 58Storage sealing and device attestation. See OTP master key.
Applet secretsDevice storageFIDO, PIV, OpenPGP and other credentials. See Seals and PINs.

Architecture — the trust chain

The host signs the final combined TrustZone ELF, including the partition table, and converts the signed ELF to UF2. The image carries the public key and its ECDSA signature. With Secure Boot enabled, the RP2350 boot ROM checks that the SHA-256 fingerprint of that public key matches a trusted slot, verifies the signature and applies the rollback policy before starting Secure firmware. The board stores the fingerprint, so recovering it cannot recover the private PEM. See the Production signing chain and the RP2350 datasheet, §10.1.1.

1. Generate (one fresh key per board, off-repo, ideally offline)

Generate a secp256k1 key for a new board. Keep a separate directory for each board and keep private keys outside the repository and the build sandbox. Use the existing key for a provisioned board.

The standard Production recipe uses an unencrypted PEM. This example protects the new file with umask 077 and refuses to overwrite an existing private PEM.

mkdir -p ~/.rs-key-secrets
cd ~/.rs-key-secrets
openssl ecparam -genkey -name secp256k1 -noout > secure_boot_key.pem
openssl ec -in secure_boot_key.pem -pubout -out secure_boot_pub.pem

Optional PEM passphrase

To store the private key in an encrypted PEM, use this block in place of the one above. OpenSSL asks for the passphrase when creating the PEM and again when extracting the public key. Use a long, unique passphrase.

mkdir -p ~/.rs-key-secrets
cd ~/.rs-key-secrets
openssl ecparam -genkey -name secp256k1 -noout |
    openssl pkcs8 -topk8 -v2 aes-256-cbc -iter 600000 > secure_boot_key.pem
openssl ec -in secure_boot_key.pem -pubout -out secure_boot_pub.pem

Adding a passphrase to an existing key changes its file encoding. Keep the same private key and compare the public keys from the old and new PEMs before replacing your working copy.

2. Back it up — before you fuse anything

Keep durable backups of the private PEM on separate media. Use encrypted storage for an unencrypted PEM. If the PEM is passphrase-protected, keep the passphrase separately. Before provisioning, restore a copy and verify that you can open it and derive the expected public key.

Keep the inspected firmware-signed.uf2 and rsk-wipe-signed.uf2 as well. They must match the board, a trusted signing key and its current rollback policy. otp_secureboot.json carries the public-key fingerprint and can be regenerated by sealing with the same private key.

3. Provision — fuse the fingerprint (slot 0)

Build and seal the final combined ELF and the separate rsk-wipe ELF. Convert both signed ELFs to UF2, inspect both files and prove the signed firmware boots before writing any Secure Boot fuses. This is Production Stage 1b. Use the otp_secureboot.json produced by the same seal as that firmware.

Enter BOOTSEL after the test boot. Stage A writes the fingerprint into slot 0 and sets its KEY_VALID bit.

rsk secure-boot load-key ~/.rs-key-secrets/otp_secureboot.json &&
    rsk secure-boot status

Check that slot 0 shows [0]KV. and SECURE_BOOT_ENABLE is still False. Reboot and verify the signed firmware. Continue with harden, a cold power cycle and debug denial check, then enable and the first enforced boot. After proving enforcement, run lock for a fixed key or skip it to retain rotation. Provision page 58 after this sequence. The commands and readback checkpoints are in Production Stage 1c.

With the version-1 recipe on a fresh board, the first normal flash boot after enable can set floor 1 and ROLLBACK_REQUIRED. Prepare both signed images at the intended version before enable. To defer anti-rollback, the Production recipe omits the rollback argument from both seals.

4. Daily use — sign every flash

Read the board’s policy with rsk secure-boot status in BOOTSEL. For a routine update use the current floor for both firmware and rsk-wipe. For an intentionally versionless setup, verify that the floor is zero and ROLLBACK_REQUIRED is clear, then omit the rollback argument. The highest version with the default OTP rows is 47. See Anti-rollback.

For an unencrypted PEM, use the two picotool seal commands in Production Stage 1b with the correct rollback argument. The nix run .#flash helper also takes an unencrypted PEM directly. It defaults to RSK_ROLLBACK=1, so set the value for the target board if using that helper.

Sign with a passphrase-protected PEM

Build both ELFs first, using the board and flash layout in the Production recipe. The pinned picotool requires an unencrypted PEM, so OpenSSL opens the key in a private temporary directory for the two seals. Set TMPDIR to a RAM-backed directory such as /dev/shm on Linux, or use an encrypted volume for temporary storage. The block removes the temporary PEM when it exits. The example assumes floor 1. Replace the rollback argument in both commands to match the board’s policy.

sign_dir=$(mktemp -d "${TMPDIR:-/tmp}/rs-key-sign.XXXXXXXX")
trap 'rm -f "$sign_dir/key.pem"; rmdir "$sign_dir"' EXIT
trap 'exit 1' HUP INT TERM
openssl ec -in ~/.rs-key-secrets/secure_boot_key.pem -out "$sign_dir/key.pem"

picotool seal --sign --hash target/trustzone/combined.elf -t elf firmware-signed.elf -t elf \
    "$sign_dir/key.pem" ~/.rs-key-secrets/otp_secureboot.json \
    --major 1 --minor 0 --rollback 1
picotool seal --sign --hash target/thumbv8m.main-none-eabihf/release/rsk-wipe -t elf \
    rsk-wipe-signed.elf -t elf "$sign_dir/key.pem" \
    --major 1 --minor 0 --rollback 1

Once both seals succeed, continue with picotool uf2 convert and picotool info -a for each signed ELF as in Production. Inspect the signature, hash and rollback metadata, then load the checked firmware UF2 in BOOTSEL.

picotool load -v firmware-signed.uf2 && picotool reboot

After USB reconnects, verify the expected firmware and applets. Keep the matching signed wipe UF2 for recovery.

Key slots and validity

Page 2 has four one-time fingerprint slots. A trusted slot has its KEY_VALID bit set and its KEY_INVALID bit clear. Revocation sets KEY_INVALID permanently. A free slot is blank with both bits clear.

Full rsk secure-boot lock requires exactly one trusted slot and completed hardening. It revokes all other slots and makes pages 1 and 2 read-only from BOOTSEL. To retain rotation, leave a free slot and keep both pages BOOTSEL-writable by skipping the full lock. See Production Stage D.

5. Rotate a key

Rotation requires a free slot and BOOTSEL write access to both key-policy pages. Use it to retire a compromised signing key or to exclude vulnerable images when the rollback floor cannot be raised further. With one initial key, at most three replacements fit. This example replaces slot 0 with slot 1. Check the actual slots in rsk secure-boot status first.

  1. Generate and back up the replacement PEM in a separate directory such as ~/.rs-key-secrets/next. Using the Production ELF workflow, sign both firmware and rsk-wipe with that key at the board’s current policy. Name the new outputs firmware-next-signed.elf / .uf2 and rsk-wipe-next-signed.elf / .uf2 so the previous artifacts stay available. Write the firmware seal’s JSON to ~/.rs-key-secrets/next/otp_secureboot.json.

  2. Enter BOOTSEL and preview provisioning into the free slot.

    rsk secure-boot rotate ~/.rs-key-secrets/next/otp_secureboot.json --slot 1 --dry-run
    

    If the slot and fingerprint are correct, provision it and read back the state. rotate performs the same slot write as load-key --slot 1. Both keys are trusted at this point.

    rsk secure-boot rotate ~/.rs-key-secrets/next/otp_secureboot.json --slot 1 &&
        rsk secure-boot status
    
  3. In BOOTSEL load the firmware UF2 signed with the replacement key. Verify that it boots and that the expected applets respond. Keep the inspected wipe image signed with the replacement key.

    picotool load -v firmware-next-signed.uf2 && picotool reboot
    
  4. Return to BOOTSEL only after proving that boot. Revoke the old slot and verify the readback. revoke refuses to remove the last trusted slot.

    rsk secure-boot revoke 0 && rsk secure-boot status
    

    Check that slot 0 is revoked and slot 1 is still trusted. Reboot and verify that the replacement firmware starts. Images signed only by the old key now fail Secure Boot.

Loss and recovery — the cases

SituationWhat to do
Lost the PEM before load-keyGenerate a new key and prepare new signed firmware, wipe and OTP JSON.
Lost the PEM after load-key, before enableWith pages 1 and 2 still writable, provision a replacement in a free slot, verify the matching firmware and recovery files, and revoke the lost key’s slot before enabling enforcement. Follow the remaining Production checks.
Lost the PEM after enableRestore the backup, use another trusted key you still have, or rotate into a free slot while pages 1 and 2 remain writable. With every trusted private key lost and rotation unavailable, only existing eligible signed files remain usable. Use a new board for future builds.
Lost the passphrase to an encrypted PEMRecover the passphrase or an accessible copy of the same key. Otherwise follow the lost-key case for the board’s current state.
Key compromisedRotate and revoke the compromised slot, or replace the board if rotation is unavailable. The board trusts signatures from that slot until revocation.
Replacing the boardGenerate a fresh signing key for the replacement. A seed backup restores non-resident FIDO credentials. See Moving to a new board for migration scope.

OTP fuses (RP2350)

RS-Key uses the RP2350’s one-time-programmable (OTP) memory for its device keys, Secure Boot policy and rollback floor. These are chip fuses. One-time passwords are covered in the OTP slot guide. For provisioning commands and their order, see Production.

What OTP is

An OTP bit can be programmed from 0 to 1. It stays set through power loss, reflashing and factory reset. Each chip has its own fuse state.

⚠️ Fuse writes are permanent. A wrong lock can make the keys unreadable, and a wrong boot policy can leave the board unable to load firmware. The provisioning CLI provides typed confirmations and --dry-run for host-initiated writes. A normal boot can also program fuses automatically during page-58 sealing or a rollback-floor advance.

Layout: pages, rows, and reliability copies

The RP2350 has 64 OTP pages of 64 rows. Each raw row is 24 bits wide. Page 58 starts at 58 × 0x40 = 0xE80. Access locks apply to whole pages.

EncodingHow to read itUsed here
RBIT-3Bitwise majority across three consecutive rowsBOOT_FLAGS0/1, rollback floor
RBIT-8A bit takes effect once three of its eight copies are setCRIT1. The harden command verifies its hardening bits in all eight copies.
ECCEach raw row has 16 data bits, six ECC bits and two polarity bitsBoot-key fingerprints, DEVK and MKEK
Page-lock wordBitwise majority across three copies of the policy byte within one raw rowPAGEn_LOCK1

See the RP2350 datasheet, §§13.4–13.6 for the register layout and encodings.

Who can write OTP, and when

  • The host through BOOTSEL. The ROM’s USB bootloader serves the picotool OTP commands subject to the page permissions. RS-Key uses this path for the initial device keys and Secure Boot provisioning.
  • Secure startup and the rescue applet. Startup seals page 58 once the keys and the migrated storage are ready, including on boards with Secure Boot disabled. The explicit rsk otp rollback-require command asks the Secure rescue applet to set ROLLBACK_REQUIRED. A write requires Secure Boot to be enabled and confirmation on the device.
  • The boot ROM during normal Secure Boot. A successful flash boot at a higher rollback version advances the OTP floor and sets ROLLBACK_REQUIRED. See Anti-rollback.

In a LOCK1 policy byte, LOCK_S is bits 1:0, LOCK_NS is bits 3:2, and LOCK_BL is bits 5:4. They represent Secure, Non-secure and bootloader access. Each lock can progress from read-write to read-only to inaccessible. LOCK_BL governs the bootloader path. It is separate from the hardware’s Secure and Non-secure access checks.

What RS-Key burns

RegionRowsContentsWriter
Boot policy, page 10x040–0x047CRIT1: Secure Boot enable, both debug disables, glitch detector enable and sensitivityrsk secure-boot harden and enable
Boot policy, page 10x048–0x04ABOOT_FLAGS0: ROLLBACK_REQUIRED at bit 11Boot ROM, or rsk otp rollback-require through Secure firmware
Boot policy, page 10x04B–0x04DBOOT_FLAGS1: KEY_VALID and KEY_INVALID slot masksrsk secure-boot load-key, rotate, revoke, lock
Rollback floor, page 10x04E–0x050, 0x051–0x053DEFAULT_BOOT_VERSION0/1: 48 logical bits across two triplicated wordsBoot ROM
Boot keys, page 20x080–0x0BFFour ECC-encoded SHA-256 fingerprints, 16 rows per slot. Starts: 0x080, 0x090, 0x0A0, 0x0B0.rsk secure-boot load-key and rotate
Device keys, page 580xE80–0xEBFDEVK, MKEK and their paired chaffrsk otp burn
Page-lock words0xF83, 0xF85Page 1 and 2 LOCK1, 0x141414rsk secure-boot lock
Page-lock word0xFF5PAGE58_LOCK1, completed value 0x3D3D3DSecure startup

After rsk secure-boot lock, the page 1 and 2 policy is read-only for BOOTSEL and Non-secure and read-write for Secure. BOOTSEL can still read the boot policy and public-key fingerprints. The Secure side can still program rollback state. Although PAGE58_LOCK1 is physically stored in page 63, it controls page 58. The A2 ROM checks the containing page’s permissions when accessing lock words (erratum RP2350-E15). Later ROMs check the page the word protects. RS-Key programs the page-58 lock from Secure firmware.

Page 58 from provisioning to sealing

  1. In BOOTSEL, rsk otp burn checks that both keys, their chaff and both page-58 lock rows are blank. It generates a device attestation key (DEVK) and a master key for sealing (MKEK), programs them, and reads back the keys and chaff before restarting. It keeps no backup copy. Provisioning uses temporary key files for picotool, preferring RAM-backed storage when available and overwriting the files before unlinking them.
  2. At startup, Secure firmware validates the OTP key material before migrating storage. Before entering Non-secure it sets the page’s SW_LOCK to deny Non-secure access and configures ACCESSCTRL to exclude Non-secure access to the OTP peripheral. This is runtime protection even while the permanent lock is pending. BOOTSEL can still read the key rows until the separate LOCK_BL takes effect.
  3. Once the remaining pre-OTP records have migrated and a fresh flash scrub succeeds, Secure startup completes and verifies all copies of the 0x3C3C3C access lock. That closes BOOTSEL and Non-secure access while Secure access remains read-write.
  4. Startup then sets 0x3D3D3D, making the page Secure read-only. This is also the migration latch. Once it takes effect, the firmware requests a reboot before serving USB. On subsequent boots, it closes the pre-OTP paths for device-sealed records. Secure firmware continues to read the keys when needed.

An older board with 0x3C3C3C still needs the latch. Some legacy records need a successful PIN use followed by a restart to complete migration. Check rsk otp status for what is pending. The lock-page58 command is a legacy service path. Current firmware normally seals during startup.

An interrupted latch can leave access protected by a majority with a third copy missing. rsk otp status reports incomplete redundancy because the ROM refuses further programming once Secure becomes read-only. If Secure writes closed before the required access lock was in place, the firmware refuses migration and reports recovery required.

Anti-imaging chaff

Page-58 contentsKey rowsPaired chaff rows
DEVK0xE80–0xE8F0xEA0–0xEAF
MKEK0xE90–0xE9F0xEB0–0xEBF

rsk otp burn reads each programmed key row in raw mode and stores the complement of all 24 bits at offset 0x20, including the ECC and polarity bits. Secure startup checks the complements while provisioning is unfinished. Normal key reads use the ECC data in the low half.

IOActive’s passive-voltage-contrast experiment can recover the OR of each physically paired bit. A bit and its complement always produce 1 in that readout, regardless of the key. An invasive technique that separates the two halves could recover the key bits. See the IOActive report and the Raspberry Pi security white paper.

Reading OTP

rsk otp status                # running firmware over CCID: page-58 sealing and migration
rsk secure-boot status        # BOOTSEL: boot flags, key slots and rollback floor
picotool otp get -r -n 0x48    # BOOTSEL: first raw copy of BOOT_FLAGS0

After sealing, BOOTSEL should refuse reads of the page-58 key rows. That checks the bootloader policy. A direct privileged Non-secure load from the OTP data window tests the runtime boundary separately. See TrustZone on hardware for the scope of those checks.

Honest limits

  • Page 58 remains Secure-readable. Ledger Donjon restored Secure debug on a decapped A4 and read the challenge secret from page 48. The same access policy makes RS-Key’s page-58 keys reachable if Secure debug is restored. Chaff protects the paired OR readout, while a logical Secure read addresses each key row individually. See the Donjon experiment and Threat model.
  • OTP state is finite and per-chip. The two default rollback words hold 48 logical bits. With those rows, the highest version accepted by the project’s picotool seal is 47. There are four one-time boot-key slots. See Anti-rollback.

Anti-rollback

Secure Boot checks that the firmware was signed by a key the board trusts. An older signed image can pass that check even if it contains a bug you have since fixed. The RP2350 boot ROM can reject that image by requiring a minimum rollback version.

This page covers firmware images. Restoring an old copy of the data flash is a separate problem. See Flash snapshot rollback.

Axis 1 — version (the rollback floor)

Three numbers appear in a release or a signed image:

NumberWhere it livesWhat it means
Release versionGit tag and release notesIdentifies the RS-Key source release
Image versionpicotool seal --major … --minor …Helps the boot ROM choose between candidate images
Rollback versionpicotool seal --rollback NCompared with the board’s minimum accepted version, called the floor

The signature covers both the rollback version and the list of OTP rows that hold its floor. RS-Key uses the two default rows. Each chip has its own floor, which starts at zero on a blank chip.

How it works in hardware

On a board enforcing Secure Boot, the boot ROM rejects an image whose rollback version is below the floor. An image at the floor passes the version check and leaves the floor unchanged. On a normal flash boot of a valid RS-Key image above the floor, the boot ROM advances the floor to the image’s version. The image still has to pass the other boot checks, including signature verification.

ROLLBACK_REQUIRED closes the versionless path. While it is clear, an image without a rollback version can still pass Secure Boot. A versioned image is checked against the floor even with the flag clear. The ROM sets the flag automatically when it advances the floor on a normal Secure Boot from flash. The first boot with --rollback 1 can therefore spend one bit and make a rollback version mandatory in the same operation. See the Raspberry Pi RP2350 datasheet, §5.1.11.

⚠️ Both the floor and the flag are irreversible. Before enabling Secure Boot with a versioned image, or flashing a version above the current floor on a secured board, prepare both a signed firmware image and a signed rsk-wipe recovery image at the intended floor. A factory reset leaves OTP intact. See Production and OTP fuses.

rsk otp rollback-require is the explicit way to set the flag from running firmware if it is still clear. It requires Secure Boot and confirmation on the device. It sets the flag without advancing the floor. Check that the running firmware and your recovery image carry a rollback version before using it. That check is the operator’s responsibility.

The limit with the default OTP rows

The two default rows hold 48 logical thermometer bits, stored with redundant copies. Advancing from floor 3 to 5 uses two logical bits. Routine updates can reuse the same rollback version without spending bits.

47 is the highest rollback version picotool seal accepts with the two default rows. The tool requires one spare bit after the version, so --rollback 48 requires a third row. RS-Key provisioning and status use the default layout. See the picotool seal implementation.

Choosing when to raise the floor

Choose a rollback version higher than every vulnerable image that can still boot under the board’s trusted keys. Include any such image you signed at a higher version but never installed. For example, if the floor is 2 and all affected signed images carry version 2 or lower, use --rollback 3. If an affected signed image carries version 3, raising the floor to 3 leaves it eligible.

After provisioning a positive floor, reuse it for routine updates. Sign the final combined TrustZone ELF with the key the board trusts, then convert the signed ELF to UF2. The nix run .#flash helper stamps RSK_ROLLBACK, which defaults to 1. Set it explicitly to match the board’s floor or the new version you intend to install.

The marker a tool can read

RS-Key release notes can flag a fix for a downgrade-exploitable bug. The release workflow copies the marker from that version’s changelog section into the raw GitHub release body, preserving it even if the notes are shortened. The marker is a single HTML comment, with optional JSON metadata containing a reason string.

<!-- @increase-anti-rollback-epoch -->
<!-- @increase-anti-rollback-epoch{"reason": "CVE-1234 was fixed"} -->

A release body without the marker carries no request to raise the floor. The marker supplies no version number. A flasher can show it to the owner, who chooses the version to sign and install on each board.

Axis 2 — key (the signature)

Secure Boot matches the public key in the image to an OTP fingerprint in a valid, unrevoked slot, then checks the image signature. Revoking a key with KEY_INVALID makes images signed only by that key ineligible, even if they meet the version floor. Revocation works at any floor.

Key rotation

On a board provisioned for rotation, rsk secure-boot rotate loads a replacement fingerprint into a free slot. Prove that the fixed firmware boots with the replacement key at the required version and re-sign rsk-wipe. Then revoke the old slot. Until revocation, both keys are trusted. See Rotate a key.

Decide at provisioning

The RP2350 has four one-time boot-key slots. With one initial key, at most three replacements fit. Full rsk secure-boot lock permanently revokes every slot except the one in use and makes OTP pages 1 and 2 read-only from BOOTSEL. Rotation through the host tools requires skipping that full lock and leaving a free slot. This leaves the key provisioning path writable from BOOTSEL. See Production hardening.

When the rollback floor reaches 47

Updates at version 47 still work with a trusted signing key. Older images at version 47 signed by that same key also remain eligible. If one of those images must be blocked, revoke its key after a proven rotation, or move to a board that trusts a fresh key.

Moving to a new board

A blank chip starts at floor zero. Provision it to trust only a new signing key and sign the current fixed firmware with that key. The old images fail Secure Boot because the new board does not trust their signing key. If you reuse the old key, the new chip’s lower floor can make old vulnerable images eligible again.

A seed backup restores deterministic, non-resident FIDO credentials. Resident passkeys, OpenPGP and PIV keys, OATH accounts, and OTP slots need separate recovery or re-enrollment.

How to verify all of this

Inspect the file and the board separately.

picotool info -a firmware-signed.uf2    # file: signature verification and rollback version
rsk secure-boot status                 # BOOTSEL: secure boot, key slots, flag and floor
rsk otp rollback-require --dry-run     # running firmware over CCID: flag and floor

File verification checks the signature against the public key in the file. Booting the image on the target board verifies that the board trusts that key and accepts the version. On a test board, isolate each refusal case:

Test imageExpected boot result
Trusted signature at the current floorBoots without advancing the floor
Same trusted key, rollback version below the floorRejected by the version check
Same trusted key, versionless, with ROLLBACK_REQUIRED setRejected because the version is missing
Untrusted or revoked signing key at the current floorRejected by Secure Boot

To test an advance, first prepare the signed firmware and recovery images at the new floor. Boot the newer image and read back the floor and flag. Try a previously bootable image sealed below the new floor, then restore the current image through BOOTSEL. Seeing a UF2 transfer succeed only proves the transfer. The test is whether the firmware actually starts.

Threat model

Assume the USB host is hostile and the Non-secure firmware can execute arbitrary privileged code. Secure code, the boot ROM and the chip’s access controls enforce the boundary. OTP provisioning and enforced Secure Boot address separate threats from physical access to the board.

The Secure USB driver owns the controller, handles endpoint operations and observes hardware resets and configuration loss. It processes USB control traffic from the host. Non-secure code handles USB classes and reassembles commands. Checked gateways copy those commands into Secure memory, where the worker and applets apply their own parsers and authorization rules. Non-secure code can forge transport state, drop traffic and observe plaintext carried through it. See Architecture and Testing.

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.

Attacker capabilities

1. A hostile host (malware on the computer)

USB setup requests, CTAPHID frames, CCID messages, ISO-7816 APDUs and CTAP2 CBOR all originate with the host. A compromised Non-secure image can also submit commands directly at the gateways.

  • Memory safety. The applet parsers and dispatch use safe Rust. The trusted code also includes low-level unsafe Rust and C, including the CMSE veneers and RSA arithmetic. See the unsafe audit.
  • Fuzzing. Targets exercise parsers, applet dispatch and stateful command sequences. Coverage varies by path and profile. See Testing.
  • 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.
  • A flash write can be interrupted, and a host picks which one is in flight. The device is bus-powered with no reserve, so the supply belongs to whoever holds the cable or the hub port, and because the host drives every operation it chooses which write a cut lands in. It needs no attacker — a knocked cable does the same thing — but it is cheap to aim, so treat it as aimed. There is no transaction underneath: one applet operation is several Fs writes, and a cut lands between any two of them. What the device owes across a cut is that nothing comes back weaker: an interrupted write left the old value or the new one, never a third; a record committed before the cut still reads back after it; a delete the cut caught halfway leaves behind no metadata describing the value it removed; and no gate comes up softer on the next boot than it went down — a torn authenticatorReset may not drop the PIN or alwaysUv record while leaving a credential usable. Write ORDER is what buys that, chosen per operation and stated where the code does it: Fs::delete drops the metadata before the value, registration writes the EF_RP entry before the credential, a reset deletes the seed before anything derived from it. Underneath the order sits a silicon assumption that a torn NOR write leaves the old bytes or detectably bad ones. PLAT-FLASH-001 remains pending a real supply-cut test on hardware. See Platform assumptions. Scope: the interrupted write. A flash read that comes back an error is a different condition and has its own clause below. Not that a cut cannot produce one: a half-programmed item header is deterministic and reads back as an error, and what keeps a store walk honest is that it skips that error on purpose rather than never meeting it.
  • A flash read can come back an error, and this firmware spells “not configured” as an absence. The backend answers a probe with the value, with no such key, or with a failure — and its own API folds the last two together: Storage::read and Storage::size return None for either, which is why a second call, last_error, exists to tell them apart. The fold is what makes this a security condition rather than a reliability one, because absence is how the tree spells no PIN set, no gate configured and not provisioned yet: a probe that merely failed then reads as a decision the owner never made. Measured, before it was fixed: one refused EF_PIN probe on an unauthenticated PIV SELECT re-seeded the factory PIN over the owner’s, after which VERIFY 123456 answered 9000 — and the same fault aimed at the management-key slot re-minted the default management key. What the device owes is that a refusal is never laundered into an answer, and three rules carry it. Two are owned by one function each and cited from the store’s refinement: a failed probe is never memoised as a decided absence, so one transient fault cannot become a permanent “file absent” for the rest of the boot; and an enumeration the medium truncated leaves the keys it never reached undecided, so a walk that stopped early cannot report them gone. The third is a per-site discipline and not a mechanical property, which is worth saying plainly: a probe whose absent arm would overwrite configured material or open a gate is answered fallibly — either propagating the failure, or resolving it to the restrictive arm where that is the safe answer — rather than collapsing it into an absence. Which class a site belongs in is decided by asking what becomes reachable if the probe answers absent where the truth is present, and it is held by a test at the site; no gate can check it, and the tree carries far more collapsing probes than fallible ones because most absences cost only a status field or a repeated repair. Scope: the read the medium refused, whoever caused it. How much of a lever a host has here is deliberately not claimed. A cut it aims leaves a half-programmed item header that reads back Error::Corrupted, and the store walk skips that one on purpose, so it truncates nothing; an interrupted page erase leaves a marker pair the backend also reports as Corrupted, and that one does reach a per-key probe in the source. Whether any of it is reachable on a board is unmeasured. The three rules hold either way, because none of them asks who caused the refusal.
  • You must be able to see and revoke every credential the device holds. Resident credentials live in EF_CRED, and the two surfaces that let you BROWSE them — enumerateRPs and the trusted-display Passkeys view — reach them through EF_RP. So a credential whose EF_RP entry is missing is one getAssertion signs with happily and neither surface will show you. enumerateCredentials and deleteCredential scan EF_CRED directly, on an rpIdHash the host supplies, so a caller who already knows the rp can still reach it: what a strand costs is DISCOVERY, and revocation only so far as revoking a thing means finding it first. It does not heal on its own either — a later registration of the same (rp, user) dedups onto the record already there instead of writing the missing entry (audit run-35). Registration and credential-management delete are therefore ordered to fail the harmless way round: the EF_RP entry is written before the credential, and the credential goes before the count that names it. The resets are not, and this page will not pretend otherwise. There the seed leads and the rest is swept in ring order, which reaches EF_RP before EF_CRED — a torn wipe can still strand a credential whose seed has already been removed. A power cut can also leave an EF_RP entry after its last credential is gone. On a successful credential scan, boot reconciles existing RP records, correcting counts and removing empty entries. It leaves a missing RP record missing.
  • A key must not outlive the algorithm attribute it was made under. An OpenPGP slot’s algorithm attribute is one PUT DATA away for anyone holding PW3, and the card reads that record again at the moment of every private-key operation: PSO:CDS, the asymmetric arm of PSO:DECIPHER and INTERNAL AUTHENTICATE take one byte of it to decide whether the slot is RSA or EC before they touch the key. The symmetric arms read no attribute at all: a PSO:DECIPHER body opening 0x02 and every PSO:ENCIPHER route to EF_AES_KEY and have returned before that read, so nothing below is about them. Only that byte — the curve and the modulus size come from the stored blob itself — so what an attribute change under a surviving key does depends on which way it goes. Across the families it is caught by accident: the old blob does not parse as the new algorithm and the operation fails. Within a family nothing catches it, and that is the case worth stating. Swap Ed25519 for P-256, or RSA-2048 for RSA-4096, and the card goes on signing and deciphering with the old key while GET DATA publishes the new parameters over it — a slot whose published description no longer describes the secret behind it. So what the device owes here is a deletion and not a validation: a PUT DATA of C1/C2/C3 that resolves to an attribute different from the one the slot already holds drops that slot’s private key and the stored public key it would go on serving first — whenever the store reports the slot present — and only then writes the new value. A key the present cache reads absent while the backend still holds it is not dropped, and the attribute goes in over it. Every probe on that path is fallible on purpose: an unreadable attribute, an unreadable key slot, or a drop the store refused each answer 6581 without writing the attribute, rather than skipping an invalidation the card could not prove unnecessary. And the internal EF the attribute lives in is not addressable — PUT DATA answers 6B00 to it even under PW3 — so the C1/C2/C3 tags are the only door. Scope: the attribute write. A write that resolves to the attribute already in force is not a change and keeps the key, and an absent attribute reads as the RSA-2048 default on both sides of that comparison. Three things this does NOT claim. The fingerprint DOs are outside the drop, so a slot goes on publishing the old key’s fingerprint in C5 until something overwrites it. TERMINATE DF sweeps attributes and keys in flash-ring order, so a factory reset that fails partway can leave a key beside a cleared attribute, and what it owes there is the 6581 it returns rather than an order. And the binding at the other end — GENERATE and IMPORT reading the slot’s attribute as they mint or take the key — is one command for every arm but the two-step RSA generate, which reads the attribute when it starts the prime search and does not read it again when it stores the key. Nothing in the applet closes that window; what closes it is the worker dispatching one command at a time.
  • A Yubico OTP the host watched being typed must not validate twice. The OTP applet types its ticket as keystrokes into whatever has focus, so a hostile host reads every OTP the key emits; what stops one being replayed is not secrecy but position. Among the fields each press of a Yubico-OTP slot encrypts into its ticket is a pair — the slot’s persisted 15-bit use counter and a one-byte RAM session counter — and the protocol’s replay rule is that a validation server rejects any OTP whose pair does not exceed the last pair it saw for that public id. The pair is therefore the defence, and the rule is that a press emits the pair the slot holds and then moves it: the session counter on every press, and the persisted use counter whenever the session counter wraps past 255. One press does not read that way — the first on a freshly configured slot, whose stored zero is written up to one before the ticket is built, so what it types is the moved value and not the zero it held. The two paths that ADVANCE the persisted half are the wrapping press and a boot’s first press, and the step that can reach the 15-bit ceiling comes from one module for both, so the ceiling cannot be enforced two different ways. The first-press 0 → 1 write sits beside it in ticket.rs and cannot reach the ceiling. UPDATE and the boot seal migration carry a slot’s record forward and leave the counter alone. SWAP leaves the stored counter alone too — but it moves the record to the other slot index, and the RAM half travels with it, because the pair belongs to the public id inside the record and not to the slot number that record happens to sit at. Because the session counter lives in RAM and comes back at zero with every boot, warm or cold, the first press of a plain Yubico-OTP slot after one advances its persisted counter before it types, as a YubiKey advances it at its first use after power-up — never a HOTP, short or static slot, and never one already at the ceiling. That is what keeps one boot’s pairs out of the next one’s, and since only a press moves it, no reboot a host can ask for walks the counter toward the ceiling. Every advance’s answer is read: a ticket whose advance the store would not take is not typed at all, because typing it re-emits — the next press reads the old counter back and pairs it with a session already used — and a press whose read the medium refused types nothing and leaves the advance owed. A store that keeps refusing therefore silences the slot until it recovers: a denial of service, where typing on would repeat. Three residuals, and the rule above hides none of them. At that ceiling neither path advances anything and the key goes on typing, so the pair repeats every 256 presses and every boot. And position is not monotone across re-provisioning: CONFIGURE writes a fresh record with a zeroed counter, gated by the slot access code whenever the existing slot reads back. And the move that carries the pair is not atomic: SWAP writes the two records one after the other and swaps the RAM halves only once both are through, with nothing to undo a step that failed. A refused second write answers 6581 with the first already landed, and so does a refused delete — the answer is read now, but where the record write has already gone in it buys the report and not the state. That direction still leaves one public id in two slots with only one of the two session halves its own, and the other slot can then type a position that id has already typed this power cycle — which a plain ykman otp swap reaches unauthenticated, an unprotected slot’s stored access code being all-zero.
  • 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. A configuration lock code (ykman config set-lock-code) closes the DeviceInfo half, as on a YubiKey: once one is set, all four writes need it (protocol.md §6.2). It keeps no retry counter, a YubiKey keeping none either, so a code a person could remember can be guessed online — use --generate. It shuts RS-Key’s own phy and LED records too, which no code opens: they change only once the lock is cleared. 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 both CTAPHID and CCID, 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 by the mask, so any single transport can re-enable it (with the code, once a lock is set), and no secret is exposed. A lock code the attacker set would end that, so setting one where none is set takes a touch of the key, on all four writers, where a YubiKey 5.8.0 asks none: with a code nobody holds, nothing turns an application back on, and the display build’s factory reset or an rsk-wipe erase, both of which destroy every credential, is the only way back. What is left is a touch given to the wrong prompt, since the BOOTSEL button cannot show what it approves; setting a code of your own at provisioning closes that too, as changing one needs the current one. Reversible describes the mask, not the flash it is written to. Repeated changes to persistent configuration consume flash endurance. The vendor and FIDO paths skip unchanged records, while a host can still send distinct values. Wear depends on the workload and flash geometry. 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 FIDO applet answers on two transports, and the second one is easier to reach. CTAP2 and U2F are served over CCID as well as CTAPHID (CTAP over CCID), so any process that can talk to pcscd can drive the whole CTAP surface — no exclusive HID handle, and none of the platform gatekeeping a browser or the Windows WebAuthn stack applies to its own FIDO path. What that does and does not buy an attacker: nothing a credential gate would have stopped. Every operation still spends the same PIN, the same pinUvAuthToken and the same physical touch, because the two transports run the same applet over the same FidoState — one PIN/UV token, one credential-management walk, and crucially one per-boot PIN-mismatch budget. A second session state would have handed a host PIN_MISMATCH_LIMIT guesses per transport instead of per power cycle, which is the restart-by-reboot attack §6.5.5.6 exists to stop; that it is shared is enforced by construction (one &RefCell<FidoState> reaches both) and pinned by both_transports_answer_from_one_session_state. What it does buy is reachability: a process that could not open the HID device can now open the card. Treat FIDO as available to anything with card access, and use ykman config usb --disable fido2 (or --disable u2f) if that is not wanted — the mask gates the two applications apart, over both transports. Client or driver binding can affect reachability on a particular host. Treat CCID as exposed whenever the interface is enabled.
  • User intent. A button confirms presence. Malware can substitute its own request before you press it. In a FIDO presence prompt, the trusted display shows the RP ID that the authenticator received and lets you approve or decline on the device. A deliberate approval applies to that prompt. A stale touch, Deny, cancellation or timeout cannot approve it. Compare the RP ID with the site you intended to use. The browser and relying party still determine whether an assertion is valid for the origin and challenge. Silent up:false assertions can still run when policy permits and return with UP clear. See the trusted display guide.

With the default presence policy, an eligible up:false assertion can return largeBlobKey without interaction when the credential’s credProtect policy permits it. alwaysUv applies to requests with UP set, and strict-up adds a presence check to silent probes. A host can read the ciphertext array with authenticatorLargeBlobs get. The optional largeblob-ext build can return the blob itself on an eligible read and seals it at rest under a seed-derived key with the credential ID as associated data. See the CTAP specification.

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

  • Secret records. The FIDO seed, attestation scalar and persistent UV token use ChaCha20-Poly1305. PIV keys and OATH and OTP secret records use AES-256-GCM. Their keys derive from the device root kbase. OpenPGP private keys use a separate AES-256-GCM data-encryption key (DEK) wrapped under PIN-derived keys. The store also authenticates record authority and contents. Before OTP, that authority uses the public serial root. The completed latch requires OTP-backed authority. A flash image can still contain public metadata.

  • OTP master key. Before provisioning, kbase derives from the public chip serial. A flash dump and that serial let an attacker recover device-sealed records and try guesses offline against legacy PIN verifiers. After migration under a fused MKEK, recovery from flash alone requires that MKEK. A PIN-derived record can stay on the public root until its PIN or resetting code is presented. See PLAT-THREAT-002 and Production setup.

  • Page-58 latch. Before the latch, a raw flash writer can plant a record under a public pre-OTP key that migration would then re-seal under the fused root. Secure startup completes the latch after the migration checks pass and a fresh flash scrub succeeds. The completed lock denies BOOTSEL and Non-secure access and leaves Secure firmware read-only access. A per-boot software lock already denies Non-secure access before the launch of Non-secure firmware. See OTP fuses.

    After the latch takes effect, device-sealed records covered by migration reject the pre-OTP and legacy cleartext formats. An unreadable fused root fails closed. Older locks that leave Secure writes enabled still need the current startup checks to complete the latch. PIN verifiers keep their pre-burn arm because their format does not identify the root. This includes the FIDO PIN, the display’s device PIN, the PIV PIN and PUK, OpenPGP’s PW1, PW3 and resetting code with their DEK copies, and the OATH OTP PIN. The fallback is a property of the verifier format. Changing a verifier in the authenticated store also requires a record and authority that the store accepts. A substituted PIN verifier by itself cannot unwrap the OpenPGP DEK. An unreadable fused MKEK blocks boot migration and is reported by READ 1E/07 as FFFE.

  • Soft-lock. The seed is wrapped with ChaCha20-Poly1305 under a 32-byte key supplied by the user. Operations that need the seed remain locked until that key is presented over an encrypted channel. A successful unlock keeps the seed in Secure RAM for use until it is cleared. See the Soft-lock guide.

  • 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), and the persistent pcmr grant, which provisioning mints at the first boot under that same root. Left alone, a flash dump plus the chip id would recover them, bypassing the burn. Boot runs a compaction lap before USB attach. Migration re-arms the EF_HARDENED marker when it replaces a record. Sealing page 58 requires successful migration and a fresh scrub, so an interrupted pass can leave the migration pending on a later boot.
    • 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.
  • FIDO seed and PIN. The current seed format uses the device root so UP-only operations such as U2F can work from a cold boot. The FIDO PIN controls use where policy requires UV. Soft-lock adds a separate wrapping key supplied by the user.

3. An attacker who can flash their own firmware

  • Secure Boot. When enforced, the boot ROM authenticates the complete combined image, including both worlds and the embedded partition table, using the enabled signing keys. The production procedure also provisions debug restrictions and glitch detectors. See Production setup.
  • 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.

One residual straddles this line, and it is written down rather than left to the reader. The RSA private operation picks a modexp window per four bits of dP/dQ, and the choice lands in an ADDRESS: PIV GENERAL AUTHENTICATE and OpenPGP PSO:CDS / INTERNAL AUTHENTICATE / DECIPHER all drive it over USB against a long-lived key, and the per-operation blinding randomises the base, never the exponent. Reading the window sequence back needs a time-resolved look inside a single operation, and the only observer holding one is the power/EM capture already listed above — so that half is out of scope for the reason this section already gives, not for a new one. The other half is not out of scope: a host that can time whole operations is the §1 attacker, and against it the pattern is one scalar per signature over an exponent that never changes. Severity, the reasoning and what would re-open it are registered as PLAT-CRYPTO-002, and the hardening that would remove it is PLAT-BUILD-005, deferred with a stated price (platform-assumptions.md, ct-audit.md). This paragraph adds a residual to the page; it excludes no observer the section did not already exclude.

5. Network

The firmware exposes its interfaces over USB. Network-originated input reaches the device through host software.

Flash snapshot rollback (the PIN-counter reset)

Reported by Token2 (issue #37, advisory PDF). An attacker with physical access and a way to read and rewrite the store can save the flash, submit PIN guesses to the device and restore the saved copy when the retry budget runs out. This repeats on-device guesses. It can reset flash-backed counters for FIDO PIN, PIV PIN/PUK, OpenPGP PINs and the OATH OTP PIN. The attack also needs a reboot that clears any separate per-boot retry state.

An old record and its matching store authority can still authenticate on the same chip. The main directory tracks the newest authority it has seen within the same backend instance, including remounts. Replaying all its authority copies after a cold boot can still restore older state. The counter partition has a separate authority. Replaying both of its banks can rewind counters without changing KVMAIN, even while the main directory remains mounted. Firmware anti-rollback applies its floor to the image. A retry budget needs durable freshness of its own, which the current store has no independent way to check. See Limitations and Anti-rollback.

  • Partition table. The default build embeds an RP2350 partition table that fences the KV store off from the USB bootloader. picotool save and picotool load over that range answer permission failure — enforced by the bootrom, not by us — while the running firmware keeps secure: rw and full access to its own data. The default BOOTSEL path rejects those direct store reads and writes. The diagnostic --no-partition-table build omits that fence.

    With Secure Boot enforced, altering the table in a signed image breaks image authentication. An older image signed by an accepted key can still replace the fence if the rollback policy allows it. Without enforcement, an attacker can install their own image with a permissive table. The fence covers BOOTSEL access to the store. Direct flash access can bypass it.

  • OTP-seeded PIN verifier. A FIDO PIN verifier created or migrated under the fused root derives from HKDF(serial_hash, HMAC(kbase, pin)). A flash dump alone lacks the MKEK needed to check guesses against that verifier. Legacy verifiers that still use the public root retain their offline risk.

  • strong-pin / fips-profile builds (opt-in). Raise the clientPIN floor to six code points and reject common patterns such as repeated digits and 123456. This raises the cost of guessing, which still depends on the chosen PIN and the attacker’s access. See Build options.

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

A4 addresses the original fault and boot-ROM attacks. It replaces the affected boot ROM and changes the OTP power-glitch circuitry. The direct antifuse readout remains applicable. RS-Key uses OTP chaff to address the demonstrated paired-row readout. Raspberry Pi’s second challenge targets side channels in the boot ROM’s AES implementation. See the A4 announcement, second challenge and OTP fuses.

A4 does not stop a laser from turning debug back on (Ledger Donjon). On a decapped A4, photon-emission imaging located the DEBUGEN register and laser pulses set the bits that restore Secure debug, despite CRIT1.DEBUG_DISABLE and DEBUGEN_LOCK; a rescue reset then stops the chip in the boot ROM before any firmware runs, and the OTP reads out. About $250k of equipment. Raspberry Pi will not respin: the attack is destructive, and with per-device keys it has single-device scope (response).

What this means for RS-Key. The project has board records from A2 and A4. The Donjon experiment read its challenge secret from page 48. It also shows why an attacker who restores Secure debug could read RS-Key’s MKEK and DEVK on page 58. Our completed latch still permits Secure reads, and a logical debug read can recover the real rows despite chaff. That application to RS-Key follows from the access policy. The published experiment used the challenge firmware. A recovered MKEK exposes device-sealed records from that board and enables offline PIN guessing against verifiers derived from it. A soft-locked seed still depends on its separate off-device key while it is locked. An organization attestation key shared across a fleet can extend the impact beyond one device. See Ledger Donjon, Testing and Attestation.

Seed backup (the deliberate exception)

Host export sends the FIDO seed over an ephemeral channel using P-256 ECDH, HKDF and ChaCha20-Poly1305. The channel can add an ML-KEM-768 shared secret. The export request also requires presence and authorization with the configured PIN. While the export window is open, export can be repeated. finalize requires a separate authorization and closes the window until a factory reset. The fips-profile build refuses export.

The PIN factor has two forms and the second is easy to miss: with a clientPIN set it is the PIN/UV token; with no clientPIN but a device PIN set, the same gate collects that PIN on the device’s own pad, so a display-flavor key whose owner never set a clientPIN is still two-factor. With neither set there is no PIN factor and the gate is the encrypted channel plus a touch — which is the state a factory-fresh key is in, and the reason finalize exists. A device PIN the running build cannot collect (the record survives a reflash to a screenless image, which has no pad) is refused, not waived: an owner who set a PIN does not silently drop to a touch. 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 BIP-39 words or SLIP-39 shares 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 Authenticator
    H->>D: MSE with P-256 public key<br/>and optional ML-KEM key
    D-->>H: P-256 public key<br/>and optional ML-KEM ciphertext
    Note over H,D: Derive the channel key with HKDF
    H->>D: BACKUP_EXPORT<br/>PIN/UV auth when FIDO PIN is set
    opt Device PIN only
        U->>D: Enter PIN on the display
    end
    U->>D: Approve seed export
    D-->>H: Seed encrypted with ChaCha20-Poly1305
    Note over H: Host decrypts the seed
    H-->>U: BIP-39 words or SLIP-39 shares
    H->>D: BACKUP_FINALIZE<br/>Apply configured PIN policy
    U->>D: Approve closing the export window
    D-->>H: Export window closed

Zeroization

Session teardown wipes PIN/UV tokens. Transient copies in Secret or under a WipeGuard are wiped when their scopes end, including error returns. The firmware also scrubs transport and exchange buffers at their reuse or revocation points. Non-secure code can observe a plaintext PIN sent over CCID before the buffers are scrubbed. Secure startup and operations that need the MKEK or DEVK read the fused keys on demand into temporary buffers. Secure code execution can call the same OTP readers.

Accepted residuals: Copy temporaries inside RustCrypto curve arithmetic and digest internals, in stack slots until the work that made them is done: core0’s dead stack is zeroed after each request, keyboard OTP frame, typed ticket and panel flow, and core1’s after each prime search (firmware/src/sweep.rs). The few hundred bytes above the shallowest of those callers — the tasks’ own poll frames, interrupt frames taken while the worker idles — no sweep reaches. The working buffers num-bigint-dig allocates inside its own arithmetic — a division’s, a modular inverse’s, a modular exponentiation’s — it frees unwiped; rsk-rsa holds a key’s values, its blinding values and a private operation’s result and intermediates in a Secret or a key type whose Drop wipes them, except the primes and d of a key RsaKey::from_p_q refuses. The heap closes both for what it holds: it wipes each block as it frees it (ZeroingHeap in firmware/src/main.rs), so a freed buffer’s bytes do not outlive the free. A num-bigint-dig value of eight limbs or fewer is held inline, not on the heap, and a local one stays in its stack slot like those temporaries.

The root clippy.toml restricts direct uses of Zeroize::zeroize and Zeroizing. A state object that needs its own wipe uses an #[expect] at the wipe site. A panic halts without unwinding, so a key unsealed at that point can remain in SRAM. Moving a secret can also leave compiler copies. Firmware builds secrets in place and passes them by reference where possible.

Reboot to BOOTSEL requires presence and leaves BOOTSEL in control of any remaining SRAM. worker::reboot wipes live key material before handing off. In the recorded RP2350 A4 test with Secure Boot off, all 520 KiB of main SRAM read back as zeros. A known pattern written through PICOBOOT read back correctly, which confirms that the zero read was a measurement. The result applies to the tested silicon and boot policy. It measures the platform’s clearing behavior. See PLAT-MEM-001 in Platform assumptions for the board record.

Firmware-requested resets go through worker::reboot. clippy.toml refuses SCB::sys_reset, rom_data::reset_to_usb_boot, rom_data::reboot / reboot_ns and Watchdog::trigger_reset anywhere else, so a new path to a reset cannot skip the wipe without an #[expect] that says why. Not covered, and none of it in the tree today: a watchdog started and left unfed (Watchdog::start), a raw write to the watchdog or power-manager registers through rp_pac, an AIRCR write through SCB::PTR, a ROM function called through its ptr(), and the ROM’s chain_image.

Supply chain & process

  • scripts/check.sh runs cargo audit, cargo deny and Gitleaks. The pre-commit hook scans the staged diff with Gitleaks and runs formatting, build and lint checks.
  • Dependencies are pinned in the workspace lockfiles. Firmware Git dependencies come from embassy-rs. The emulator has its own picoem pin.
  • Advisory exceptions. deny.toml lists exceptions for unmaintained or deprecated dependencies. The firmware uses rsk-rsa for RSA private-key operations. The signing and deciphering paths blind the base on each operation. See the constant-time audit for scope and residuals.

Post-quantum notes

FIDO2 credentials support ML-DSA-44 (COSE −48), ML-DSA-65 (−49) and ML-DSA-87 (−50). rsk-mldsa uses hedged signing with 32 fresh DRBG bytes per signature and checks the implementation against NIST ACVP vectors. The constant-time analysis and stack measurements have their own scope. See the constant-time audit and image testing.

The vendor MSE channel uses ML-KEM-768 alongside P-256 when the client supplies an encapsulation key. The standard CTAP PIN/UV protocols use their own key agreement. See the MSE protocol.

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.

Assurance case

One argument, in four parts, for why RS-Key’s security claims hold: what it promises, what it is defending against, where the trust boundaries run, and why the design and the implementation are expected to survive contact with each.

This page argues; it does not carry the evidence. Every claim below points at the page that does, and those pages are where a disagreement should be settled. It is deliberately short on adjectives and explicit about what it cannot justify — a residual named here is worth more than a claim nobody can check.

What is claimed

  1. Secrets do not leave. The FIDO master seed, resident passkeys, OpenPGP and PIV private keys, OATH and OTP secrets, and the PINs never cross the USB boundary, and no protocol command exists that exports them — except the one deliberate exception, seed backup, which is an owner-initiated ceremony and is argued separately in threat-model.md.
  2. Use is gated on a human. Operations that consume a key require the authorizations their protocol defines — PIN or UV, physical touch, an OpenPGP UIF, a PIV management key — and the gates are spent and enforced before the key is touched, not after.
  3. A hostile host cannot corrupt the device. Every byte arriving over USB is parsed by memory-safe code that either answers or refuses; no input sequence produces memory corruption, a wedged transport, or a state the next boot comes up softer for.
  4. Interruption does not weaken it. A power cut lands wherever the host aims it, and what the device owes across one is that nothing comes back weaker: an interrupted write leaves the old value or the new one, a committed record still reads back, and no gate is softer on the next boot than it was before.
  5. At rest, flash alone is not enough. On a device whose OTP master key is burned, a full flash image does not yield the secrets it stores.
  6. The build is the source. A published release is reproducible from this repository and cryptographically tied to it.

Claim 5 is conditional on purpose: before the OTP burn the seal root derives from on-chip state an attacker with the chip can reconstruct (production.md, otp-fuses.md).

The threat model, in brief

The full statement is threat-model.md; it defines four attackers and the defences compose in tiers, each assuming the ones before it.

AttackerPositionTreatment
Hostile hostDrives every byte over USB, picks when the power diesDefended: memory safety, protocol gates, write ordering
Thief with the powered-off deviceFull flash image, no PINDefended after the OTP burn: at-rest sealing
Attacker who can flash firmwareReplaces the imageDefended by secure boot + anti-rollback; undefended on an unfused board
Physical / lab attackDecapping, glitching, probingOut of scope — the RP2350 is not a secure element
Network—No network interface exists

Two boundaries of the model are worth restating here because the rest of this page leans on them. A compromised, unlocked host can drive any operation the owner has already authorized — a security key attests presence and possession, not the intent of every byte — and touch requirements bound the rate rather than eliminate the class. And physical attacks are not merely unmitigated but architecturally out of reach: the claim is never “the key survives a lab”, it is “the key survives the cable”.

Trust boundaries

Six places where data or execution changes trust level. Each is a place where a mistake is a vulnerability rather than a bug.

B1 — the USB cable. Everything inbound is attacker-controlled: CTAPHID frames, the CCID bulk stream, ISO-7816 APDUs, CTAP2 CBOR. Crossing inward means parsing; crossing outward means a status word or a signature, never key material. This is the boundary every fuzz target sits on.

B2 — transport to worker. USB and the transports run on a high-priority interrupt executor; applet dispatch runs in a single worker task on the thread executor that owns the flash and the TRNG outright (architecture.md). Ownership is the synchronization — there are no mutexes to get wrong — and the transports cannot reach persistent state except by handing the worker a request.

B3 — RAM to flash. Secrets are sealed before they are stored, at one chokepoint rather than at each call site: kbase = HKDF(serial_hash, otp_master_key) keys the at-rest seals (architecture.md). Crossing this boundary outward without a seal is the defect class the chokepoint exists to make visible.

B4 — the boot chain and the partition table. The bootrom verifies the signed image before it runs; the shipped image then carries a partition table that denies the USB bootloader read and write over the KV range, while secure code keeps it (build.md). The firmware’s own provisioning and recovery complete before the USB pull-up, so a host never sees a half-initialized device (architecture.md).

B5 — the owner. Touch, the PIN, and on a display build the trusted screen, are the one channel a hostile host cannot drive. Everything that depends on “the human agreed” crosses here, which is also why the trusted display is where a display build’s promises concentrate (guides/display.md).

B6 — source to artifact. The gate, the release pipeline and the signing keys sit between a commit and a firmware image someone flashes. Provenance is published and verifiable (supply-chain.md, releases.md).

Secure design principles, and where each one lands

Saltzer and Schroeder’s list, against what the tree actually does. The point of the exercise is the mismatches it would expose, so a principle that is only partly honoured says so.

Economy of mechanism. no_std, no mutexes; one worker owning flash and TRNG; the async executor supplying the concurrency an earlier design needed a second core and hand-rolled queues for. Less machinery is fewer states to get wrong. Partly honoured: there is one heap, which RSA’s big integers and FIDO’s boxed ML-DSA keys need and nothing else uses, and it wipes each block it frees.

Fail-safe defaults. alwaysUv ships on. The harder rule is the one learned from a defect: a flash read that fails must never be laundered into an absence, because absence is how this tree spells no PIN set and not provisioned. A probe whose absent arm would open a gate is answered fallibly or resolved to the restrictive arm (threat-model.md).

Complete mediation. Authorization is re-checked at use, not cached into a capability: a private-key operation re-reads its slot’s algorithm attribute every time, and a PIN retry is spent before the comparison, so a power cut during verification cannot buy a free guess.

Open design. AGPL-3.0-only, a published threat model, a published wire protocol (protocol.md), the formal models and their failures in the repository (formal.md). The keys are the only secret; nothing rests on an unpublished mechanism.

Separation of privilege. Distinct authorities gate distinct things — OpenPGP PW1 and PW3, the PIV management key against the PIV PIN, touch against knowledge. The irreversible steps (secure-boot signing, OTP fuse burns) are a separate ceremony under separate keys, performed by a person, never by a build.

Least privilege. The partition table denies the USB bootloader access to the KV store; applets own disjoint file-id ranges and a reset wipes exactly its own predicate; no applet crate may name another — the count is zero and cargo deny keeps it there (architecture.md); CI workflows declare minimal permissions.

Least common mechanism. The per-operation counters live in their own KV partition so their churn never forces compaction of long-lived records; the crate graph is tiered with every edge pointing strictly downward, generated and gated rather than asserted.

Psychological acceptability. The LED and the touch button say what the device is waiting for; the trusted display says what is being signed. A gate whose reason is invisible gets clicked through, so the visible half is part of the mechanism, not decoration.

Common implementation weaknesses, and what stops them

WeaknessWhy it does not happen hereEvidence
Memory corruption (CWE-119/125/787)Safe no_std Rust; every unsafe site enumerated and justifiedunsafe.md, fuzzing + Miri (testing.md)
Improper input validation (CWE-20)Every external parser is a fuzz target, with a floor in the gate so the set cannot quietly emptytesting.md
Authentication / authorization bypass (CWE-287/862/863)Gates spent before use; retry counters and lockout; sequence properties model-checkedformal.md, assurance-matrix.md
Weak randomness (CWE-330/338)RP2350 hardware TRNG with health checks seeding an HMAC-DRBG; no language-default RNG in the imagethreat-model.md
Cleartext storage of secrets (CWE-312)One seal chokepoint before anything reaches the storearchitecture.md
Timing side channels (CWE-208)Constant-time comparisons and blinded private-key paths, audited against the built imagect-audit.md
Secrets left in memory (CWE-226)Zeroization on the paths that hold key materialthreat-model.md
Torn write / interrupted state (CWE-367 family)Per-operation write ordering, stated where the code does it; refinement proofs over the store and resetstore-refinement.md, reset-refinement.md
Downgrade and rollback (CWE-757)Secure boot plus the OTP anti-rollback epoch; bcdDevice names the build preciselyanti-rollback.md
Hardcoded credentials (CWE-798)Test keys exist only behind explicit build knobs; gitleaks runs in the pre-commit hook and in the one CI job no change can skipbuild.md
Vulnerable dependencies (CWE-1395)cargo audit, cargo deny and cargo vet in the gate; pinned lockfiles; git dependencies restrictedthreat-model.md

The argument these rows share is structural rather than per-bug: each weakness is tied to a gate row that fails, so the countermeasure is checked on every change instead of being asserted once on this page. Where that is not true — and the next section is the list — it is said plainly.

Residuals

What this case does not justify:

  • Physical and lab attacks. Out of scope by construction; the RP2350 is not a secure element (limitations.md).
  • A compromised unlocked host. It can use what you have authorized. Touch bounds the rate; nothing eliminates the class.
  • Before the OTP burn, at-rest sealing is not worth much: the root derives from on-chip state a chip-level attacker can reconstruct.
  • Hand-written cryptography. rsk-mldsa’s constant-time posture is a source-level claim — branch-free reductions, masked norm checks, no secret division — not proven at machine code, and none of the post-quantum code has had a third-party audit.
  • Platform assumptions are assumptions. What the silicon owes this design is registered, and some entries are still pending a board measurement rather than discharged (platform-assumptions.md).
  • Per-site disciplines cannot be gated. The fallible-probe rule above is held by tests at each site and by review, not by a mechanical property; the tree carries far more collapsing probes than fallible ones, and which class a site belongs to is a judgment.
  • One maintainer. Review by a second pair of eyes is not a property this project can currently claim (GOVERNANCE.md).

Checking it yourself

The gate is one command and CI runs exactly it, so the evidence behind this page is reproducible without special access: testing.md for the layers, reproducing.md for the evidence artifacts, formal.md for the models and what they do and do not cover. A claim here that you cannot reproduce is a bug in this page; report it under SECURITY.md if it is exploitable, and as an issue if it is not.

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

RS-Key is experimental firmware. Its security review is project-led. The threat model describes the security boundary, and Testing describes the checks and their scope.

Cryptography

  • RSA side-channel coverage has limits. rsk-rsa uses base blinding and checks CRT results before returning them. In the optimized CRT path, the private exponent still selects a table address during modular exponentiation. A host observing whole-operation timing and a lab observing activity inside one operation are different cases. See the constant-time audit and the residual and deferred hardening in PLAT-CRYPTO-002 and PLAT-BUILD-005.

Flash storage

  • Integrity depends on the root. Storage v2 authenticates expected records and detects damaged or missing values. Before OTP provisioning, its root derives from the public chip serial. A raw flash writer can forge authority under that root. Secure startup closes the public-root path when migration and the fresh flash scrub finish and page 58 is sealed. See OTP fuses.
  • Freshness is limited to a live backend instance. The main directory and counter banks retain the latest authority they have accepted in RAM. Replacing both counter banks with an older copy during a live mount is rejected, including for PIN retries. Reads authenticate the requested value, so unrelated damage may surface only at mutation or recovery. After a cold boot, replaying older valid flash state can restore old records and counters. The BOOTSEL partition table limits access to the store. Firmware anti-rollback applies to images. See Flash snapshot rollback.
  • Legacy import has a trust boundary. A verified newer publication takes precedence over an older import manifest. If all v2 evidence is lost and the surviving media looks like a valid legacy layout, boot can admit it as legacy. Import can preserve readable bytes and check their layout. The integrity of data written by the legacy store depends on that store’s own guarantees.
  • Mirroring consumes erase cycles. In a software NOR run of 20,000 updates to one four-byte counter, v2 programmed 1,941,056 bytes and erased each of its ten counter sectors 47 times. The legacy backend programmed 320,628 bytes and erased each of its 32 sectors once or twice. The v2 run left the main payload and directory unchanged. This measures one write pattern. Physical endurance depends on the flash chip and use pattern. See Storage and failure injection.

Seals and PINs

  • Page 58 and the records it protects. After the latch closes, device-sealed records covered by migration require the fused MKEK. An unreadable MKEK blocks migration at boot and prevents those records from opening under the public root. A legacy lock can deny BOOTSEL reads while the latch still awaits completion. See Production setup.
  • Legacy PIN verifiers remain readable by the applets. The verifier format permits a fallback to the old root after the latch closes. Substituting a verifier also requires flash state that the authenticated store will accept. A substituted verifier does not unwrap the original OpenPGP data-encryption key (DEK).
  • PIN-dependent migration needs the PIN. Present each existing PIN or update its reference as directed during provisioning. This includes the PIV PUK and the OpenPGP admin PIN and resetting code, which ordinary use may never present. A legacy OpenPGP DEK copy can remain reachable through an offline guess against the old root, even after another reference migrated. See PLAT-THREAT-002 in Platform assumptions and the production procedure.
  • PIV data objects can be visible in a flash dump. The card requires PIN verification to read Cardholder Fingerprints (5FC103), Facial Image (5FC108), Printed Information (5FC109) and Iris Images (5FC121) through PIV. The objects are authenticated in storage and their contents are plaintext. The per-object limit is 3063 bytes. The card stores data supplied by the host. See the PIV guide.

Algorithms and implementations

The fips-profile build applies algorithm and PIN restrictions. The FIPS-style profile guide covers its validation status.

  • OpenPGP curves. The applet supports brainpoolP256r1 and brainpoolP384r1. Its supported set excludes brainpoolP512r1, X448 and Ed448. The advertised algorithm list reflects the implemented curves.
  • RSA decryption exposes a padding result. A host that can drive OpenPGP PSO:DECIPHER with PW1 verified can distinguish a successful PKCS#1 v1.5 decrypt from a refusal. That provides a padding oracle to an authorized caller. The unpadding code uses masks for its checks. Returning plaintext on success still exposes its length.
  • On-card RSA generation can be slow. The prime search dominates RSA-3072 and RSA-4096. Both cores can search with the hot path in SRAM. Latency varies with board, build and the number of candidates rejected. The firmware sends keepalives while supported transports wait. See RSA on core1.
  • ML-DSA needs client support. RS-Key supports ML-DSA-44, -65 and -87 for FIDO2. advertise-pqc enables their advertisement in getInfo. A client can request the algorithms with that flag off. Unknown-algorithm parsing and ML-DSA credential creation are separate compatibility issues. Mozilla documents the former fix in authenticator-rs and tracks the latter separately. See Build options and Firefox’s ML-DSA issue.
  • ML-KEM scope. The vendor MSE channel can combine P-256 with ML-KEM-768 when the host supplies an encapsulation key. Standard CTAP PIN/UV protocols still use P-256. See the MSE protocol.

Backup & migration

  • Seed backup recovers the deterministic FIDO identity. Restoring the seed can recover non-resident credentials when the client or relying party still has their credential IDs. Resident passkeys, OpenPGP and PIV private keys, OATH credentials and OTP slots require separate migration or re-enrolment.
  • Finalizing closes the export window. Retain the phrase or enough SLIP-39 shares before finalizing. A factory reset reopens the window for a new identity. The fips-profile build blocks seed export. See the seed backup guide.
  • Flash geometry is part of the upgrade contract. Keep FLASH_SIZE and KVMAIN when updating a provisioned key. Changing either can move the partitions away from existing data. See Build options.

Hardware / physical

  • Physical and lab attacks. The security boundary is the general-purpose RP2350 family. A4 addresses the original A2 boot ROM and OTP power-glitch findings. Direct antifuse imaging remains a concern, and a separate lab attack recovered a challenge secret after restoring Secure debug on a decapped A4. RS-Key uses chaff for the demonstrated paired-row readout. It still relies on Secure reads of page 58. The application of the debug attack to those rows is an inference from their access policy. See the threat model and Ledger Donjon’s experiment.
  • TRNG health checks and entropy. The firmware leaves the RP2350’s continuous health checks enabled. Their success does not quantify entropy from a degraded source. A raw-source measurement under desk conditions is pending in PLAT-TRNG-002. Qualification across supply, temperature and process is an accepted gap in PLAT-TRNG-003. See Platform assumptions.
  • Flash failures can look like absence to callers. The storage API has both lossy reads and probes that distinguish absence from failure. Security-sensitive provisioning and authorization paths use fallible probes or take a restrictive path. The effect of a real interrupted program or erase is a separate hardware question. The supply-cut assumption in PLAT-FLASH-001 is pending. See the threat model.
  • External-flash XIP has a time-of-check gap. Secure Boot verifies the image, then the CPU fetches instructions from flash. An interposer on the external flash bus can serve different bytes at those stages. The combined firmware and its working memory exceed the available SRAM. RP2354 puts flash inside the package, which removes the exposed external flash chip from that attack path. The FIDO2 demonstration on Romu used Bitmerse’s RS-Key port. See Hardware and the RP2350 datasheet.
  • TrustZone separates USB framing from Secure services. Secure owns the USB controller and lifecycle, applets, storage and OTP. Non-secure code sees plaintext that crosses its transport, including a host PIN sent in a plain CCID APDU. Secure applets share one trust domain. See Architecture for the boundary and Testing for the scope of board results.
  • Anti-rollback is an image policy. The OTP version floor has 48 one-way steps. The boot ROM checks a versioned image against the floor. ROLLBACK_REQUIRED requires a rollback version on signed images. See Anti-rollback.
  • Firmware images are signed for production and execute from flash. RS-Key uses signed XIP images. The RP2350’s encrypted-boot mechanism loads a payload into SRAM. See the RP2350 datasheet.
  • The display build runs beyond the nominal clock ratings. It sets the RP2350 to 160 MHz, above the 150 MHz rating. The write-only PIO link clocks the panel at 80 MHz. The ST7789T3 specifies a minimum serial write cycle of 16 ns (62.5 MHz). The driver cannot read back pixels to detect a panel transfer error. Measurements apply to the clock and board used. See the trusted display guide and ST7789T3 datasheet.

Protocol / compatibility

  • USB identity affects discovery. The default identity is 0x1209:0xF1D2 with the RS-Key reader name. ykman and Yubico Authenticator look for the Yubico reader name and use the opt-in VIDPID=Yubikey5 build for interop. Linux device permissions and CCID driver recognition are separate from application discovery. See Build options and Linux setup.
  • FIDO attestation can identify the device. Ordinary packed basic attestation carries a stable per-device certificate. A client that receives that certificate can correlate registrations. A CTAP client can request attestationFormatsPreference: ["none"] to omit the statement when enterprise attestation is not performed. An eligible enterprise request can return the provisioned organization’s chain. See Attestation.
  • PIV attestation uses a device-generated identity. Host import into slot f9 and replacement of object 5FFF01 are refused after management authentication, with 6A80. ATTEST uses the device’s identity. See the PIV guide.
  • OpenPGP attestation uses a device-generated identity. Its certificate is self-signed. Host writes to attributes DA or certificate FC return 6B00. Import and generation requests for the attestation slot return 6A80. See the OpenPGP guide.
  • PIV retry budgets must be nonzero. With PIN and management authentication in place, SET RETRIES returns 6A80 for a zero PIN or PUK budget and leaves the counters intact.
  • SELECT by AID accepts P2 = 04. RS-Key accepts it alongside P2 = 00 for clients such as PicoForge.
  • OpenPGP secure messaging is unavailable. OpenPGP commands use ordinary APDUs. Access still depends on the command’s PIN and presence policy.
  • The available presence input depends on the board. Ordinary builds use BOOTSEL or a configured GPIO. The display adds on-device PIN entry and a named prompt for operations that require confirmation. The shipped builds use PINs for user verification and offer no biometric reader. See Hardware and the threat model.

Operational

  • A logical deletion can leave old flash bytes. Superseded records can remain until compaction or a scrub reclaims their sectors. OTP migration schedules a scrub of superseded weak-root copies and requires a fresh successful scrub before sealing page 58.
  • Using a stolen key depends on its remaining gates. Someone with the device and its PIN can authorize the operations that PIN covers when they also satisfy the operation’s other gates. FIDO soft-lock protects the seed with a separate off-device key. See Soft-lock and the threat model.

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: 77. Twenty-eight in the applet firmware and tools, thirty-seven in Secure startup and Non-secure transport, and twelve in disposable hardware diagnostics. Fourteen are in main.rs and presence.rs: the heap init and its zeroing allocator (5), and the eight GPIO-pin steals (the presence button, the LED power-enable rail, the nuisance USR LED, the display build’s wake button, and — display builds only — the panel’s CS/DC/RST/TP_RST control lines). Three for the per-core prime sieves; one stack limit per core, core0’s in main.rs too; two for the dead-stack sweep and its probe; two in the standalone flash-wipe tool. One reads an uncached flash byte. Three align and clear complete response buffers. One restricts the shared flash context and backend to core0.

flowchart TB
    subgraph fw["firmware/src/main.rs + firmware/src/presence.rs"]
      c["heap init"]
      c2["zeroing allocator (×5)"]
      d["GPIO pin steal ×8 (presence, LED power, USR LED, display wake + CS/DC/RST/TP_RST)"]
      d2["core0 stack limit (MSPLIM)"]
    end
    subgraph kg["firmware/src/core1.rs"]
      e["per-core prime sieves (×3)"]
      e2["core1 stack limit (MSPLIM)"]
    end
    subgraph sw["firmware/src/sweep.rs + sweep/buffer.rs"]
      s1["dead-stack sweep"]
      s2["residue probe (bench builds)"]
      s3["complete response buffers (×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.

The compiler holds the crate boundary: the workspace denies unsafe_code, and only firmware, firmware-ns, rsk-wipe and — on the device target, for SRAM link-section attributes — rsk-rsa lift the denial at their crate root. The build scripts lift it at their one set_var statement. Which file and site inside those crates is this page’s business, held against the tree by scripts/platform_gate.py. Every unsafe block and unsafe impl also carries a // SAFETY: comment, which clippy::undocumented_unsafe_blocks refuses to build without.

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

1. Heap initialization — PLAT-UNSAFE-003

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

A 128 KiB heap exists for rsk-rsa’s big integers (num-bigint-dig, the only allocating dependency) and for FIDO’s boxed ML-DSA keys. 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.

2–6. The zeroing allocator — PLAT-UNSAFE-013

#![allow(unused)]
fn main() {
unsafe impl GlobalAlloc for ZeroingHeap {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
        unsafe { self.0.alloc(layout) }
    }
    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
        let len = layout.size();
        let head = ptr.align_offset(size_of::<u32>()).min(len);
        let words = (len - head) / size_of::<u32>();
        unsafe {
            for i in 0..head {
                ptr.add(i).write_volatile(0);
            }
            let body = ptr.add(head).cast::<u32>();
            for i in 0..words {
                body.add(i).write_volatile(0);
            }
            for i in head + words * size_of::<u32>()..len {
                ptr.add(i).write_volatile(0);
            }
            self.0.dealloc(ptr, layout);
        }
    }
}
}

The global allocator is LlffHeap behind a wrapper that zeroes each block as it is freed. num-bigint-dig frees the limbs of its own working buffers unwiped — a division’s, an inverse’s, a modular exponentiation’s — rsk-rsa drops the primes of a key RsaKey::from_p_q refuses, and a freed block keeps its bytes until an allocation reuses it. alloc forwards unchanged. dealloc writes zeroes over exactly the layout.size() bytes the caller hands back, which GlobalAlloc’s contract makes a live block this allocator returned for that layout, then forwards. It stores words over the block’s 4-aligned body and bytes only at its unaligned ends: an RSA key generation frees tens of megabytes through this path, and a byte loop is four times the stores. realloc is the trait’s default, an alloc, a copy and a dealloc through these two, so a grown vector’s old block is wiped as well. The writes are volatile, so no optimisation can drop them as stores into memory about to be freed. Safe alternative: none; GlobalAlloc is an unsafe trait with unsafe fn methods, and each forwarding call is an unsafe operation. Containment: two forwarding calls and three loops bounded by the caller’s own layout.

7–14. GPIO pin type-erasure (presence button, LED power rail, USR-LED-off, display wake + control pins, ×8) — PLAT-UNSAFE-004

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

Eight 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 plus the panel’s CS/DC/RST/TP_RST control lines, all by board-config number, in the panel block of 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, the wake pin, nor the four panel control pins is ever handed to another driver. Two checks hold that jointly: the LED data pin is resolved at runtime from the host-writable phy record, and the filter chain in main drops a value that names the presence pin, LED_POWER_PIN or USR_LED_PIN back to the build default — so a host cannot aim the data pin at a pad another driver owns. On top of that, 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), rejects a WAKE_PIN in the LCD range (10..=18) or on the hard-wired touch I2C1 pair (PIN_6/7) — which a WAKE_PIN=6 build did not, until 0x0A10 — and rejects any of CS/DC/RST/TP_RST/BL colliding with each other, with the hard-wired PIO serial output (PIN_10/11) or I2C1 (PIN_6/7) lines, an enabled WAKE_PIN, or LED_PIN/LED_POWER_PIN when their LED driver is built — a collision silently drives one pad from two owners at runtime, so it is checked at build time.

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

15–17. The per-core prime sieves — PLAT-UNSAFE-005

#![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, in `search`
unsafe { (*core::ptr::addr_of_mut!(CORE1_SIEVE)).scrub() };        // core1, on the STOP edge
let sieve = unsafe { &mut *core::ptr::addr_of_mut!(CORE0_SIEVE) }; // core0, in `run_rsa_search`
}

The dual-core keygen runs one running small-prime sieve per core (each 2.5 KiB of 16-bit 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; each core also scrubs its own sieve when its search ends, so the last candidate — which is the prime that was found — does not sit here until the next job. That end-of-search scrub deliberately stays on the owning core: STOP does not wait for core1, so a scrub issued from core0 (e.g. on the reboot path) would alias a live &mut while core1 is still inside try_candidate_le. 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: three call sites — two on core1 (search, end-of-search scrub), one on core0; 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.

18–19. The per-core stack limits (main.rs, core1.rs) — PLAT-UNSAFE-006

#![allow(unused)]
fn main() {
unsafe { cortex_m::register::msplim::write(&raw const _stack_end as u32) }; // core0, entering `main`
unsafe { cortex_m::register::msplim::write(stack_floor) };                  // core1, entering `core1_main`
}

Core1’s stack is an ordinary Stack<16384> array in .bss, so a push past its end writes into whichever statics the linker placed below — silently, and with no diagnostic. flip-link does not reach it: that guards core0’s stack by moving it to the bottom of RAM, and core1’s is a different stack. ARMv8-M’s MSPLIM traps the stack-pointer decrement itself, which a read-only MPU guard band would not: a frame big enough to step over the band writes past it and never faults, and the modexp chain on this core reserves ~6 KiB at a time. Programming it is a bare MSR that no safe API wraps. Core0 gets the same instruction for a weaker reason, and it is worth being plain about: flip-link already puts that stack at the bottom of RAM, so an overflow runs off into unmapped space and faults with or without this — there is no gap here to close. What the write buys is independence from the linker. Drop flip-link and that floor disappears silently, along with the only thing keeping this stack out of .bss; MSPLIM states the bound in code, where it can be read and where removing it is a visible edit. It is also where the dead-stack sweep (sections 23–24) reads core0’s floor: without the write it reads 0 and sweeps nothing. Safe alternative: none. cortex-m offers no checked form, and the MPU route is both weaker (above) and more unsafe, not less. Containment: one write per core, on the core that owns that stack, before anything has pushed, with that stack’s own base as the value — no legitimate frame sits below it. A violation raises UsageFault/HardFault on core1. That is not graceful: embassy_rp::multicore::pause_core1 spins unbounded on the inter-core FIFO, and a core1 sitting in a fault handler never answers it, so the next flash write hangs the device until it is replugged. That is the trade being made — a wedge a replug clears, rather than a silent write into whatever .bss the linker put below, issued by the routine that is at that moment generating and storing a key.

Dead-stack sweep (firmware/src/sweep.rs)

20–21. The sweep and its probe — PLAT-UNSAFE-014

#![allow(unused)]
fn main() {
unsafe { core::ptr::with_exposed_provenance_mut::<u32>(word).write_volatile(0) }; // the sweep, either core
unsafe { core::ptr::with_exposed_provenance::<u8>(addr).read_volatile() }         // the probe, `bench` only
}

What a request’s crypto leaves below the stack pointer — a RustCrypto Copy temporary, the hmac crate’s padded key block, a SHAKE reader’s state — no Drop or Secret can reach, because the frame that held it has returned. So core0’s dead stack is zeroed after every request, keyboard OTP frame and typed ticket (by the worker), every flow the panel runs (through the display’s hooks) and before a boot whose TRNG seed failed halts, and core1 zeroes its own after every prime search: every word from the floor that core’s MSPLIM holds (sections 21–22) up to its stack pointer, both read by the code on that core, thirty-two stores a pass. Nothing under the live pointer is a value: the stack grows down, and what is below belongs to frames that have returned. An interrupt taken mid-sweep pushes its frame below the pointer and returns before the loop runs again, so no store lands under a live frame; what a handler leaves in the part already swept waits for the next sweep. A measurement build (--features bench) adds vendor INS 0x15, which reads the same region to count a pattern in it and can stop the sweep for a positive control; check.sh holds it out of the default image with the other debug commands. Safe alternative: none; memory no Rust value owns has no safe handle. Containment: one function, bounded by two registers of the core it runs on, called at three points in the worker, from the display’s hooks, in core1’s job loop and before a failed boot’s halt, each after the work’s frames have returned; the probe only reads.

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

22–23. Raw flash erase/program in a critical section — PLAT-UNSAFE-008

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)

  • firmware/build.rs: unsafe { env::set_var(k, v) } copies the selected board-config file’s values (BOARD=<name>) back into the env before the build reads them. Same single-threaded host-side build-script context; never reaches the firmware 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.
  • Edition-2024 placements in crates/rsk-rsa/src/lib.rs: #[cfg_attr(target_os = "none", unsafe(link_section = ".data.small_primes"))] on the small-prime table, and .data.sieve_step for IncrementalSieve::step. The RSA window loop (crates/rsk-rsa/src/privexp.rs) and Montgomery conversion, multiplication, squaring and reduction (crates/rsk-rsa/src/montgomery.rs) use .data.bignum_* (PLAT-UNSAFE-011). The Secure linker collects those code inputs into .rsk_exec. The window closure uses executable scratch SRAM so its code leaves room for the main stack.

SRAM placement for public journal hashing — PLAT-UNSAFE-011

firmware/src/flash_storage/sha256.rs, firmware/src/flash_storage/stream.rs, firmware/src/flash_storage/quad.rs and firmware/src/core1.rs place digest, stream, QMI and park routines in the existing .data.ram_func input section. Startup copies it before use; the TrustZone linker includes it in the read-only executable SRAM range. The digest reads journal bytes through SharedFlash::read and checks aligned tails with the same exclusive CPU stream. Its direct erased-tail routine also lives in .data.ram_func: each FIFO word is checked without a staging copy, with the same bounds, status, timeout, final count and final address checks. Safe alternative: ordinary flash placement is correct but competes with the journal stream for XIP cache lines. Containment: SHA sees public metadata only; the CPU stream serves bulk reads under the existing flash bounds and guards. Both have bounded waits, and the stream checks progress without raw XIP pointers or a new executable window. Quad commands execute before core1 starts; mode changes run then or after its interrupt-masked SRAM acknowledgment. Core0 masks interrupts during direct QMI access, restores the old mode on a failed public-byte probe, and runs the full USB fence in SRAM if QMI cannot quiesce. Continuous reads are primed with one word before omitting EBh. A failed probe exits enhanced read before restoring QMI, then verifies the original mode; a failed restore probe fences USB. Only the allowlisted chip’s volatile QE bit is written, without WEL; unsupported protection layouts are refused.

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.

TrustZone transport build

These sites implement the mandatory Secure and Non-secure split. They are included in the runtime count above; their platform obligations and measured scope are explicit. See the TrustZone section.

24–38. Secure startup and worker ownership — PLAT-TZ-001

firmware/src/trustzone/mod.rs. Startup owns the core registers until the validated NS reset vector is entered. Secure boot, worker and display share one cooperative IRQ executor; LED and EP0 callbacks have separate owners. The launch sets banked masks and FP policy, then a C entry clears every shared GPR/FP register. The linker-size symbol is read by address only: an empty NS image halts before initialization, so the import-library ELF cannot launch stale NS flash. Dynamic S/NS/NSC bounds come from one build layout. The RP2350 A2 record covers launch and resource isolation; full FPU model fidelity remains separate.

tests/tz_hardware/nonsecure.rs adds four diagnostic sites: banked entry reads, its own MPU disable, and the selected LDR/STR. tests/tz_hardware/secure.rs adds the banked launch read and two SAU selector writes, restoring the selector afterwards. These templates compile only in a separate test checkout. Architectural snapshots and deliberately denied accesses need assembly or volatile pointers; NS reads outside the public data control are discarded, and the runner excludes OTP stores.

Safe alternative: the architecture exposes these launch registers and Embassy requires the interrupt callback; the wrapper supplies the one-owner transfer. Containment: startup-only writes, a Secure vector and stack, and an owned worker on one Secure executor.

39–44. Secure USB controller ownership and packet spans — PLAT-TZ-002

firmware/src/trustzone/usb.rs, firmware/src/trustzone/usb/control.rs and firmware/src/usb_fence.rs. The controller mutex owns endpoints and DPRAM; packet copies are at most 64 bytes and the complete NS RAM span passes TT before it becomes a slice. Clearing endpoint availability precedes the volatile DPRAM wipe. The EP0 pipe moves once to SWI_IRQ_2; only its bound handler services that executor. Epoch checks fence input and output at bus lifecycle changes.

Safe alternative: DPRAM wiping and CMSE pointer conversion require raw memory access; Embassy requires an IRQ callback and a Send wrapper for the single task transfer. Containment: Secure-only USB access, bounded packet copies, serialized checks and copies, and one owner for the control pipe.

45–46. Worker gateway spans — PLAT-TZ-003

firmware/src/worker.rs. The C veneer validates each complete span through the Secure TT helpers before calling the exported implementation. The worker copies input into its own exchange, bounds reply length, and wipes its Secure exchange at completion or abandonment. Output export is serialized with lifecycle observation; revocation wipes the temporary NS output before return.

Safe alternative: the CMSE C boundary carries raw pointers and integer lengths; Rust slices are created only after that boundary validates them. Containment: bounded copies, Secure-owned exchange state, generation tickets and USB epoch checks.

47–54. Non-secure local interrupts and USB task ownership — PLAT-TZ-004

firmware/trustzone/nonsecure/src/main.rs, firmware/trustzone/nonsecure/src/time.rs and firmware/trustzone/nonsecure/src/notify.rs. NS masks and restores only its core0 interrupt state. Its critical-section implementation does not acquire a Secure spinlock. SendUsb moves once to the NS interrupt task; handlers store state in NS-local synchronization. TIMER1 and SWI_IRQ_4 have their installed NS handlers before interrupt enable. SWI_IRQ_4 changes only an NS-local generation and waiter list; Secure pends it after publication and cleanup, without sharing a controller reference.

Safe alternative: the critical-section backend, interrupt enable and Embassy task transfer require these unsafe contracts. Containment: one core, one task owner, NS-local locks, and matching interrupt starters and handlers.

55–63. Non-secure calls to bounded Secure gateways — PLAT-TZ-005

firmware/trustzone/nonsecure/src/main.rs, firmware/trustzone/nonsecure/src/usb.rs, firmware/trustzone/nonsecure/src/session.rs and firmware/trustzone/nonsecure/src/keyboard.rs. Calls use the Cargo-shared numeric ABI. Secure checks selectors, complete NS RAM spans, lengths and epochs, copies packets and retains no NS pointer. Ticket abandonment fences dropped futures. Keyboard calls consume only output already authorized by Secure; a revoked session blocks export. Deliberately invalid startup pointers must be rejected by the gateway without a memory access.

Safe alternative: the C CMSE entries expose an unsafe FFI; their Rust callers cannot express the hardware span check in a reference type. Containment: Secure validation at every entry, integer tickets and epochs, bounded buffers and negative image probes.

The CMSE export attributes and FFI declarations are counted separately from runtime sites. firmware/src/trustzone/gateway.c supplies GCC-generated SG veneers and BXNS returns. These software checks do not establish complete silicon isolation or physical disconnect detection.

64. Secure MPU registers — PLAT-TZ-006

firmware/src/trustzone/mpu.rs writes only the current core’s architectural MPU registers during Secure startup or a serialized Secure flash call. The checked planner partitions SRAM without overlaps and refuses an invalid linker or stack range. The HAL copies trusted boot2 code to the stack; its bounded execution window runs with NS interrupts masked and restores the MPU before unmasking. Safe alternative: the architectural bank aliases are MMIO; the existing PAC has no typed bank API covering this setup. Containment: Secure-only calls, aligned checked regions, bounded stack code and an RAII restore on every normal return, including flash errors. Panic/fault recovery and hardware timing still require their own validation.

65. Hostile NS image probe — PLAT-TZ-007

firmware/trustzone/nonsecure/src/probe.rs is feature-gated test code that disables its own NS MPU, then deliberately reads or writes protected memory/MMIO. The Secure policy remains intact. Its exported marker and target contain no secret and live in NS RAM; a zero target waits for the emulator’s resource selection. Safe alternative: a deliberate denied access needs raw memory; a named assembly instruction lets the runner distinguish a real word load from a word store. Containment: disposable emulator-only image; exact instruction, marker and fault assertions, a completion barrier and relaxed-grant falsifiers; excluded from normal builds.

66–67. Fatal Secure exception — PLAT-TZ-008

firmware/src/trustzone/fault.rs never resumes an interrupted worker or borrows its state. The fatal latch rejects all gateways; direct S-owned MMIO detaches USB and clears pending DPRAM before the terminal loop. The exported stop symbol lets the image backend execute that cleanup before declaring the image dead. tests/tz_hardware/secure.rs::read uses volatile reads of public core/MMIO registers and the bounded USB payload to record the fatal fence. It never exports key memory or borrows interrupted owners. The disposable diagnostic adds a watchdog after the production fence; retained public words use scratch 0, 1 and 3, preserving the PIN-lock and ROM-owned slots. The ordinary fatal path remains terminal.

Safe alternative: the exception ABI requires an unsafe handler; normal Worker::reboot cannot safely borrow an arbitrarily interrupted worker. Containment: no reboot, flash/OTP write or unsafe RAM alias; terminal admission until cold boot. This path fences authorization but does not claim SRAM wiping.

68. Uncached page-state byte reads — PLAT-UNSAFE-015

firmware/src/flash_storage/stream.rs::read_uncached reads one byte through the RP2350 translated uncached alias at 0x14000000, as defined by the pico-sdk 2.2.0 address map. The host-tested byte and pair helpers check every offset against the configured chip before either hardware callback. A compile-time bound keeps the complete chip inside the alias window; SharedFlash retains its exclusive borrow. Safe alternative: the existing cached HAL read is correct but fills cache lines for small page-state probes. The new path reads the same translated address with the existing permissions. Containment: one volatile u8 load, initialized flash bytes, byte alignment, no MMIO stores, no new grants, and unchanged authority, root and payload checks. The byte load has no software deadline and a bus fault is not a flash error. A fatal Secure exception uses the USB fence before stopping.

69–71. Full response-buffer wiping — PLAT-UNSAFE-016

Safe alternative: byte-wise Zeroize clears the same arrays but repeats a volatile store and loop step for every byte. Word stores require validated alignment, exclusive access and exact byte edges.

Containment: firmware/src/sweep/buffer.rs::wipe_bytes lends exclusively borrowed SRAM to align_to_mut::<u32>. Every bit pattern is valid for either element type; the disjoint byte edges and aligned middle cover exactly the original slice. Volatile stores clear both byte edges, eight words per full pass and all remaining words, followed by a sequentially consistent compiler fence. The worker passes both complete response arrays after copying the reply; neither the buffer extent nor the existing dead-stack sweep and publication ordering changes.

The Secure USB gateway owns its initialized 64-byte packet in Secret<Packet64>. Once created, its exhaustive Zeroize delegates the complete array to this primitive on every exit, including empty and refused operations, before releasing serialization. No filled packet is moved or returned, and no wipe is narrowed to the data length.

The Non-secure exchange gateway uses the same primitive through a borrowed ReplyGuard. It borrows the complete ABI-sized span from one buffer under the exchange mutex, up to 7612 bytes, and clears it on completion, abandonment and future Drop before releasing the pending ticket. The host reply-buffer harness covers alignments, byte edges, canaries, errors and pending-future destruction. These are three shared source sites compiled in both worlds; no new pointer primitive or smaller wipe is added.

The same borrowed guard clears the complete 64-byte packets in Non-secure EndpointIn::write and ControlPipe::data_in on completion, errors and future Drop. Their initialized buffers and guard lifetimes, including the existing control abandonment and epoch checks, are unchanged.

72–76. Scratch SRAM code initialization — PLAT-TZ-009

firmware/src/trustzone/mod.rs::initialize_scratch_code copies one linker-bounded flash section into disjoint SRAM8/9 before the executor, core1 or Non-secure code starts. The section includes zero padding through the end of SRAM; no old RAM bytes become executable. DSB/ISB precede execution. Both cores subsequently map the complete section read-only executable, including during flash operations. tests/tz_hardware/secure.rs adds four runtime sites: linker-bounded immutable code/load slices, separate controlled Secure LDR/STR operations and an MPU selector helper which restores the selector. Its linker imports and scratch execution placement also require explicit unsafe contracts. Secure probes select only three public scratch addresses. The diagnostic verifies the full copy, actual processor and flash MPU window; it is compiled only in the separate checkout. Assembly and raw linker/register addresses are needed to test these hardware permissions.

Safe alternative: the discontiguous linker destination is not owned by a Rust value or covered by the ordinary runtime data-copy range. Containment: one startup call, linker size and overlap assertions, no mutable alias after initialization, and no change to shared RAM or existing capacities.

77. Core0 flash context — PLAT-UNSAFE-017

firmware/src/flash_storage.rs implements Sync for the private Core0Context, holding the flash/SHA/QMI/backend references in Cell<Option<Context>>. The context accessors check SIO.CPUID == 0 before touching the cell; the backend accessor checks through get before borrowing the referenced RefCell. Installation is single-shot, before storage boot and USB admission; later operations only copy the installed references to the existing static flash, SHA, QMI and backend RefCells. Core1 fails before cell access.

Safe alternative: storing the references in every flash handle prevents compile-time construction of the large backend. A global lock over the flash operations would change interrupt and borrowing behavior. The context holds immutable references; the peripherals and backend retain checked borrows. Containment: the cells and context type are private, no accessor returns a reference to its Option, and the non-Send references and backend borrow cannot be transferred between Rust threads. The static backend is bound to its runtime key source once; unbound operations fail before flash I/O.

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 modexp, sieve and primality primitives — the modexp on both of its callers, the prime search and the sign_crt that PIV GENERAL AUTHENTICATE and OpenPGP PSO:CDS / INTERNAL AUTHENTICATE / DECIPHER reach over USB against a long-lived key.

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

The audit checks the machine code of the comparisons used for PINs, MACs and access codes. It also covers private RSA operations reachable over USB. The constant-time comparison loops branch on public lengths. The audit findings record the old RSA fallback and OTP access-code defects.

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.

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 — one helper inside rsk-rsa draws a fresh r around every secret-exponent modexp, fixed-width CRT and software alike, and with the fix above so was the raw fallback, until 0x0A4F removed it. (Re-checked at 0.4.12, when the operation moved off rsa 0.9.10’s own blind/unblind.)
  • 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.

What the image says

Read out of target/trustzone/combined.elf with arm-none-eabi-objdump -d -l --inlines, built by clang LLVM (rustc version 1.99.1 (58cf8f9c3)). A site’s verdict is constant-time when no conditional branch inside any address run the inline chain attributes to it reads flags set from a buffer load; the callers are the first-party frames those chains name, so a surface that stops routing through the site leaves this table.

SiteClassVerdictSurfaces that inline it
rsk_crypto::mac::ct_eqcomparatorconstant-timeOATH SET CODE, OATH VALIDATE, OATH PIN match helper, OATH PIN-gated code match, OTP applet APDU dispatch onto the access-code comparator, OTP slot configure access code, OTP command dispatch access code, OTP slot swap access code, OTP slot swap access code, inner, OTP slot update access code, OTP access-code sweep, PIV slot metadata default-value check, PIV mutual authenticate, PIV single authenticate, storage v2 root-bound SHA prefix before extending an authenticated append, mounted storage root equality before same-arm snapshot replacement, the mounted directory binding on a warm backend read, the exact mounted context for volatile read-tag hints, fresh root binding for storage v2 cached main authority reads, the full mounted directory binding with a command-local HMAC context, the full mounted directory binding with a command-local HMAC context, storage v2 freshly read complete journal against the exact expected append, storage v2 authority-header MAC at boot and before persistent operations, PIN/HOTP counter entry identity before copying its physical frame, storage v2 complete counter-bank authentication before counter reads or updates, storage v2 counter checkpoint publication and full-set digest validation, storage v2 counter checkpoint publication and full-set digest validation, storage v2 counter checkpoint publication and full-set digest validation, PIN/HOTP entry, payload and padding equality across both physical replicas, PIN/HOTP entry, payload and padding equality across both physical replicas, fresh-root counter proof and complete-bank equality for public counter reads, PIN/HOTP mounted authority lookup before counter reads, the fresh complete counter-bank fingerprint match before mounted-directory reuse, fresh-root authenticated counter reads and failure invalidation, storage v2 replicated counter authority agreement and recovery, storage v2 fresh counter-bank fingerprints and root binding before mounted-directory reuse, storage v2 freshly observed counter-bank fingerprints before mounted-directory reuse, storage v2 replicated counter authority agreement after complete replay, counter authority context equality before returning a mounted proof, the cached counter authority context match during proof lookup, fresh-root complete counter payload authentication before returning bytes, counter payload tag equality with the current authority context, counter payload MAC equality under its authenticated entry and authority, attended storage v2 legacy-import manifest authentication, attended storage v2 legacy-import root, epoch and frozen-set validation, storage v2 main authority checkpoint and complete-directory validation, storage v2 complete physical bank fingerprints before reusing mounted state for mutation, the fresh-root complete payload proof before returning backend bytes, the optional cached complete-payload tag match on a backend read, storage v2 main authority selection and repeated recovery, storage v2 main journal directory agreement during resolution and recovery, the fresh-root mounted proof before absence or recovery, binding volatile read tags to the exact mounted authority, mounted-context equality before retaining volatile read tags, mounted-context equality before reusing a complete-payload tag, the cached context match for a complete-payload tag lookup, mounted-context equality before remembering a complete-payload tag, the cached context match for complete-payload tag insertion, mounted-context equality before reusing a mounted-authority tag, the cached context match for a mounted-authority tag lookup, storage v2 full-value MAC before decoding stored security records, the complete stored payload and expected entry, the complete stored payload and expected entry, the complete stored payload with a command-local HMAC context, storage v2 authenticated main write/delete transaction decoding, storage v2 main transaction chain and publication validation, CTAP pinUvAuthProtocol MAC verify, management configuration lock code verify, FIDO device-local PIN verify, FIDO’s forwarder onto the canonical comparator, FIDO device-PIN hash verify, FIDO clientPIN hash verify, panel path, FIDO clientPIN hash verify, FIDO credential key-handle verify, vendor device-PIN gate, pad path, vendor device-PIN gate, OATH’s forwarder onto the canonical comparator, OpenPGP default reset-code neutralisation, OpenPGP PW1/PW3/RC verify, OpenPGP’s forwarder onto the canonical comparator, PIV PIN/PUK reference verify, PIV’s forwarder onto the canonical comparator, storage v2 counter scan engine complete-directory digest verification, storage v2 main journal replay and complete-directory validation

What holds which half of this page. Only the table above is derived: scripts/ct_gate.py rebuilds it from the image on every gate run, and the row goes red when a surface stops routing through the comparator or a new one starts. The prose around it is held by almost nothing — claims_gate fires only on a sentence naming a registered SEC-… id, and this page names none. Measured with a refuted scope sentence in place: the claims, run-count and constant-time gates and docs.sh check were all exit 0, and the citation gate, red that day over line drift in other files, said nothing about this page. The single exception is the scope paragraph at the top of this page. ct_gate anchors on its rsk-rsa clause and asks three things of the paragraph that carries it: it must name the modexp and the sign_crt that reaches it over USB, it may not re-scope them to key generation, and it may not be one of two paragraphs carrying the anchor, because an earlier one would shield it. Anchored instead on a sentence five lines above the clause and refusing one spelling of one word, the rule was walked past thirteen ways — a synonym, eight spellings, the clause moved into a list, a decoy paragraph, and an editor inserting a blank line. Nothing holds the findings table, the residuals, or this sentence.

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

  • The RSA private operation is now entirely in-tree. The rsa crate left in 0.4.12 and RUSTSEC-2023-0071 (“Marvin”) with it, so that residual is closed as a dependency question — but the mitigation it named is what remains load-bearing: every private-key path, including CRT, is base-blinded per operation, and none of them is exempt. See threat-model.md.

  • RSA-2048 blinding inversion uses variable-time Lehmer batches with an exact Euclidean fallback. The operands are the fresh random blinding factor and the public modulus. Private exponentiation and the final Bellcore check use the existing schedules.

  • rsk-rsa modexp secret-indexed window lookup: the window index is a secret nibble — of the candidate in the keygen prime search, and of dP/dQ in sign_crt. Both reach privexp::backend::pow on the device. The index folds into the table’s base pointer. The instruction sequence is independent of the nibble’s value; only the address changes (crates/rsk-rsa/src/privexp.rs, the &table[index * w..][..w] input to mul).

    There is no XIP-cache channel — and not because the core is cacheless. The RP2350 does put a cache in front of its QSPI flash, and it is load-bearing enough that hot loops were moved out of XIP to escape it (architecture.md, limitations.md, testing.md). That cache sits on the flash path, and neither end of this access is on it. The table is in scratch, a stack buffer in crates/rsk-rsa/src/privexp.rs, and every stack it can sit on is SRAM: core0’s, which the linker bounds with _stack_end and _stack_start, and — for the keygen half, which core1 runs too — core1’s CORE1_STACK (firmware/src/core1.rs), a .bss static outside that pair and SRAM by the same script. The code that reads it is SRAM-resident by link section. Rust places the private window loop in .data.bignum_hl with the conversion to Montgomery form. The arithmetic kernels occupy the other .data.bignum_* input sections. The public exponentiation schedule lives in flash and calls the same SRAM arithmetic. The CRT wrapper prepares and combines residues outside the SRAM window loop.

    What that does not settle. An SRAM access is not a cache access, but it is not nothing. Two mechanisms could still turn the address into a time, and this audit measures neither: SRAM banking, and data-dependent multiplier latency inside mul_acc. The banking half is an assumption and not a finding — if the bank a cycle touches follows the address, then a secret nibble picks it, and nothing in this tree establishes that. It is the conservative reading of the SoC’s memory organisation; the nearest in-tree note (firmware/src/core1.rs, the core1-stats counters) is about cross-core XIP/bus contention rather than SRAM banks, and citing it here would be citing the wrong thing. Deciding either mechanism needs the instrumented hardware harness Coverage & limits asks for, and both are unmeasured here in both directions. Physical EM/power capture stays out of scope (threat-model.md). What is no longer claimed is the bound: the CRT path is reached over USB and runs on a long-lived dP/dQ, so this is not a one-shot keygen event, and the base blinding above does not answer it — blinding randomizes the base, not the exponent nibbles that choose the window. Concurrency belongs to the keygen half alone: the prime filter races this modexp on both cores, and core1 takes nothing but keygen jobs (firmware/src/core1.rs), so the USB-reachable sign/decrypt path runs it single-core. A fixed-address selection would require a separate change to the Rust table selection and new verification of the emitted code.

    Severity: LOW, recorded rather than left pending. It is registered as PLAT-CRYPTO-002 in platform-assumptions.md with the four surfaces, the blinding gap, the absent cache channel and the triggers that re-open it. What makes it low is the OBSERVATION and not the code: recovering the window sequence needs a time-resolved look inside one operation, and no in-scope observer has one. On all four surfaces the private operation runs to completion before any response byte leaves, and the 61xx / GET RESPONSE chaining that may follow is transport-level (crates/rsk-device/src/ccid.rs) over a buffer already computed — so a host measures a single end-to-end latency, and the exponent is fixed for the life of the key, so that latency is the same scalar for every signature and carries nothing about which nibble sat where. The observer that would hold a time-resolved trace is the power/EM prober threat-model.md §4 puts out of scope. Two things keep this a residual rather than a non-issue. Nothing has measured whether an RP2350 SRAM read’s cycle count follows its address at all — the paragraph above says so, in both directions. And the arithmetic that stands in for that measurement is a bound and not a result: the sixteen entries are temp + k·half with half a multiple of 32 bytes, so they share every address bit below 32 and each read is a contiguous multiple-of-32-byte run, which no stripe whose period divides 32 bytes can tell apart and which a high-bit-selected bank holds whole at ≤ 4 KiB.

    The fixed-address lookup remains deferred in PLAT-BUILD-005. The unused assembly lookup is excluded by CONSTANT_MEMORY_ACCESS_PATTERN=0. The Rust port continues to select a table entry directly.

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 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 — physical capture of the modexp window-lookup access pattern, and any DPA on the secure-boot AES, both already noted in the threat model. What is out of scope is the capture. The lookup itself is not keygen-only: its USB-reachable half stands open and unmeasured under Documented residuals, not excluded.
  • Third-party crate internals (RustCrypto, num-bigint-dig) were audited only at the usage boundary. Their own CT properties are inherited from upstream — num-bigint-dig’s exponentiation is variable-time, which is what the blinding above exists to answer for.

Formal model

formal/ in the repository holds a TLA+ model of the authenticator’s security state, the mutation matrix that keeps it falsifiable, and the registry that ties its properties to the code. This page is the map; the deep prose — every abstraction with its direction, every hole a review found and what closing it cost — lives in formal/README.md next to the model itself.

RS-Key is not formally verified, and the model’s own page opens by saying so. What exists is narrower and it is measured: the paragraph to quote is in Testing, under “Formal claims — what is and is not verified”.

The nine modules

RSKeySecurityState.tla models the FIDO security state: PIN retries, the pinUvAuthToken and its permissions, which transport owns the touch, which channel owns a stateful walk, the reset window, the persistent gate records, and the position at which power is lost inside a multi-write flash sequence. TLC checks its invariants exhaustively at small constants.

RSKeyAppletSeams.tla models what the first module deliberately leaves out: the applets’ access statuses — PIV, OpenPGP and OATH’s seven doors, what a SELECT means for each, what a refused authentication costs, and the access-code removal gate.

RSKeyStore.tla models the flash layer one level beneath both — rsk-fs’s key/value store over a Storage backend: whether a torn delete can orphan a file’s metadata, and whether the in-RAM present-cache can read a committed key as absent. It is a lift of the Rust power-cut oracle (powercut.rs) that had been reachable only by the fuzzer, and it is the store model the roadmap’s refinement pilot inducts its persistent-state invariant over.

RSKeyRetryLattice.tla models the retry & recovery budget lattice of the two applets that have one — PIV (PIN, PUK) and OpenPGP (PW1, PW3, RC): the finite counter behind each reference, the maximum it is refilled to, the recovery reference that refills it, OpenPGP’s SET PIN RETRIES (which refills PW1, the RC and PW3 under PW3’s status, a new maximum each), and the anti-bruteforce arithmetic that is identical at every one. It is the part of the applet surface with no safe oracle — exhausting a real PUK ladder blocks the card and the only way back takes the keys — so an exhaustive check of every verify/block/recover interleaving can run only in a model.

RSKeyAppletPolicies.tla covers the four applets’ remaining stateful doors: PIV NEVER/ONCE/ALWAYS slot policy and freshness spending, OpenPGP algorithm- attribute invalidation, OATH access-code plus touch gates, and Yubico OTP slot- code mutation plus its combined use/session replay position. OATH and OTP codes have no retry counter; keeping this separate avoids proving invented budgets. All four fit in one exhaustive graph: 2,268 distinct states at depth 14.

RSKeyAdminSurface.tla models the surface above all of them: the enabled-applications mask, the always-on carve-out that keeps ykman config usb --disable reversible, and the operator-presence gate on the privileged rescue commands. Two of its four mutants rebuild defects that actually shipped — the mask that was a DeviceInfo report rather than an enforcement, and the lock-code write that silently re-enabled every disabled application.

RSKeyTrustedDisplay.tla models the confirm ceremony — the display build’s anti-phishing promise, what is confirmed is what is shown, as three machine-checkable rules: an RP-naming operation completes only through the card that names it, a press that predates the card approves nothing, and no exit but a deliberate Allow ever reads as Confirmed. Two of its three mutants are shipped display-build defects.

RSKeyBootHardening.tla models the two machines at the reset line — the one-shot at-rest scrub lap (EF_HARDENED never lies about superseded weak-sealed copies, and every lazy re-key or delete re-arms it) and the scratch-word lock carry (a warm reset moves the whole soft lock, never half of it). It exists because firmware/ has no host tests by construction: the model is the only instrument that exercises these interleavings. Its PowerOnClearsScratch2 assumption is deliberately explicit and still awaits an RP2350 hardware measurement; TLC does not turn it into a hardware fact.

RSKeyTransport.tla models the CTAPHID frame reassembler — the channel, sequence and length checks a multi-frame message passes before dispatch: one host application’s continuation never assembles into another’s message, an out-of-order frame aborts rather than fills the gap, and a declared length never overruns the buffer. It is already unit-tested and fuzzed per frame; the model checks the invariants that live in the interleaving, which those do not assert.

Refinement pilots

The token pilot connects a small abstract token machine to the detailed FIDO model and a bounded projection of FidoState. The cross-reset pilot closes the deliberately deferred reboot seam for ResetNeverWeakensSurvivingState: concrete reset phases share the production FID classifier, Kani proves the finite projection inductive, and the existing rsk-fs oracle drives the full reset through byte-granular power cuts. The real-board script is a destructive witness, not a proof, and its presence in the evidence graph does not assert that a current hardware run passed.

Neither pilot covers NoAuthorizationBypass, which is the property those two were rehearsals for. The authorization slice design writes down its A/B/C maps, callers, assumptions, bounds, mutants and exit before any of that proof code exists — a plan and a measurement contract, not evidence.

Trace validation

The models’ fidelity to the code is kept by hand — citations, mutants, co-refutation — and one thing none of that measures is whether the code as it runs stays inside a model’s behaviors. TraceSeams.tla closes that empirically: a real session recorded from the software emulator is replayed against the applet-seams model step by step, and a step the model refuses is a TLC deadlock at that exact position. A second, hand-written session the model must reject is required to go red, so the replay harness is proven able to refuse. A green replay is evidence about the recorded sessions, not a proof about all runs; coverage grows by recording richer sessions.

Which image a claim is about

Every statement above says “the firmware”, and the firmware is nineteen flake packages, six cargo features no package expresses, and six board presets under both. The assurance matrix is the per-configuration disposition — generated from those three sources and the property registry, so a new image arrives as a column of declared gaps instead of as silence.

Which threat a claim is against

The threat model is the root every chain above hangs from, and naming the page names no threat. Each P0-family property cites a clause of it — docs/threat-model.md#TM-…, an id of assurance/threat_clauses.toml, whose entries are held one-to-one against the page’s own headings and bullets so a new clause cannot arrive unclassified. A property with no clause is a recorded finding rather than a blank, and says which of two things it is: the page is missing a threat this tree defends against, or the property is against nothing. The other direction is printed on every run — a stated defence that no property answers is the same finding from the other end.

The checks of the checks

An invariant no defect can violate is the TLA+ analogue of a test that cannot fail, and this tree has been bitten by that class enough times to check for it mechanically:

  • every invariant carries mutants — each Bug* switch rebuilds a real RS-Key defect or removes a defence the tree has, and its Solo_*.cfg run must come back RED;
  • every green run has a floor (formal/floors.txt) — a GREEN that got smaller than its recorded distinct-state count is reported as FLOOR, because a collapsed state space passes every invariant vacuously and once did;
  • a vacuous run is named — a spec nothing enabled exits non-zero rather than reading as a pass;
  • every scope constant carries a measured minimum (formal/scopes.txt) — the floor watches the search, this watches the CONSTANTS the search runs over. Three mutants are GREEN one element below the shipped scope: two need a second channel to have somebody to splice into, one needs a second FID to have a record worth losing. A configuration below its recorded minimum is refused;
  • the source is linted first — two TLA+ traps that leave a spec well-formed and meaningless (a precedence slip turning an assignment into a guard, an action pinned to a no-op by its own UNCHANGED) are refused before TLC runs.

scripts/test_run_tlc.py keeps the runner itself falsifiable in the merge gate. Its four artificial corruptions are a broken jar, a Solo invariant that misses its mutant, a one-state VACUOUS run, and a muted Mut switch. Direct RED and FLOOR cases keep all three job verdict boundaries explicit, and four more hold every reader of a log that has a NUL hole in it — the state where a finished 48.7 M-state GREEN was reported VACUOUS. The last hold TLC’s metadir, which it names after the current second: a start in the second a run refuted in its initial state left its directory in is not refused, between two runs or between the rows of one tier, no metadir outlives the runner, and each part of that is cut out of the runner once to watch its case fall.

Co-refutation

TLC proving that a model invariant rejects a defect does not show that the production tests reject the same defect. scripts/comutate.py closes that gap: each model mutant is an exact patch that re-injects the same semantic defect into Rust, then runs the smallest relevant host-test slice in a throwaway git worktree. A failing test is co-refuted; a green slice is an abstraction gap; a defect made impossible by a shipped structural fix is unreachable only with recorded evidence. A compile failure is never counted as a kill.

The phase-2 denominator is the FIDO mutant roster, and it MOVES with that roster rather than standing at the roadmap’s original 28 — it is 31 now. The generated table in formal/README.md records every one, its target invariant, its model verdict and its code-level verdict: 30 of 31 are co-refuted, one is unreachable, and none is a gap. Deriving that roster found six real coverage gaps; each now has a regression harness. Later modules extend the live roster to 103 entries: all 97 executable patches are killed, and six are unreachable.

The applet batch — the 24 seam, retry-lattice and policy mutants — was added because the roster had a measurable skew: 31 of its first 43 patches sat in three crates, and the four applet crates four of the nine modules are written about held none. Measuring them found three more coverage gaps — including the Rust half of SEC-SEAM-006, whose model half had been closed two revisions earlier — each now closed by a regression harness. Two further gap verdicts turned out to be the batch’s own defects rather than the tree’s: an adversarial review found both patches modelled a different defect from the switch they were named after, and the faithful versions are unreachable — defence in depth whose removal changes nothing observable. A red run is not evidence until the reason it went red is read.

The assurance gate cheaply checks the closed roster, patch anchors, expectations, floors and generated table freshness. The expensive full measurement runs weekly next to cargo-mutants; run --write-readme publishes the 28-row table only after measuring every executable phase-2 patch.

The registry

Every property TLC checks has an entry in assurance/properties.toml — id, statement, source and status, nothing else hand-written. A check-assurance.sh row, scripts/assurance_gate.py, derives the rest per run: which module defines the property, which configurations check it, which mutants target it, which Kani harnesses, fuzz targets, Rust files and device tests carry its name. The gate holds the graph closed in both directions — nothing TLC checks may be unregistered, nothing registered may be unchecked — and a status must equal the evidence ceiling: a Kani harness carrying the property’s name forces BOUNDED, and PROVEN is refused until that evidence class exists in the tree.

The owner functions carry the property back into the code: a doc line of the form Refines `RSKeySecurityState!NoTokenAfterInvalidation` — SEC-FIDO-003 sits on each function the model’s ownership table names, the gate validates every tag, and every invariant in every shipped baseline configuration must be named in production Rust somewhere. Firmware sources count as owners for the boot module. The shared check runs from both assurance_gate.py and citation_gate.py.

The evidence table and 28-member workspace coverage ledger in formal/README.md are generated from that same audit. Cross-model Supports tags close the two FIDO properties whose persistent half is owned by the store module. The ordinary gate rejects a stale block; regenerate it after evidence moves with python scripts/assurance_gate.py --write-readme.

assurance/crates.toml is the same discipline one level up: all 28 workspace members classified — state modelled, modelled in part with the gap named, unmodelled with the roadmap module named, pure with the differential or proof files named, or out of scope with a reason. The ledger exists because enumerating crates from memory has already missed four of them.

Running it

nix develop                       # pins TLC and exports TLA2TOOLS_JAR
cd formal
./run-tlc.sh safety               # model + mutants + floors: the tier CI runs
./run-tlc.sh liveness             # the temporal half, at the heap floors.txt gives it
./run-tlc.sh all                  # both
./run-tlc.sh Shipped.cfg          # one configuration
./run-tlc.sh --tiers              # what each tier runs, for the gate
TLC_SHARD=2/3 ./run-tlc.sh safety # one shard of it, the way the weekly job runs
python3 ../scripts/assurance_gate.py   # the registry, held against the tree
python3 ../scripts/assurance_gate.py --write-readme  # refresh its README table
python3 ../scripts/comutate.py --lint  # closed roster + patch/table freshness
python3 ../scripts/comutate.py run     # re-inject the whole live defect roster
python3 ../scripts/comutate.py run --write-readme  # measure + refresh its table
python3 ../scripts/run_count_gate.py --record <log>  # keep a roster run's matrix

Both timings are from recorded runs on an Apple M5 Pro (18 cores) at the default WORKERS=2: safety over 262 configurations in 9469 s and liveness over 4 in 3185 s — 27 GREEN, 239 RED, no row short of its floor.

The measurements come from the runner’s run records. CI runs the safety tier on the schedule and path filters in deep-checks.yml. Run liveness locally with the heap settings in formal/floors.txt. The registry and co-refutation lint gates run on every pull request as part of check-assurance.sh; the full co-refutation roster runs weekly.

Assurance matrix

RS-Key is not formally verified. This page is generated from the registry and reports what evidence exists, not that a whole-system theorem does. The Definition of done keeps this sentence a requirement until one exists, and scripts/claims_gate.py holds every page naming three or more registered properties to it. What is out of scope and what is accepted: limitations and the threat model.

Which security property is claimed about which buildable image. The rows are the P0-family properties of assurance/properties.toml; the columns are derived from nix/firmware.nix, firmware/Cargo.toml and firmware/boards/, so a new package, feature or board arrives as a column of gap cells rather than as silence. scripts/matrix_gate.py regenerates this page and scripts/check.sh diffs it.

The point of the page is the thing a single-build claim hides: the firmware is not one thing. Four of the nineteen images remove the physical-consent gate the authorization properties are about, one swaps the CTAP large-blob surface with no flake package at all, and the board axis changes the flash geometry on which a whole KV store once survived a “successful” wipe.

These are the committed configurations, not the buildable ones. Every mkFirmware knob falls back to a like-named environment variable and lib.mkFirmware is exported, so FLASH_SIZE=2M nix build --impure .#firmware is an image no column below describes — including under a disposition whose reason says “no cargo feature and no build knob”. What this page disposes of is what the flake ships and what CI builds; a one-off --impure combination is outside it by construction.

DispositionCodeMeans
coveredcovthe evidence the registry records was produced on this configuration; outside the legacy evidence baseline the cell names the check.sh rows, and the gate re-derives both that they build THIS image and that they ran evidence the registry actually derives for the property — a Kani harness, a fuzz target or a tests/*.py, never a crate’s unit tests
equivalentequthis configuration enables exactly the cargo features another does; same_as names it, the gate re-derives both closures, and the cell must write down the build knobs that still differ
conditionalcndclaimed only under a stated condition
out-of-scopeoosthe claim is not made here — the code it is about is absent, or the gate it is about is compiled out
gapgapnobody has decided yet; the column’s settling question is below

The retained default-build basis refers to the featureless legacy evidence baseline. It has no current buildable column; dated bundles retain its scope. TrustZone is mandatory. Its independently built Non-secure closure is compared separately (NS: below), including the OTP strict-config policy. Changing the default does not promote earlier legacy evidence to TrustZone. The direct-Cargo evidence reader cannot establish a composed TrustZone run.

The axes

  • 20 flake packages (nix/firmware.nix), of which 14 are published by .github/workflows/release-build.yml — the published set is a named subset of the matrix, never the matrix.
  • 7 orthogonal cargo features (firmware/Cargo.toml) that no flake package expresses.
  • 6 board presets (firmware/boards/*.toml): BOARD=<name> sets the same knobs the flake arguments do, and no cargo feature.

Columns

The last cell is DERIVED, not declared: the per-crate cargo-feature closure this column resolves to, against the featureless TrustZone comparison baseline’s. It is the same derivation the equivalent rule refuses a cell on, so a column reading — there compiles the workspace exactly as that comparison baseline does and its whole delta is knobs — and a column that names a crate has that crate’s code moving under every row of its column, which is the fact a gap there is about.

#ConfigurationKindPublishedCargo featuresBuild mode / knobsCompiles unlike the comparison baseline
01firmwarepackageyes—trustzone=true—
02firmware-no-touchpackagenono-touchtrustzone=truefirmware +no-touch
03firmware-fipspackageyesfips-profiletrustzone=truefirmware +fips-profile, rsk-fido +fips-profile, rsk-piv +fips-profile
04firmware-pqcpackageyesadvertise-pqctrustzone=truefirmware +advertise-pqc, rsk-fido +advertise-pqc
05firmware-fips-pqcpackageyesadvertise-pqc, fips-profiletrustzone=truefirmware +advertise-pqc +fips-profile, rsk-fido +advertise-pqc +fips-profile, rsk-piv +fips-profile
06firmware-no-touch-pqcpackagenoadvertise-pqc, no-touchtrustzone=truefirmware +advertise-pqc +no-touch, rsk-fido +advertise-pqc
07firmware-no-touch-fipspackagenofips-profile, no-touchtrustzone=truefirmware +fips-profile +no-touch, rsk-fido +fips-profile, rsk-piv +fips-profile
08firmware-no-touch-fips-pqcpackagenoadvertise-pqc, fips-profile, no-touchtrustzone=truefirmware +advertise-pqc +fips-profile +no-touch, rsk-fido +advertise-pqc +fips-profile, rsk-piv +fips-profile
09firmware-strong-pinpackageyesstrong-pintrustzone=truefirmware +strong-pin, rsk-fido +strong-pin
10firmware-strong-pin-pqcpackageyesadvertise-pqc, strong-pintrustzone=truefirmware +advertise-pqc +strong-pin, rsk-fido +advertise-pqc +strong-pin
11firmware-always-uvpackageyesalways-uvtrustzone=truefirmware +always-uv, rsk-fido +always-uv
12firmware-always-uv-pqcpackageyesadvertise-pqc, always-uvtrustzone=truefirmware +advertise-pqc +always-uv, rsk-fido +advertise-pqc +always-uv
13firmware-strict-uppackageyesstrict-uptrustzone=truefirmware +strict-up, rsk-fido +strict-up
14firmware-strict-up-pqcpackageyesadvertise-pqc, strict-uptrustzone=truefirmware +advertise-pqc +strict-up, rsk-fido +advertise-pqc +strict-up
15firmware-picopackageno—trustzone=true, vidpid=Pico—
16firmware-displaypackageyesdisplaytrustzone=true, flashSize=16M, ledKind=nonefirmware +display, rsk-bip39 (added), rsk-device +display, rsk-display (added), rsk-slip39 (added), rsk-ui (added)
17firmware-display-v2packagenodisplaytrustzone=true, flashSize=16M, ledKind=none, tpChip=cst3530firmware +display, rsk-bip39 (added), rsk-device +display, rsk-display (added), rsk-slip39 (added), rsk-ui (added)
18firmware-2mbpackageyes—trustzone=true, flashSize=2M, kvmain=896K—
19firmware-16mbpackageyes—trustzone=true, flashSize=16M—
20firmware-strict-configpackageyesstrict-configtrustzone=truefirmware +strict-config, rsk-device +strict-config, rsk-fido +strict-config, rsk-mgmt +strict-config, rsk-otp +strict-config, rsk-vendor +strict-config, NS:firmware-ns +strict-config, NS:rsk-otp +strict-config
21keygen-benchfeaturen/akeygen-benchtrustzone=truefirmware +keygen-bench
22core1-statsfeaturen/acore1-statstrustzone=truefirmware +core1-stats
23benchfeaturen/abenchtrustzone=truefirmware +bench, rsk-bench (added), rsk-fido +bench
24fido-conformancefeaturen/afido-conformancetrustzone=truefirmware +fido-conformance, rsk-fido +fido-conformance +strict-up
25ea-conformance-rpidfeaturen/aea-conformance-rpidtrustzone=truefirmware +ea-conformance-rpid, rsk-fido +ea-conformance-rpid +fido-conformance +strict-up
26largeblob-extfeaturen/alargeblob-exttrustzone=truefirmware +largeblob-ext, rsk-fido +largeblob-ext
27preview-signfeaturen/apreview-signtrustzone=truefirmware +preview-sign, rsk-fido +preview-sign
28abrobot-16mboardn/a—trustzone=true, flash.kvmain_kb=1408, flash.size_mb=16, led.kind=ws2812, led.max_leds=4, led.order=grb, led.pin=16, presence.active_high=False, presence.pin=23, presence.source=gpio, usb.vidpid=RSKey—
29abrobot-4mboardn/a—trustzone=true, flash.kvmain_kb=1408, flash.size_mb=4, led.kind=ws2812, led.max_leds=4, led.order=grb, led.pin=16, presence.active_high=False, presence.pin=23, presence.source=gpio, usb.vidpid=RSKey—
30seeed-xiaoboardn/a—trustzone=true, flash.kvmain_kb=896, flash.size_mb=2, led.kind=ws2812, led.order=grb, led.pin=22, led.power_pin=23, presence.source=bootsel, usb.vidpid=RSKey, usr_led.active_high=False, usr_led.pin=25—
31tenstar-usbboardn/a—trustzone=true, flash.kvmain_kb=1408, flash.size_mb=16, led.kind=ws2812, led.order=grb, led.pin=22, presence.source=bootsel, usb.vidpid=RSKey—
32waveshare-oneboardn/a—trustzone=true, flash.kvmain_kb=1408, flash.size_mb=4, led.kind=ws2812, led.order=rgb, led.pin=16, presence.source=bootsel, usb.vidpid=RSKey—
33waveshare-touch-lcdboardn/a—trustzone=true, display.bl_pin=16, display.bl_pwm_channel=A, display.bl_pwm_slice=0, display.cs=13, display.dc=14, display.rst=15, display.spi_freq_hz=80000000, display.tp_chip=cst328, display.tp_rst=17, display.wake_active_high=False, display.wake_pin=25, flash.kvmain_kb=1408, flash.size_mb=16, led.kind=none, presence.source=bootsel, usb.vidpid=RSKey—

The matrix

41 rows × 33 columns = 1353 cells. Column numbers are the table above.

Property010203040506070809101112131415161718192021222324252627282930313233
SEC-FIDO-001gapoosgapgapgapoosoosoosgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-FIDO-002gapoosgapgapgapoosoosoosgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-FIDO-003gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-FIDO-004gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-FIDO-005gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-FIDO-006gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-FIDO-006Agapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-FIDO-006Bgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-FIDO-006Cgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-FIDO-007gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-FIDO-008gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-SEAM-001gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-SEAM-002gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-SEAM-003gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-SEAM-006gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-STORE-001gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-STORE-002gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-STORE-003gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-STORE-004gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-STORE-005gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-STORE-006gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-LAT-001gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-LAT-002gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-LAT-003gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-LAT-004gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-POL-001gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-POL-002gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-POL-003gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-POL-004gapoosgapgapgapoosoosoosgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-POL-005gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-POL-006gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-ADM-002gapoosgapgapgapoosoosoosgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-ADM-004gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-DISP-001oosoosoosoosoosoosoosoosoosoosoosoosoosoosoosgapgapoosoosoosoosoosoosoosoosoosoosoosoosoosoosoosoos
SEC-DISP-002oosoosoosoosoosoosoosoosoosoosoosoosoosoosoosgapgapoosoosoosoosoosoosoosoosoosoosoosoosoosoosoosoos
SEC-DISP-003oosoosoosoosoosoosoosoosoosoosoosoosoosoosoosgapgapoosoosoosoosoosoosoosoosoosoosoosoosoosoosoosoos
SEC-BOOT-001gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-BOOT-002gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-TRANS-001gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-TRANS-002gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap
SEC-TRANS-003gapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgapgap

Dispositions

out-of-scope — basis crate-absent

  • columns: firmware, firmware-no-touch, firmware-fips, firmware-pqc, firmware-fips-pqc, firmware-no-touch-pqc, firmware-no-touch-fips, firmware-no-touch-fips-pqc, firmware-strong-pin, firmware-strong-pin-pqc, firmware-always-uv, firmware-always-uv-pqc, firmware-strict-up, firmware-strict-up-pqc, firmware-pico, firmware-2mb, firmware-16mb, firmware-strict-config, keygen-bench, core1-stats, bench, fido-conformance, ea-conformance-rpid, largeblob-ext, preview-sign, abrobot-16m, abrobot-4m, seeed-xiao, tenstar-usb, waveshare-one, waveshare-touch-lcd
  • properties: SEC-DISP-001, SEC-DISP-002, SEC-DISP-003
  • rsk-display owns the ceremony and rsk-ui the screen model, and both are dep:-gated behind --features display. The feature resolution the gate re-runs puts neither crate in any of these builds, so there is no ceremony to make a claim about. Note what this does NOT say: waveshare-touch-lcd is the trusted-display BOARD and still lands here, because a board preset sets knobs and never a cargo feature — the panel pins are compiled as inert constants.

out-of-scope — basis gate-compiled-out (feature = no-touch; gate: firmware/src/presence.rs; hook: rsk_sdk::UserPresence)

  • columns: firmware-no-touch, firmware-no-touch-pqc, firmware-no-touch-fips, firmware-no-touch-fips-pqc
  • properties: SEC-FIDO-001, SEC-FIDO-002, SEC-POL-004, SEC-ADM-002
  • no-touch replaces the button watcher with an instant auto-confirm (firmware/src/presence.rs), so the physical-consent gate these four statements are ABOUT is not in the image: “the live authorization its own gate requires”, “a presence decision produced for one transport”, “a confirmed physical press”, “a Confirmed operator presence”. The claim is not weakened here, it is not made — and the tree already treats these builds that way. None of the four is published, firmware/Cargo.toml says “Never ship a no-touch build”, and release-build.yml refuses to create a release carrying one. “No-touch image” in the singular is the phrasing that hid four packages.

Open gaps

The middle column is derived, and it is what a gap here costs: the open rows whose OWNING crates — the ones whose production Rust carries the property’s tag — are among the crates the column compiles unlike the comparison baseline, above. Outside it, the code the statement is about did not move and the question is whether the rest of the image reaches it; inside it, the statement is about a different compilation. Every P0-family row carries a production tag, so the one direction this number could be wrong in — an untagged row counting as not moving — is empty here.

The two after it are the ledger’s, and they are Stage 0’s last exit bullet: who owes the answer, and what would end the deferral. Settled by is typed rather than dated — evidence is a check.sh row built at this column, absence an out-of-scope argument, sameness an equivalent one, and ruling a decision no derivation can produce, which is the maintainer’s. The gate refuses sameness where the closure delta is non-empty and absence where neither of its bases can reach a row, so two of the four are claims the tree can already disagree with.

Configurationgap rowsof which the owner crate movesOwed bySettled byThe question that would settle them
firmware380contributorevidenceWhich applet and authorization properties retain scoped evidence in the default combined TrustZone image? Earlier monolithic evidence stays in dated bundles. The Secure IRQ worker, hardware-owned USB epochs, CMSE packet gateways, fatal admission fencing and banked FP policy need evidence from this build. Crypto, presence and reset image tests cover specific behavior. Resolve each property against its current implementation and evidence before claiming coverage.
firmware-no-touch341contributorabsenceBeyond the four presence statements: which rows depend on a presence decision only INDIRECTLY — a reset is reached through a touch, so does SEC-FIDO-006’s torn-reset argument still describe an image where the touch is instant?
firmware-fips3817contributorevidencefips-profile changes rsk-fido and rsk-piv — the PIN policy and the permitted algorithm set. check.sh runs the rsk-fido and rsk-piv test suites under it, so the question is narrow: does any P0-family invariant’s model take the PIN floor or the algorithm set as a parameter, and if so, was it re-checked at the profile’s values?
firmware-pqc3811contributorevidenceadvertise-pqc only adds ML-DSA-44 to the getInfo algorithm list — is that the whole delta for every P0-family row, or does the larger credential/attestation path move with it?
firmware-fips-pqc3817contributorevidenceAs firmware-fips, on the combination with advertise-pqc; the pair is published and nothing measures the two features together.
firmware-no-touch-pqc3410contributorabsenceAs firmware-no-touch, plus: does advertising ML-DSA-44 in getInfo change any authorization path, or only the algorithm list?
firmware-no-touch-fips3416contributorabsenceAs firmware-no-touch, plus the fips-profile question: the locked algorithm policy also raises the PIN floor, so which retry/gate properties are re-measured under it?
firmware-no-touch-fips-pqc3416contributorabsenceThe union of the firmware-no-touch, firmware-fips and firmware-pqc questions; no evidence is measured on the three-feature combination at all.
firmware-strong-pin3811contributorevidenceA six-code-point floor and a trivially-guessable-PIN refusal. Does any P0-family statement quantify over PIN values, or do they all treat the PIN as an opaque secret whose policy is someone else’s row?
firmware-strong-pin-pqc3811contributorevidenceAs firmware-strong-pin, on the combination with advertise-pqc.
firmware-always-uv3811contributorevidencealways-uv ships alwaysUv ON, which changes what SEC-FIDO-001’s gate DEMANDS rather than whether it is enforced — and SEC-FIDO-006B is about the alwaysUv gate surviving a reset, with a compiled-in default this column moves. Do the model’s gate constants cover the alwaysUv-on arm? THE MODEL HALF IS ANSWERED: AlwaysUvShipped is AS-AUTH-2 in assurance/assumptions.toml, and formal/AlwaysUv.cfg runs TypeOK plus the eight P0-launch invariants with it TRUE — GREEN over 31 451 172 distinct states at depth 51, per formal/runs.toml. Read the cfg for that count, never this sentence: it said “all six invariants”, and the file has carried nine entries in every commit it has ever had, so the number was wrong when it was written rather than gone stale — a count restated beside a file is a count that disagrees with it. THE CODE HALF IS NOT, and its cost is a number rather than an omission: cargo test -p rsk-fido --features always-uv --target "$HOST" came back 496 passed, 176 failed and 1 ignored — the harness’s own running 673 tests, rc 101 — run at commit 709cb52, because alwaysUv with no PIN answers PUAT_REQUIRED and the suite is written against the default door. The run is NAMED here because the sentence it replaces was not: is 493 passed and 176 FAILED, present tense, no commit, no date, over a suite that grows most weeks — a measurement written as a property of the column. The commit IS the date and is deliberately the only half written here: git dates a sha exactly, and scripts/run_count_gate.py refuses a second copy of a day its generated regions already print — the tier-run table of assurance/reports/assurance-vector.md prints this one, and typing it again here reddens that row (driven, EXIT=1). Write the target the way scripts/check.sh does: this said aarch64-apple-darwin, which is one maintainer’s host triple pinned into a shared register, and CI runs the same row at x86_64-unknown-linux-gnu. And say which convention the denominator uses, because this tree has two and they differ by exactly the one ignored test: 673 is passed + failed + IGNORED, which is the number the harness prints and the number every count below is in. The pair 446/172 is NOT a superseded version of this one and must not be reconciled with it: it is what assurance/bundle/logs/cargo-test-always-uv.log holds, over 619 tests, and 619 counts the same way — two true measurements of a growing suite, which is why the bundle’s own framing of that log is the thing to fix and not this number. The 669 that stood here was the third convention, passed + failed with the ignored test dropped; under the log’s it was 670, and no reader could have told the two apart. So no check.sh row exercises this column, and covered may rest only on the default build or on such a row — the matrix has no basis for “the model half is checked at this column’s own constant”, which is evidence-schema work and not a cell anybody can fill here.
firmware-always-uv-pqc3811contributorevidenceAs firmware-always-uv, on the combination with advertise-pqc.
firmware-strict-up3811contributorevidencestrict-up demands a touch on EVERY assertion, dropping the silent up:false pre-flight. That strengthens the gate — but SEC-FIDO-002 is about presence decisions not crossing transports, and this column produces strictly more of them. Is the model’s transport arity still the right one?
firmware-strict-up-pqc3811contributorevidenceAs firmware-strict-up, on the combination with advertise-pqc.
firmware-pico380contributorevidenceWhich properties hold for the combined TrustZone image with the Pico USB identity? Its former legacy closure equivalence does not establish the new execution mode or its Non-secure composition.
firmware-display416contributorevidenceThis column is NOT default + display: it also sets flashSize = 16M and ledKind = none, and it re-routes user presence through the panel’s Approve/Deny instead of the button. Each non-display row therefore has to answer three questions, not one — and the flash-geometry half is the same 16 MB question the board axis carries. It reaches the three SEC-DISP-* rows too, which is why they are gap here and not covered: the ceremony’s evidence — formal/Display.cfg, the rsk-ui/rsk-display host tests and the check.sh rows that compile the feature — was every bit of it produced at the DEFAULT 4 MB geometry. The BUILD half is answered now: build firmware (display) sets FLASH_SIZE=16M too, so the gate compiles the image this column IS rather than a combination no package ships. The EVIDENCE half is not, and that is what keeps these three at gap — Display.cfg, the rsk-ui/rsk-display host tests and the three co-mutants all run at the default geometry, and BugPadSubstitutesForCard runs in rsk-fido with no display feature at all. Closing it takes evidence produced at this configuration, or a conditional saying what the ceremony claim is conditional on.
firmware-display-v2416contributorevidenceThe V2 package selects the CST3530 driver with DISPLAY_TP_CHIP=cst3530. The gate builds it and checks the stack floor. The image harness can exercise its I2C transactions and report handling. Touch alignment, timing and the electrical behavior still need evidence from a physical V2 board.
firmware-2mb380contributorevidence2 MB with KVMAIN shrunk to 896 K. Do the store properties’ models take the partition size as a parameter, and were they checked at the shrunk one? The scope floors in formal/floors.txt are about model constants, not about the device’s own capacity.
firmware-16mb380contributorevidence16 MB with the default 1408 K KVMAIN. This is the geometry on which a whole KV store survived a wipe the device reported as successful — so for every store and boot row the question is not “does the code differ” (it does not) but “was the evidence ever produced against this partition map”.
firmware-strict-config3815contributorevidenceThe largest feature delta in the tree: five crates, and it re-imposes the presence/PIN gates on device-config writes that the DEFAULT build leaves ungated. SEC-ADM-002 and SEC-ADM-004 are about exactly that surface, so this column is the one where their disposition may be STRONGER than the default’s — which the matrix has no way to say until someone measures it.
keygen-bench381contributorevidenceA debug vendor command (INS 0x13) that firmware/Cargo.toml says never to ship, and it exposes a timing oracle over the primality primitives. Its never-shipped half is settled above; its sameness half is settled by measurement, and against the hoped-for answer — the closure is NOT the default build’s, so same-cargo-features is refused here by derivation rather than by opinion. No cargo-feature column can ever earn that basis, because the feature NAMING the column is in that column’s own closure by construction, which makes “is it equivalent” a question the derivation answers before it is asked. What the derivation does say is how narrow the delta is, and the page counts it: the crate set is the default build’s exactly and firmware is the only crate whose features move, so all but one of the open rows here own code that resolves identically. What is left is not derivable — does a vendor INS answering on this image, gated by nothing, reach a statement whose own crate did not move? SEC-BOOT-002 is the row where that is not even the question, because firmware is its owner.
core1-stats381contributorevidenceAs keygen-bench: INS 0x12 exposes per-core candidate/find rates, which time the RSA keygen prime search. The measurement lands in the same place and for the same reason — the crate set is the default build’s, firmware alone moves — so this column’s narrowness is not inherited from that one’s, it is re-derived on every run and printed beside this row.
bench3811contributorevidenceAs keygen-bench, and the one of the three the measurement separates rather than groups: bench is not a firmware-only delta. It turns on rsk-fido/bench and pulls rsk-bench into the image, so the rsk-fido-owned rows and SEC-BOOT-002 are open on a column where the code they are ABOUT is a different compilation, and the rest are not. It is also the only one of the three with check.sh rows — and none of them is evidence for a P0-family statement: clippy (bench fw) and clippy (bench host) are lints, and test (bench) selects rsk-fido under the name FILTER bench, which --list answers with the harness’s own four selector tests and one #[ignore]d timing loop — no invariant among them. So covered has nothing to rest on here either, and the open question is the keygen-bench one plus whichever rsk-fido statements a second timing entrypoint can reach.
fido-conformance3811contributorevidenceBuilt only for the FIDO Conformance Tool run: it suppresses the EdDSA advertisement. Its “is a conformance-only build in the supported set” half was the same parked ruling the three measurement columns carried and is settled above with them. What is left is narrower AND wider than the sentence used to say, because the closure the page derives names a second feature: fido-conformance implies strict-up, so this column also demands a touch on EVERY assertion. Two questions then, not one — does any P0-family row depend on the advertised algorithm list, and does firmware-strict-up’s transport-arity question apply here too?
ea-conformance-rpid3811contributorevidenceAdds the conformance tool’s RPID to the vendor-facilitated enterprise-attestation list, which is an authorization-relevant allowlist. SEC-FIDO-001 is about gates; is an EA RPID list one of them?
largeblob-ext3811contributorevidenceThe sharpest orthogonal feature: it serves the CTAP 2.3 largeBlob extension INSTEAD OF the 2.1 largeBlobKey + authenticatorLargeBlobs pair (the spec forbids both), it carries four check.sh rows, and it has zero flake packages — so nothing in the release axis would ever have given it a cell. Does the swapped surface move any credential-management or authorization transition the P0-launch models name?
preview-sign3811contributorevidenceYubico’s draft previewSign extension, off by default: a registration that asks for it gains an ARKG seed and a second attestation object, and an assertion signs the site’s digest behind the same UP and UV gates, storing nothing. Does either path move a gate, a counter or a record a P0-launch model names?
abrobot-16m380contributorevidenceThe 16 MB geometry question of firmware-16mb, plus a GPIO presence source instead of BOOTSEL.
abrobot-4m380maintainerevidenceThe narrowest column with anything open, and it is now one group and one question: does a GPIO button on 23 (active-low) deliver the Confirmed/Cancelled semantics the presence model assumes of BOOTSEL — same debounce, same cancellation, same per-transport arbitration? Only the four rows that quantify over a presence decision are still open on it. The four reset clauses used to be held here as reached-through-a-touch; that is a reachability argument and it is withdrawn in the cell above, where applied evenly it would have taken SEC-FIDO-003 out with them. What is left is genuinely about the button: crates/rsk-device/src/presence.rs arbitrates the scope and firmware/src/presence.rs holds the latch, and both compile identically here — the one arm that moves is the raw sample.
seeed-xiao380contributorevidence2 MB with KVMAIN at 896 K — the firmware-2mb question on a board that also gates the LED behind a power pin.
tenstar-usb380contributorevidenceThe 16 MB geometry question of firmware-16mb; presence is BOOTSEL, as on the default image (issue #125).
waveshare-one380contributorevidenceWhich properties have evidence under the default TrustZone build on the reference board? The board geometry remains known, but it does not transfer legacy execution evidence to the combined image.
waveshare-touch-lcd380maintainerrulingThe trusted-display BOARD without the display feature: 16 MB geometry, no addressable LED, and panel pins compiled as inert constants. The geometry question is firmware-16mb’s. The sharper half is now measured rather than asked: this preset IS buildable without --features display — build.rs parses the [display] keys with no CARGO_FEATURE_DISPLAY gate — and nothing in check.sh builds firmware on it at all. The board loop builds rsk-wipe, and both BOARD= firmware rows pin waveshare-one. So the column is real and WHOLLY UNEXERCISED, and what is left to decide is whether the tree should build it, or whether it should be a knob of firmware-display instead.

Property names

IDInvariantTranche
SEC-FIDO-001NoAuthorizationBypassp0-launch
SEC-FIDO-002NoCrossTransportTouchConsumptionp0-launch
SEC-FIDO-003NoTokenAfterInvalidationp0-launch
SEC-FIDO-004NoAccessibleSecretWithoutGatep0-launch
SEC-FIDO-005NoUnmanageableCredentialp0-launch
SEC-FIDO-006ResetNeverWeakensSurvivingStatep0-launch
SEC-FIDO-006AResetKeepsThePinGatep0-launch
SEC-FIDO-006BResetKeepsTheAlwaysUvGatep0-launch
SEC-FIDO-006CResetKeepsTheBackupSealp0-launch
SEC-FIDO-007RamNeverOutlivesFlashSeedp0-launch
SEC-FIDO-008NoLiveTokenWithoutPinRecordp0-launch
SEC-SEAM-001NoStatusOutsideItsSelectionp0b
SEC-SEAM-002NoStatusAfterARefusedAuthp0b
SEC-SEAM-003NoKeyOpOnTheAdminStatusp0b
SEC-SEAM-006AccessCodeRemovalNeedsTheCodep0b
SEC-STORE-001NoOrphanedMetadatap0-launch
SEC-STORE-002NoFalseAbsentp0-launch
SEC-STORE-003NoRecordLostToMetaWritep0-launch
SEC-STORE-004NoFalseMetaAbsentp0-launch
SEC-STORE-005CacheHonestp0-launch
SEC-STORE-006NoSilentOrphanp0-launch
SEC-LAT-001NoAuthWhenBlockedp0b
SEC-LAT-002WrongAttemptIsChargedp0b
SEC-LAT-003BudgetRisesOnlyWithItsSecretp0b
SEC-LAT-004CountWithinMaximump0b
SEC-POL-001PivOperationNeedsSlotPolicyp0b
SEC-POL-002PivAlwaysSpendsFreshnessp0b
SEC-POL-003AttributeChangeInvalidatesTheKeyp0b
SEC-POL-004OathCredentialNeedsItsGatesp0b
SEC-POL-005OtpSlotMutationNeedsItsCodep0b
SEC-POL-006OtpCounterNeverRepeatsp0b
SEC-ADM-002PrivilegedOpNeedsPresencep0b
SEC-ADM-004DisabledAppletNeverDispatchesp0b
SEC-DISP-001ConfirmNamesTheOperationp0b
SEC-DISP-002StaleTouchApprovesNothingp0b
SEC-DISP-003OnlyAllowConfirmsp0b
SEC-BOOT-001MarkerNeverLiesp0b
SEC-BOOT-002TheWholeLockRidesp0b
SEC-TRANS-001NoCrossChannelSplicep0b
SEC-TRANS-002NoSequenceGapp0b
SEC-TRANS-003NoBufferOverrunp0b

Assurance vector

A property can have evidence at several layers. For example, a model can rule out a bad state, a Rust test can exercise the matching transition, and a board test can check the hardware event that triggers it. Each result has its own scope.

The generated assurance vector lists that evidence by property. Use the property ID to find its model and code references, evidence bundle, tool or platform dependencies and remaining gaps. The assurance matrix shows how the scope changes across build configurations. The formal model explains what the models represent.

Bounds

RS-Key is not formally verified. This page is generated from the registry and reports what evidence exists, not that a whole-system theorem does. The Definition of done keeps this sentence a requirement until one exists, and scripts/claims_gate.py holds every page naming three or more registered properties to it. What is out of scope and what is accepted: limitations and the threat model.

Every bound every closed slice was taken at, and what each one stops being proved. The rows are not written here: they are read out of assurance/bundle/*.toml, one per bound_* key, by scripts/bounds_gate.py, which regenerates this page on every gate run and refuses a stale copy of it.

It replaces a hand-typed table. Fourteen rows stood under The bounds in the slice design, no script read them, and six mutations — a docs bound moved while the bundle stood still, a bundle bound moved while the docs stood still, a row renamed after a constant that does not exist, a row deleted — were green on all eight gates. A number a reader trusts and no gate reads is the defect this page exists to end.

What is rendered

Every bundle the tree has — 17 of them. Not the first slice’s alone: the exit criterion says the slice’s bundle because there was one when it was written, and rendering one now would leave most of the tree’s bounds unshown, which is the same table written in parallel with a smaller denominator.

Every one of the 17 is a p0-launch row of assurance/configurations.toml, all in the SEC-FIDO and SEC-STORE family, so all the bundles and the P0-launch rows that have any raw evidence at all are one set. The rest of that tranche is the difference, derived here rather than typed: 0 of its 17 rows carry no bundle, so there is nothing to render for them — none.

PropertyInvariantBundleMethod rowsBoundsWith a per-bound consequence
SEC-FIDO-001NoAuthorizationBypassassurance/bundle/SEC-FIDO-001.toml83333
SEC-FIDO-002NoCrossTransportTouchConsumptionassurance/bundle/SEC-FIDO-002.toml84141
SEC-FIDO-003NoTokenAfterInvalidationassurance/bundle/SEC-FIDO-003.toml94646
SEC-FIDO-004NoAccessibleSecretWithoutGateassurance/bundle/SEC-FIDO-004.toml73232
SEC-FIDO-005NoUnmanageableCredentialassurance/bundle/SEC-FIDO-005.toml73333
SEC-FIDO-006ResetNeverWeakensSurvivingStateassurance/bundle/SEC-FIDO-006.toml94242
SEC-FIDO-006AResetKeepsThePinGateassurance/bundle/SEC-FIDO-006A.toml73232
SEC-FIDO-006BResetKeepsTheAlwaysUvGateassurance/bundle/SEC-FIDO-006B.toml73333
SEC-FIDO-006CResetKeepsTheBackupSealassurance/bundle/SEC-FIDO-006C.toml83737
SEC-FIDO-007RamNeverOutlivesFlashSeedassurance/bundle/SEC-FIDO-007.toml52626
SEC-FIDO-008NoLiveTokenWithoutPinRecordassurance/bundle/SEC-FIDO-008.toml84242
SEC-STORE-001RSKeyStore!NoOrphanedMetadataassurance/bundle/SEC-STORE-001.toml42424
SEC-STORE-002RSKeyStore!NoFalseAbsentassurance/bundle/SEC-STORE-002.toml42424
SEC-STORE-003RSKeyStore!NoRecordLostToMetaWriteassurance/bundle/SEC-STORE-003.toml42424
SEC-STORE-004RSKeyStore!NoFalseMetaAbsentassurance/bundle/SEC-STORE-004.toml42424
SEC-STORE-005RSKeyStore!CacheHonestassurance/bundle/SEC-STORE-005.toml42424
SEC-STORE-006RSKeyStore!NoSilentOrphanassurance/bundle/SEC-STORE-006.toml42424

541 of 541 bounds carry a per-bound consequence. The column is stops_<name> beside bound_<name> in the bundle — the same way shipped_relation already travels with a method row, one field down — so the consequence moves with the number instead of being re-typed beside it. A cell reading — would be a bound the bundle carries no such field for; what such a bound costs is then only in its row’s shipped_relation, printed under each table as the row note.

The bounds, by property

SEC-FIDO-001 — NoAuthorizationBypass

Method 1 — tier A: the requirement gate over the abstract relation

model-check over formal/RSKeyTokenGate.tla + TokenGate.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_states44nothing by omission: the 44 are the WHOLE A domain and the number is a pin that they are reached, not a shrink of them. What no bound on this row can reach is the level above it — that the shipped machine holds no state this eight-boolean record cannot express
bound_ops11any protected operation the abstract alphabet does not name; and, inside the eleven, every requirement tier A has no vocabulary for — presence, the reset window, the retry counter, an rpId identity — because the oracle answers those TRUE and hands the obligation to tier B
bound_outcomes3the difference between a silent drop and a rejection. The alphabet is Silent, Authorized and Rejected and the invariant reads only the Authorized edges, so a defect that turns one refusal into the other is admitted here
bound_relation_tuples63888nothing by omission — the comprehension is enumerated whole. What its size costs is the FORM of the statement: read over the whole of it the predicate names no variable and TLC answers at startup with no counterexample, so the invariant is written as the slice at the current state and the 44 have to be pinned reachable instead

Row note (shipped_relation). 44 A states is the WHOLE domain, so this bound is not a shrink; the floor is a pin at 44 because the invariant is the relation’s slice at the current state

Method 2 — tier A: the oracle is not the relation

exhaustive sweep over TokenGateOracle.cfg + TokenGateDisagreement.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_states22anything about the other half of the domain. The walk is exactly the set on which the requirement gate and the relation-read gate differ, so on every A state outside it the two definitions agree and this row cannot tell a second definition from the relation read back to itself
bound_pairs31nothing by sampling — the 31 are the whole disagreement set, computed by the model rather than chosen. What the count does not say is that any one of them is a defect: it is the measurement that the oracle is a SECOND definition, which the refuted per-FID projection is the reason for

Row note (shipped_relation). the disagreement set is exact, not sampled: every (state, op) pair of AStates × Ops is compared

Method 3 — tier B: every invariant Shipped.cfg names, over the shipped constants

model-check over Shipped.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps2an rpId-binding defect needing a third relying party. The measured minimum is 1 and no mutant in the roster backs the module’s own >= 2 comment
bound_channels2a three-channel interleaving, at B
bound_max_retries8nothing individually. The soft lock is unreachable unless MaxRetries exceeds MismatchLimit, so the real constraint is a relation between two constants and a per-constant minimum cannot express it — which is why formal/scopes.txt records - for both
bound_mismatch_limit3nothing individually — see stops_max_retries; the pair is what is bounded, not either constant
bound_max_clock1anything about elapsed time. At 0 the Tick action is measured dead, so 1 is the smallest non-degenerate value and not a claim about the clock
bound_reset_window0the INSIDE-the-window arm. RESET_WINDOW_MS (10000) is the shipped value; at 0 the model only ever sees a closed window, so the reset-window clause is exercised on re-opening and never on a legitimate in-window reset
bound_symmetry_permutationspermutations of RPs and Channelssoundness under liveness. Safety configurations only
bound_credentials_per_rp1anything about slot exhaustion or MAX_RESIDENT_CREDENTIALS (256)

Row note (shipped_relation). MaxRetries and MismatchLimit ARE the shipped MAX_PIN_RETRIES (8) and PIN_MISMATCH_LIMIT (3); RPs and Channels are 2 against an unbounded device; ResetWindow 0 exercises the window closed only, so a legitimate in-window reset is never seen; MaxClock 1 is the smallest value at which Tick is not dead

Method 4 — tier B: AS-AUTH-2’s other arm

model-check over AlwaysUv.cfg. cfg: none. features: always-uv (modelled as the compiled default, not built).

BoundValueWhat stops being proved
bound_rps2an rpId-binding defect needing a third relying party, on the alwaysUv arm
bound_channels2a three-channel interleaving, on the alwaysUv arm
bound_max_retries2the ladder as the image walks it. Two rungs against the shipped eight, so a defect that needs a third failed PIN attempt to be reached is outside this arm’s reachable set and Shipped.cfg is the row that runs the ladder
bound_mismatch_limit1the two rungs between one mismatch and the shipped three, and any approach to the soft lock that needs them

Row note (shipped_relation). the retry ladder is REDUCED on this arm and the shipped one is not: the arm buys the alwaysUv reachability question, and Shipped.cfg is the row that is about the ladder

Method 5 — tier C: the walk guard over a symbolic operation sequence

bounded proof over crates/rsk-fido/src/state_kani.rs::no_authorization_bypass_walk_owner. cfg: kani. features: kani-soft.

BoundValueWhat stops being proved
bound_sequence5any defect needing a sixth dispatch — Begin, Next, unrelated command, Begin, Next, Next is already six
bound_channels2a three-channel interleaving. Two is the measured model minimum for BugCmWalkIgnoresChannel; it has never been measured at the code level
bound_clock_values2a leg landing inside the idle window after a partial advance; the window is exercised as open or fully expired, never partially. The two values are T0 and T0 + PUAT_MAX_USAGE_PERIOD_MS (600000)
bound_totalsfull symbolic u16 — not a shrink, and saying so is the pointnothing — this one is not a shrink, and saying so is the point of listing it

Row note (shipped_relation). 5 operations against a device that dispatches unboundedly; Begin/Next/other/Begin/Next/Next is already six

Method 6 — tier C: the Begin’s own decision, at its call site

bounded proof over crates/rsk-fido/src/credmgmt_kani.rs::no_authorization_bypass_rps_begin_at_call_site + …_creds_begin_at_call_site. cfg: kani. features: kani-soft.

BoundValueWhat stops being proved
bound_sequence1any defect needing a second dispatch after the Begin; this row proves one Begin out of one starting state and the walk harness (#5) is what covers a sequence
bound_channels2a three-channel interleaving at the call site
bound_symbolic_bytes1every pinUvAuthParam whose difference from the genuine MAC is not that one bit — a symbolic-length payload makes the compression function symbolic with it, and one harness over both Begins had not converged after 40 minutes and 8 GiB
bound_totalsfull symbolic u16nothing — not a shrink

Row note (shipped_relation). one Begin from one starting state; the pinUvAuthParam is a genuine 32-byte v2 MAC with ONE symbolic bit, because a symbolic-length payload makes the compression function symbolic with it — measured, one harness over both Begins had not converged after 40 minutes and 8 GiB

Method 7 — the cfg(kani) constant shrinks on this path

review over docs/assurance-bounds.md. cfg: kani. features: kani-soft.

BoundValueWhat stops being proved
bound_ctap_max_message3a pinUvAuthParam arriving across more than two continuation frames. Shipped is one INIT plus 128 continuations; rsk-device’s RESP_CAP IS this constant, so every harness in rsk-device — including the seven in presence_kani.rs — proves over a transport two frames wide
bound_chain_buf_size16any chained APDU over 16 bytes. Shipped is 3072, and rsk-device’s FidoCcidApplet is an rsk_sdk::Applet, so the FIDO applet’s CCID chaining is proved at 16
bound_resp_chain_cap16any chained response over 16 bytes; shipped is 3072
bound_cfg_not_kani_assertions2the equality of the two widths the getInfo response and the transport publish. crates/rsk-device/src/ctap.rs gates MAX_MSG_SIZE == RESP_CAP behind cfg(not(kani)), and rsk-usb does the same for the frame-multiple assertion; neither is a proof obligation and both are about the SHIPPED width, so under Kani the two constants are not held equal to each other

Row note (shipped_relation). CTAP_MAX_MESSAGE is 129 frames shipped and 3 under cfg(kani), and rsk-device’s RESP_CAP IS that constant, so all seven presence_kani.rs harnesses prove over a two-continuation transport; rsk-sdk’s CHAIN_BUF_SIZE/RESP_CHAIN_CAP are 3072/3072 shipped and 16 here. What stops being proved: a pinUvAuthParam arriving across more than two continuation frames, and any chained APDU over 16 bytes

Method 8 — the ghost’s completeness

exhaustive sweep over scripts/ghost_gate.py over formal/RSKeySecurityState.tla. cfg: none. features: none.

BoundValueWhat stops being proved
bound_actions21nothing by omission — the 21 are every operator Next reaches, derived on each run rather than listed beside the module. What the equality cannot say is whether an action that records is recording the RIGHT thing; the Solo_ configurations and the code twins are what that is for
bound_routes24the value written. The rule compares which occurrences of the name exist inside a viol assignment and which policy each consults, never what the recorded name means once the guard is satisfied
bound_guards11any defect INSIDE a policy operator. The assignment is held to the guard it consults by NAME, so swapping one policy for another is a finding and weakening the body of one is not

Row note (shipped_relation). the whole module: every operator Next reaches, and every occurrence of the name inside a viol’ assignment

SEC-FIDO-002 — NoCrossTransportTouchConsumption

Method 1 — tier B: the invariant over the whole reachable space of the shipped constants

model-check over formal/RSKeySecurityState.tla::NoCrossTransportTouchConsumption Shipped.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps2nothing this invariant can express — it names pres.granted, pres.cancelBy, pres.scope and the ghost, and no constant. What two costs it is reach alone: a falsifying presence state that first arises over a third relying party is not in the set searched
bound_channels2nothing this invariant can express, and note which arity this is NOT: the transport count is Owners, a five-element set fixed in the module, so no .cfg can widen it. What two costs is reach — a cross-transport consumption that first arises over a third concurrent channel is not in the set searched
bound_max_retries8nothing at all. The ladder is off this property’s path, and at the shipped value it is not a shrink either; what it buys is that the PIN doors are reachable at the depth the image has
bound_mismatch_limit3nothing at all, for the same reason as the ladder it pairs with — no clause of this invariant names a mismatch counter, and three IS the shipped limit
bound_max_clock1nothing this invariant can express. What one Tick costs is reach: a falsifying state that needs a second unit of elapsed time is not in the set searched
bound_reset_window0nothing this invariant can express. What zero costs is reach: a reset STARTED inside the shipped window is a prefix no run here produces, so a presence decision crossing a transport during a legitimate in-window reset is not in the set searched

Row note (shipped_relation). MaxRetries and MismatchLimit ARE the shipped MAX_PIN_RETRIES (8) and PIN_MISMATCH_LIMIT (3); RPs and Channels are 2 against an unbounded device; MaxClock 1 is the smallest value at which Tick is not dead; ResetWindow 0 runs the window closed only. NONE OF THE SIX IS ON THIS PROPERTY’S PATH — the invariant names pres.granted, pres.cancelBy, pres.scope and the ghost, and no constant. What the six buy it is the reachable set a falsifying state would have to appear in; what they cost it is nothing it can express. The bound that IS on its path is not in this list and is not a configuration knob at all: Owners is a five-element SET fixed in the module at formal/RSKeySecurityState.tla:144, so the transport arity cannot be widened by a .cfg — AS-XT-2

Method 2 — tier B: the other arm of all three registered scope constants, against this invariant

model-check over AlwaysUv.cfg PermWide.cfg ForceChange.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_arms_run3the fourth standing assumption. Three of the four scripts/assumption_gate.py tracks have both arms run against this invariant; PowerOnClearsScratch2 lives in RSKeyBootHardening and no configuration checking this property takes either of its arms, so nothing here says whether a power-on that fails to clear scratch2 can carry a presence decision across a transport
bound_rps2a falsifying state that first arises over a third relying party, on all three arms
bound_channels2a falsifying state that first arises over a third concurrent channel, on all three arms
bound_max_retries2nothing — the ladder is off this property’s path, so eight rungs down to two is free here in a way it is not for SEC-FIDO-001
bound_mismatch_limit1nothing, for the same reason: no clause names the mismatch counter, so one against the shipped three costs this invariant no term

Row note (shipped_relation). three configurations, one per constant: AlwaysUvShipped TRUE (formal/AlwaysUv.cfg), WidePerms TRUE (PermWide.cfg, one relying party) and ForceChangeModelled TRUE (ForceChange.cfg). The retry ladder is REDUCED on all three — 8:3 becomes 2:1 — and for THIS invariant that shrink is free in a way it is not for SEC-FIDO-001, because neither constant appears in the property. What the three rows buy is that of the four standing assumptions scripts/assumption_gate.py tracks, THREE have both arms run against this property; the fourth, PowerOnClearsScratch2, lives in RSKeyBootHardening and the overlap with the configurations checking this invariant is ZERO. That is a stronger position than SEC-FIDO-001 and SEC-FIDO-007, which each have one such constant

Method 3 — non-degeneracy: the invariant can go red, on a name that is its own, at five different (owner, canceller) pairs

model-check over Solo_BugUnscopedCancel.cfg Solo_BugPanelCancelable.cfg Solo_BugUnscopedOtpCancel.cfg Solo_BugNoDropStaleCancelAtEntry.cfg Solo_BugTouchNotSpent.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_invariants_checked2anything about the other eight invariants. Each row checks TypeOK and this name alone, which is what makes a RED this property’s rather than a sibling’s — and the price is that a state falsifying two at once is seen here as falsifying one
bound_armed_switches1any defect that needs TWO of the model’s bug switches at once. One armed switch per row is what attributes the kill, and a cross-term between two injected defects is not a state any of the five reaches
bound_isolated_rows5a sixth way for this invariant to fail. Five arms are five defects somebody wrote a switch for, so non-degeneracy is shown for those five and for no failure mode nobody modelled
bound_counterexample_depth_max7nothing — the depths are MEASURED trace lengths and not a bound the configurations impose. What they say is that the five land on four different (scope, cancelBy) pairs rather than all tripping on the first; what they cannot say is that a longer trace would find nothing else

Row note (shipped_relation). each of the five arms ONE Bug* switch with every other FALSE and checks TypeOK and this invariant and nothing else, which is what tells a kill from a neighbouring invariant’s. Unlike SEC-FIDO-007 the Solo rows are not the only place this property is observed to fail: its invariant IS in formal/gen-configs.sh:105-107’s ALL_INV, so the five Mut_ twins that check the whole set report THIS name too — measured, all ten, and that is the b_mut_twins row. The four cancel counterexamples land at depths 4, 5, 5 and 5 and the confirm one at 7, on four DIFFERENT (scope, cancelBy) pairs, which is what says each reaches its own boundary rather than all five tripping on the first

Method 4 — tier C: the cancel clause at code level — the wait that ends Cancelled was cancelled by the transport that owns it

bounded proof over crates/rsk-device/src/presence_kani.rs::no_cross_transport_touch_consumption_cancel. cfg: kani. features: kani-soft.

BoundValueWhat stops being proved
bound_budget_polls3any defect that first appears on a fourth poll. The shipped wait polls for its whole ten-second budget at a 16 ms tick — hundreds of iterations — and every one past the third is outside this harness
bound_unwind6nothing beyond the poll budget it covers. At 6 against a budget of 3 the unwinding is slack, so it is not the binding bound on this row and BUDGET_POLLS is; too small would be loud rather than silent, because Kani fails the unwinding assertion
bound_scopes4an arbiter handed a scope byte that is none of the four. scope is drawn symbolically over the four SCOPE_* values and assumed to be one of them, so a fifth byte reaching the arbiter is outside the proof
bound_cancel_producers2a cancel from a producer that is neither host path. Both host cancels are raised or not in every slice, so the interleaving of THOSE two is symbolic and a third source of cancellation is not modelled
bound_stale_cancel_arm1the stale-cancel drop at the wait’s EXIT. Of the two drops only the one at entry is pinned here; observing the other needs a second wait, which is a unit test’s and not this harness’s

Row note (shipped_relation). BUDGET_POLLS is 3 and the unwind bound 6 (crates/rsk-device/src/presence_kani.rs:20-25), against a shipped wait whose budget is MIN_TIMEOUT_SECS 10 s at a 16 ms poll — about 625 iterations. scope is fully symbolic over the four SCOPE_* bytes and both host cancels are raised or not in every slice, so the interleaving is symbolic; what is NOT symbolic is the SCHEDULE, because Kani reads the arbiter’s atomics sequentially and says so — AS-XT-1. There is no cfg(kani) constant shrink on this path: git grep -n 'cfg(kani)' crates/rsk-device/src outside the harness files is one hit, the mod proofs hook at crates/rsk-device/src/presence.rs:260. SEC-FIDO-001’s method table says CTAP_MAX_MESSAGE’s shrink puts ‘all seven presence_kani.rs harnesses’ over a two-continuation transport; measured here, that constant is real for the crate build and INERT for these seven — RESP_CAP lives in ctap.rs and ccid.rs and none of the seven constructs either

Method 5 — tier C: the confirm clause, and the premise it reasons from proved rather than assumed

bounded proof over crates/rsk-device/src/presence_kani.rs::no_cross_transport_touch_consumption_confirm crates/rsk-device/src/presence_kani.rs::a_hold_that_satisfied_a_ceremony_is_spent_by_it. cfg: kani. features: kani-soft.

BoundValueWhat stops being proved
bound_ceremonies2a hold that spans three ceremonies. Two is what the harness runs, the second on a finger that never lifted, and the model’s TouchConfirm is what covers a longer hold
bound_budget_polls3any defect that first appears on a fourth poll of either ceremony, the same shrink as the cancel row
bound_unwind6nothing beyond the poll budget it covers; at 6 against 3 polls the unwinding is slack on this row too
bound_scopes4a ceremony whose scope byte is none of the four. The two scopes are independently symbolic over the four SCOPE_* values, which is the whole alphabet the type admits and nothing outside it

Row note (shipped_relation). two ceremonies under independently symbolic scopes, the second running on a finger that never lifted. Stated as one implication rather than an assume, so no premise can silently go unreachable, and the premise itself is the second harness rather than an assumption. The Rust proved is STRONGER than the model needs: spent carries no owner, so a still-held press confirms for nobody — including the same transport again — while the model’s usedBy only forbids the CROSS-transport case. Two ceremonies is the bound: a hold spanning three is not proved here and the model’s TouchConfirm is what covers it

Method 6 — the production side: which sites own the decision, whether the tagged owners are those sites, and what the derived columns see

review over crates/rsk-device/src/presence.rs::request_cancel crates/rsk-device/src/presence.rs::cancel_otp_wait crates/rsk-device/src/presence.rs::pending_for firmware/src/presence.rs::up_pending scripts/assurance_gate.py. cfg: none — every site above is unconditional production code on a button build; the two cfg(feature = "display") forwarders at firmware/src/presence.rs:269-275 are counted apart and are AS-XT-4’s. features: none.

BoundValueWhat stops being proved
bound_tagged_owners3any owner outside the three the tag set names. This is a count of SITES and not a shrink of a shipped constant, because a review has no other unit, so what it covers is exactly the sites that were read
bound_cancel_writers2nothing by omission on this axis — cancel_requested.store(true is exactly two sites and both carry a tag, so both halves of the cancel decision are covered. What a count of sites cannot say is that a future third writer would be noticed
bound_scope_writers4any scope write outside the four call sites in the worker. The sequencing around a dispatch is the worker’s, and reading four sites says which they are and not that the order between them is right
bound_credited_files2the difference between a file and a site. The derived column counts FILE names, so a second owner inside an already-counted file moves nothing — which is why one credited file carrying no tag never reddened a row
bound_untagged_credited_files1any warning from the derived column about exactly this. One of the two credited files carries no tag and the column still reads 2, so the column cannot distinguish a covered file from a counted one
bound_harnesses_in_file7the five harnesses the column does not count. Seven live in the proof file and two are credited, so whatever the other five prove is outside every derived number this row feeds
bound_harnesses_counted2any claim that the two counted harnesses are the strongest available. The count is what the column credits, not a judgement about which proofs are load-bearing

Row note (shipped_relation). git grep -n 'cancel_requested.store(true' is exactly TWO sites — crates/rsk-device/src/presence.rs:120 inside request_cancel’s SCOPE_FIDO test and :131 inside cancel_otp_wait’s SCOPE_OTP test — and both carry a tag, so both halves of the cancel decision are covered, which is the thing that had to be confirmed rather than assumed. The four set_wait_scope call sites are firmware/src/worker.rs:484, :795, :934 and :938. Two files are credited to the rust column and one of them carries no tag; seven harnesses live in the proof file and two are counted. These bounds are counts of SITES and not shrinks of a shipped constant, because a review has no other unit — the same weakness SEC-FIDO-007 recorded about its own review row

Method 7 — the code twin: the same defect in production Rust, driven to the name of every test that fell and the direction each fell in

mutation over formal/comutants.toml scripts/comutate.py crates/rsk-device/src/presence_tests.rs::w4c_no_cancel_crosses_a_transport_boundary. cfg: none. features: none — the slice formal/comutants.toml names is exactly cargo test -p rsk-device, on the default feature set.

BoundValueWhat stops being proved
bound_patch_hunks1any defect the one hunk cannot express. A co-refutation patch is a hunk count and not a shrink of a shipped constant, so what is driven is the defect somebody wrote and not the class it belongs to
bound_patched_files1a defect that has to span two files. All five of this property’s comutants patch the tagged owner, which is the healthy case; a cross-file ordering defect is not something this apparatus can inject
bound_failing_tests3which assertion is load-bearing. Three tests fall, and a count of them says the mutant died and not that any one of the three was written for this property
bound_owner_canceller_pairs6the two pairs the sweep excludes — an owner raising its own cancel — and any pair over a transport the four owners do not include
bound_comutants_for_this_property5any model switch with no code twin. Five comutants stand against this invariant and the register is what defines the set, so a modelled defect nobody wrote a patch for has no code-level verdict here

Row note (shipped_relation). all five of this property’s comutants patch ONE file, crates/rsk-device/src/presence.rs, which is the tagged owner — the healthy case, and not SEC-FIDO-007’s, where the patched file was neither an owner nor tagged. BugUnscopedCancel and BugPanelCancelable share an ANCHOR (formal/comutants.toml:165-169 and :459-463 quote the same three lines), which the file’s own note says in as many words: the model splits the scope test three ways and the code fuses it into one guard. One of the five was re-driven by hand here; the other four are the recorded expect = "killed", which the comutants job of .github/workflows/deep-checks.yml re-drives WEEKLY as a gating row and the scripts/check-assurance.sh:"comutants lint" row lints on every pull request. The six pairs are w4c’s sweep: four owners × two host-reachable cancels, less the two an owner may raise for itself

Method 8 — the scope disposition: why four build columns are out-of-scope and not gap, and what that leaves open

review over assurance/configurations.toml firmware/src/presence.rs::poll_pressed docs/assurance-matrix.md. cfg: none. features: none — no-touch is the feature the four columns add, and no evidence in this bundle was built with it.

BoundValueWhat stops being proved
bound_columns_total31any build outside the thirty-one columns the ledger carries. The disposition is decided per column, so a configuration nobody listed has no cell to be gap or out-of-scope in
bound_columns_out_of_scope4nothing about the four, and that is the point: on a no-touch image no presence decision is produced at all, so a property about where a decision may be applied has no subject. What SURVIVES the disposition is that the arbiter and all three tagged functions ARE compiled into those images — what is absent is the wait, not the arbitration
bound_columns_claimed3twenty-seven of the thirty-one. Three columns carry a claim, so the invariant is asserted for three builds and for no other
bound_columns_gap24everything on those twenty-four columns. A gap is the honest remainder — nobody has judged — and three of them are board columns that move presence.source off BOOTSEL, where the decision’s producer is not the one this evidence was taken over
bound_board_columns_moving_presence3the three boards themselves. Naming which gap columns change the presence source says where the evidence would have to be retaken and never that it holds there

Row note (shipped_relation). this is the only row of the eleven-bundle programme with out-of-scope cells, and the disposition is DECIDED rather than open: on the four no-touch images ButtonWait::wait — the sole caller of set_up_pending(true) on a non-display build — is never called, because ButtonPresence::wait is cfg(not(feature = "no-touch")) and request/request_ceremony return Presence::Confirmed outright (firmware/src/presence.rs:208-264). So no presence DECISION is produced at all, and a property about where a decision may be applied has no subject. gap would say nobody has judged; out-of-scope says the claim is not made, which is the true state — and the tree already treats those builds that way, firmware/Cargo.toml saying ‘Never ship a no-touch build’ and release-build.yml refusing to release one. NOTE WHAT SURVIVES: Arbiter and all three tagged functions ARE compiled into those images; what is absent is the wait, not the arbitration. The 24 gap cells are the honest remainder and three of them are board columns that move presence.source off BOOTSEL

SEC-FIDO-003 — NoTokenAfterInvalidation

Method 1 — tier B: the whole invariant over the shipped constants, on the arm the image actually builds

model-check over formal/RSKeySecurityState.tla::NoTokenAfterInvalidation + Shipped.cfg::NoTokenAfterInvalidation. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps2an rpId-binding defect that needs a third relying party; two is what the ghost’s binding half is checked over
bound_channels2a three-channel interleaving of the invalidators — two channels is every concurrency this row searches
bound_max_retries8nothing by shrinking: eight IS the shipped MAX_PIN_RETRIES, so the two mutants that reach this invariant through the retry ladder walk the rungs the image has. The row that costs this property ladder depth is the reduced arm below, not this one
bound_mismatch_limit3nothing by shrinking, for the same reason as the ladder it pairs with — three IS PIN_MISMATCH_LIMIT, so the soft-lock approach is at shipped depth here
bound_max_clock1every question about elapsed time. One Tick is the whole clock, so the TIMER invalidator — expire_stale_token against a usage period this model has no wall clock for — is exercised as some time has passed and never at a duration
bound_reset_window0the reset invalidator as a legitimate in-window reset. At zero the window is only ever seen closed, so reset is reached through ResetStart and ResetConfirmed and never through the power-up window the shipped device opens

Row note (shipped_relation). MaxRetries and MismatchLimit ARE the shipped MAX_PIN_RETRIES (8) and PIN_MISMATCH_LIMIT (3) at crates/rsk-fido/src/consts.rs:371,375, and for THIS property that matters in a way it does not for SEC-FIDO-007: BugWrongPinKeepsToken and BugLocalPinKeepsToken are both reached through the retry ladder, so the ladder is on the path. RPs and Channels are 2 against an unbounded device; MaxClock 1 is the smallest value at which Tick is not dead, which bounds the TIMER arm — expire_stale_token is a tagged owner and PUAT_MAX_USAGE_PERIOD_MS (600 000 ms) is a wall clock this model does not have. ResetWindow 0 runs the window closed only, so the reset invalidator is exercised through ResetStart/ResetConfirmed and never through a legitimate in-window reset. This is the ONLY one of the four GREEN rows at AlwaysUvShipped = FALSE

Method 2 — tier B: the same invariant on the arm of AlwaysUvShipped the default image does not build

model-check over AlwaysUv.cfg::AlwaysUvShipped. cfg: none. features: always-uv (modelled as the compiled default, not built).

BoundValueWhat stops being proved
bound_rps2an rpId-binding defect needing a third relying party, on the alwaysUv arm
bound_channels2a three-channel interleaving, on the alwaysUv arm
bound_max_retries2the two rungs this arm does not have. Both mutants that reach this invariant walk the ladder, so at two rungs against the shipped eight this arm is not where a retry-shaped defect is caught
bound_mismatch_limit1the two mismatches between one and the shipped three, and any approach to the soft lock that needs them — the same shrink the ladder takes, on the counter it pairs with
bound_max_clock1every question about elapsed time, as on the shipped row: one Tick, so the timer invalidator is exercised as some time has passed only
bound_reset_window0the in-window reset arm, as on the shipped row — the window is seen closed on this arm too

Row note (shipped_relation). the retry ladder is REDUCED here and the shipped one is not — 8:3 becomes 2:1 (formal/AlwaysUv.cfg:6-7) — because the arm buys the alwaysUv reachability question and Shipped.cfg is the row that is about the ladder. What the row buys this property is that a registered standing assumption is run BOTH ways against it. What it costs is stated rather than implied: the two mutants that walk the ladder would have two fewer rungs to walk here, so this arm is not where a retry-shaped defect is caught

Method 3 — tier B: the permission alphabet’s other arm, which is the one this invariant’s own term reads

model-check over PermWide.cfg::WidePerms. cfg: none. features: none.

BoundValueWhat stops being proved
bound_perm_subsets16nothing — sixteen is the whole four-bit domain and this axis is a WIDENING, not a shrink. It is worth more to this invariant than to its neighbours because tok.perms # {} is a term of the second conjunct, so the domain the permission set is drawn from is a domain the invariant quantifies over
bound_rps1the rpId-binding half of the ghost. One relying party is the price this row pays for the wide permission domain, so on this configuration a token has no second relying party to be wrongly bound to
bound_channels2a three-channel interleaving of the invalidators, on the wide-permission arm
bound_max_retries2the six rungs between two and the shipped eight, so the two ladder-walking mutants are shallower here than on the shipped row
bound_mismatch_limit1the two mismatches between one and the shipped three, on the wide-permission arm

Row note (shipped_relation). WidePerms = TRUE draws ps from SUBSET Perms — all sixteen subsets of {mc, ga, cm, acfg} instead of the five PermSets narrows to (RSKeySecurityState.tla:174-177). This row is worth MORE to this property than to SEC-FIDO-001, and the reason is textual: tok.perms # {} is a TERM of the second conjunct, so the domain the token’s permission set is drawn from is the domain the invariant quantifies over. The cost is on the other axis and is real — RPs drops to 1, so the rpId-binding half of the ghost has no second relying party to be bound to on this row, and AlwaysUvShipped is TRUE here as well

Method 4 — tier B: the forced-PIN-change gate’s other arm, a gate that refuses token ISSUANCE after a correct PIN

model-check over ForceChange.cfg::ForceChangeModelled. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps1the rpId-binding half of the ghost, which this arm drops to one relying party the same way the wide-permission arm does
bound_channels2a three-channel interleaving, on the forced-change arm
bound_max_retries2the six rungs between two and the shipped eight; a retry-shaped defect is not what this arm is for
bound_mismatch_limit1the two mismatches between one and the shipped three, on the forced-change arm

Row note (shipped_relation). ForceChangeModelled = TRUE turns on gate.forceChange, EF_MINPINLEN byte 1, which clientpin.rs reads at the two get_pin_token doors and change_pin clears. It belongs to this property because it is a refusal AFTER the PIN has verified — a grant that must not be minted rather than one that must be retired — and assurance/platform.toml PLAT-MODEL-010 is discharged on it. What the arm does NOT reach is the built-in-UV door (clientpin.rs:544-546), which has no action in this module at all, and the panel’s own clear at clientpin.rs:1366

Method 5 — non-degeneracy: the invariant can go red, seven different ways, and each red names it rather than a sibling

model-check over Solo_BugTokenSurvivesPinChange.cfg Solo_BugStopUsingKeepsPerms.cfg Solo_BugWrongPinKeepsToken.cfg Solo_BugLocalPinKeepsToken.cfg Solo_BugChangePinKeepsPpuat.cfg Solo_BugPinWriteBeforeRevoke.cfg Solo_BugSetPinKeepsPpuat.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_invariants2anything about the invariants a solo row does not check. TypeOK and this name alone is what tells a kill from a neighbouring invariant’s, and the price is that a state falsifying two at once is seen here as falsifying one
bound_armed_switches1any defect needing two switches at once. One armed switch is what attributes the kill to the defect that was injected
bound_configurations7an eighth way for this invariant to fail. Seven switches are seven defects somebody wrote, so non-degeneracy covers those seven and no failure mode nobody modelled
bound_conjuncts_falsified3nothing — all three conjuncts are separately falsified, which is the strongest single statement in this bundle, because a conjunction whose clauses are never falsified apart is a conjunction with a passenger. What it does not say is that each clause is falsified in every way it could be

Row note (shipped_relation). every one of the seven checks TypeOK and this invariant and NOTHING ELSE (formal/gen-configs.sh:181-184 emits the SOLO block — the WORKING-TREE numbers, re-taken by content after a sibling slice grew that file by 69 lines NET — 72 added and 3 removed, 923 lines to 992; the same four lines stood at :173-176 at this bundle’s build.commit, which stays where it is because scripts/evidence_gate.py:515-546 dates a bundle by a commit git can resolve and the one carrying this file does not exist yet), with exactly one Bug* TRUE and every other FALSE, which is what tells a kill from a neighbouring invariant’s. mut = 7 IS this set: assurance_gate.solo_target_counts counts single-target Solo_* configurations. All three conjuncts are separately falsified — the ghost by BugPinWriteBeforeRevoke, the session term by four, the persistent term by two — and that is the strongest single statement in this bundle, because a conjunction whose clauses are never falsified apart is a conjunction with a passenger

Method 6 — tier C: the session token’s own state machine, over a symbolic five-operation sequence

bounded proof over crates/rsk-fido/src/state_kani.rs::no_token_after_invalidation. cfg: kani. features: kani-soft.

BoundValueWhat stops being proved
bound_sequence5any defect needing a sixth operation. Five from one starting state against a device that dispatches unboundedly, so an invalidation sequence that has to set itself up over six steps is outside this harness
bound_opcodes8any invalidator the alphabet does not name. The four the registry statement names are all in the eight, so what is left out is any OTHER route by which a grant could be retired or kept alive
bound_symbolic_permission_bytes6nothing — the permission bytes are full symbolic u8, one per step plus the opening grant, so this axis is not a shrink and no permission valuation is excluded
bound_clock_values2a token that expires strictly BETWEEN the two clock values. The timer arm is exercised at T0 and at the end of the usage period and nowhere in between
bound_clauses4the persistent grant. Four clauses are the session token’s; pcmr lives in flash, no clause here names it, and AS-NTAI-3 is the row that owns that hole

Row note (shipped_relation). five operations from one starting state against a device that dispatches unboundedly, drawn from eight opcodes — Begin, MarkUsed, ConsumeAfterUp, Stop, ResetToken, AuthenticatorReset, PowerCycle, TimePasses — so the four invalidators the registry statement names are all in the alphabet. The permission sets are FULL symbolic u8, one per step plus the opening grant, which is not a shrink. The clock is two values, T0 and T0 + PUAT_MAX_USAGE_PERIOD_MS, so the timer arm is exercised at its edges and nowhere between. Every clause is an EQUALITY, not an implication, which is what stops an authenticator that retires everything on sight from satisfying it. What is NOT here: the persistent pcmr grant, which is in flash — the harness header says so, and AS-NTAI-3 is the row that owns it

Method 7 — tier C: the credentialManagement gate’s own decision, at its call site, with a replayed MAC

bounded proof over crates/rsk-fido/src/credmgmt_kani.rs::no_token_after_invalidation_at_call_site. cfg: kani. features: kani-soft.

BoundValueWhat stops being proved
bound_sequence4any replay that needs a fifth step to set up. Four operations is the whole run, so a longer approach to the same call site is outside it
bound_opcodes3any invalidator outside the three this run can issue; the walk harness above is the row that carries the eight-opcode alphabet
bound_symbolic_permission_bytes1every valuation the other steps could carry. One permission byte is symbolic and the rest are concrete, so a defect that needs two different permission sets inside one run is outside this harness
bound_mac_payloads1anything about pinproto::verify as a MAC. One concrete payload is driven, so what is shown is that THIS replayed MAC still verifies — never that a forged one would not, which is TCB-2’s
bound_clauses2the same pair of clauses at the other three token gates. They are inline in functions that need a Ctx, and a Ctx drags p256 into the reachable set where Kani 0.67.0 aborts in codegen, so this pair is proved at one door of four

Row note (shipped_relation). the real verify_cm_token (credmgmt.rs:300-310) is driven, not a predicate standing in for it, and the pinUvAuthParam is a genuine v2 MAC minted while the grant was live and then REPLAYED. C2 is the load-bearing clause and it is the one that makes C1 mean something: the replayed MAC still verifies, so at this call site and at config.rs:245-247 zeroing permissions is not defence in depth — it is the only defence. One concrete payload, so this says nothing about pinproto::verify as a MAC (TCB-2). Only the cm permission and only this one of the four token gates: the other three are inline in functions that need a Ctx, and a Ctx drags p256 into the reachable set where Kani 0.67.0 aborts in codegen

Method 8 — the production side: which sites own each of the three conjuncts, and whether the tagged owners are those sites

review over crates/rsk-fido/src/state.rs::stop_using_token + crates/rsk-fido/src/seed.rs::clear_ppuat + crates/rsk-fido/src/clientpin.rs::write_pin_verifier. cfg: none — every site above is unconditional production code; the two Kani mirrors are not, and are named in the rows above rather than counted here. features: none.

BoundValueWhat stops being proved
bound_tagged_owners6any owner outside the six tagged sites. This is a count of SITES and not a shrink of a shipped constant, because a review has no other unit
bound_tagged_files3anything the derived column can see about a site. assurance_gate.grep_word returns FILE names, so a seventh tag inside a counted file moves nothing — which is why the tag missing from the third conjunct has never reddened a row
bound_conjuncts3the third conjunct’s ownership. Session maps onto three tagged sites and persistent onto three; the ORDER the ghost is written for maps onto none, because write_pin_verifier is untagged
bound_untagged_owner_sites4coverage of the sites the tag set does not reach. Two invalidators the statement names by word, reset and power cycle, are owned by sites carrying a sibling property’s tag or no tag at all
bound_citations_read23any citation the review never opened. Twenty-three OCCURRENCES were read, which is a count of readings and not of sources
bound_citations_wrong5how many SOURCES are wrong. The occurrences collapse onto fewer distinct references — one of them is written three times — so the defect count is smaller than the occurrence count and this bound cannot say by how much

Row note (shipped_relation). six tags over three files, and the rust column is 3 because assurance_gate.grep_word returns FILE names — a seventh tag in a counted file moves nothing, which is the reason the missing one has never reddened a row. The mapping is clean on two conjuncts and empty on the third: session gets state.rs:610/:649/:698, persistent gets clientpin.rs:184/:239 and seed.rs:360, and the ORDER — the conjunct SetPinWrite and ChangePinWrite write the ghost for — gets nothing, because write_pin_verifier is untagged. Two more invalidators the statement names by word, reset and power cycle, are owned by state.rs:545 and state.rs:436 and carry SEC-FIDO-006’s tag and no tag respectively. The citation bounds are OCCURRENCES, not distinct citations: 23 read and 5 wrong over 3 distinct references, and the distinction matters because one of the three is written three times. This bound is a count of sites and of citations, not a shrink of a shipped constant, because a review has no other unit

Method 9 — the code twins: the same defects injected into production Rust, and the one that could not be

mutation over formal/comutants.toml::BugStopUsingKeepsPerms + scripts/comutate.py + crates/rsk-display/src/gates.rs::local_pin_gate. cfg: none. features: none — the slices are cargo test -p rsk-fido and cargo test -p rsk-display on the default feature set.

BoundValueWhat stops being proved
bound_patched_files3a defect that has to span files the three do not include. A comutant is a hunk in a file, so a cross-file ordering defect is not something this apparatus can inject
bound_patched_crates2any invalidation door outside the two crates these patches reach
bound_patch_hunks9the CLASS each hunk belongs to. Nine hunks over six switches are the defects somebody wrote; a variant of the same defect that no hunk expresses has no code-level verdict here
bound_killed6anything about the seventh switch. Six carry a killed patch, so the co-refutation column covers six of the model’s seven defects
bound_unreachable1the setPIN arm at code level. No site’s removal reproduces setPIN keeps the grant alone, because the authoritative revoke is the chokepoint changePIN shares — so that switch has a model verdict and no code twin, which is why mut is 7 and co is 6

Row note (shipped_relation). six of the seven switches carry a patch with expect = "killed", which that file’s own status vocabulary (:20-22) defines as a RECORDED verdict and not a plan; the hunk count is the find/find2/find3 blocks summed over the six. Two crates, because BugLocalPinKeepsToken patches rsk-display — the only co-refutation entry for this property outside rsk-fido, and the door the model calls the fourth. The seventh, BugSetPinKeepsPpuat, is status = "unreachable" and its evidence field is a CODE-level measurement, not a model one: there is no site whose removal reproduces setPIN keeps the grant alone, because the authoritative revoke is the chokepoint changePIN shares. That asymmetry is why mut is 7 and co is 6

SEC-FIDO-004 — NoAccessibleSecretWithoutGate

Method 1 — the invariant over the whole reachable space at the SHIPPED constants

model-check over formal/RSKeySecurityState.tla::NoAccessibleSecretWithoutGate + Shipped.cfg::NoAccessibleSecretWithoutGate. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps2a falsifying state that first arises over a third relying party. The clause names two booleans and no relying party, so what two costs is reach and not a term
bound_channels2a falsifying state that first arises over a third concurrent channel — reach again, for the same reason
bound_max_retries8nothing by shrinking: eight IS the shipped ladder, and this is the ONE of the four green configurations that runs it. The ladder is off this property’s path and is what makes the PIN doors reachable at all
bound_mismatch_limit3nothing by shrinking, for the same reason as the ladder it pairs with — three IS the shipped mismatch limit
bound_max_clock1any falsifying state that needs a second unit of elapsed time. One Tick is the whole clock here
bound_reset_window0the in-window arm. At zero a reset may start only at clock 0, so a gate record dropped during a legitimate power-up-window reset is a prefix no run on this row produces

Row note (shipped_relation). MaxRetries and MismatchLimit ARE the shipped MAX_PIN_RETRIES (8) and PIN_MISMATCH_LIMIT (3) at crates/rsk-fido/src/consts.rs:371,375; RPs and Channels are 2 against an unbounded device; MaxClock 1 is the smallest value at which Tick is not dead; ResetWindow 0 runs the window closed only. THE RETRY LADDER IS NOT ON THIS PROPERTY’S PATH — gate.ppuat => pin.set names two booleans and no constant — but the ladder is what makes the PIN doors reachable, so what the six buy is the state set a falsifying state would have to appear in. And this is the ONE row of the four GREEN configurations that runs the shipped ladder at all: the other three set MaxRetries 2 and MismatchLimit 1, and two of those run one RP

Method 2 — the same invariant on the other arm of the three standing assumptions that have one

model-check over AlwaysUv.cfg::NoAccessibleSecretWithoutGate + PermWide.cfg + ForceChange.cfg. cfg: none. features: always-uv is modelled as the compiled default on the AlwaysUv arm, not built — no image was produced for any row here.

BoundValueWhat stops being proved
bound_rps2a falsifying state that first arises over a third relying party, on all three arms — and on two of the three the count is 1, so those rows have no second relying party at all
bound_channels2a falsifying state that first arises over a third concurrent channel, on all three arms
bound_max_retries2the six rungs between two and the shipped eight. All three arms run the reduced ladder, so the shipped constants are Shipped.cfg’s alone
bound_mismatch_limit1the two mismatches between one and the shipped three, on all three arms
bound_configurations3any arm of a standing assumption that no configuration takes. Three arms are three rows, and of the four configurations asserting this invariant three are the alwaysUv arm the default image does not build

Row note (shipped_relation). three arms and one caveat that is the honest half. AlwaysUvShipped is TRUE here and FALSE on Shipped.cfg, so BOTH arms of that assumption check this invariant; of the four configurations that ASSERT it, PermWide.cfg is the only one on WidePerms’ TRUE arm and ForceChange.cfg the only one on ForceChangeModelled’s — the roster’s other configurations taking either arm are mutants, which name this invariant in order to fall past it rather than to assert it. The caveat: all three run a REDUCED ladder (2:1 against the shipped 8:3, formal/AlwaysUv.cfg:6-7) and PermWide.cfg and ForceChange.cfg run ONE relying party. So of the four configurations that assert this invariant GREEN, three are the alwaysUv arm the default image does not build, and the shipped constants are Shipped.cfg alone

Method 3 — non-degeneracy: the invariant CAN go red, and the red names it rather than a sibling

model-check over Solo_NoAccessibleSecretWithoutGate.cfg::BugResetGatesFirst + Solo_BugPpuatIsAGate.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_invariants2anything about the rest of the invariant set. Each configuration checks TypeOK and this name and nothing else — which is what tells this kill from a neighbour’s, and it is needed here because on a multi-invariant configuration TLC reports the first violated name and it need not be this one
bound_armed_switches1any defect needing two switches at once. One armed switch is what attributes the red to the defect that was injected
bound_counterexample_states11nothing — eleven is a MEASURED trace length and not a bound the configuration imposes. It is the shorter of the two rows; the same clause needs thirteen on the other
bound_depth11nothing, for the same reason: the depth is what the search found and not a cap it was given, so it cannot say that a longer trace would find nothing else

Row note (shipped_relation). the two bounds above are Solo_NoAccessibleSecretWithoutGate.cfg’s, the SHORTER of the two rows; Solo_BugPpuatIsAGate.cfg needs 13 states and depth 13 for the same clause. Each configuration checks TypeOK and this invariant and NOTHING ELSE — formal/Solo_NoAccessibleSecretWithoutGate.cfg:50-52 and formal/Solo_BugPpuatIsAGate.cfg:50-52 — and arms exactly one Bug* switch with every other FALSE, which is what tells this kill from a neighbouring invariant’s. It is needed in a way it is not on Shipped.cfg: formal/gen-configs.sh:106 puts this invariant in ALL_INV, so on a multi-invariant configuration TLC reports the first violated name and it need not be this one — measured, Solo_BugSetPinKeepsPpuat.cfg reports NoTokenAfterInvalidation under the same switch whose Mut_ twin reports this invariant

Method 4 — which of the three clauses the recorded verdicts are actually about

exhaustive sweep over formal/runs.toml + assurance/bundle/logs/SEC-FIDO-004/tlc-Historical_E77.log + assurance/bundle/logs/SEC-FIDO-004/tlc-Solo_NoAccessibleSecretWithoutGate.log. cfg: none. features: none.

BoundValueWhat stops being proved
bound_clauses3two clauses of three. Only one is observed to fail anywhere in this tree, so for the other two there is no evidence that a red is even reachable
bound_red_rows5nothing by sampling — five is every row of formal/runs.toml whose verdict names this invariant, and every one of the five has its raw log in the backed-up tier. What exactness does not buy is discrimination: the apparatus reports all five the same way
bound_distinct_counterexamples2any failure mode outside the two traces. Both end at the same action with the same two fields set, so the five red rows are two observations and not five
bound_clauses_observed1non-degeneracy for the two clauses nothing falsifies. One of three is observed to fail; the other two are asserted by every configuration and refuted by none, which is the state a passenger conjunct would also be in

Row note (shipped_relation). the sweep is EXACT and not sampled: every row of formal/runs.toml whose verdict names this invariant is five, every one of the five has its raw log in the backed-up tier, and every one of the five final states was read. Two distinct counterexamples: a 13-state one shared by four rows (three of them byte-identical over the 404-line trace body, the fourth differing in the two lines that carry gate.ppuatStale) and an 11-state one. Both end at ResetAborts with gate.ppuat TRUE and pin.set FALSE. The bound that matters is the last: ONE of three clauses is observed to fail anywhere in this tree, and the apparatus reports all five as RED: NoAccessibleSecretWithoutGate without distinguishing them

Method 5 — the production side: which sites own each half of clause 3, and whether the tagged owners are among them

review over crates/rsk-fido/src/seed.rs::ensure_ppuat + crates/rsk-fido/src/credmgmt.rs::authorized_by_ppuat + crates/rsk-fido/src/reset.rs::is_fido_gate_fid. cfg: the two projection sites at rsk-device/src/ctap.rs are cfg-gated and reach no image; every other site above is unconditional production code. features: none.

BoundValueWhat stops being proved
bound_tagged_owners2any owner outside the two tagged sites. This is a count of SITES and not a shrink of a shipped constant, because a review has no other unit
bound_producer_sites1a second producer. One put_sealed32 of the record is the whole write side that was read, so the argument is as complete as that grep is
bound_consumer_sites3a reader the three do not include, and any claim about ORDER: the count says which sites read the record, never that a reader runs after the producer it depends on
bound_sweep_sites2any phase of the wipe outside the two sweep predicates. One puts the record in the SECRETS phase and one keeps it out of the GATES phase, and a third classification site would be outside the review
bound_files_in_argument5anything in a sixth file. Five files carry the argument, two of them only through cfg-gated projections that reach no image
bound_crates2a site in a third crate. The argument spans two, so a consumer of this record outside them is not covered

Row note (shipped_relation). one producer (seed.rs:342, the sole put_sealed32 that MINTS the record; 0x09D9’s boot re-seal at seed.rs:528 writes it again and mints nothing); three consumers (seed.rs:325 load_ppuat, credmgmt.rs:288 through it, and clientpin.rs:462 which is also the producer’s call site); two sweep sites (reset.rs:283 is_fido_fid, which puts the record in the SECRETS phase, and reset.rs:255 is_fido_gate_record, which keeps it out of the GATES phase). Five files — seed.rs, credmgmt.rs, clientpin.rs, reset.rs and crates/rsk-device/src/ctap.rs:241,276, the two cfg-gated projections — across rsk-fido and rsk-device. This bound is a count of sites and not a shrink of a shipped constant, because a review has no other unit; the honest reading of that is in the counterpart bundle and it applies here too

Method 6 — the code twin: the same defect injected into production Rust, driven against the tree’s own suite

mutation over formal/comutants.toml::BugPpuatIsAGate + crates/rsk-fido/src/reset.rs::is_fido_gate_record + crates/rsk-fido/src/reset_tests.rs::a_torn_reset_never_leaves_a_grant_without_its_pin. cfg: none. features: none — the slice is cargo test -p rsk-fido on the default feature set.

BoundValueWhat stops being proved
bound_patch_hunks1any defect the single hunk cannot express. The patch reverts one commit in the shipped file, so what is driven is that defect and not the class it belongs to
bound_patched_files1a defect that has to span two files
bound_tests_fallen1which assertion is load-bearing. One test falls now and the count says the mutant died, not that the test was written for this property — it reads the gate set, which is what the patch edits. It was three before provisioning began minting the grant; see retired_owners_of_the_kill for why the two torn-wipe tests no longer reach the state
bound_slice_crates1any test outside the one crate the slice runs. A kill by a test in another crate would not be observed by this row

Row note (shipped_relation). the patch puts \|\| fid == EF_PAUTHTOKEN.get() back on is_fido_gate_record (formal/comutants.toml:404-420) — eab4b5c reverted, in the shipped file, not a model edit — and it is the ONE co-refutation in this tree whose patch site is a function this property’s own tag sits on. Driven here rather than transcribed: a throwaway worktree at 31c21a7, the anchor asserted to resolve exactly once, cargo test -p rsk-fido --target aarch64-apple-darwin against the main build cache. expect = "killed" in that file is a RECORDED verdict per its own status vocabulary (:19-21), and this run is the second observation of it

Method 7 — what the tag gate can and cannot see about which site owns this property

exhaustive sweep over scripts/assurance_gate.py over crates/rsk-fido/src/credmgmt.rs::authorized_by_ppuat and crates/rsk-fido/src/reset.rs::is_fido_gate_fid. cfg: none. features: none.

BoundValueWhat stops being proved
bound_variants4nothing by omission — four is every subset of the two tags and the sweep is exhaustive over them. What exhaustiveness cannot reach is a THIRD tag: a site that starts owning this property arrives outside the sweep
bound_tags2which side of the implication a tag is on. The rule counts to one and the sweep measures that either tag alone clears it, so a tree whose only tag sits on a half that cannot falsify the invariant is still green
bound_owner_configurations9any configuration outside the nine the rule reads. A tag is owed only for the invariants those nine check, so an invariant checked nowhere among them owes none

Row note (shipped_relation). the sweep is over EVERY subset of the two tags — none, each alone, both — driven through check_tags, the gate’s own entry point, with production_rust pointed at copies rather than at the tree, so nothing was edited. The rule it exercises is scripts/assurance_gate.py:1068-1077: for each of the nine OWNER_CFGS, every invariant that configuration checks must carry a Refines tag SOMEWHERE in production Rust. It is a count-to-one rule and the sweep is what makes that a measurement instead of a reading: either tag alone clears it, and the rule knows nothing about which side of the implication a tag is on

SEC-FIDO-005 — NoUnmanageableCredential

Method 1 — the invariant over the whole reachable space of the shipped constants

model-check over formal/RSKeySecurityState.tla::NoUnmanageableCredential + Shipped.cfg::NoUnmanageableCredential. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps2every interleaving that needs a second credential for ONE relying party. store.cred and store.rpent are subsets of RPs, so the cardinality IS this invariant’s own domain — two relying parties with one credential each, against a device that holds hundreds over as many; AS-CRED-1 is the row that owns it
bound_channels2a falsifying state that first arises over a third concurrent channel
bound_max_retries8nothing by shrinking: eight IS the shipped ladder. It is off this property’s path and is what makes the doors above the store reachable
bound_mismatch_limit3nothing by shrinking, for the same reason as the ladder it pairs with
bound_max_clock1any falsifying state that needs a second unit of elapsed time
bound_reset_window0the in-window arm. At zero the wipe is reached only outside the power-up window, so an interleaving that begins inside a legitimate in-window reset is not searched

Row note (shipped_relation). MaxRetries and MismatchLimit ARE the shipped MAX_PIN_RETRIES (8) and PIN_MISMATCH_LIMIT (3) at crates/rsk-fido/src/consts.rs; MaxClock 1 is the smallest value at which Tick is not dead; ResetWindow 0 runs the window closed only. RPs = 2 IS on this property’s path, and that is the difference from SEC-FIDO-007’s identical-looking row: store.cred and store.rpent are SUBSETs of RPs, so the cardinality is the invariant’s own domain — two relying parties, one credential each, against a device that holds MAX_RESIDENT_CREDENTIALS (256) credentials over as many RPs. What two buys is that the counterexamples below are not artefacts of a single-RP degeneracy; what it costs is every interleaving that needs a second credential for ONE rp, which is AS-CRED-1

Method 2 — the same invariant on the three arms the default image does not build, so the assertion is not one configuration’s

model-check over AlwaysUv.cfg::NoUnmanageableCredential PermWide.cfg::NoUnmanageableCredential ForceChange.cfg::NoUnmanageableCredential. cfg: none. features: none.

BoundValueWhat stops being proved
bound_arms3any arm of a standing assumption no configuration takes. What the three buy is that all four of the tree’s non-mutant configurations assert this invariant, which is the whole of its numerator; none of the three constants they vary is on this property’s path, so they buy no depth on it
bound_rps2every interleaving needing a second credential for one relying party, on the three arms as on the shipped row
bound_channels2a falsifying state that first arises over a third concurrent channel, on all three arms
bound_max_retries2the six rungs between two and the shipped eight, on the alwaysUv arm — free here, because no clause of this invariant names a retry count
bound_mismatch_limit1the two mismatches between one and the shipped three, and nothing this invariant can express

Row note (shipped_relation). the retry ladder is REDUCED on the AlwaysUv arm (formal/AlwaysUv.cfg:6-7, 2:1 against the shipped 8:3) and left alone on the other two. AND NONE OF THE THREE CONSTANTS THE ARMS VARY IS ON THIS PROPERTY’S PATH: AlwaysUvShipped is a gate default, WidePerms is the permission-set cardinality and ForceChangeModelled is a PIN-policy flag, while store.cred \subseteq store.rpent names two store fields and no gate. What the three rows buy is therefore not depth on the invariant but that all four of the tree’s non-mutant configurations assert it — which is the whole of the 4 of 40 numerator, and which most MODELLED-ONLY rows do not have

Method 3 — non-degeneracy: the invariant CAN go red, in each of the three places the tree models it failing, and the red names it rather than a sibling

model-check over Solo_BugCredBeforeRp.cfg::BugCredBeforeRp Solo_BugDeleteRpBeforeCred.cfg::BugDeleteRpBeforeCred Solo_BugSeedDoesNotLead.cfg::BugSeedDoesNotLead. cfg: none. features: none.

BoundValueWhat stops being proved
bound_invariants2anything about the rest of the invariant set. TypeOK and this name alone is what tells these kills from a neighbour’s
bound_armed_switches1any defect needing two switches at once
bound_solo_configurations3a fourth ordering. The three switches are the three orderings the shipped tree chose — registration, credential-management delete and the wipe — so an ordering nobody wrote a switch for is not shown to be falsifiable
bound_counterexample_depths14nothing — the depth is the deepest MEASURED trace of the three and not a cap the configurations impose; the other two fall shallower

Row note (shipped_relation). each configuration checks TypeOK and this invariant and NOTHING else, and arms exactly one Bug* with every other FALSE — which is what tells these kills from a neighbouring invariant’s. The three switches are the three orderings the shipped tree chose: registration (EF_RP before EF_CRED, credential.rs:887 vs :925), credential-management delete (EF_CRED before the count, credmgmt.rs:766 vs :738) and the wipe (the seed before the batch — the FIDO_SEED_FIDS loop at reset.rs:116-120, under the comment at :108-110 that says why). The depth bound is the deepest of the three traces, 14 on Solo_BugDeleteRpBeforeCred; the other two fall at 7 and 13. Unlike SEC-FIDO-007, the Solo_ rows are not the ONLY place this property is observed to fail — formal/gen-configs.sh:185-187 puts a mutant’s target invariant FIRST in a Mut_ configuration’s INVARIANTS block, so all three Mut_ twins report this name too

Method 4 — the historical row: the wipe order this tree had before 0x08BF, run against the whole invariant set

model-check over Historical_E76.cfg::BugSeedDoesNotLead. cfg: none. features: none.

BoundValueWhat stops being proved
bound_invariants7clause attribution. Seven invariants are checked at once, so TLC reports the first violated name and a red on this row need not be this property’s — which is what the solo rows above exist for
bound_armed_switches1any defect needing a PAIR of switches at once — and note what the one switch buys here now: this configuration and Mut_BugSeedDoesNotLead.cfg were the same file under two names when this row was written and differ at exactly line 48 today, so the roster’s denominator counts forty distinct configurations rather than one of them twice
bound_states_searched986872269anything about WHICH of the seven invariants earned the green. The search is complete now — 0 states left on queue, depth 58 — so the count is the whole reachable set rather than the point a violation stopped it at, and a completed search is equally silent about all seven names. The key was bound_states_before_abort while this configuration aborted; there is no abort to count to any more

Row note (shipped_relation). the configuration is the pre-0x08BF tree — BugSeedDoesNotLead = TRUE — at Shipped.cfg’s constants, and it is the row that says this invariant is what the E76 fix was FOR. It is also this bundle’s first finding about the apparatus rather than the property, AND THAT FINDING HAS SINCE BEEN REPAIRED AT THE GENERATOR. diff formal/Historical_E76.cfg formal/Mut_BugSeedDoesNotLead.cfg was EMPTY when this row was written, both emitted with the same four arguments, so the two files were one configuration under two names and the cfgs = 40 denominator counted 39 distinct ones. formal/gen-configs.sh:322 now passes TRUE for the repair — emit Historical_E76.cfg BugSeedDoesNotLead TRUE TRUE — where the Mut_ loop at :329 still passes FALSE, so diff is the single hunk 48c48 on FixSweepDropsCredsBeforeRpEntries and the forty are forty distinct. THE RUN OF THE NEW CONTENT NOW EXISTS and this row is derived from it: formal/runs.toml’s safety tier, recorded at 9cafee7, has Historical_E76.cfg GREEN states=986872269 distinct=77563872 depth=58 1927s. So the counterfactual repair HOLDS the invariant the E76 defect breaks — Mut_BugSeedDoesNotLead.cfg, the same switch with FixSweepDropsCredsBeforeRpEntries = FALSE, is still RED at 1 875 109 states — and the pair of constants costs the reachable set nothing: the distinct count is Shipped.cfg’s 77 563 872 exactly, at Shipped.cfg’s depth of 58, for 36 072 more states generated

Method 5 — the production side: which sites own each half, whether the tags reach them, and what reachable by the management surface means in Rust that store.rpent does not say

review over crates/rsk-fido/src/credential.rs::credential_store + crates/rsk-fido/src/credmgmt.rs::decrement_rp + …settle_rp_records + …enumerate_rps + crates/rsk-fido/src/passkeys.rs::for_each_rp. cfg: none — every site above is unconditional production code; the invariant’s name appears in no cfg-gated mirror. features: none.

BoundValueWhat stops being proved
bound_tagged_owners4any owner outside the four the tag set names. This is a count of SITES and not a shrink of a shipped constant, because a review has no other unit
bound_writer_sites10a writer in a file the review did not open. Ten entries over four files is what was read, and one entry holds three best-effort rollbacks, so the site count is larger than the entry count
bound_reader_sites3anything about what a reader DOES with a slot it read. The count names the three browse surfaces and not their agreement — measured, two of them disagree on one skip condition
bound_skip_conditions3the invariant itself, and this is the finding: a record that exists and is SKIPPED satisfies store.rpent as plain set membership while being exactly what the clause forbids. Three skip conditions are three ways for that to happen, and no model bound reaches any of them
bound_files_in_argument4anything in a fifth file
bound_crates1a site outside rsk-fido. The whole argument is in one crate, so a management surface in another would be outside it

Row note (shipped_relation). eight writer entries over four files in ONE crate — ten sites, since one entry holds the three best-effort rollbacks — against the three functions the tag set names; the count is a count of sites and not a shrink of a shipped constant, because a review has no other unit. The three skip conditions are the finding: an EF_RP read the flash refuses now fails the host walk (credmgmt.rs:393) and still drops the slot from the display’s (passkeys.rs:112), and both surfaces drop one when n < RP_PREFIX \|\| buf[0] == 0 (credmgmt.rs:401, passkeys.rs:116) and when unseal_rp_id fails (credmgmt.rs:436, passkeys.rs:121) — and store.rpent is plain set membership, so a record that exists and is skipped satisfies the invariant while being exactly what the clause forbids. The two surfaces do not even agree with each other on the third: enumerate_rps answers CtapError::Other for the WHOLE walk, so one unsealable record hides every other relying party from the host, while for_each_rp skips that one and lists the rest

Method 6 — the five sites the tree already records as open in this class, and whether the model’s abstraction hides them

review over CHANGELOG.md crates/rsk-fido/src/credential.rs::bump_rp crates/rsk-fido/src/credmgmt.rs::delete_credential crates/rsk-fido/src/largeblobext.rs::discard. cfg: none. features: none.

BoundValueWhat stops being proved
bound_open_sites5any site in this class the CHANGELOG’s list does not name. The five were read from a list the tree already keeps, so the review is exactly as complete as that list is
bound_sites_in_the_forbidden_direction0nothing about whether the five are harmless. Measured, none can falsify this invariant — every one strands an EF_RP entry OVER a credential that is gone, which is the direction cred subseteq rpent does not constrain — so the zero says this property does not reach them and SEC-STORE-006 is where that direction is asserted
bound_model_actions_that_can_fail0every one of the five leaks. No action of the model can FAIL a flash write, so an Err returned by Fs::put and a best-effort rollback that itself fails are outside every configuration in this bundle
bound_tear_producers2a tear anywhere but between two writes that succeeded. Both producers act between successful writes, so the failure mode where the write itself returns an error is not a tear this model can produce

Row note (shipped_relation). CHANGELOG.md [0.4.11] Still open, same class, and named here names five sites as open, same class, so the next sweep starts from a list: the power-cut window between the RP bump and the credential write; delete_credential removing EF_CRED and then answering NotAllowed when the EF_RP write fails; decrement_rp’s own let _ = fs.delete(EF_RP + j); the trusted-display delete swallowing the same failure; and largeblobext::discard. MEASURED AGAINST THE INVARIANT, AND THIS IS THE ANSWER: none of the five can falsify it. Every one strands an EF_RP entry OVER a credential that is gone or never landed — rpent \supset cred, the direction cred \subseteq rpent does not constrain — which is precisely why the shipped order was chosen. What the model hides is therefore not a defect in this property’s direction but the five leaks themselves: no action of RSKeySecurityState can FAIL a flash write (the two tear producers are PowerCut, RSKeySecurityState.tla:1522, and ResetAborts, :1484, and both act between two writes that succeeded), so an Err returned by Fs::put and a best-effort rollback that itself fails are outside every configuration. AS-CRED-3 is the row that owns it, and SEC-STORE-006 NoSilentOrphan is where that direction is asserted instead

Method 7 — the code twins: the same three defects injected into production Rust, and whether the tree’s own suite catches them

mutation over formal/comutants.toml::BugCredBeforeRp + scripts/comutate.py + crates/rsk-fido/src/credential_tests.rs::a_failed_registration_never_leaves_a_credential_without_its_rp. cfg: none. features: none — the slice is cargo test -p rsk-fido --lib on the default feature set, with --target aarch64-apple-darwin because the workspace default target is the firmware’s.

BoundValueWhat stops being proved
bound_registered_twins3any model switch with no code twin. Three are registered, one per switch targeting this invariant, so the code-level verdict covers the defects somebody wrote patches for
bound_patch_hunks2any defect the two hunks cannot express. They defer one call past one write in the shipped file, which is that defect and not the class it belongs to
bound_patched_files1a defect that has to span two files
bound_driven_here1the other two verdicts as OBSERVATIONS. One of the three was re-driven for this bundle; the other two are transcribed from the register, so their kills are recorded rather than re-measured
bound_credited_configurations3what the killing tests are ABOUT. The credit is three because the index reads solo configurations by invariant name; the tests that fall are named for this property’s shape and not for the property, and no derived column counts them

Row note (shipped_relation). three twins are registered — one per model switch, at formal/comutants.toml:96, :131 and :352 — and all three carry expect = "killed", which is a RECORDED verdict per that file’s own status vocabulary (:19-21) and not a plan. ONE of the three was re-driven for this bundle, BugCredBeforeRp, whose two hunks defer bump_rp past the EF_CRED write in the shipped file; the other two are transcribed from the register and are marked as such in the mutation table. The credit is three because comutate.solo_index reads the Solo_ configuration BY INVARIANT NAME (scripts/comutate.py:338-366) and all three switches target this invariant. What the column does NOT say, and the source does: the killing tests are named for this property’s shape but not for the property, and no derived column counts them

SEC-FIDO-006 — ResetNeverWeakensSurvivingState

Method 1 — the conjunction over the whole reachable space of the shipped constants

model-check over Shipped.cfg::ResetNeverWeakensSurvivingState formal/RSKeySecurityState.tla::ResetNeverWeakensSurvivingState. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps2a torn prefix that first goes wrong over a third relying party; no clause names one, so what two costs is reach and not a term
bound_channels2a torn prefix that first goes wrong over a third concurrent channel
bound_max_retries8nothing by shrinking — eight IS the shipped ladder, and no clause of this conjunction names a retry count
bound_mismatch_limit3nothing by shrinking, for the same reason as the ladder it pairs with
bound_max_clock1any prefix that needs two units of elapsed time — and, with the window at zero, one Tick is also what closes the window, so the two bounds bite together on this row
bound_reset_window0the whole of the shipped power-up window but its first instant. InResetWindowGuard is sys.clock <= ResetWindow, so a reset may START only at clock 0 and one Tick refuses it: a reset begun late inside the shipped RESET_WINDOW_MS is a prefix no configuration here tears. What is NOT skipped is the touch — the ceremony runs unconditionally after the window check

Row note (shipped_relation). MaxRetries and MismatchLimit ARE the shipped MAX_PIN_RETRIES (8) and PIN_MISMATCH_LIMIT (3) at crates/rsk-fido/src/consts.rs:371,375; RPs and Channels are 2 against an unbounded device; MaxClock 1 is the smallest value at which Tick is not dead. ResetWindow 0 is the one that costs THIS property something. InResetWindowGuard is sys.clock <= ResetWindow (RSKeySecurityState.tla:1264-1267), so with ResetWindow 0 and MaxClock 1 a reset may START only at clock 0 and one Tick refuses it: the CTAP 2.1 §6.6 power-up window is exercised at its narrowest, and a reset begun late inside the shipped RESET_WINDOW_MS — 10 000 ms at crates/rsk-fido/src/consts.rs:407 — is a prefix no configuration here tears. The touch is not the thing being skipped: crates/rsk-fido/src/reset.rs:37-51 runs the ceremony unconditionally after the window check, and TouchGuard is an enabling conjunct of ResetConfirmed

Method 2 — the same conjunction on the other arms of the three registered scope constants

model-check over AlwaysUv.cfg PermWide.cfg ForceChange.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps2 on AlwaysUv.cfg, 1 on PermWide.cfg and ForceChange.cfga torn prefix that first goes wrong over a further relying party — and on two of the three arms there is no second one at all, so the ordering is checked over a single credential holder there
bound_channels2a torn prefix that first goes wrong over a third concurrent channel, on all three arms
bound_max_retries2nothing this conjunction can express: no clause names a retry count, so six rungs off the ladder is nearly free here
bound_mismatch_limit1nothing this conjunction can express, for the same reason
bound_arms3clause B on any arm where it can fail. All three arms take AlwaysUvShipped TRUE, and on that value clause B cannot fail — so what the three buy is the other value of three standing booleans and not a second chance at that clause

Row note (shipped_relation). all three REDUCE the retry ladder to 2:1 and two of them drop to one relying party, and for this property that shrink is nearly free: no clause names a retry count and snap.surv needs only one member to be non-empty. What the three arms buy is the other value of AlwaysUvShipped, WidePerms and ForceChangeModelled — and the first of those is not free at all in the other direction, because all three arms take AlwaysUvShipped = TRUE, on which clause B cannot fail. Measured: of the 40 configurations naming this invariant, exactly 3 take that arm and all 3 are among the 4 GREEN

Method 3 — clause isolation: which conjunct a mutant actually breaks, which the parent’s own verdict cannot say

model-check over SoloClause_ResetKeepsThePinGate.cfg SoloClause_ResetKeepsTheAlwaysUvGate.cfg SoloClause_ResetKeepsTheBackupSeal.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_invariants2anything about the rest of the invariant set; TypeOK and one clause is the whole of what each row checks
bound_clauses3any conjunct outside the three. Clause isolation is what the parent’s verdict cannot give, and it is given here for exactly the three the conjunction has
bound_armed_switches2isolation of the DEFECT on one of the three rows. Two switches are on there, because arming one drags its companion in, so that row isolates the clause and not the bug
bound_configurations3a fourth clause-isolating row. Three configurations are three clauses, so a conjunct nobody wrote a row for would have no isolated verdict
bound_depths16, 18 and 8nothing — the depths are MEASURED trace lengths and not caps. What they say is why the parent’s verdict cannot name a clause: the shallowest is reported every time a search checks all three, so the other two are never the reported name

Row note (shipped_relation). each configuration checks TypeOK and ONE clause and nothing else (formal/gen-configs.sh:171-176 emits exactly that, and :261-262 is the loop that names the three), so a RED cannot be a sibling clause’s. Two of the three arm BugResetGatesFirst and the third arms BugBackupSealedNotAGate — which drags BugSeedDoesNotLead in with it through companion_bug (formal/gen-configs.sh:34-44), so that row is the only one here where TWO switches are on and the isolation is of the CLAUSE, not of the defect. The depths are the content: clause 3 falls at 8 where clauses 1 and 2 need 16 and 18, which is why a search that checks all three reports the third every time

Method 4 — tier C: the induction domain is preserved by every concrete reset step, including a power cut and the boot after it

bounded proof over crates/rsk-fido/src/reset_refinement_kani.rs::reset_never_weakens_surviving_state_across_reboot. cfg: kani. features: kani-soft.

BoundValueWhat stops being proved
bound_steps1every reachability question. Closure under one symbolic step out of a symbolic pre-state is an induction and carries to sequences; what it cannot say is that any particular interleaving is REACHED, so a step whose precondition no real run satisfies is proved about all the same
bound_actions13any reset step the thirteen do not name. The step is selected from those and applied once, so a transition the shipped reset can make and apply_symbolic_step has no arm for is outside the closure argument
bound_symbolic_booleans14every field of FidoState the projection does not carry. Fourteen booleans are the WHOLE projection, and there is one because a direct run through the real FidoState::reset() was stopped with the prover still expanding zeroize loops — so what is closed under a step is the projection and not the state
bound_progress_values5nothing by omission — five is the whole ResetProgress enum and the pre-state draws every variant, so this axis is not a shrink
bound_covers1every witness but the one. The single cover is a power-cut-with-a-snapshot, so nothing on this row says any OTHER interesting pre-state is reachable, and an assertion over a vacuous domain would pass the same way

Row note (shipped_relation). ONE symbolic step out of a symbolic pre-state, not a sequence: apply_symbolic_step selects one of 13 actions by raw % 13 and the harness applies it once, so what is proved is that the domain is closed under a step and never that a particular interleaving reaches anything. The 14 booleans (6 persistent, 6 snapshot, 2 volatile) are the WHOLE projection — ResetVolatileView observes two fields of a FidoState that has dozens, and docs/reset-refinement.md records why: a direct run through the real FidoState::reset() was stopped after 72.45 s with CBMC still expanding zeroize loops past 398 iterations. The projection is the reason there is a verdict at all

Method 5 — tier C: each conjunct after the same step, independently of the conjunction that names it

bounded proof over crates/rsk-fido/src/reset_refinement_kani.rs::reset_keeps_the_pin_gate crates/rsk-fido/src/reset_refinement_kani.rs::reset_keeps_the_always_uv_gate crates/rsk-fido/src/reset_refinement_kani.rs::reset_keeps_the_backup_seal. cfg: kani. features: kani-soft.

BoundValueWhat stops being proved
bound_harnesses3nothing these three assertions add on their own. On the tree as it stands the parent’s well_formed(post) already implies each clause after the same step, so what the three buy is their covers and a mutation signal, not new coverage
bound_steps1every reachability question, exactly as on the parent row: one step is an induction and not a walk
bound_covers3anything beyond the three antecedents they witness. One cover per clause says that clause’s antecedent is satisfiable and nothing about any other valuation
bound_shared_precondition1every pre-state well_formed refuses. All four harnesses assume the same one predicate, so if it were too strong all four would be proved over a smaller domain and none of them would notice

Row note (shipped_relation). AND ON THE TREE AS IT STANDS THESE THREE ASSERTIONS ARE IMPLIED BY THE ROW ABOVE. All four harnesses assume well_formed(pre), apply the same one symbolic step, and the parent asserts well_formed(post) — whose last conjunct IS the conjunction (crates/rsk-fido/src/reset_assurance.rs:267). So clause_i(post) follows from it. What the three DO add is a kani::cover! each, and those are not implied: the parent’s single cover is a power-cut-with-a-snapshot witness and says nothing about any clause’s antecedent being satisfiable. The other thing they add appears only under mutation — see §8’s the parent conjunction loses a conjunct row

Method 6 — the production side: which sites own the ordering, and what the five tags and the three columns actually count

review over crates/rsk-fido/src/reset.rs::reset crates/rsk-fido/src/reset.rs::sweep crates/rsk-fido/src/reset.rs::is_fido_gate_record crates/rsk-fido/src/state.rs::reset crates/rsk-fido/src/lib.rs::load_keydev crates/rsk-fido/src/reset_assurance.rs::well_formed. cfg: none — every site above is unconditional production code; reset_assurance.rs is the exception and is proved absent from every image by scripts/check.sh:588. features: none.

BoundValueWhat stops being proved
bound_tagged_sites5any owner outside the five tagged sites. This is a count of SITES and not a shrink of a shipped constant, because a review has no other unit
bound_tagged_files3anything the derived column can see about a site. assurance_gate.grep_word returns FILE names, so two of the five tags move nothing — and one of those is about a SECOND reset path, the trusted-display factory wipe, which the model does not have at all
bound_clause_tagged_sites3the ordering between the tagged sites. Three sites carry a clause’s tag, and a count of them says which sites own a clause, never that they run in the order the clause needs
bound_gate_records5the two gate records no clause names. The phase holds five and the clauses name three, so a record dropped from the gate phase that no clause mentions is outside this argument
bound_wipe_steps5the step boundary the model folds away. The wipe is five ordered steps and the model has four actions for them, ResetConfirmed folding the first two into one, so a tear BETWEEN those two is not a prefix any configuration produces
bound_crates1a site outside rsk-fido. Every site in the argument is in one crate, so an ordering owner elsewhere would be outside it

Row note (shipped_relation). five parent tags in three files, and the column is 3 because assurance_gate.grep_word returns FILE names — two tags move nothing, and one of them (survives_factory_reset) is about the trusted-display factory wipe, a SECOND reset path the model does not have at all. The gate phase holds five records and the clauses name three; the wipe is five ordered steps and the model has four actions for them, ResetConfirmed folding step 1 and step 2 into one. Every site is in one crate, which is what makes rust = 3 a count of three files of rsk-fido and not a spread

Method 7 — the code twins: each model switch as the real defect in production Rust, killed by the tree’s own suite

mutation over formal/comutants.toml::BugResetGatesFirst scripts/comutate.py crates/rsk-fido/src/reset.rs::reset. cfg: none. features: none — the slice each row names is cargo test -p rsk-fido on the default feature set.

BoundValueWhat stops being proved
bound_twins3any model switch with no code twin, and any defect of the same shape nobody registered
bound_patch_hunks4the CLASS each hunk belongs to. Four hunks over three switches are the defects somebody wrote; a variant no hunk expresses has no code-level verdict here
bound_patched_files1a defect that has to span two files
bound_slice_crates1any test outside the one crate the slice runs, and any schedule but the weekly one — no row of check.sh re-drives these

Row note (shipped_relation). three of the tree’s 31 co-refutation rows credit this invariant, and all three patch one file: BugResetGatesFirst swaps the two sweep calls (1 hunk), BugBackupSealedNotAGate drops EF_BACKUP_SEALED from the gate match arm (1 hunk), BugStateResetAfterWipe moves ctx.state.reset() behind ensure_seed (2 hunks). expect = "killed" is a RECORDED verdict per that file’s own status vocabulary (formal/comutants.toml:19-21), not a plan, and it is re-driven by the weekly comutate run rather than by any row of check.sh

Method 8 — the fuzz rung: what the byte-granular probe’s oracle actually asserts, read rather than run

review over fuzz/fuzz_targets/power_cut.rs::reset_property_holds fuzz/fuzz_targets/power_cut.rs::reset_probe. cfg: none. features: none — a nightly cargo fuzz build of the fuzz/ workspace, no feature flag.

BoundValueWhat stops being proved
bound_oracle_asserts1any verdict finer than the whole conjunction. One assertion means a passing run says only that the fold held, so a clause the fixture made vacuously true is indistinguishable from one that was tested
bound_clauses_folded3which clause fell. All three ARE in the expression, so nothing is omitted; what the folding costs is on the reporting side — a failure names the function while the module doc lists the three clauses by name
bound_snapshot_valuations1the seven other snapshot valuations. The fixture writes all four records before the reset, so three snapshot booleans are TRUE by construction and the eight combinations the Kani harnesses draw symbolically are never explored here
bound_cut_budget_bytes1048575a power cut later than the budget allows. The cut point is drawn from three bytes, so a tear further into the reset than that is not a prefix this target can produce

Row note (shipped_relation). the probe drives the REAL rsk_fido::reset::reset over the real SeqStorage on a mock NOR that can lose power inside a write, then mounts a fresh Fs, scans, runs ensure_seed and boots a second time. That is the strongest rung below the board. What it does NOT have is the split the two tiers above it do: reset_property_holds folds all three clauses into ONE boolean expression (fuzz/fuzz_targets/power_cut.rs:248-250), so a failure names the function and never the clause — while the module doc at :28-31 lists all three clauses by name. And the fixture pins one snapshot valuation: EF_CRED, EF_PIN, EF_ALWAYS_UV and EF_BACKUP_SEALED are all written before the reset, so snap.pin, snap.auv and snap.sealed are TRUE by construction and the 2^3 the Kani harnesses draw symbolically is never explored. The cut budget is data[1] & 0x0f over three bytes, so 0..1 048 575 bytes

Method 9 — the board rung, and what its column is worth: the HIL witness is OWNED and has never been recorded

accepted risk over tests/29_reset_power_cut.py::cut_during_reset docs/reset-refinement.md. cfg: none. features: none.

BoundValueWhat stops being proved
bound_recorded_runs0everything the board rung would say. The column counts a FILE that names the invariant, and no run is recorded, so nothing here is evidence that a real power cut on real hardware preserves the property — PLAT-FLASH-001 owns the missing result and is pending
bound_asserts2any clause the two assertions do not separate. One folds clauses A and B and reports only that the operation was refused, without saying which gate refused it
bound_clauses_localised1clauses A and B. Only clause C has an assertion of its own, so a board run that went red on the folded one would not say which of the two gates it was

Row note (shipped_relation). this is the only one of the eleven registry rows whose test column is 1, and the column counts a FILE that names the invariant. formal/README.md’s own sentence is the one to read: a runtime column of one means the HIL harness is owned and discoverable, not that a board run passed. The script needs a throwaway board, the no-touch image and either an operator’s hand or a relay, and it can exit INCONCLUSIVE when the reset finishes before power goes. Its two assertions fold clauses A and B together (assert assertion_status != 0 — refused, without saying which gate refused) and give clause C its own (current != owner_seed). PLAT-FLASH-001 is the registry row that owns the missing result, and it is pending

SEC-FIDO-006A — ResetKeepsThePinGate

Method 1 — the clause by name over the whole reachable space of the shipped constants

model-check over Shipped.cfg::ResetKeepsThePinGate formal/RSKeySecurityState.tla::ResetKeepsThePinGate. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps2a torn prefix that first goes wrong over a third relying party. snap.surv needs one member to be non-empty, so two is reach and not a term of the clause
bound_channels2a torn prefix that first goes wrong over a third concurrent channel
bound_max_retries8nothing by shrinking — eight IS the shipped ladder at crates/rsk-fido/src/consts.rs, and this clause names no retry count. pin.retries is 8 in the falsifying state and plays no part in it
bound_mismatch_limit3nothing this clause can express, for the same reason as the ladder it pairs with
bound_max_clock1any prefix that needs two units of elapsed time — and with the window at zero, one Tick is also what closes the window, so the two bounds bite together here
bound_reset_window0the whole of the shipped power-up window but its first instant. A reset may START only at clock 0, so a reset begun late inside the shipped RESET_WINDOW_MS — 10 000 ms — is a prefix no configuration here tears. The touch is NOT what is skipped: crates/rsk-fido/src/reset.rs:37-51 runs the ceremony unconditionally after the window check
bound_invariants12nothing about this clause — twelve is what this configuration checks, TypeOK and eleven invariants, and this clause is one of the twelve by name. What twelve costs is attribution rather than coverage: NoAccessibleSecretWithoutGate and ResetNeverWeakensSurvivingState are two of the other eleven, both are about pin.set, and a RED here would be reported under whichever of the three TLC reached first

Row note (shipped_relation). MaxRetries and MismatchLimit ARE the shipped MAX_PIN_RETRIES and PIN_MISMATCH_LIMIT; RPs and Channels are 2 against an unbounded device; MaxClock 1 is the smallest value at which Tick is not dead; ResetWindow 0 is the one that costs this clause something. The verdict is GREEN, and the name is in the INVARIANTS block — measured, twelve indented names between INVARIANTS and SYMMETRY, with ResetKeepsThePinGate among them. This is the only GREEN configuration in the tree that names this clause: grep -l over formal/*.cfg returns exactly two files and the other one must be RED

Method 2 — clause isolation: that this conjunct has an owner of its own, which the parent’s verdict cannot say

model-check over SoloClause_ResetKeepsThePinGate.cfg::ResetKeepsThePinGate. cfg: none. features: none.

BoundValueWhat stops being proved
bound_invariants2anything about the rest of the invariant set. TypeOK and this one clause is the whole of what this row checks, which is exactly why its RED cannot be a neighbour’s — and equally why it says nothing about whether a neighbour would have caught the same defect
bound_armed_switches1any defect the one switch does not build. One armed switch is also what makes the runner compare the reported name: formal/floors.txt:SoloClause_*.cfg gives this family RED - with no invariant column, and formal/run-tlc.sh:229-237 then DERIVES the expected name from the configuration’s own INVARIANTS block whenever armed_count is 1 — which it is here, measured
bound_clauses1the other two conjuncts of the parent. This row is about one third of ResetNeverWeakensSurvivingState and is silent on the rest
bound_depth16nothing — sixteen is a MEASURED trace length and not a cap. What it says is why the parent cannot report this clause: the third conjunct falls at depth 8, so a search that checks all three reports the third every time
bound_distinct_states918170nothing by omission; the search stopped on the counterexample with 333 663 states still on the queue, so this is the space explored before the first violation and not the space of the configuration

Row note (shipped_relation). this configuration checks TypeOK and ONE clause and arms exactly one switch, BugResetGatesFirst = TRUE, at Shipped.cfg’s own constants — measured by reading the file, forty-six CONSTANTS assignments of which thirty-five are the Bug family and exactly one of those is TRUE. So a RED cannot be a sibling clause’s, and the reported name is compared rather than taken on trust

Method 3 — whether the isolated RED is evidence of a catch the neighbouring property would have missed

model-check over Solo_NoAccessibleSecretWithoutGate.cfg::BugResetGatesFirst Solo_BugResetGatesFirst.cfg::ResetNeverWeakensSurvivingState. cfg: none. features: none.

BoundValueWhat stops being proved
bound_configurations2any third reading of the same switch. BugResetGatesFirst is armed by FIVE configurations in this tree — measured, grep -l 'BugResetGatesFirst = TRUE' formal/*.cfg — and these two plus this clause’s own are the three whose INVARIANTS blocks make the comparison legible
bound_switch1every other defect. This row compares three verdicts of ONE switch and says nothing about a defect no switch in the tree builds
bound_depths11 and 8nothing — both are measured trace lengths. Read against this clause’s own 16 they are the content of the row: the same switch reddens the neighbouring invariant five levels shallower and the parent eight, so neither search ever reaches the state this clause is about

Row note (shipped_relation). Solo_NoAccessibleSecretWithoutGate.cfg arms BugResetGatesFirst alone and checks TypeOK plus NoAccessibleSecretWithoutGate; Solo_BugResetGatesFirst.cfg arms the same switch alone and checks TypeOK plus the parent. Both are RED. What the pair establishes is bounded and is stated as such: this clause’s own falsifying state ALSO falsifies NoAccessibleSecretWithoutGate, evaluated by hand on the printed state, so the isolated RED is a localisation and not a demonstration of unique reach. The converse IS witnessed — the neighbour’s falsifying state has snap.surv = {}, which makes this clause vacuous there — so the two are separated in one direction only

Method 4 — tier C: the clause holds after one concrete reset step out of any well-formed pre-state

bounded proof over crates/rsk-fido/src/reset_refinement_kani.rs::reset_keeps_the_pin_gate. cfg: kani. features: kani-soft.

BoundValueWhat stops being proved
bound_steps1every reachability question. Closure under one symbolic step out of a symbolic pre-state is an induction and carries to sequences; what it cannot say is that any particular interleaving is REACHED, so a step whose precondition no real run satisfies is proved about all the same
bound_actions13any reset step the thirteen do not name. One of the thirteen is a deliberate outsider — action eleven deletes an OpenPGP record outside the FIDO wipe — and a transition the shipped reset can make that apply_symbolic_step has no arm for is outside the closure argument
bound_symbolic_booleans14every field of FidoState the projection does not carry. Fourteen — six persistent, six snapshot, two volatile — is the WHOLE projection, so what is closed under a step is the projection and not the state
bound_progress_values5nothing by omission; five is the whole ResetProgress enum and the pre-state draws every variant
bound_covers1MORE than the parent bundle claims, and this is the row where that is measured. One cover per clause does NOT say this clause’s antecedent is satisfiable: the shipped condition names three of the antecedent’s four conjuncts and puts persistent.pin, the CONSEQUENT, where the fourth belongs. §8’s four code rows drive it
bound_antecedent_conjuncts_covered3the fourth conjunct, snapshot.credential. A witness satisfying the shipped cover may have it FALSE, and with it false the clause holds vacuously — so the cover cannot distinguish a domain in which this clause is non-trivially satisfied from one in which it cannot fail

Row note (shipped_relation). the harness assumes well_formed(pre) at crates/rsk-fido/src/reset_refinement_kani.rs:125, applies exactly one step, and asserts reset_keeps_the_pin_gate(&volatile) under the message ResetKeepsThePinGate at :130-133. Baseline on this tree: VERIFICATION SUCCESSFUL, 604 checks, 0 failed, 8 unreachable, one cover SATISFIED, 0.99 s. AND THE ASSERTION IS IMPLIED BY THE PARENT HARNESS: all four assume the same well_formed, take the same step, and the parent asserts well_formed(post) whose last conjunct at crates/rsk-fido/src/reset_assurance.rs:267 IS the conjunction. What this harness adds is its cover and a mutation signal — and the cover is the half this bundle found wanting

Method 5 — whether tier C’s non-vacuity guard can fail, driven rather than argued

mutation over crates/rsk-fido/src/reset_refinement_kani.rs::symbolic_snapshot crates/rsk-fido/src/reset_assurance.rs::reset_keeps_the_pin_gate. cfg: kani. features: kani-soft.

BoundValueWhat stops being proved
bound_arms4any question the four do not ask. Four arms answer: does the shipped cover accept a vacuous witness, does the repair still hold, does the shipped cover go UNSATISFIABLE on any vacuity route at all, and does one particular mutation model the defect it was written for
bound_harness1the two sibling clause harnesses. Their covers have the SAME shape — each names three of four antecedent conjuncts and substitutes the consequent — but only this one was driven, and a shape is not a verdict
bound_conjuncts_named3nothing this row proves; three of four is the count the arms are about, and the missing one is named
bound_solver_seconds0.90 to 1.08nothing — these are measured verification times off Kani’s own summary lines, not caps. What they say is that the repair is free: 0.98 s against a 0.99 s baseline

Row note (shipped_relation). every arm is one edit to the SCRATCH COPY described in build.scratch_workspace, never to this tree. The baseline arm reproduces this tree’s verdict, which is what makes the other three attributable to it. The two arms that matter are: the shipped cover conjoined with !snapshot.credential is SATISFIED, and the shipped cover under a real vacuity mutation is UNSATISFIABLE. Together they bound the finding — the guard is not inert, it simply does not guard the conjunct it omits

Method 6 — the production side: which line destroys EF_PIN, what holds the order, and what the tag counts

review over crates/rsk-fido/src/reset.rs::reset crates/rsk-fido/src/reset.rs::sweep crates/rsk-fido/src/reset.rs::is_fido_gate_record crates/rsk-fido/src/reset.rs::is_fido_gate_fid crates/rsk-fido/src/consts.rs::EF_PIN. cfg: none. features: none.

BoundValueWhat stops being proved
bound_tagged_sites1any owner outside the one tagged site. This is a count of SITES and a review has no other unit; the site that the clause is ABOUT — the five-line order at reset.rs:107-128 and reset.rs:72 — carries no tag at all
bound_gate_records5the four members this clause does not name. EF_DEVICE_PIN and EF_MINPINLEN are in the phase and in no clause of any property, which the source says out loud at reset.rs:244-250, so a torn reset that drops either early is unobserved by every rung here
bound_clause_records1everything but EF_PIN = 0x1080. One record is the whole of what this clause is about at the FID level
bound_destroying_sites2any third way the record can go. The gate sweep at reset.rs:128 is the reset’s own destroyer; the device-wide Fs::factory_wipe is the second, and is the reason is_fido_gate_fid is pub. Neither is reached by the model, which has an ordering over completed writes and no factory wipe at all

Row note (shipped_relation). the clause is a statement about five consecutive lines and their order is enforced by nothing but their sequence. sweep at reset.rs:141 is batched at 64 with a progress backstop and returns Err when the walk did not complete, so an un-yielded FID counts as absent only on a finished walk — which is the mechanism the clause’s consequent depends on and which no configuration models

Method 7 — what the two runtime columns of this row’s vector actually assert about THIS clause

review over fuzz/fuzz_targets/power_cut.rs::reset_property_holds tests/29_reset_power_cut.py::old_credential_without_gates. cfg: none. features: none.

BoundValueWhat stops being proved
bound_oracle_conjuncts1any attribution at all. The fuzz oracle’s first conjunct is !credential_usable || (has_data(EF_PIN) && has_data(EF_ALWAYS_UV)) — clauses A and B &&-folded — so a failure names the function and never the clause, and a run that dropped EF_ALWAYS_UV reports identically to one that dropped EF_PIN
bound_assertions1the same attribution, one rung up. tests/29_reset_power_cut.py:526-530 asserts the old credential’s assertion was REFUSED; the refusal could be either gate’s and the assertion does not say. The failure MESSAGE prints both option flags, so a human reading a red run could tell — the assertion could not
bound_recorded_board_runs0everything the board column might have been. No run of that script is recorded anywhere in the tree; hardware is 0 on this row’s vector, build names no board revision because there is no board result to date one, and PLAT-FLASH-001 owns the missing result with status = "pending"

Row note (shipped_relation). both files NAME this clause in their doc comments — fuzz/fuzz_targets/power_cut.rs:29-31 and tests/29_reset_power_cut.py:12-14 list all three — and neither can report it. So of the four non-zero evidence columns on this row, two are counts of files whose oracles fold this clause into a sibling’s. The columns are not wrong; they count what they say they count, which is a file

SEC-FIDO-006B — ResetKeepsTheAlwaysUvGate

Method 1 — the clause over the whole reachable space of the shipped constants, on the one green configuration that names it

model-check over Shipped.cfg::ResetKeepsTheAlwaysUvGate formal/RSKeySecurityState.tla::ResetKeepsTheAlwaysUvGate. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps2a torn prefix that first goes wrong over a third relying party. The clause needs only snap.surv # {}, so two is reach and not a term of the claim
bound_channels2a torn prefix that first goes wrong over a third concurrent channel
bound_max_clock1any prefix needing two units of elapsed time — and with ResetWindow = 0 one Tick is also what closes the reset window, so the two bounds bite together on this row
bound_reset_window0the whole of the shipped power-up window but its first instant: a reset may START only at clock 0, so a reset begun late inside the shipped RESET_WINDOW_MS — 10 000 ms at crates/rsk-fido/src/consts.rs:407 — is a prefix this row never tears. The touch is NOT what is skipped; crates/rsk-fido/src/reset.rs:37-51 runs the ceremony unconditionally after the window check
bound_invariants12nothing about this clause by omission — twelve is what this configuration’s INVARIANTS block names, TypeOK and eleven invariants, and the last three are the clauses. It is worth the count because two other bundles describe this same block as nine, which was true at b819ee5 and is false at the commit these runs were taken at
bound_green_bases1any second green configuration. Of the two hundred and ten configurations, forty name the parent invariant and exactly two name this clause; only one of those two is green, so this row is the whole of the clause’s positive model evidence and there is no independent arm to corroborate it

Row note (shipped_relation). MaxRetries 8 and MismatchLimit 3 ARE the shipped MAX_PIN_RETRIES and PIN_MISMATCH_LIMIT at crates/rsk-fido/src/consts.rs:371,375; RPs and Channels are 2 against an unbounded device. The constant that matters to THIS clause is AlwaysUvShipped = FALSE, and it is the shipped image’s own value: firmware/Cargo.toml’s default feature set does not name always-uv. On that value the record exists exactly when the flag is on, so the model’s consequent gate.alwaysUv and the firmware’s EF_ALWAYS_UV presence are the same fact — which is the correspondence the whole ladder below rests on and which the other arm breaks

Method 2 — non-degeneracy: that the clause has a falsifying state at all on the constants its green run uses, and that the state is this clause’s and not a sibling’s

model-check over SoloClause_ResetKeepsTheAlwaysUvGate.cfg SoloClause_ResetKeepsThePinGate.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_invariants2anything about the rest of the invariant set; TypeOK and one clause is the whole of what each row checks, which is exactly what makes a RED attributable
bound_armed_switches1every defect but the one. BugResetGatesFirst is the sole model owner of this clause, so a defect the phase swap does not produce has no red row here
bound_constant_deltas1any doubt about whether the green base could go red. This configuration differs from Shipped.cfg in ONE constant (BugResetGatesFirst = TRUE) besides its invariant block — measured by diff, which reports that line and the INVARIANTS block and nothing else — so the red and the green are the same model with one switch between them
bound_depth18nothing — eighteen is a MEASURED trace length and not a cap. What it says is why the parent cannot name this clause: the sibling clause falls at sixteen and the third at eight, so a search checking all three reports the shallowest every time
bound_distinct_states2063890nothing by shrinking; it is what the search visited before the counterexample, and it is the figure to read against the parent’s own solo row, which reaches a violation in five thousand three hundred and thirty-one

Row note (shipped_relation). each configuration checks TypeOK and ONE clause (formal/gen-configs.sh:182-189 emits exactly that under SOLO, and :330-332 is the loop that names the three), so a RED here cannot be a sibling clause’s. Both rows arm the same switch, clause_mutant at formal/gen-configs.sh:321-328 mapping the first two clauses onto BugResetGatesFirst with the comment that the phase order is their only owner. The pair is what separates the two clauses by a WITNESS: in this clause’s counterexample pin.set is TRUE, so clause A holds there; in clause A’s, snap.auv is FALSE, so this clause is vacuous there

Method 3 — the other arm of the constant this clause depends on, and what the clause is worth on it

model-check over AlwaysUv.cfg PermWide.cfg ForceChange.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_arms3this clause, on every one of them. All three take AlwaysUvShipped = TRUE, and on that value the clause has no falsifying state: what the three arms buy is the other value of three standing booleans for the OTHER invariants, and for this one they buy a vacuous conjunct
bound_falsifying_states0the whole of what a green run normally means. Zero is not a measurement of these runs — TLC reports no such count — it is the consequence of gate.alwaysUv having two writers, one that clears the antecedent’s snap and one that can only raise the flag on this arm
bound_rps2 on AlwaysUv.cfg, 1 on PermWide.cfg and ForceChange.cfga torn prefix over a further relying party, and on two of the three arms there is no second one at all. For this clause that shrink costs nothing extra, since the arm has already cost it everything
bound_max_retries2nothing this clause can express: it names no retry count, so six rungs off the ladder is free here
bound_configurations_arming_the_mutant0the ability to EXHIBIT the vacuity rather than argue it. Measured: five configurations set AlwaysUvShipped = TRUE and five arm BugResetGatesFirst, and the two sets are disjoint — every configuration arming this clause’s mutant takes the FALSE arm. So no recorded run shows the switch failing to redden the clause on the TRUE arm; the claim rests on reading the two writers

Row note (shipped_relation). these three are the arms the scope registry buys — AlwaysUvShipped, WidePerms and ForceChangeModelled — and all three happen to take the first of them TRUE. On the shipped image the constant is FALSE, so these rows describe a build the tree publishes and does not ship. formal/gen-configs.sh:211-225 states the consequence in the generator itself and is the reason clauses=1 is on Shipped.cfg and on no other baseline: recording the clause as asserted on these three would be recording a row that cannot go red

Method 4 — tier C: the clause holds of the Rust projection after any one concrete reset step

bounded proof over crates/rsk-fido/src/reset_refinement_kani.rs::reset_keeps_the_always_uv_gate crates/rsk-fido/src/reset_assurance.rs::reset_keeps_the_always_uv_gate. cfg: kani. features: kani-soft.

BoundValueWhat stops being proved
bound_steps1every reachability question. Closure under one symbolic step out of a symbolic pre-state is an induction and carries to sequences; what it cannot say is that any particular interleaving is REACHED, so a step whose precondition no real run satisfies is proved about all the same
bound_actions13any reset step the thirteen do not name. One is selected by action % 13 and applied once, so a transition the shipped reset can make and apply_symbolic_step has no arm for is outside the closure argument
bound_symbolic_booleans14every field of FidoState the projection does not carry. Fourteen booleans — six persistent, six snapshot, two volatile — are the WHOLE projection, and there is one because a direct run through the real reset was stopped with the prover still expanding zeroize loops
bound_covers1every witness but the one. This harness’s single kani::cover! says its own antecedent is satisfiable and nothing about any other valuation
bound_feature_arms1the arm this clause is about. scripts/kani.sh selects -p rsk-fido --features kani-soft, so the proof runs on the default build only; nothing bounded is proved about the build where the record’s presence inverts

Row note (shipped_relation). AND THE ASSERTION IS IMPLIED BY THE PARENT HARNESS on the tree as it stands, which this bundle says rather than presenting an independent proof: all four harnesses assume well_formed(pre), take the same one symbolic step, and well_formed ends in the conjunction (crates/rsk-fido/src/reset_assurance.rs:267), so well_formed(post) already gives this clause. What the harness adds is its own cover and a signal if the conjunction ever loses a conjunct. The α is ALSO not the model: its consequent is persistent.always_uv, the record’s presence, where the TLA+ consequent is the flag — the same fact only while the compiled default is off

Method 5 — the production side: which sites decide this clause, and which of them the tag counts

review over crates/rsk-fido/src/reset.rs::reset crates/rsk-fido/src/reset.rs::sweep crates/rsk-fido/src/reset.rs::is_fido_gate_record crates/rsk-fido/src/config.rs::toggle_always_uv crates/rsk-fido/src/config.rs::always_uv_state crates/rsk-fido/src/config.rs::DEFAULT_ALWAYS_UV. cfg: none. features: none.

BoundValueWhat stops being proved
bound_tagged_sites1every site the tag is not on, which is where the property lives. The one tag is on the CLASSIFIER; the ordering that makes the clause true is two untagged lines at crates/rsk-fido/src/reset.rs:127-128, and the writer that decides what the record MEANS is in another file entirely
bound_gate_records5the two members no clause names. is_fido_gate_record matches EF_PIN, EF_DEVICE_PIN, EF_ALWAYS_UV, EF_MINPINLEN and EF_BACKUP_SEALED; three clauses cover three of them, and a torn reset that drops either of the other two early is unobserved by every artifact in this bundle
bound_flag_writers2any site outside the two. toggle_always_uv creates and removes the record; the gate sweep removes it. crates/rsk-fido/src/config.rs:328-330’s always_uv_enabled READS it and resolves a faulted read to ON rather than to the default, which is a strictness this clause does not model at all
bound_feature_sites2any dependence the two sites do not carry. git grep 'feature = "always-uv"' crates/rsk-fido/src returns exactly crates/rsk-fido/src/config.rs:316 and crates/rsk-fido/src/conformance/config.rs:77 — neither is in reset.rs or reset_assurance.rs, so no verification-side file in this bundle can tell the two builds apart

Row note (shipped_relation). the review is over the shipped source at b185fc3 with crates/rsk-fido/ clean in the working tree, and its result is a split: the model’s consequent is the FLAG and the Rust α’s is the RECORD, and toggle_always_uv is what makes the two coincide — it deletes the record when the new value equals DEFAULT_ALWAYS_UV and writes it otherwise, so record-present means flag-on exactly while that default is off

Method 6 — the runtime rungs, and whether either of them could report THIS clause rather than its sibling

review over fuzz/fuzz_targets/power_cut.rs::reset_property_holds fuzz/fuzz_targets/power_cut.rs::reset_probe tests/29_reset_power_cut.py::cut_during_reset. cfg: none. features: none.

BoundValueWhat stops being proved
bound_oracles2any rung either oracle does not reach. One is a boolean over a mounted store, the other a sequence of CTAP commands after an operator’s cut, and neither has an assertion this clause owns
bound_separable_clauses1this clause and its PIN sibling, on both rungs. reset_property_holds folds them into one conjunct — !credential_usable || (fs.has_data(EF_PIN) && fs.has_data(EF_ALWAYS_UV)) — so a failure names the function; tests/29_reset_power_cut.py:526-529 folds them into assert assertion_status != 0, which says the assertion was refused without saying which gate refused it. Only the backup seal is separable, and it is the sibling this bundle is not about
bound_recorded_runs0everything the board rung would say. The test column counts a FILE that names the invariant; no board run is recorded anywhere, hardware is 0 on the evidence vector, and PLAT-FLASH-001 owns the missing result at status = "pending"
bound_asserts2any clause the two device assertions do not separate, and one of the two is the folded one. The script prints alwaysUv from getInfo in its failure message, so an operator reading a red run can see the flag — but the assertion does not test it

Row note (shipped_relation). both rungs drive the REAL reset: the fuzz target cuts inside the store writes and remounts, the device script asks an operator to pull the cable. Their oracles read what the device answers, which for alwaysUv is the FLAG on the device side (getInfo options.alwaysUv) and the RECORD on the fuzz side (fs.has_data(EF_ALWAYS_UV)) — a third spelling of the same split, and on the shipped default build the two agree

Method 7 — mutation: what has to break before something goes red about this clause, at the code tier

mutation over formal/comutants.toml crates/rsk-fido/src/reset_assurance_tests.rs::reset_property_controls_go_red_on_each_early_gate_mutant assurance/bundle/logs/SEC-FIDO-006B/cargo-test-reset-assurance-flavours.log. cfg: none. features: the default set and always-uv, driven separately.

BoundValueWhat stops being proved
bound_patched_lines2every defect the swap does not produce. The twin is the two sweep calls exchanged and nothing else, so a wipe that keeps the order and drops the record for another reason has no twin here
bound_slices1any suite the slice does not run. cargo test -p rsk-fido is the whole of what the kill is measured over, so a defect only the emulator or a device suite would catch reads as survived
bound_negative_controls1any control over the WIPE. The one per-clause control sets persistent.always_uv = false by hand after begin() and asserts the clause method returns false — it proves the method can fail, not that the phase order is what keeps it true
bound_feature_flavours2nothing, and that is the finding rather than a gap in the row: both flavours were driven and both are green, so the pair bounds no defect and instead measures that the α cannot tell them apart

Row note (shipped_relation). the twin patches the shipped file at the shipped lines: formal/comutants.toml:340-347’s find is crates/rsk-fido/src/reset.rs:127-128 verbatim, and its replace is the same two lines exchanged. The flavour probe drives the shipped test module unmodified under two feature sets, which is why its verdict is about the abstraction and not about a patch

SEC-FIDO-006C — ResetKeepsTheBackupSeal

Method 1 — the clause over the whole reachable space of the shipped constants, as one of the twelve names that configuration checks

model-check over Shipped.cfg::ResetKeepsTheBackupSeal formal/RSKeySecurityState.tla::ResetKeepsTheBackupSeal. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps2a torn prefix that first goes wrong over a third relying party — and for THIS clause that costs less than for its siblings, because its antecedent names no credential at all: snap.seed /\ snap.sealed is true with store.cred empty, which the recorded counterexample confirms
bound_channels2a torn prefix that first goes wrong over a third concurrent channel
bound_max_retries8nothing by shrinking, and eight IS the shipped ladder at crates/rsk-fido/src/consts.rs:371. This clause names no retry count
bound_mismatch_limit3nothing by shrinking, for the same reason as the ladder it pairs with
bound_max_clock1any prefix that needs two units of elapsed time; with the window at zero one Tick is also what closes the window, so the two bounds bite together here
bound_reset_window0the whole of the shipped power-up window but its first instant. A reset may START only at clock 0, so a reset begun late inside the shipped RESET_WINDOW_MS — 10 000 ms at crates/rsk-fido/src/consts.rs:407 — is a prefix this configuration never tears. The touch is not what is skipped: crates/rsk-fido/src/reset.rs:43-51 runs the ceremony unconditionally after the window check
bound_invariant_names12any obligation outside the twelve. TypeOK and eleven invariants is what this configuration checks, and this clause is one of the three added to that block after the existing bundles’ runs were recorded — a sibling bundle describing the block as nine names is describing a different file

Row note (shipped_relation). MaxRetries and MismatchLimit ARE the shipped MAX_PIN_RETRIES and PIN_MISMATCH_LIMIT at crates/rsk-fido/src/consts.rs:371 and :375; RPs and Channels are two against an unbounded device. The clause held at every reachable state of this run, and that is a stronger reading than it looks: TLC evaluates an invariant at every state, so GREEN here is a verdict about (Idle /\ snap.seen) => ((snap.seed /\ snap.sealed) => gate.backupSealed) over the whole set and not about a sampled prefix. Measured against sed -n '/^INVARIANTS/,/^SYMMETRY/p' formal/Shipped.cfg, which lists TypeOK and eleven names

Method 2 — non-degeneracy: the clause alone, with its own defect armed, so a RED cannot belong to a sibling conjunct

model-check over SoloClause_ResetKeepsTheBackupSeal.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_invariants2anything about the rest of the invariant set; TypeOK and this one clause is the whole of what the row checks
bound_armed_switches2isolation of the DEFECT. Two switches are armed — BugBackupSealedNotAGate and its companion BugSeedDoesNotLead — so what this configuration isolates is the CLAUSE, and the falsifying behaviour needs both. The mechanism is derived in x_companion_mechanism rather than asserted
bound_depth8nothing by capping — eight is a MEASURED trace length and not a bound. What it says is why the parent’s verdict cannot name a conjunct: this clause falls two states shallower than either sibling, so a search checking all three reports this one every time
bound_distinct_states5359any behaviour outside the reachable set this configuration explored. It is three orders of magnitude smaller than either sibling clause’s run, which is the same fact as the depth: the shallow clause is the cheap one to falsify and the one that masks the others

Row note (shipped_relation). the configuration checks TypeOK and this clause and nothing else — formal/gen-configs.sh:358 emits exactly that inside the loop over CLAUSE_INV at formal/gen-configs.sh:121, and clause_mutant at formal/gen-configs.sh:348 is what pairs this clause with BugBackupSealedNotAGate. Its constants are Shipped.cfg’s, verbatim, except the two armed switches. formal/floors.txt:SoloClause_*.cfg gives the family a wildcard RED row with no invariant column, so the runner does not compare the reported name for these; the name in formal/runs.toml:138 is the one TLC printed

Method 3 — the localisation claim: that every parent-level reset verdict in this tree reports THROUGH this clause, which is the reason the clause split exists at all

model-check over Solo_BugBackupSealedNotAGate.cfg Solo_BugResetGatesFirst.cfg Solo_BugSeedDoesNotLead.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_configurations3a fourth reset-family switch. BugStateResetAfterWipe is the one not run here, and it is the parent bundle’s row — its falsifying state carries the same three fields, so including it would add a fourth instance and not a fourth kind
bound_clause_reported1which conjunct a reader would have to open the trace to learn. The parent invariant is what the verdict column prints; that the trace is this clause is recovered by reading the final state, and no column in this tree carries it
bound_depths8, 8 and 13nothing — the three are MEASURED trace lengths. Read against the two sibling clauses’ 16 and 18, they are the whole localisation argument
bound_switches2the pair as a unit. Two DISTINCT defects reach this clause at the parent level — the marker’s own and the phase-order one — and the third configuration is the companion, present to show it does NOT reach this clause

Row note (shipped_relation). formal/RSKeySecurityState.tla:1826-1830 claims all four reset-family mutants report the umbrella invariant on its third clause. Verified here by opening the final state of each artifact rather than by citing the comment: Solo_BugBackupSealedNotAGate.cfg and Solo_BugResetGatesFirst.cfg both end at ResetAborts with snap.surv empty, snap.pin FALSE, snap.seed TRUE, snap.sealed TRUE and gate.backupSealed FALSE — so the two sibling clauses are VACUOUS there and only this one is falsified, on a switch whose only model owner the sibling clauses are. The third artifact is the control in the other direction: Solo_BugSeedDoesNotLead.cfg falls on NoUnmanageableCredential at a state with snap.sealed FALSE, so the companion does not reach this clause and is not what its verdict is about

Method 4 — tier C: the clause holds of the projected reset state after one concrete step out of a symbolic pre-state

bounded proof over crates/rsk-fido/src/reset_refinement_kani.rs::reset_keeps_the_backup_seal crates/rsk-fido/src/reset_assurance.rs::reset_keeps_the_backup_seal. cfg: kani. features: kani-soft.

BoundValueWhat stops being proved
bound_steps1every reachability question. Closure under one symbolic step out of a symbolic pre-state is an induction and carries to sequences; what it cannot say is that any particular interleaving is REACHED, so a step whose precondition no real run satisfies is proved about all the same
bound_actions13any reset step the thirteen do not name. apply_symbolic_step at crates/rsk-fido/src/reset_refinement_kani.rs:56-94 selects one by action % 13 and applies it once; a transition the shipped reset can make with no arm here is outside the closure argument. The arm that matters for this clause is reset.delete(EF_BACKUP_SEALED) at crates/rsk-fido/src/reset_refinement_kani.rs:77
bound_symbolic_booleans14every field of FidoState the projection does not carry. Fourteen booleans — six persistent, six snapshot, two volatile — are the WHOLE projection, so what is closed under a step is the projection and not the state
bound_progress_values5nothing by omission: five is the whole ResetProgress enum at crates/rsk-fido/src/reset_assurance.rs:62-68 and the pre-state draws every variant, so this axis is not a shrink
bound_covers1every witness but the one. The single kani::cover! at crates/rsk-fido/src/reset_refinement_kani.rs:173-178 witnesses snapshot.seen /\ snapshot.owner_seed /\ owner_seed_reachable /\ persistent.backup_sealed, and says nothing about any other valuation being reachable

Row note (shipped_relation). AND THIS ASSERTION IS IMPLIED BY THE PARENT HARNESS ON THE TREE AS IT STANDS, which this bundle says rather than presenting an independent proof: reset_never_weakens_surviving_state_across_reboot assumes the same well_formed(pre), applies the same one step, and asserts well_formed(post) — whose last conjunct at crates/rsk-fido/src/reset_assurance.rs:267 IS the conjunction. What this harness adds is its cover, which is not implied, and a mutation signal if the conjunction ever loses this conjunct. It is also the reason the property reads BOUNDED at all: status is rebuilt from the derivation and kani > 0 is what selects it. The α is WIDER than the TLA+ clause in one place and that widening belongs to this clause alone — see c_alpha_is_not_the_model

Method 5 — the production side: which site decides the marker’s phase, which sites read it, and what the derived column can see of any of that

review over crates/rsk-fido/src/reset.rs::is_fido_gate_record crates/rsk-fido/src/reset.rs::reset crates/rsk-fido/src/reset.rs::sweep crates/rsk-fido/src/vendor.rs::try_backup_sealed crates/rsk-fido/src/vendor.rs::backup_export. cfg: none — every site above is unconditional production code except crates/rsk-display/src/backup.rs, which is named in prose and not resolved here because it is behind the display feature. features: none.

BoundValueWhat stops being proved
bound_tagged_sites1every owner outside the one tagged site. The clause’s whole rust column is one Refines line on is_fido_gate_record, so the ordering block that the property actually lives in — crates/rsk-fido/src/reset.rs:107-128 — carries no tag of its own and is invisible to the derivation
bound_gate_records5the four gate records this clause does not name. The phase holds five and this clause is about one, so a torn prefix that drops EF_DEVICE_PIN or EF_MINPINLEN early is outside this argument entirely
bound_consumers2a third reader of the marker. Two exist — the host export at crates/rsk-fido/src/vendor.rs:874 and the on-device reveal at crates/rsk-display/src/backup.rs:47 — and the second is compiled in only on a display build, so on the default image this clause guards one surface and on a display image it guards two. The model has one boolean and no consumer at all
bound_writers2any path that could set the marker other than the two finalize surfaces. Both write the same one byte, so no reader can tell which wrote it, and neither can the model
bound_crates1the display crate, which is where the second consumer lives. Everything else in this argument is in rsk-fido, which is what makes rust = 1 a count of one file rather than a spread

Row note (shipped_relation). the marker’s phase is decided at exactly one site — the matches! arm at crates/rsk-fido/src/reset.rs:258 — and consumed at two, in two different crates, one of them behind a feature. The runtime consumer is FAIL-CLOSED where this clause is fail-open: backup_sealed at crates/rsk-fido/src/vendor.rs:1073 answers true for a probe the medium could not complete, precisely because the absent arm hands out the master seed. So the only way the window re-opens on a live seed is a reset that removed the record, which is the behaviour this clause constrains and the reason it has no runtime backstop

Method 6 — the code twin: the model switch as the real defect in production Rust, and what the tree’s own suite is actually detecting when it kills it

mutation over formal/comutants.toml::BugBackupSealedNotAGate scripts/comutate.py::armed_subject crates/rsk-fido/src/reset_assurance_tests.rs::a_backup_seal_swept_with_the_secrets_is_a_reopened_export_window. cfg: none. features: none — the slice the row names is cargo test -p rsk-fido on the default feature set.

BoundValueWhat stops being proved
bound_twins1any defect of this shape nobody registered. One comutant credits this clause, against the parent’s three, so a variant that re-opens the window some other way has no code-level verdict here
bound_patch_hunks1the CLASS the hunk belongs to. One hunk drops one alternative from one match arm; a defect that needed two edits, or an edit anywhere but that arm, is not expressed
bound_patched_files1a defect that has to span two files — which the two-consumer shape above makes plausible and no comutant covers
bound_slice_crates1any test outside cargo test -p rsk-fido, and any schedule but the weekly one — no row of scripts/check.sh re-drives this
bound_deterministic_killers1the two transcribers and the coin flip, which is the whole point of the count. Three tests in the slice go red on this patch and only one of them is about the defect; the other three killers are recorded in the mutation register rather than counted here

Row note (shipped_relation). formal/comutants.toml:194 carries status = "patch" and expect = "killed", which that file’s own vocabulary at formal/comutants.toml:19-21 defines as a RECORDED verdict and not a plan. It is re-driven by the weekly comutate run and by no row of scripts/check.sh. THE ROW ALSO CARRIES ITS OWN CORRECTION, and it is the longest note in that file: it was status = "unreachable" on a verdict MEASURED IN THE MODEL AND WRITTEN ABOUT THE CODE. What the code answers is recorded in the register below, with which part of it this bundle re-measured and which it inherited

Method 7 — the fuzz rung: what the byte-granular probe’s oracle asserts about this clause, read rather than run

review over fuzz/fuzz_targets/power_cut.rs::reset_property_holds fuzz/fuzz_targets/power_cut.rs::reset_probe. cfg: none. features: none — a nightly cargo fuzz build of the fuzz workspace, no feature flag.

BoundValueWhat stops being proved
bound_oracle_conjuncts2any verdict finer than the two. The oracle at fuzz/fuzz_targets/power_cut.rs:240-250 is one boolean expression whose first conjunct folds the two sibling clauses and whose second is this one, so a failure names the function and the reader has to know which conjunct is which
bound_separable_asserts1the separation the two tiers above have. One assertion covers all three clauses, so a passing run cannot distinguish a clause that was exercised from one the fixture made vacuously true
bound_snapshot_valuations1the other snapshot valuations. reset_probe writes EF_CRED, EF_PIN, EF_ALWAYS_UV and EF_BACKUP_SEALED before the reset at fuzz/fuzz_targets/power_cut.rs:276-279, so snap.sealed is TRUE by construction and the symbolic draw the Kani harness makes over it never happens here
bound_cut_budget_bytes1048575a power cut later in the write stream than the budget allows. The cut point is u32::from_be_bytes([0, data[1] & 0x0f, data[2], data[3]]) at fuzz/fuzz_targets/power_cut.rs:283-288, so a tear further in than that is not a prefix this target can produce

Row note (shipped_relation). the probe drives the REAL rsk_fido::reset::reset over a cuttable mock NOR, then mounts a fresh store, runs boot-time seed provisioning and boots a second time. It is the strongest rung below the board, and it is the ONLY rung of this clause’s ladder where the RAM copy of the seed is drawn: data[4] & 1 loads state.keydev_dec at fuzz/fuzz_targets/power_cut.rs:291-293, which is what makes owner_reachable in the oracle mean more than the flash record. No log of any run is in the tree and none is in this bundle

Method 8 — the board rung, and what its column is worth: this clause OWNS an assertion on hardware, and no run of it has ever been recorded

accepted risk over tests/29_reset_power_cut.py::cut_during_reset. cfg: none. features: none.

BoundValueWhat stops being proved
bound_recorded_runs0everything the board rung would say. The test column counts a FILE that names the invariant; no run is recorded anywhere, so nothing here is evidence that a real supply cut on real silicon preserves this clause. PLAT-FLASH-001 owns the missing result and is pending, and its own board record reads outcome = "planned"
bound_clause_asserts1nothing this clause needs — and it is the one place in the whole ladder where THIS clause is better off than its siblings. tests/29_reset_power_cut.py:537 asserts current != owner_seed under its own name; the sibling clauses share one folded assertion at tests/29_reset_power_cut.py:526-527 that says only that the operation was refused, without saying which gate refused it
bound_flavours1the display flavour’s second surface. The script drives the host BACKUP_STATE and read_seed path only, so the on-device recovery-phrase reveal — the marker’s other consumer — has no board assertion at any rung

Row note (shipped_relation). the script needs a throwaway board, the no-touch image, and either an operator’s hand or a relay, and it can exit inconclusive when the reset finishes before power goes. Its clause-C arm is conditional: it reads BACKUP_STATE, and only when the device reports NOT sealed does it try to read the seed back and assert it changed. So a board run in which the marker survived the cut passes this arm without exercising it, which is the correct shape for the property and worth saying out loud beside a column that reads one

SEC-FIDO-007 — RamNeverOutlivesFlashSeed

Method 1 — the invariant over the whole reachable space of the shipped constants

model-check over formal/RSKeySecurityState.tla::RamNeverOutlivesFlashSeed + Shipped.cfg::RamNeverOutlivesFlashSeed. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps2nothing this invariant can express — ram => store.seed names two booleans and no constant. What two costs is reach alone: a falsifying state that first arises over a third relying party is not in the set searched
bound_channels2nothing this invariant can express; what two costs is reach — a falsifying state first arising over a third concurrent channel is not in the set searched
bound_max_retries8nothing at all. The ladder is off this property’s path and eight IS the shipped value, so this axis is neither a shrink nor a term
bound_mismatch_limit3nothing at all, for the same reason as the ladder it pairs with
bound_max_clock1nothing this invariant can express. What one Tick costs is reach: a falsifying state needing a second unit of elapsed time is not in the set searched
bound_reset_window0nothing this invariant can express. What zero costs is reach: a reset started inside the shipped window is a prefix no run here produces

Row note (shipped_relation). MaxRetries and MismatchLimit ARE the shipped MAX_PIN_RETRIES (8) and PIN_MISMATCH_LIMIT (3) at crates/rsk-fido/src/consts.rs:371,375; RPs and Channels are 2 against an unbounded device; MaxClock 1 is the smallest value at which Tick is not dead; ResetWindow 0 runs the window closed only. AND NONE OF THE SIX IS ON THIS PROPERTY’S PATH: ram => store.seed names two booleans and no constant, so what the six buy is the reachable set a falsifying state would have to appear in, and what they cost this invariant is nothing it can express. That is the honest difference from SEC-FIDO-001, where MaxRetries IS the retry ladder the invariant is about

Method 2 — the same invariant on the arm of AlwaysUvShipped the default image does not build

model-check over AlwaysUv.cfg::RamNeverOutlivesFlashSeed. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps2a falsifying state that first arises over a third relying party, on the alwaysUv arm — reach again, since the invariant names no relying party
bound_channels2a falsifying state that first arises over a third concurrent channel, on the alwaysUv arm
bound_max_retries2nothing this invariant can express: neither constant appears in ram => store.seed, so six rungs off the ladder is free here in a way it is not for SEC-FIDO-001
bound_mismatch_limit1nothing this invariant can express, for the same reason
bound_max_clock1any falsifying state needing a second unit of elapsed time, on this arm as on the shipped one
bound_reset_window0the in-window arm, on this arm as on the shipped one

Row note (shipped_relation). the retry ladder is REDUCED here and the shipped one is not — 8:3 becomes 2:1 (formal/AlwaysUv.cfg:6-7) — because the arm buys the alwaysUv reachability question and Shipped.cfg is the row that is about the ladder. For THIS invariant the shrink is free in a way it is not for SEC-FIDO-001: neither constant appears in ram => store.seed. What the row does buy is that both arms of a registered standing assumption run against this property, which SEC-FIDO-001 also has and the other MODELLED-ONLY rows mostly do not

Method 3 — non-degeneracy: the invariant CAN go red, and the red names it rather than a sibling

model-check over Solo_RamNeverOutlivesFlashSeed.cfg::BugStateResetAfterWipe. cfg: none. features: none.

BoundValueWhat stops being proved
bound_invariants2anything about the rest of the invariant set — and the isolation is not optional here: the two structural facts are kept OUT of the model’s all-invariants block, and the Mut_ twin under this same switch is recorded going RED on a SIBLING’s name
bound_armed_switches1any defect needing two switches at once. One armed switch is what makes this the only place in the tree where this property is observed to fail
bound_rps2a falsifying state that first arises over a third relying party, on the one row where this invariant is seen to fail
bound_channels2a falsifying state that first arises over a third concurrent channel, on that same row

Row note (shipped_relation). the configuration checks TypeOK and this invariant and NOTHING ELSE (formal/Solo_RamNeverOutlivesFlashSeed.cfg:50-52), and arms BugStateResetAfterWipe alone with every other Bug* FALSE — which is what tells this kill from a neighbouring invariant’s. It is needed here in a way it is not on Shipped.cfg: formal/gen-configs.sh:109-114 keeps the two structural facts OUT of ALL_INV precisely so a mutant reports the first invariant it violates, and formal/runs.toml:93 records Mut_BugStateResetAfterWipe.cfg going RED: ResetNeverWeakensSurvivingState — a SIBLING’s name — under the same switch. So the Solo row is the only place in the tree where this property is observed to fail

Method 4 — the production side: which sites own the antecedent, and whether the tagged owner is one of them

review over crates/rsk-fido/src/seed.rs::ensure_seed + crates/rsk-fido/src/state.rs::clear_keydev_dec + crates/rsk-fido/src/lib.rs::load_keydev. cfg: none — every writer and reader above is unconditional production code; the two projection sites are not, and the bound counts them apart for that reason. features: none.

BoundValueWhat stops being proved
bound_tagged_owners1any owner outside the one tagged site. This is a count of SITES and not a shrink of a shipped constant, because a review has no other unit
bound_ram_writer_sites4a writer the grep did not reach. Four are one producer and three destroyers, and a count of them says which sites write the RAM copy, never that they run in an order the implication needs
bound_ram_reader_sites4anything about what a reader DOES with the copy it read. Four sites read it and the count is of sites, not of uses
bound_projection_sites2nothing about a shipped image — both projection sites are cfg-gated and neither is in one. They are counted apart for that reason, so no bound here credits them as production coverage
bound_files_in_argument6anything in a seventh file — and the measurement is the point: the slice page estimated three files, named the tag’s file, and missed both writers and the ordering site
bound_crates2a site outside the two crates. A holder of the RAM copy in a third would be outside the argument

Row note (shipped_relation). the four writers are one producer (vendor.rs:608) and three destroyers (vendor.rs:607, config.rs:435, and reset.rs:107 through FidoState::reset -> Drop); the four readers are crates/rsk-fido/src/lib.rs:108, config.rs:421, config.rs:427 and vendor.rs:1005; the two projection sites are crates/rsk-device/src/ctap.rs:261 and crates/rsk-fido/src/reset_assurance.rs:49 and BOTH are cfg-gated, so neither is in a shipped image. Six files and two crates against the THREE files docs/authorization-slice.md:484-487 estimated (seed.rs, state.rs, lib.rs) — the estimate named the tag’s file and missed both writers and the ordering site, and seed.rs is the one of the three that contains no keydev_dec at all. This bound is a count of sites, not a shrink of a shipped constant, because a review has no other unit

Method 5 — the code twin: the same defect injected into production Rust is caught by the tree’s own suite

mutation over formal/comutants.toml::BugStateResetAfterWipe + scripts/comutate.py + crates/rsk-fido/src/reset_tests.rs::a_torn_reset_never_leaves_the_session_running_on_a_wiped_seed. cfg: none. features: none — the slice is cargo test -p rsk-fido on the default feature set.

BoundValueWhat stops being proved
bound_patch_hunks2any defect the two hunks cannot express. They move one call behind another in the shipped file, which is the historical regression and not the class it belongs to
bound_patched_files1a defect that has to span two files
bound_slice_crates1any test outside the one crate the slice runs
bound_credited_configurations1what the killing TEST is about. The one credit exists only because the index reads solo configurations by invariant name; the test that falls is not a test of this property, and the source says so

Row note (shipped_relation). the patch moves ctx.state.reset() from ahead of the flash work to behind ensure_seed (formal/comutants.toml:373-386) — the E76 regression, in the shipped file, not a model edit — and expect = "killed" is a RECORDED verdict per that file’s own status vocabulary (:19-21), not a plan. The one credited configuration is Solo_RamNeverOutlivesFlashSeed.cfg, which comutate.solo_index reads BY INVARIANT NAME (scripts/comutate.py:338-366); without that reading the kill is credited to SEC-FIDO-006 and this row’s column is the co = 0 docs/authorization-slice.md:455-469 describes correcting. What the column does NOT say, and the source says so in as many words, is that the killing TEST is a test of this property

SEC-FIDO-008 — NoLiveTokenWithoutPinRecord

Method 1 — the invariant over the whole reachable space of the shipped constants

model-check over formal/RSKeySecurityState.tla::NoLiveTokenWithoutPinRecord + Shipped.cfg::NoLiveTokenWithoutPinRecord. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps2nothing this invariant can express — tok.live => pin.set names two booleans and no relying party. What two costs is reach alone
bound_channels2nothing this invariant can express; what two costs is reach — a falsifying state first arising over a third concurrent channel is not in the set searched
bound_max_retries8nothing by shrinking: eight IS the shipped ladder, and this constant is ON this property’s path, because the only producer of the antecedent is reachable only through a successful PIN attempt. So the approach runs at full shipped depth here and is reduced on all three arms below
bound_mismatch_limit3nothing by shrinking, for the same reason as the ladder it pairs with — three IS the shipped mismatch limit and the antecedent’s approach passes through it
bound_max_clock1any falsifying state that needs a second unit of elapsed time
bound_reset_window0the in-window arm. At zero the reset that clears the PIN record is reached only outside the power-up window

Row note (shipped_relation). MaxRetries and MismatchLimit ARE the shipped MAX_PIN_RETRIES (8) and PIN_MISMATCH_LIMIT (3) at crates/rsk-fido/src/consts.rs; RPs and Channels are 2 against an unbounded device; MaxClock 1 is the smallest value at which Tick is not dead; ResetWindow 0 runs the window closed only. FOUR of the six are off this property’s path — tok.live => pin.set names two booleans and no constant — but two are NOT, and that is the difference from the counterpart: MaxRetries and MismatchLimit bound the PIN-attempt ladder, and GetPinToken (the only producer of the antecedent) is reachable only THROUGH a successful PinAttempt. A ladder of 8 is the shipped one, so the antecedent’s own approach is at full shipped depth here and reduced on the three arms below

Method 2 — the same invariant on the arm of AlwaysUvShipped the default image does not build

model-check over AlwaysUv.cfg::NoLiveTokenWithoutPinRecord. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps2a falsifying state that first arises over a third relying party, on the alwaysUv arm
bound_channels2a falsifying state that first arises over a third concurrent channel, on the alwaysUv arm
bound_max_retries2the six rungs between two and the shipped eight, and it costs more here than for the counterpart property: the ladder is on the antecedent’s approach path, so this arm reaches a live token over a shallower PIN-attempt sequence than the image has
bound_mismatch_limit1the two mismatches between one and the shipped three, on the same approach path
bound_max_clock1any falsifying state needing a second unit of elapsed time, on this arm
bound_reset_window0the in-window arm, on this arm as on the shipped one

Row note (shipped_relation). the retry ladder is REDUCED here and the shipped one is not — 8:3 becomes 2:1 (formal/AlwaysUv.cfg:6-7) — because the arm buys the alwaysUv reachability question and Shipped.cfg is the row that is about the ladder. It matters MORE for this property than for the counterpart: the ladder is on the antecedent’s approach path, so this arm reaches tok.live over a shallower PIN-attempt sequence than the shipped image has. What it buys is that the guard whose inertness this invariant licenses — ~(gate.alwaysUv /\ ~pin.set) at RegisterStart:935 and AssertStart:1056 — is checked on the arm where gate.alwaysUv is the compiled default, which is the only arm where that conjunct can be reached with a live guard

Method 3 — the same invariant with the permission domain widened to all sixteen subsets

model-check over PermWide.cfg::NoLiveTokenWithoutPinRecord. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps1the second relying party. One is the price this row pays for the wide permission domain, and it is harmless to this implication, which names no relying party at all
bound_channels2a falsifying state that first arises over a third concurrent channel, on the wide-permission arm
bound_max_retries2the six rungs between two and the shipped eight, on the approach to the antecedent
bound_mismatch_limit1the two mismatches between one and the shipped three, on that same approach
bound_perm_subsets16nothing — sixteen is the whole four-bit domain and this axis is a WIDENING. What it does not buy is reach on this property: tok.live is a flag and not a set, so the permission domain is off the implication and this row is a second arm of a standing boolean rather than new depth

Row note (shipped_relation). WidePerms draws ps from SUBSET Perms rather than from PermSets’ five, so the sixteen are the whole four-bit domain and this bound is not a shrink — it is the widening PLAT-MODEL-001 exists for. RPs falls to 1 to pay for it (formal/PermWide.cfg:4), which is a REAL narrowing on this row and a harmless one: the implication names no rp, and GetPinToken’s r \in RPs \cup {NoRp} only decides which credential a token is bound to. The permission set is likewise off the implication — tok.live is a flag, not a set — so what this row buys is a second arm of a standing boolean rather than new reach on the property

Method 4 — the same invariant with EF_MINPINLEN’s forced-PIN-change gate modelled

model-check over ForceChange.cfg::NoLiveTokenWithoutPinRecord. cfg: none. features: none.

BoundValueWhat stops being proved
bound_rps1the second relying party, dropped on this arm as on the wide-permission one and harmless for the same reason
bound_channels2a falsifying state that first arises over a third concurrent channel, on the forced-change arm
bound_max_retries2the six rungs between two and the shipped eight, on the approach to the antecedent
bound_mismatch_limit1the two mismatches between one and the shipped three, on that same approach
bound_gate_bits5any gate state the record’s five fields cannot hold. Five is a count of the MODEL’s own structure and not a compressed shipped constant — the reset’s gate-record list is five as well, and the two fives are not the same five

Row note (shipped_relation). ForceChangeModelled TRUE puts gate.forceChange in play, and it is the one standing boolean of the three that lands directly on this property’s antecedent: PLAT-MODEL-010 records that the flag REFUSES token issuance after a correct PIN, so this arm is the only one where a successful PinAttempt does not reach tok' = [live \|-> TRUE, …]. The five gate bits are the record fields gate carries (ppuat, ppuatStale, alwaysUv, backupSealed, forceChange), which is a count of the model’s own structure and not a compressed shipped constant — the reset’s own gate-record list is five too (reset.rs:258) and the two fives are not the same five

Method 5 — non-degeneracy: the invariant CAN go red, the red names it rather than a sibling, and the counterexample lands on the untagged half

model-check over Solo_NoLiveTokenWithoutPinRecord.cfg::BugStateResetAfterWipe. cfg: none. features: none.

BoundValueWhat stops being proved
bound_invariants2anything about the rest of the invariant set — and the isolation is not optional here: the two structural facts are kept out of the all-invariants block, and the Mut_ twin under this same switch is recorded going RED on a sibling’s name
bound_armed_switches1any defect needing two switches at once. One armed switch is what makes this the only place in the tree where this property is observed to fail
bound_counterexample_states12nothing — twelve is the counterexample’s MEASURED length and not a bound the configuration imposes. What it carries is the evidence: the falsifying state is reached only after the gate sweep, which is the untagged half
bound_rps2a falsifying state that first arises over a third relying party, on the one row where this invariant is seen to fail
bound_channels2a falsifying state that first arises over a third concurrent channel, on that same row

Row note (shipped_relation). the configuration checks TypeOK and this invariant and NOTHING else (formal/Solo_NoLiveTokenWithoutPinRecord.cfg:50-52) and arms BugStateResetAfterWipe alone with every other Bug* FALSE — measured, armed_count over that file is 1. It is needed here for the reason formal/gen-configs.sh:109-114 gives in as many words: the two structural facts are kept OUT of ALL_INV so a mutant reports the first invariant it violates, and formal/runs.toml:93 records Mut_BugStateResetAfterWipe.cfg going RED on a SIBLING’s name under the same switch. So this is the only place in the tree where this property is observed to fail. The twelve states are the counterexample’s length and not a bound the configuration imposes — a review-shaped bound in a model-check row, and it is here because the depth is the evidence: the falsifying state is reached only after ResetSweepGates, which is the untagged half

Method 6 — the production side: which sites own each half of the implication, and whether the one tag is on a half that can falsify it

review over crates/rsk-fido/src/clientpin.rs::issue_token + crates/rsk-fido/src/state.rs::begin_using_token + crates/rsk-fido/src/reset.rs::reset. cfg: none — every site above is unconditional production code except crates/rsk-fido/src/conformance/mod.rs:177, which is cfg(test) and is counted apart in owners_antecedent rather than in these bounds. features: none.

BoundValueWhat stops being proved
bound_tagged_owners1any owner outside the one tagged site — and which HALF it is on: the tag sits on the antecedent, and the half with the recorded history is the consequent. This is a count of SITES and not a shrink of a shipped constant, because a review has no other unit
bound_antecedent_sites4an antecedent site the review did not open. Four were read, one of them the record gate the door runs first, and a count of sites says which they are and never that the order between them holds
bound_consequent_sites5anything about what a consequent site DOES. Five sites clear or overwrite the record, and the count names them without saying that each leaves the implication standing
bound_production_token_callers1coverage of the caller outside a shipped image. One in-image caller is counted; the cfg(test) site is counted apart, so no bound here credits it
bound_files_in_argument5anything in a sixth file — and the measurement is the point: the slice page estimated ONE file, the tag’s, which is the antecedent half only
bound_crates2a site outside the two crates, including any other holder of the record the consequent names

Row note (shipped_relation). the four antecedent sites are the definition (state.rs:626), its one in-image caller (clientpin.rs:469), the door above it (clientpin.rs:369) and the record gate that door runs first (clientpin.rs:750-758); the five consequent sites are reset.rs:107, the phase-2 sweep at :128, the membership predicate at :235-259, Fs::factory_wipe at crates/rsk-fs/src/fs.rs:543 and the overwriting writer at clientpin.rs:914-915. Five files over two crates, against the ONE file docs/authorization-slice.md:462-467 estimated (crates/rsk-fido/src/clientpin.rs) — the estimate named the tag’s file, which is the antecedent half only, and the half with the recorded history is in a file it did not name. THIS BOUND IS A COUNT OF SITES, not a shrink of a shipped constant, because a review has no other unit; the same weakness the counterpart recorded, at the same group

Method 7 — the code twin: what the co = 1 column credits, which configuration attributes it, and what the killing assertion is actually about

mutation over formal/comutants.toml::BugStateResetAfterWipe + scripts/comutate.py::solo_invariants + crates/rsk-fido/src/reset_tests.rs::a_torn_reset_never_leaves_the_session_running_on_a_wiped_seed. cfg: none. features: none — the slice formal/comutants.toml names is cargo test -p rsk-fido on the default feature set.

BoundValueWhat stops being proved
bound_patch_hunks2any defect the two hunks cannot express. They move one call behind another in the shipped file, which is the historical regression and not the class it belongs to
bound_patched_files1a defect that has to span two files
bound_credited_configurations1the credit under the older attribution path. The single-answer resolver names a sibling’s configuration for this bug, so without the by-invariant reading this kill is credited to SEC-FIDO-006 alone
bound_tests_asserting_the_token_half0everything the co-refutation column implies about THIS property. Zero tests assert the token half: the twin’s one falling test asserts a seed field, and the only test that asserts both EF_PIN gone and the permissions cleared tears nothing, so the mutant leaves it green — the kill is credited here and is not a kill of this invariant
bound_slice_crates1any test outside the one crate the slice runs — and this row was not re-driven here, so the verdict it records is the tree’s own recorded status

Row note (shipped_relation). the patch moves ctx.state.reset() from ahead of the flash work to behind ensure_seed (formal/comutants.toml:373-386) — the E76 regression, in the shipped file — and expect = "killed" is a RECORDED verdict in that file’s own status vocabulary. The one credited configuration is Solo_NoLiveTokenWithoutPinRecord.cfg, reached only because comutate.solo_index reads solo-style configurations BY INVARIANT NAME; comutate.solo_invariant, the older single-answer path, resolves this bug to Solo_BugStateResetAfterWipe.cfg and answers ResetNeverWeakensSurvivingState, so the kill is credited to SEC-FIDO-006 alone. AND THE FOURTH BOUND IS THE FINDING: ZERO tests in this tree assert the token half. The twin’s one falling test asserts state.keydev_dec.is_none(); the only test that asserts both !fs.has_data(EF_PIN) and paut.permissions == 0 tears nothing, so the mutant leaves it green. This row was NOT re-run here — comutate.py run patches a shared working tree and other agents are in it — so the verdict this bundle records for it is the tree’s own recorded status, and the mutation group says so

Method 8 — the two arguments that rest on this invariant, and the measurement that says the guard it makes redundant is inert while the invariant is not

review over formal/RSKeySecurityState.tla::ConfigGuard + formal/README.md::NoLiveTokenWithoutPinRecord + formal/gen-configs.sh::EXTRA_INV. cfg: none. features: none.

BoundValueWhat stops being proved
bound_dependent_model_sites3any site outside the module that rests on this sentence. Three model sites were read; the Rust that carries the same conjunct is not in the count
bound_measured_inert_conjuncts1the inertness of any other guard. One conjunct was measured, by removing it from both call sites at once, and no other guard in the module has been checked the same way
bound_states_changed_by_removal0anything about the INVARIANT. The zero says the GUARD disables nothing; the invariant itself has a reachable falsifying state the moment one switch is armed, and reading the zero as a claim about the property is the confusion this row exists to refuse
bound_transitions_changed_by_removal0the currency of the measurement. Both zeros are the review’s, recorded in formal/README.md and not re-taken here — no TLC run was performed for this bundle

Row note (shipped_relation). three sites in the module rest on this sentence: ConfigGuard at :1091 carries no pin.set conjunct because config.rs:245-247 tests the MAC and PERM_ACFG and nothing else, and the two ~(gate.alwaysUv /\ ~pin.set) conjuncts at :935 and :1056 are kept only because the Rust has them. formal/README.md:950-954 records the measurement: removed from BOTH call sites the reachable space is bit-identical AND the transition count is unchanged, so the conjunct disables nothing. THE DISTINCTION THIS ROW EXISTS FOR: it is the GUARD that is inert, not the invariant. The invariant has a reachable falsifying state — 98 069 distinct, depth 12 — the moment one switch is armed. The two zeros are that measurement’s, taken by the review formal/README.md records and NOT re-taken here; no TLC run was performed for this bundle

SEC-STORE-001 — RSKeyStore!NoOrphanedMetadata

Method 1 — show that NoOrphanedMetadata holds of every reachable state of the flash layer, over the whole action set and not one path through it

model-check over Store.cfg formal/RSKeyStore.tla. cfg: none. features: none.

BoundValueWhat stops being proved
bound_fids2any shape that needs a third file — a three-way aliasing of the present map, or a metadata blob holding more records than the pair can put in it. AS-RESET-2 is the row that says why the pair is argued to be enough, and it is argued rather than shown
bound_values_per_fid3nothing about a value the model never writes. Two stored values plus the absent sentinel is what makes an overwrite observable; a third would add no distinction this invariant reads
bound_variables7every part of the real Fs outside these seven — the dynamic-fid vector, the write generation counter, the sealed-payload layer, and flash geometry of any kind
bound_invariants6whatever is true of the store and is not one of these six. A GREEN run says nothing about a clause nobody wrote down
bound_bug_switches9any defect outside the nine formal/gen-configs.sh emits a switch for. The mutation score below is out of those nine and not out of the defects the store can have
bound_next_disjuncts7any action the model does not have. There is no compaction, no factory_wipe, and no concurrent second caller in this Next

Row note (shipped_relation). the model is Fs over a Storage, with the medium’s failure modes as switches and the geometry left out. What is shipped is one instance of that shape at 16-bit FIDs; what is checked is two FIDs, and AS-RESET-2 is the row that argues the step between them

Method 2 — show that the GREEN above is not vacuous — that a configuration which BREAKS NoOrphanedMetadata is refused, and refused BY NAME

mutation over StoreMut_BugDeleteValueBeforeMeta.cfg StoreSolo_BugDeleteValueBeforeMeta.cfg StoreMut_BugDeleteMetaOnlyUnderPresent.cfg StoreSolo_BugDeleteMetaOnlyUnderPresent.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_bug_switches_for_this_invariant2the other switches of the nine. A switch that breaks a sibling invariant is evidence about that sibling, and this row does not borrow it
bound_tiers2nothing about a tier this property has no configuration in. Where the count is 1 there is no Solo_ half and the row says so instead of implying one
bound_recorded_runs4every run not in the [[artifact]] rows below. A verdict with no log beside it is a sentence, and this bundle carries none
bound_killed4whether the kill was for the modelled defect rather than its inverse. That is the direction column of every [[mutation]] row, read one at a time, and two of twenty-four co-refutation patches in this tree failed exactly there
bound_store_configurations22any configuration formal/gen-configs.sh does not emit. The roster is generated, so a defect nobody wrote a switch for has no row anywhere in it
bound_distinct_states_green364everything the mutants explore beyond the clean run’s space. A RED row stops at its first violation, so its own state count is a property of when TLC found the bug and not of the space

Row note (shipped_relation). a switch is a defect the shipped tree does not have: gen-configs.sh writes every Bug* FALSE in Store.cfg, so the mutants say what the model would catch and not what the code does

Method 3 — read the production sites the model claims to abstract, and say whether the ordering the invariant rests on is the ordering the code has

review over crates/rsk-fs/src/fs.rs::delete crates/rsk-fs/src/fs.rs::force_delete crates/rsk-fs/src/fs.rs::force_delete_halves crates/rsk-fs/src/powercut.rs::delete_landed crates/rsk-fs/src/store_assurance.rs::delete_orphaned_metadata. cfg: none. features: none.

BoundValueWhat stops being proved
bound_refinement_markers5every site that refines this invariant and says so nowhere. The markers are doc comments, so a site that drifts out of one is invisible to this count
bound_fs_removal_sites4removals outside Fs. assurance/deleters.toml’s own header says its two scope rules cannot see these four, which is why they are a separate table
bound_fs_source_lines895everything read as prose rather than as code. A line count is the size of what was read, not evidence that it was read correctly
bound_reviewers1independence. One reader wrote this bundle and read these sites, so nothing here is a second opinion and the row says so rather than leaving the count out
bound_files_read3the rest of the crate. rsk-fs is fifteen source files and this row opened the ones the subjects name
bound_crate_kani_proofs13whether any of them is about THIS invariant. The count is the crate’s; the attribution is the registry’s NAME match, and this bundle records where the two disagree

Row note (shipped_relation). this is the only row of the four that touches shipped Rust, and it is a READING rather than a proof. TCB-1 is what carries it to the image

Method 4 — carry NoOrphanedMetadata out of the model and onto something the host runs: the model’s Delete-step violation predicate, projected onto a real StoreView

trace over crates/rsk-fs/src/store_assurance.rs::delete_orphaned_metadata. cfg: none. features: none.

BoundValueWhat stops being proved
bound_view_fids3any shape needing a fourth file. store_assurance::VIEW_FIDS is a three-element array, so the host sweep’s projection is as narrow as the model’s pair plus one
bound_step_predicates3the fourth invariant, which has none. crates/rsk-fs/src/store_assurance.rs says why: NoSilentOrphan forbids an answer rather than a state
bound_kani_proofs_in_crate13every clause no harness in the crate states. Thirteen proofs is the crate’s whole bounded surface, and only five of them ran for this bundle
bound_harnesses_run5the eight this bundle did not run — the four in powercut_kani.rs, the one in fs_kani.rs, and three more of the refinement file. Their verdicts are not here
bound_symbolic_fids24the shipped 65536. Under cfg(kani) FID_PRESENT_BYTES is 3, so the map is 24 bits and EF_META is re-aliased to 0x0017 to sit inside it — a shrink crates/rsk-fs/src/store_meta_kani.rs itself lists three consequences of
bound_cover_properties2whether the harness reached anything a cover does not name. Two satisfied covers say the assumed domain is non-empty, not that it is the right one

Row note (shipped_relation). the projection is verification-only and excluded from production builds, so this row says the shipped primitives satisfy the model’s clauses — not that the shipped image was checked

SEC-STORE-002 — RSKeyStore!NoFalseAbsent

Method 1 — show that NoFalseAbsent holds of every reachable state of the flash layer, over the whole action set and not one path through it

model-check over Store.cfg formal/RSKeyStore.tla. cfg: none. features: none.

BoundValueWhat stops being proved
bound_fids2any shape that needs a third file — a three-way aliasing of the present map, or a metadata blob holding more records than the pair can put in it. AS-RESET-2 is the row that says why the pair is argued to be enough, and it is argued rather than shown
bound_values_per_fid3nothing about a value the model never writes. Two stored values plus the absent sentinel is what makes an overwrite observable; a third would add no distinction this invariant reads
bound_variables7every part of the real Fs outside these seven — the dynamic-fid vector, the write generation counter, the sealed-payload layer, and flash geometry of any kind
bound_invariants6whatever is true of the store and is not one of these six. A GREEN run says nothing about a clause nobody wrote down
bound_bug_switches9any defect outside the nine formal/gen-configs.sh emits a switch for. The mutation score below is out of those nine and not out of the defects the store can have
bound_next_disjuncts7any action the model does not have. There is no compaction, no factory_wipe, and no concurrent second caller in this Next

Row note (shipped_relation). the model is Fs over a Storage, with the medium’s failure modes as switches and the geometry left out. What is shipped is one instance of that shape at 16-bit FIDs; what is checked is two FIDs, and AS-RESET-2 is the row that argues the step between them

Method 2 — show that the GREEN above is not vacuous — that a configuration which BREAKS NoFalseAbsent is refused, and refused BY NAME

mutation over StoreMut_BugCacheFaultAsAbsent.cfg StoreSolo_BugCacheFaultAsAbsent.cfg StoreMut_BugTruncatedScanDecidesAll.cfg StoreSolo_BugTruncatedScanDecidesAll.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_bug_switches_for_this_invariant2the other switches of the nine. A switch that breaks a sibling invariant is evidence about that sibling, and this row does not borrow it
bound_tiers2nothing about a tier this property has no configuration in. Where the count is 1 there is no Solo_ half and the row says so instead of implying one
bound_recorded_runs4every run not in the [[artifact]] rows below. A verdict with no log beside it is a sentence, and this bundle carries none
bound_killed4whether the kill was for the modelled defect rather than its inverse. That is the direction column of every [[mutation]] row, read one at a time, and two of twenty-four co-refutation patches in this tree failed exactly there
bound_store_configurations22any configuration formal/gen-configs.sh does not emit. The roster is generated, so a defect nobody wrote a switch for has no row anywhere in it
bound_distinct_states_green364everything the mutants explore beyond the clean run’s space. A RED row stops at its first violation, so its own state count is a property of when TLC found the bug and not of the space

Row note (shipped_relation). a switch is a defect the shipped tree does not have: gen-configs.sh writes every Bug* FALSE in Store.cfg, so the mutants say what the model would catch and not what the code does

Method 3 — read the production sites the model claims to abstract, and say whether the ordering the invariant rests on is the ordering the code has

review over crates/rsk-fs/src/fs.rs::known_absent crates/rsk-fs/src/fs.rs::settle crates/rsk-fs/src/fs.rs::scan crates/rsk-fs/src/fs.rs::try_read. cfg: none. features: none.

BoundValueWhat stops being proved
bound_refinement_markers2every site that refines this invariant and says so nowhere. The markers are doc comments, so a site that drifts out of one is invisible to this count
bound_fs_removal_sites4removals outside Fs. assurance/deleters.toml’s own header says its two scope rules cannot see these four, which is why they are a separate table
bound_fs_source_lines895everything read as prose rather than as code. A line count is the size of what was read, not evidence that it was read correctly
bound_reviewers1independence. One reader wrote this bundle and read these sites, so nothing here is a second opinion and the row says so rather than leaving the count out
bound_files_read2the rest of the crate. rsk-fs is fifteen source files and this row opened the ones the subjects name
bound_crate_kani_proofs13whether any of them is about THIS invariant. The count is the crate’s; the attribution is the registry’s NAME match, and this bundle records where the two disagree

Row note (shipped_relation). this is the only row of the four that touches shipped Rust, and it is a READING rather than a proof. TCB-1 is what carries it to the image

Method 4 — carry NoFalseAbsent out of the model and onto something the host runs: the three harnesses the registry counts as this row’s kani=3, run for this bundle

bounded proof over crates/rsk-fs/src/store_refinement_kani.rs::no_false_absent_from_a_neighbours_delete crates/rsk-fs/src/store_refinement_kani.rs::no_false_absent_survives_a_faulted_confirm crates/rsk-fs/src/store_refinement_kani.rs::no_false_absent_reader_trusts_only_a_decided_bit. cfg: kani. features: none.

BoundValueWhat stops being proved
bound_view_fids3any shape needing a fourth file. store_assurance::VIEW_FIDS is a three-element array, so the host sweep’s projection is as narrow as the model’s pair plus one
bound_step_predicates3the fourth invariant, which has none. crates/rsk-fs/src/store_assurance.rs says why: NoSilentOrphan forbids an answer rather than a state
bound_kani_proofs_in_crate13every clause no harness in the crate states. Thirteen proofs is the crate’s whole bounded surface, and only five of them ran for this bundle
bound_harnesses_run5the eight this bundle did not run — the four in powercut_kani.rs, the one in fs_kani.rs, and three more of the refinement file. Their verdicts are not here
bound_symbolic_fids24the shipped 65536. Under cfg(kani) FID_PRESENT_BYTES is 3, so the map is 24 bits and EF_META is re-aliased to 0x0017 to sit inside it — a shrink crates/rsk-fs/src/store_meta_kani.rs itself lists three consequences of
bound_cover_properties2whether the harness reached anything a cover does not name. Two satisfied covers say the assumed domain is non-empty, not that it is the right one

Row note (shipped_relation). the projection is verification-only and excluded from production builds, so this row says the shipped primitives satisfy the model’s clauses — not that the shipped image was checked

SEC-STORE-003 — RSKeyStore!NoRecordLostToMetaWrite

Method 1 — show that NoRecordLostToMetaWrite holds of every reachable state of the flash layer, over the whole action set and not one path through it

model-check over Store.cfg formal/RSKeyStore.tla. cfg: none. features: none.

BoundValueWhat stops being proved
bound_fids2any shape that needs a third file — a three-way aliasing of the present map, or a metadata blob holding more records than the pair can put in it. AS-RESET-2 is the row that says why the pair is argued to be enough, and it is argued rather than shown
bound_values_per_fid3nothing about a value the model never writes. Two stored values plus the absent sentinel is what makes an overwrite observable; a third would add no distinction this invariant reads
bound_variables7every part of the real Fs outside these seven — the dynamic-fid vector, the write generation counter, the sealed-payload layer, and flash geometry of any kind
bound_invariants6whatever is true of the store and is not one of these six. A GREEN run says nothing about a clause nobody wrote down
bound_bug_switches9any defect outside the nine formal/gen-configs.sh emits a switch for. The mutation score below is out of those nine and not out of the defects the store can have
bound_next_disjuncts7any action the model does not have. There is no compaction, no factory_wipe, and no concurrent second caller in this Next

Row note (shipped_relation). the model is Fs over a Storage, with the medium’s failure modes as switches and the geometry left out. What is shipped is one instance of that shape at 16-bit FIDs; what is checked is two FIDs, and AS-RESET-2 is the row that argues the step between them

Method 2 — show that the GREEN above is not vacuous — that a configuration which BREAKS NoRecordLostToMetaWrite is refused, and refused BY NAME

mutation over StoreMut_BugMetaAddDropsOnFault.cfg StoreMut_BugMetaWriteTearsBlob.cfg StoreMut_BugMetaDeleteTearsBlob.cfg StoreInductionMut_BugMetaAddDropsOnFault.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_bug_switches_for_this_invariant3the other switches of the nine. A switch that breaks a sibling invariant is evidence about that sibling, and this row does not borrow it
bound_tiers2nothing about a tier this property has no configuration in. Where the count is 1 there is no Solo_ half and the row says so instead of implying one
bound_recorded_runs4every run not in the [[artifact]] rows below. A verdict with no log beside it is a sentence, and this bundle carries none
bound_killed4whether the kill was for the modelled defect rather than its inverse. That is the direction column of every [[mutation]] row, read one at a time, and two of twenty-four co-refutation patches in this tree failed exactly there
bound_store_configurations22any configuration formal/gen-configs.sh does not emit. The roster is generated, so a defect nobody wrote a switch for has no row anywhere in it
bound_distinct_states_green364everything the mutants explore beyond the clean run’s space. A RED row stops at its first violation, so its own state count is a property of when TLC found the bug and not of the space

Row note (shipped_relation). a switch is a defect the shipped tree does not have: gen-configs.sh writes every Bug* FALSE in Store.cfg, so the mutants say what the model would catch and not what the code does

Method 3 — read the production sites the model claims to abstract, and say whether the ordering the invariant rests on is the ordering the code has

review over crates/rsk-fs/src/fs.rs::meta_add_reserve crates/rsk-fs/src/fs.rs::rebuild_meta crates/rsk-fs/src/fs.rs::meta_delete crates/rsk-fs/src/store_assurance.rs::meta_add_lost_a_record crates/rsk-fs/src/powercut.rs::meta_add_landed. cfg: none. features: none.

BoundValueWhat stops being proved
bound_refinement_markers2every site that refines this invariant and says so nowhere. The markers are doc comments, so a site that drifts out of one is invisible to this count
bound_fs_removal_sites4removals outside Fs. assurance/deleters.toml’s own header says its two scope rules cannot see these four, which is why they are a separate table
bound_fs_source_lines895everything read as prose rather than as code. A line count is the size of what was read, not evidence that it was read correctly
bound_reviewers1independence. One reader wrote this bundle and read these sites, so nothing here is a second opinion and the row says so rather than leaving the count out
bound_files_read3the rest of the crate. rsk-fs is fifteen source files and this row opened the ones the subjects name
bound_crate_kani_proofs13whether any of them is about THIS invariant. The count is the crate’s; the attribution is the registry’s NAME match, and this bundle records where the two disagree

Row note (shipped_relation). this is the only row of the four that touches shipped Rust, and it is a READING rather than a proof. TCB-1 is what carries it to the image

Method 4 — carry NoRecordLostToMetaWrite out of the model and onto something the host runs: the model’s MetaAdd-step violation predicate, projected onto a real StoreView

trace over crates/rsk-fs/src/store_assurance.rs::meta_add_lost_a_record. cfg: none. features: none.

BoundValueWhat stops being proved
bound_view_fids3any shape needing a fourth file. store_assurance::VIEW_FIDS is a three-element array, so the host sweep’s projection is as narrow as the model’s pair plus one
bound_step_predicates3the fourth invariant, which has none. crates/rsk-fs/src/store_assurance.rs says why: NoSilentOrphan forbids an answer rather than a state
bound_kani_proofs_in_crate13every clause no harness in the crate states. Thirteen proofs is the crate’s whole bounded surface, and only five of them ran for this bundle
bound_harnesses_run5the eight this bundle did not run — the four in powercut_kani.rs, the one in fs_kani.rs, and three more of the refinement file. Their verdicts are not here
bound_symbolic_fids24the shipped 65536. Under cfg(kani) FID_PRESENT_BYTES is 3, so the map is 24 bits and EF_META is re-aliased to 0x0017 to sit inside it — a shrink crates/rsk-fs/src/store_meta_kani.rs itself lists three consequences of
bound_cover_properties2whether the harness reached anything a cover does not name. Two satisfied covers say the assumed domain is non-empty, not that it is the right one

Row note (shipped_relation). the projection is verification-only and excluded from production builds, so this row says the shipped primitives satisfy the model’s clauses — not that the shipped image was checked

SEC-STORE-004 — RSKeyStore!NoFalseMetaAbsent

Method 1 — show that NoFalseMetaAbsent holds of every reachable state of the flash layer, over the whole action set and not one path through it

model-check over Store.cfg formal/RSKeyStore.tla. cfg: none. features: none.

BoundValueWhat stops being proved
bound_fids2any shape that needs a third file — a three-way aliasing of the present map, or a metadata blob holding more records than the pair can put in it. AS-RESET-2 is the row that says why the pair is argued to be enough, and it is argued rather than shown
bound_values_per_fid3nothing about a value the model never writes. Two stored values plus the absent sentinel is what makes an overwrite observable; a third would add no distinction this invariant reads
bound_variables7every part of the real Fs outside these seven — the dynamic-fid vector, the write generation counter, the sealed-payload layer, and flash geometry of any kind
bound_invariants6whatever is true of the store and is not one of these six. A GREEN run says nothing about a clause nobody wrote down
bound_bug_switches9any defect outside the nine formal/gen-configs.sh emits a switch for. The mutation score below is out of those nine and not out of the defects the store can have
bound_next_disjuncts7any action the model does not have. There is no compaction, no factory_wipe, and no concurrent second caller in this Next

Row note (shipped_relation). the model is Fs over a Storage, with the medium’s failure modes as switches and the geometry left out. What is shipped is one instance of that shape at 16-bit FIDs; what is checked is two FIDs, and AS-RESET-2 is the row that argues the step between them

Method 2 — show that the GREEN above is not vacuous — that a configuration which BREAKS NoFalseMetaAbsent is refused, and refused BY NAME

mutation over StoreMut_BugMetaDeleteDropsOnFault.cfg StoreSolo_BugMetaDeleteDropsOnFault.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_bug_switches_for_this_invariant1the other switches of the nine. A switch that breaks a sibling invariant is evidence about that sibling, and this row does not borrow it
bound_tiers2nothing about a tier this property has no configuration in. Where the count is 1 there is no Solo_ half and the row says so instead of implying one
bound_recorded_runs2every run not in the [[artifact]] rows below. A verdict with no log beside it is a sentence, and this bundle carries none
bound_killed2whether the kill was for the modelled defect rather than its inverse. That is the direction column of every [[mutation]] row, read one at a time, and two of twenty-four co-refutation patches in this tree failed exactly there
bound_store_configurations22any configuration formal/gen-configs.sh does not emit. The roster is generated, so a defect nobody wrote a switch for has no row anywhere in it
bound_distinct_states_green364everything the mutants explore beyond the clean run’s space. A RED row stops at its first violation, so its own state count is a property of when TLC found the bug and not of the space

Row note (shipped_relation). a switch is a defect the shipped tree does not have: gen-configs.sh writes every Bug* FALSE in Store.cfg, so the mutants say what the model would catch and not what the code does

Method 3 — read the production sites the model claims to abstract, and say whether the ordering the invariant rests on is the ordering the code has

review over crates/rsk-fs/src/fs.rs::meta_delete crates/rsk-fs/src/fs.rs::mark_absent crates/rsk-fs/src/store_assurance.rs::meta_delete_false_absent crates/rsk-fs/src/store_meta_kani.rs::a_faulted_meta_read_is_never_cached_as_an_absent_blob crates/rsk-fs/src/powercut.rs::meta_delete_landed. cfg: none. features: none.

BoundValueWhat stops being proved
bound_refinement_markers2every site that refines this invariant and says so nowhere. The markers are doc comments, so a site that drifts out of one is invisible to this count
bound_fs_removal_sites4removals outside Fs. assurance/deleters.toml’s own header says its two scope rules cannot see these four, which is why they are a separate table
bound_fs_source_lines895everything read as prose rather than as code. A line count is the size of what was read, not evidence that it was read correctly
bound_reviewers1independence. One reader wrote this bundle and read these sites, so nothing here is a second opinion and the row says so rather than leaving the count out
bound_files_read4the rest of the crate. rsk-fs is fifteen source files and this row opened the ones the subjects name
bound_crate_kani_proofs13whether any of them is about THIS invariant. The count is the crate’s; the attribution is the registry’s NAME match, and this bundle records where the two disagree

Row note (shipped_relation). this is the only row of the four that touches shipped Rust, and it is a READING rather than a proof. TCB-1 is what carries it to the image

Method 4 — carry NoFalseMetaAbsent out of the model and onto something the host runs: the harness at the fault site, beside the step predicate it does not replace

bounded proof over crates/rsk-fs/src/store_meta_kani.rs::a_faulted_meta_read_is_never_cached_as_an_absent_blob crates/rsk-fs/src/store_assurance.rs::meta_delete_false_absent. cfg: kani. features: none.

BoundValueWhat stops being proved
bound_view_fids3any shape needing a fourth file. store_assurance::VIEW_FIDS is a three-element array, so the host sweep’s projection is as narrow as the model’s pair plus one
bound_step_predicates3the fourth invariant, which has none. crates/rsk-fs/src/store_assurance.rs says why: NoSilentOrphan forbids an answer rather than a state
bound_kani_proofs_in_crate13every clause no harness in the crate states. Thirteen proofs is the crate’s whole bounded surface, and only five of them ran for this bundle
bound_harnesses_run5the eight this bundle did not run — the four in powercut_kani.rs, the one in fs_kani.rs, and three more of the refinement file. Their verdicts are not here
bound_symbolic_fids24the shipped 65536. Under cfg(kani) FID_PRESENT_BYTES is 3, so the map is 24 bits and EF_META is re-aliased to 0x0017 to sit inside it — a shrink crates/rsk-fs/src/store_meta_kani.rs itself lists three consequences of
bound_cover_properties2whether the harness reached anything a cover does not name. Two satisfied covers say the assumed domain is non-empty, not that it is the right one

Row note (shipped_relation). the projection is verification-only and excluded from production builds, so this row says the shipped primitives satisfy the model’s clauses — not that the shipped image was checked

SEC-STORE-005 — RSKeyStore!CacheHonest

Method 1 — show that CacheHonest holds of every reachable state of the flash layer, over the whole action set and not one path through it

model-check over Store.cfg formal/RSKeyStore.tla. cfg: none. features: none.

BoundValueWhat stops being proved
bound_fids2any shape that needs a third file — a three-way aliasing of the present map, or a metadata blob holding more records than the pair can put in it. AS-RESET-2 is the row that says why the pair is argued to be enough, and it is argued rather than shown
bound_values_per_fid3nothing about a value the model never writes. Two stored values plus the absent sentinel is what makes an overwrite observable; a third would add no distinction this invariant reads
bound_variables7every part of the real Fs outside these seven — the dynamic-fid vector, the write generation counter, the sealed-payload layer, and flash geometry of any kind
bound_invariants6whatever is true of the store and is not one of these six. A GREEN run says nothing about a clause nobody wrote down
bound_bug_switches9any defect outside the nine formal/gen-configs.sh emits a switch for. The mutation score below is out of those nine and not out of the defects the store can have
bound_next_disjuncts7any action the model does not have. There is no compaction, no factory_wipe, and no concurrent second caller in this Next

Row note (shipped_relation). the model is Fs over a Storage, with the medium’s failure modes as switches and the geometry left out. What is shipped is one instance of that shape at 16-bit FIDs; what is checked is two FIDs, and AS-RESET-2 is the row that argues the step between them

Method 2 — show that the GREEN above is not vacuous — that a configuration which BREAKS CacheHonest is refused, and refused BY NAME

mutation over StoreSolo_CacheHonest.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_bug_switches_for_this_invariant1the other switches of the nine. A switch that breaks a sibling invariant is evidence about that sibling, and this row does not borrow it
bound_tiers1nothing about a tier this property has no configuration in. Where the count is 1 there is no Solo_ half and the row says so instead of implying one
bound_recorded_runs1every run not in the [[artifact]] rows below. A verdict with no log beside it is a sentence, and this bundle carries none
bound_killed1whether the kill was for the modelled defect rather than its inverse. That is the direction column of every [[mutation]] row, read one at a time, and two of twenty-four co-refutation patches in this tree failed exactly there
bound_store_configurations22any configuration formal/gen-configs.sh does not emit. The roster is generated, so a defect nobody wrote a switch for has no row anywhere in it
bound_distinct_states_green364everything the mutants explore beyond the clean run’s space. A RED row stops at its first violation, so its own state count is a property of when TLC found the bug and not of the space

Row note (shipped_relation). a switch is a defect the shipped tree does not have: gen-configs.sh writes every Bug* FALSE in Store.cfg, so the mutants say what the model would catch and not what the code does

Method 3 — read the production sites the model claims to abstract, and say whether the ordering the invariant rests on is the ordering the code has

review over crates/rsk-fs/src/fs.rs::meta_delete crates/rsk-fs/src/fs.rs::mark_absent crates/rsk-fs/src/fs.rs::known_absent crates/rsk-fs/src/store_meta_kani.rs::a_faulted_meta_read_is_never_cached_as_an_absent_blob. cfg: none. features: none.

BoundValueWhat stops being proved
bound_refinement_markers1every site that refines this invariant and says so nowhere. The markers are doc comments, so a site that drifts out of one is invisible to this count
bound_fs_removal_sites4removals outside Fs. assurance/deleters.toml’s own header says its two scope rules cannot see these four, which is why they are a separate table
bound_fs_source_lines895everything read as prose rather than as code. A line count is the size of what was read, not evidence that it was read correctly
bound_reviewers1independence. One reader wrote this bundle and read these sites, so nothing here is a second opinion and the row says so rather than leaving the count out
bound_files_read2the rest of the crate. rsk-fs is fifteen source files and this row opened the ones the subjects name
bound_crate_kani_proofs13whether any of them is about THIS invariant. The count is the crate’s; the attribution is the registry’s NAME match, and this bundle records where the two disagree

Row note (shipped_relation). this is the only row of the four that touches shipped Rust, and it is a READING rather than a proof. TCB-1 is what carries it to the image

Method 4 — carry CacheHonest out of the model and onto something the host runs: the two harnesses at the fault site this invariant is the premise of

bounded proof over crates/rsk-fs/src/store_meta_kani.rs::a_faulted_meta_read_is_refused_rather_than_rebuilt_from_empty crates/rsk-fs/src/store_meta_kani.rs::a_faulted_meta_read_is_never_cached_as_an_absent_blob. cfg: kani. features: none.

BoundValueWhat stops being proved
bound_view_fids3any shape needing a fourth file. store_assurance::VIEW_FIDS is a three-element array, so the host sweep’s projection is as narrow as the model’s pair plus one
bound_step_predicates3the fourth invariant, which has none. crates/rsk-fs/src/store_assurance.rs says why: NoSilentOrphan forbids an answer rather than a state
bound_kani_proofs_in_crate13every clause no harness in the crate states. Thirteen proofs is the crate’s whole bounded surface, and only five of them ran for this bundle
bound_harnesses_run5the eight this bundle did not run — the four in powercut_kani.rs, the one in fs_kani.rs, and three more of the refinement file. Their verdicts are not here
bound_symbolic_fids24the shipped 65536. Under cfg(kani) FID_PRESENT_BYTES is 3, so the map is 24 bits and EF_META is re-aliased to 0x0017 to sit inside it — a shrink crates/rsk-fs/src/store_meta_kani.rs itself lists three consequences of
bound_cover_properties2whether the harness reached anything a cover does not name. Two satisfied covers say the assumed domain is non-empty, not that it is the right one

Row note (shipped_relation). the projection is verification-only and excluded from production builds, so this row says the shipped primitives satisfy the model’s clauses — not that the shipped image was checked

SEC-STORE-006 — RSKeyStore!NoSilentOrphan

Method 1 — show that NoSilentOrphan holds of every reachable state of the flash layer, over the whole action set and not one path through it

model-check over Store.cfg formal/RSKeyStore.tla. cfg: none. features: none.

BoundValueWhat stops being proved
bound_fids2any shape that needs a third file — a three-way aliasing of the present map, or a metadata blob holding more records than the pair can put in it. AS-RESET-2 is the row that says why the pair is argued to be enough, and it is argued rather than shown
bound_values_per_fid3nothing about a value the model never writes. Two stored values plus the absent sentinel is what makes an overwrite observable; a third would add no distinction this invariant reads
bound_variables7every part of the real Fs outside these seven — the dynamic-fid vector, the write generation counter, the sealed-payload layer, and flash geometry of any kind
bound_invariants6whatever is true of the store and is not one of these six. A GREEN run says nothing about a clause nobody wrote down
bound_bug_switches9any defect outside the nine formal/gen-configs.sh emits a switch for. The mutation score below is out of those nine and not out of the defects the store can have
bound_next_disjuncts7any action the model does not have. There is no compaction, no factory_wipe, and no concurrent second caller in this Next

Row note (shipped_relation). the model is Fs over a Storage, with the medium’s failure modes as switches and the geometry left out. What is shipped is one instance of that shape at 16-bit FIDs; what is checked is two FIDs, and AS-RESET-2 is the row that argues the step between them

Method 2 — show that the GREEN above is not vacuous — that a configuration which BREAKS NoSilentOrphan is refused, and refused BY NAME

mutation over StoreMut_BugDeleteHidesFaultedDrop.cfg StoreSolo_BugDeleteHidesFaultedDrop.cfg. cfg: none. features: none.

BoundValueWhat stops being proved
bound_bug_switches_for_this_invariant1the other switches of the nine. A switch that breaks a sibling invariant is evidence about that sibling, and this row does not borrow it
bound_tiers2nothing about a tier this property has no configuration in. Where the count is 1 there is no Solo_ half and the row says so instead of implying one
bound_recorded_runs2every run not in the [[artifact]] rows below. A verdict with no log beside it is a sentence, and this bundle carries none
bound_killed2whether the kill was for the modelled defect rather than its inverse. That is the direction column of every [[mutation]] row, read one at a time, and two of twenty-four co-refutation patches in this tree failed exactly there
bound_store_configurations22any configuration formal/gen-configs.sh does not emit. The roster is generated, so a defect nobody wrote a switch for has no row anywhere in it
bound_distinct_states_green364everything the mutants explore beyond the clean run’s space. A RED row stops at its first violation, so its own state count is a property of when TLC found the bug and not of the space

Row note (shipped_relation). a switch is a defect the shipped tree does not have: gen-configs.sh writes every Bug* FALSE in Store.cfg, so the mutants say what the model would catch and not what the code does

Method 3 — read the production sites the model claims to abstract, and say whether the ordering the invariant rests on is the ordering the code has

review over crates/rsk-fs/src/fs.rs::delete crates/rsk-fs/src/fs.rs::force_delete crates/rsk-fs/src/fs.rs::force_delete_halves crates/rsk-fs/src/powercut.rs::delete_landed. cfg: none. features: none.

BoundValueWhat stops being proved
bound_refinement_markers4every site that refines this invariant and says so nowhere. The markers are doc comments, so a site that drifts out of one is invisible to this count
bound_fs_removal_sites4removals outside Fs. assurance/deleters.toml’s own header says its two scope rules cannot see these four, which is why they are a separate table
bound_fs_source_lines895everything read as prose rather than as code. A line count is the size of what was read, not evidence that it was read correctly
bound_reviewers1independence. One reader wrote this bundle and read these sites, so nothing here is a second opinion and the row says so rather than leaving the count out
bound_files_read2the rest of the crate. rsk-fs is fifteen source files and this row opened the ones the subjects name
bound_crate_kani_proofs13whether any of them is about THIS invariant. The count is the crate’s; the attribution is the registry’s NAME match, and this bundle records where the two disagree

Row note (shipped_relation). this is the only row of the four that touches shipped Rust, and it is a READING rather than a proof. TCB-1 is what carries it to the image

Method 4 — carry NoSilentOrphan out of the model and onto something the host runs: the ghost viol the faulted Delete arm writes, against the production pair that keeps the two failures apart

trace over formal/RSKeyStore.tla crates/rsk-fs/src/fs.rs::force_delete_halves. cfg: none. features: none.

BoundValueWhat stops being proved
bound_view_fids3any shape needing a fourth file. store_assurance::VIEW_FIDS is a three-element array, so the host sweep’s projection is as narrow as the model’s pair plus one
bound_step_predicates3the fourth invariant, which has none. crates/rsk-fs/src/store_assurance.rs says why: NoSilentOrphan forbids an answer rather than a state
bound_kani_proofs_in_crate13every clause no harness in the crate states. Thirteen proofs is the crate’s whole bounded surface, and only five of them ran for this bundle
bound_harnesses_run5the eight this bundle did not run — the four in powercut_kani.rs, the one in fs_kani.rs, and three more of the refinement file. Their verdicts are not here
bound_symbolic_fids24the shipped 65536. Under cfg(kani) FID_PRESENT_BYTES is 3, so the map is 24 bits and EF_META is re-aliased to 0x0017 to sit inside it — a shrink crates/rsk-fs/src/store_meta_kani.rs itself lists three consequences of
bound_cover_properties2whether the harness reached anything a cover does not name. Two satisfied covers say the assumed domain is non-empty, not that it is the right one

Row note (shipped_relation). the projection is verification-only and excluded from production builds, so this row says the shipped primitives satisfy the model’s clauses — not that the shipped image was checked

Platform assumptions

The firmware and its models depend on properties outside the Rust applets. The RP2350 must enforce the access policy. The boot ROM must honor the provisioning and signature policy. Flash and SRAM must behave as the storage and reset code expect. Compilers, solvers and peripheral models also affect what a test or proof can establish.

Each assumption has a PLAT-* identifier. The platform register records the expected behavior, what can establish it, and whether there is evidence. Read the scope of a passing board result before applying it to another stepping, boot policy or build. The board records keep the test criteria with the observations.

See TrustZone for the firmware boundary, Testing for model and hardware checks, and Limitations for assumptions that fall outside the project’s claims.

FIDO authorization slice — design

The scope, the maps, the bounds, the mutants and the exit for the first end-to-end assurance slice: SEC-FIDO-001, NoAuthorizationBypass. This page is the design and the measurement plan, written before any of the proof code it describes exists. It closes nothing, moves no property status, and adds no gate row.

RS-Key is not formally verified, and a design page is the easiest place to forget it: nothing below is evidence, and the closed slice it plans does not make the firmware proven either.

Its purpose is narrow and worth stating so nobody reads more into it: fix a scope that can be checked, so that the cost of actually closing the slice can be observed rather than estimated. The three completed pilots — token, cross-reset and store — are the rehearsals this plans against; Formal model is the overview. Every number below was measured on the tree at the commit this page landed in, with the command named beside it.

One warning belongs at the top rather than at the bottom. SEC-FIDO-001 leads the registry on all four of the evidence columns — 46 configurations, 11 model mutants, 11 co-refuted, and 4 Kani harnesses against SEC-STORE-002’s three, which is the tree’s next-best. On the axes this slice is about it is the strongest row there is, so the cost of closing it is a floor and not a price. The weak-end counterpart is designed alongside it, at the end of this page, for exactly that reason.

What the tree already discharges

The slice is mostly assembly. Nine mechanisms already exist; each discharges part of the obligation and none discharges the whole, and the value of this section is the second column.

ArtifactDischargesDoes not
formal/RSKeyTokenAbstract.tlatier A: 44 abstract token states, 11 Ops, 3 Outcomes, one four-argument AllowedEventRel, outcomes as labels so an unauthorized success stays distinguishable from a stutterstate NoAuthorizationBypass at all — A carries no invariant, and has no presence, channel, retry, soft-lock or reset-window vocabulary
formal/RSKeyTokenRefinement.tla, RSKeyTokenView.tlanative INSTANCE refinement B→A over TokenGamma, plus R1oStep’s outcome obligation and R1oOutcomeCoverage’s equality guard on 23 outcome-producing action namesany coverage guard on the viol ghost — the outcome set and the authorization-recording set are different sets
formal/RSKeyTokenExport.tla, scripts/export_token_relation.py, scripts/generate_token_edges.pythe A relation serialized to Rust and checked exhaustively on the host, so A’s semantics cannot drift from the generated tablegive A an oracle independent of A: the export is A, so it can only catch transcription errors
assurance/token_refinement.toml + scripts/token_refinement_gate.pythe ownership ledger for the token half: 11 volatile writers, 14 persistent writers, 7 outcome producers, each with a derived-and-checked dispositionown anything outside the token: the retry budget, the soft lock, the reset window and the walk owner have no ledger anywhere
formal/RSKeySecurityState.tlatier B: 53 actions, the named invariants counted from Shipped.cfg in the testing evidence report — six of them are the ones formal/README.md maps to Rust, and this cell read six for the whole set — Guard/Policy separation so an invariant can be falsified rather than restatedclose the ghost’s completeness — see the B map below, where the count is off by ten
formal/TraceSecurity*.tla, scripts/security_trace.py, formal/traces/security-phase4.jsonlruntime correspondence: a 40-line recorded emulator session replayed as 74 steps, 41 state boundaries, 15 outcome boundaries, 7 gate boundaries, with R4c predicting the gate’s answer, and eight TraceSecurityBad*.cfg — seven registered RED with the invariant each must break named, one a deliberate GREEN control — proving the replay can refusereach the property. The row itself prints distinct_actions=22 of the model’s 53, and only 10 of the 21 actions that record this invariant are among them — the whole credentialManagement family is unreached, which is the family the one existing Kani harness is about. Nor does it witness a board: the apparatus is tools/emu and its fidelity is an assumption nothing here discharges
formal/comutants.toml + scripts/comutate.py69 patched code twins and 4 recorded-unreachable, floored at 0 pending; 11 of them belong to NoAuthorizationBypass and all 11 are expect = "killed"falsify a proof. Measured: 0 of the 69 slice invocations run cargo kani — every one is a cargo test -p …. The property’s only Kani harness is reddened by no recorded mutant
assurance/configurations.toml + scripts/matrix_gate.py + assurance matrixthe configuration axis: 40 P0-family properties × 31 build configurations = 1240 cells, of which 37 covered, 139 equivalent, 0 conditional, 106 out-of-scope and 958 gapdecide this row’s 24 gaps. SEC-FIDO-001 is covered on firmware, equivalent on firmware-pico and waveshare-one, out-of-scope on the four no-touch images, and gap on the other 24
assurance/threat_clauses.toml + scripts/threat_gate.pythe root: SEC-FIDO-001’s source names a clause of the threat model, TM-HOST-GATES, and 39 of 40 P0-family properties are traced across 50 clauses (37 defence, 13 context), 1 untracedsay anything about sufficiency — a clause is an anchor, not an argument that the property covers it

Measured with python3 scripts/assurance_gate.py, python3 scripts/matrix_gate.py, python3 scripts/threat_gate.py, python3 scripts/token_refinement_gate.py, python3 scripts/comutate.py --lint, python3 scripts/verdict_gate.py and python3 scripts/kani_gate.py.

Property and configuration

The slice covers SEC-FIDO-001. The calibration cases use SEC-FIDO-007 and SEC-FIDO-008. The assurance vector links to the generated evidence for each property.

SEC-FIDO-001’s configuration column is firmware — the default image, no cargo feature and no build knob. Everything below is about that column, and about firmware-pico and waveshare-one only through the derived same-cargo-features equivalence the matrix already carries.

What is in this slice, and what is not

One registry row, four clauses. In: the token and its permission; the retry budget and the soft lock; the reset window; the walk’s owning channel. Those are the four things the invariant’s ghost and its two structural conjuncts are about, and each gets an A/B/C treatment below.

Out, and each for a stated reason — a slice whose edges are vague is a slice whose cost cannot be measured:

  • SEC-FIDO-002’s cross-transport touch obligation is a separate registry row with seven harnesses of its own in crates/rsk-device/src/presence_kani.rs, two of them carrying its name. It appears here only where a mutant is shared;
  • getNextAssertion ownership. The stateful assertion walk appears in no formal/*.tla module, and the walk-owner harness’s own “what this does not prove” list says the gna walk is not modelled. It is a stage-4 obligation this slice does not take;
  • EF_DEVICE_PIN and EF_MINPINLEN. The model carries one PIN record and says so in as many words above LocalPinEnabled — “the device PIN is no CTAP credential, and EF_DEVICE_PIN is not modelled” — while EF_MINPINLEN appears in no module at all. Both are stage-4, neither is here;
  • every configuration column but the three named above. The slice’s evidence is produced on firmware and the matrix keeps it there.

The A map

The statement. For every abstract event (pre, op, outcome, post) the relation admits, an Authorized outcome implies the gate that operation’s requirement names held in pre:

NoAuthorizationBypassA ==
    \A e \in AllowedRelation :
        e[3] = "Authorized" => RequiredGate(e[2], e[1])

The domain. AStates has 44 elements — five permission shapes × the live/rpBound/pinSet/persistentGrant combinations the shape constraint admits, which is 12 for the empty shape and 8 for each of the other four. With 12 Ops and 3 Outcomes the candidate tuple space is 44 × 12 × 3 × 44 = 69 696, which is the space the generated Rust table is already checked over exhaustively.

Where the oracle comes from, and why that is the whole design. RequiredGate must be transcribed from CTAP 2.3 §6.5 and §6.8 — from the requirement — and not read off AllowedEventRel. Defined the second way it is algebraically the relation, the check cannot fail, and §4.3’s eleventh condition refuses the claim regardless of the other ten. This tree has already paid for that mistake once, in the per-FID projection whose oracle was the code and which reported 0 divergences over 5⁴ inputs. So the design carries a disagreement obligation: the set of tuples on which RequiredGate and AllowedEventRel differ is computed, enumerated and written into the bundle. If it is empty, the A map is degenerate and the slice does not proceed.

What A deliberately does not say. This is the load-bearing limitation of the whole slice and it must not be discovered later:

  • A has no presence, no channel, no retry counter, no soft lock and no reset window. NoAuthorizationBypass at tier B is a four-clause property — the token and its permission, the retry budget and soft lock, the reset window, and the walk’s owning channel — and only the first has an image in A. The other three are complementary source obligations, not A-level claims;
  • rpBound is a boolean, so a token bound to the wrong relying party is invisible at A. The rpId-identity half belongs to B;
  • A observes record presence, never record contents, so nothing about PIN entropy, verifier derivation or MAC verification is in scope;
  • persistentGrant is that record, not a platform holding it. Since 0x09CB the device writes EF_PAUTHTOKEN itself at a boot, a finished reset or a backup load (ProvisionGrant), so UseCm’s grant arm is met by a record nobody may have been handed. Possession is the token’s secrecy and has no image in A. B keeps the issued grant apart as gate.ppuat and PpuatGuard reads it, but no mutant in the roster takes that half of the guard out;
  • A has no time, so PUAT_MAX_USAGE_PERIOD_MS (600000) and RESET_WINDOW_MS (10000) are outside it by construction.

The B map

B is formal/RSKeySecurityState.tla. The invariant is three conjuncts:

  1. the ghost — "NoAuthorizationBypass" \notin viol;
  2. the §6.5.5.7 triad, read out of state — (upSpent /\ tok.live) => tok.perms = {};
  3. the soft lock reflecting its policy — (lock.policyMism >= MismatchLimit) => lock.soft, with PIN_MISMATCH_LIMIT (3) and MAX_PIN_RETRIES (8) as the shipped constants the configuration pins.

Mechanised. TLC checks the invariant over the whole reachable space of each of the 46 configurations that name it (grep -lw NoAuthorizationBypass formal/*.cfg | wc -l — -w, because the bare -l also matches the tier-A NoAuthorizationBypassA in two more and printed 48). formal/Shipped.cfg pins RPs = {r1, r2}, Channels = {c1, c2}, MaxRetries = 8, MismatchLimit = 3, MaxClock = 1, ResetWindow = 0; the roster as a whole is not one scope, and python3 scripts/scope_gate.py prints the spread it runs at. The B→A step is mechanised for the token clause only, natively: R1sTokenStateRefinement == Abs!Spec in TokenRefinement.cfg and R1oTokenOutcomes plus R1oOutcomeCoverage in TokenRefinementOutcome.cfg, both floored GREEN, with TokenRefinementBadMap.cfg and TokenRefinementDeadToken.cfg registered RED as the negative witnesses.

Asserted, not mechanised — and this is the gap the slice owns. The ghost clause is only as strong as the completeness of the actions that populate it. The invariant’s own comment says “Those eleven are the whole list; no other action is gated by an authorization.” Measured over the module, 21 of the model’s 53 actions can add the name:

  • through PinAttempt — GetPinToken, WrongPin, MintPpuat, ChangePinStart;
  • directly — LocalCeremonyStart, LocalPinWrong, LocalPinOk, SetPinStart, RegisterTouched, RegisterNdTouched, AssertFinish, CmBeginViaPpuat, CmNext, ResetStart, ResetConfirmed;
  • through TokenBypass — RegisterStart, RegisterNdStart, AssertStart, ConfigOp, CmBeginViaToken, DeleteCredStart.

The comment names twelve of them once PinAttempt is expanded into its four callers, and calls the list “eleven” — a count that matches neither its nine written items nor the twelve actions they stand for. Nine actions it names nowhere record the invariant: LocalCeremonyStart, LocalPinWrong, LocalPinOk, SetPinStart, RegisterTouched, RegisterNdStart, RegisterNdTouched, AssertFinish and ResetConfirmed: three for the on-panel ceremony, two for the token-less registration arm, three continuations of flows whose Start the comment does list (RegisterTouched, AssertFinish, ResetConfirmed) — and SetPinStart, which is a Start of a flow the comment omits entirely. Nothing in the tree compares the sentence to the set. R1oOutcomeCoverage is the only completeness equality inside the models and it guards a different set: the 23 names of TokenOutcomeActions. So the design’s B-level obligation is a second such equality, over the authorization-recording set, derived from the module rather than listed.

The C map

Three production surfaces, and the registry sees only the first. Naming the difference is the point.

Level 1 — what the registry derives (rust = 2). assurance_gate.py greps production Rust for the literal invariant name, so the column is exactly the files carrying a Refines RSKeySecurityState!NoAuthorizationBypass — SEC-FIDO-001 tag: crates/rsk-fido/src/state.rs (twice: CredMgmtState::may_walk_rps, and PinLock) and crates/rsk-fido/src/clientpin.rs (spend_and_verify_pin_hash).

Level 2 — what co-refutation already drives. The 11 killed twins patch 7 files across 3 crates: rsk-fido/src/state.rs (BugCmWalkIgnoresChannel, BugConsumeKeepsMcGa, BugNoConsumeAfterUp), rsk-fido/src/clientpin.rs (BugSetPinOverExisting), rsk-fido/src/makecredential.rs (BugUvNotRqdIgnoresRk, BugTokenlessIgnoresAlwaysUv), rsk-fido/src/reset.rs (BugWarmResetReopensWindow), rsk-device/src/presence.rs (BugHostPreemptsLocalWait, BugNoTouchRequired), rsk-device/src/ctap.rs (BugSoftLockLostOnWarmReset) and rsk-display/src/gates.rs (BugLocalPinIgnoresBudget). Five of those seven files carry no tag, which is why the derived column says 2.

Level 3 — what the property is about. The 21 actions’ owners. The token half is ledgered already (assurance/token_refinement.toml); the retry/soft-lock, reset-window and walk-owner clauses are not ledgered anywhere.

The callers

A projection over a function nobody calls the way the model assumes is where the last pilot died, so the callers are written down first and the projection second.

Concrete gateProduction callersReached by the harness?
CredMgmtState::may_walk_rpsone — enumerate_rps, crates/rsk-fido/src/credmgmt.rs, the else if !… armno — reproduced
CredMgmtState::may_walk_credsone — enumerate_creds, same file, same shapeno — reproduced
spend_and_verify_pin_hashthree — changePIN’s old-PIN check, the getPinToken door, and the on-pad PIN door, all in crates/rsk-fido/src/clientpin.rsno harness exists
—counted the way the registry counts: production files only, dropping any filename containing kani or tests, which is assurance_gate.py’s own rule. Stating it is the difference between a table a reader can reproduce and one they must trust
FidoState::pin_lock / restore_pin_lockcrates/rsk-device/src/ctap.rs on both sides of a warm reset, with the board half in firmware/src/pin_lock.rsno harness exists
enforce_pintwo distinct private functions, one in makecredential.rs and one in getassertion.rs, one call site each — not one gate with two callersno
verify_cm_tokenthree, all in credmgmt.rsno
authorized_by_ppuatone — authorize_cm, credmgmt.rsno
authenticator_configone — the CBOR dispatch in crates/rsk-fido/src/lib.rsno
vendor::pin_gatesix sites in crates/rsk-fido/src/vendor.rsno
consume_after_user_presenceone — Ctx::user_presence_test in crates/rsk-fido/src/up.rs, which the four makeCredential / getAssertion user-presence tests (two in makecredential.rs, two in getassertion.rs) go through; the two success paths build their UP bit from the UpFlag it returnsno

What the one existing harness actually proves. no_authorization_bypass_walk_owner in crates/rsk-fido/src/state_kani.rs runs a symbolic five-operation interleaving over an eight-symbol opcode alphabet with two channels, and asserts an equality — may_walk_rps(probe) == (rp_owner == Some(probe)) — before and after every operation, on both channels. Its oracle is non-degenerate by construction and the file says how: rp_owner/cred_owner are tracked from the opcode and never read back out of st, so a guard that refuses everything fails it too. It carries three kani::cover!s, counted into the tier ratchets scripts/kani_gate.py holds against the tree.

What it does not do is call either real caller. begin_rps and begin_creds are local re-implementations of the cursor writes in enumerate_rps / enumerate_creds, composed by hand with the cm.reset() that the credentialManagement subcommand demux performs one frame out.

What is missing is the decision, not the state. The state a refused authorize_cm leaves behind is reachable in the harness — W_OTHER_CM_SUBCOMMAND performs the same retire_sequences_except plus cm.reset() — but the Begin’s own gate, the pinUvAuthParam MAC and the cm permission bit and the rpId binding, is never evaluated. The harness proves what follows an authorization it assumes; the property is about the authorization.

Three further divergences the phrase “reproduces the cursor writes” covers over, and a design that does not list them is making them silently:

  1. begin_rps writes rp_total in one shot. The real enumerate_rps sets rp_total = 0 first and returns Err(NoCredentials) on an empty scan before advancing rp_counter or stamping last_leg_ms — an intermediate state the harness has no shape for;
  2. the real Begin reaches load_keydev() and can fail to the host after all three cursor fields are written, so an errored Begin can leave a live walk cursor behind. The harness cannot express an errored Begin at all;
  3. begin_creds never writes cm.rp_id_hash, which the real enumerate_creds(begin = true) does and which the demux reads back to serve a Next. That is a cursor field, not an abstraction the page defers to B.

None of the three breaks B1 or B2 in any state checked by hand — may_walk_rps is false throughout — but “checked by hand” is the reason they are listed rather than the reason they can be omitted.

So the C map’s obligation is stated as a composition, not as a rewrite: prove the guard at its call site, with the authorization step in the harness rather than assumed away. credmgmt_kani.rs’s existing no_token_after_invalidation_at_call_site is the shape to copy, and the only harness in the two crates named for a call site rather than for a function.

The assumptions

Each is named, classed, and given a discharger. The last column is the one that matters for planning: scripts/assumption_gate.py structurally accepts only a boolean TLA constant that some configuration assigns both ways and some reachable definition reads. Anything else has nowhere to be written down in that registry — which was the finding, and the split below is what chose the answer to it. The class has a second registry now, platform assumptions, whose gate derives these very ids from this page.

idAssumptionClassWho could discharge itExpressible in assumption_gate today
AS-AUTH-1tools/emu implements the same authorization gates as the firmware, so a recorded session is evidence about the firmwaretool fidelitya board recording of the same session, compared boundary by boundaryno — not a model constant
AS-AUTH-2The build does not ship always-uv, so gate.alwaysUv is a free state variable rather than pinned truebuild configurationthe matrix’s firmware-always-uv column, whose settling question already names SEC-FIDO-001yes, with work — its content is a boolean over gate.alwaysUv, which reachable definitions already read (UvRequired, McTokenlessPolicy, the mc/ga guards) and ConfigOp already flips. A constant pinning it in Init and disabling that flip, generated both ways by gen-configs.sh, is the same shape PowerOnClearsScratch2 needed. The obstacle is work, not the gate
AS-AUTH-3A CTAPHID channel id is a routing label the sender writes, so channel ownership is a scoping rule and never an authentication onethreat modela clause of the threat model; state.rs states it in prose todayno
AS-AUTH-4PowerOnClearsScratch2 — a real power-on clears the watchdog word the soft lock rides inplatformthe board measurement assurance/assumptions.toml already describesregistered, but not against this slice. The constant is declared and read only in RSKeyBootHardening, and the overlap between the 13 configurations that assign it and the 46 that check NoAuthorizationBypass is zero (comm -12 over the two grep -lw lists). The soft lock is this slice’s clause 3 and the assumption underneath it is the boot module’s; borrowing the row without saying so would be the same slice-boundary error this page is written against
AS-AUTH-5PermSets, five of the sixteen subsets, is the set a host can actually obtainmodel fidelityreading the two production sites that mint permissions; it is argued in the module, not measuredno
AS-AUTH-6One credential per relying partymodel abstractionthe store slice; MAX_RESIDENT_CREDENTIALS (256) is the shipped cardinalityno
AS-AUTH-7Kani/CBMC is sound for the harness’s arithmetic and the pinned solver is the one that rantool TCBthe pinned toolchain and a recorded tool hashno
AS-AUTH-8ea-conformance-rpid’s enterprise-attestation allowlist is not an authorization gatebuild configurationthe matrix’s own settling question for that column, which asks exactly thisno

Zero of the eight were registered against this slice, and measuring that is what this page contributed. AS-AUTH-4 was registered, but in another module and reachable from none of this slice’s configurations; AS-AUTH-2, and arguably -3 and -8, could be encoded today at the cost of writing the constant and its two arms; AS-AUTH-5 (a set, not a boolean), -6 (a cardinality), -1 and -7 (facts about a tool, not about the model) have no expressible form at all. That last group is what assurance/platform.toml was stood up for, and all eight have an entry there now — scripts/platform_gate.py derives these ids from this page and from this slice’s own bundle, and reddens on one no entry claims. Registered is not discharged: the platform assumptions page prints that ratio in its first sentence, and AS-AUTH-4’s route still ends at a board.

The bounds

Every shrink, and what each stops proving, is now the bounds page: generated from assurance/bundle/*.toml by scripts/bounds_gate.py and byte-diffed on every gate run. Fourteen rows stood here instead, and they were this stage’s own exit criterion failing on its own page — no script read them, so a bound moved here while the bundle stood still was green on all eight gates, as was the reverse, as was a row named after a constant that does not exist.

formal/scopes.txt still records the measured per-constant minima and which invariant each was measured against. What the generated page adds is the attribution — which property, which [[method]] obligation, which artifact — and the consequence, which is the column worth keeping and the one that has to travel with the number rather than beside it. So it is carried per bound in the bundle, stops_<name> next to bound_<name>, the way shipped_relation already travels with a method row.

Three rows that stood here name no bundle key at all: the two cfg(not(kani)) compile-time assertions on the path, the safety-only symmetry argument, and the one-credential-per-relying-party cardinality. Their absence from the generated page is what “derived from the bundle” costs — a consequence with no measured bound behind it was a sentence this page asserted on its own authority.

The mutants

What must redden which level, and with which reason. A red run is not evidence until the direction is read — AGENTS.md records two of twenty-four co-refutation patches scoring a kill for the inverse defect, and the tell was that every failure said “should have succeeded” and none said “should have been refused”.

LevelMutantMust reddenExpected reason
Aan edge added to AllowedRelation that is Authorized with ~pinSet and no live tokenthe new A-level configurationNoAuthorizationBypassA violated on that edge, naming the op
ARequiredGate weakened to TRUE for one opE4a’s disagreement configuration, not the invariantit stops being RED for that op’s tuples. A disagreement configuration that goes GREEN is a refusal, not a pass
Bthe 11 existing switches11 Solo_*.cfg and the Mut_* family — already registered RED in formal/floors.txtthe invariant named by each Solo_*
Bdeleting one action’s viol writethe new ghost-completeness rowthe row names the action whose write is gone
B→AMutateTokenGamma, BugDeadTokenAuthorizedTokenRefinementBadMap.cfg, TokenRefinementDeadToken.cfg — already REDthe refinement or the outcome clause
CBugCmWalkIgnoresChannel re-driven against the harness rather than the unit suitecargo kani -p rsk-fido --harness no_authorization_bypass_walk_ownerassertion NoAuthorizationBypass/B1 or /B2
Ca new authorize_cm-weakening patch at the call sitethe new at-call-site harnessthe authorization assertion, not the cursor assertion
traceMutateUvNotRqd, MutateAlwaysUvArm, MutateResetWindow, MutatePinSetfour TraceSecurityBad*.cfg — already RED, each with its reason recordedR4cGateAnswers, at one of the 7 gate boundaries

The sixth row is the finding this table exists for. No recorded mutant reddens any Kani harness in this tree: all 67 patched co-mutants run cargo test -p …. The property’s single proof is therefore falsified by nothing, which is the same shape as a guard whose wiring nothing exercises — one layer in.

Exit criteria

Each row names a command and the value that command must print. The failure column is not decoration: an exit nobody can make red is the defect three stages of this programme shipped, and the reviewer of this page found five of an earlier nine in that state — satisfiable by prose, by a wildcard, or by doing nothing. What survives is below, with the repairs named.

#Command and the value it must printWhat would make it fail
E1not the rust column. python3 scripts/assurance_gate.py prints rust=N by grepping whole file text, doc comments included, so pasting the Refines … — SEC-FIDO-001 line into five files moves it from 2 to 7 with no other work. The predicate is instead: python3 scripts/token_refinement_gate.py accepts the retry/soft-lock, reset-window and walk-owner clauses as ledgered sites, and rejects an unowned onethe ledger is extended by hand without extending what the gate derives, so a new gate site arrives as silence rather than as an unowned site. That is the failure assurance/properties.toml’s header records, one register over
E2the A-level configuration has an exact row in formal/floors.txt naming its invariant, not a Solo_*/Mut_* wildcard match, and python3 scripts/verdict_gate.py exits 0naming it Mut_… or Solo_…. verdict_gate.py reports 25 wildcard families covering 165 of 200 configurations, every one RED -; a new mutant swallowed by one of those satisfies a weaker E2 and lands in exactly the hole this page’s own last section reports. formal/run-tlc.sh compares the reason only where the row names an invariant
E3for each of the 21 recording actions, a script deletes every route by which that action adds the name and asserts the new completeness row goes red naming itdeleting only one route. RegisterStart, RegisterNdStart and AssertStart each record by two independent routes — viol \cup TokenBypass and a ButtonFreePolicy disjunct — so a per-action single deletion leaves the other standing, the row stays green, and E3 reports a pass over a half-deleted guard. Also fails if the completeness set is derived from the same expression it checks
E4aat tier A: a configuration whose invariant is RequiredGate(op, s) = GateFromRelation(op, s) goes RED, and its counterexample set is written into the bundlethe two agree everywhere. Note the direction — NoAuthorizationBypassA is only about Authorized tuples, so a green A tier is compatible with agreement on all of them; the non-degeneracy evidence must therefore be this separate red configuration, over all three outcomes, and not the invariant itself
E4bat tier C: for each new harness, the bundle records the input class on which the requirement and the code differ, demonstrated by a patch that makes the harness red — not by a disagreement in the shipped treethere is no such class, i.e. the oracle was transcribed from the code. A Kani oracle that disagrees with shipped code is a failed proof, so at this tier non-degeneracy can only be shown by mutation, never by a divergence count. This is the D5 refutation, restated so it is checkable at the tier it actually applies to
E5cargo kani -p rsk-fido --harness no_authorization_bypass_walk_owner goes red under the BugCmWalkIgnoresChannel patch, and names NoAuthorizationBypass/B1 or /B2it reddens on a different assertion. The patch rewrites may_walk_rps’s body to drop the channel conjunct, so B1’s equality must fail on the non-owning probe specifically; a different assertion means a different defect
E6a schema check over the bundle: every one of the ten groups present, every leaf non-empty, and every numeric cost field a number rather than a rangeten headings with one line each. “Unabridged” is not a predicate until something counts leaves, so the contract below is written as leaves and the check is over them
E7after the slice, each matrix cell it closed carries a [[cell]] whose basis python3 scripts/matrix_gate.py re-derives; cells it did not close still read gapusing the existing state as the criterion. matrix_gate.py exits 0 today and the row already shows 24 gap, so “still shows 24 gap” was a no-op — it could only redden if someone edited the matrix, never as a consequence of failing to do the work
E8SEC-FIDO-001’s status is still BOUNDEDnothing — and this is not an exit, it is a guard-rail, kept in the table under its own name so a reader counting ten rows does not read ten exits. It reddens only if someone moves the scalar assurance_gate.py derives from a harness name
E9nix develop -c ./scripts/check.sh and nix develop -c ./scripts/check-assurance.sh each exit 0, taken without a pipe, and print ALL CHECKS PASSED and ALL ASSURANCE CHECKS PASSED — the slice’s bundle and bounds rows run in the secondreading the exit code through a pipe. check.sh prints no row count — only == <name> == per row and the final line — so the earlier form of this criterion compared a hand-counted number against a number the same work item wrote, and a bundle recording a lower count passed

Nine exits and one guard-rail — E8, which reddens only if someone moves the scalar. E4a and E4b decide whether the slice was worth doing; E2, E3 and E5 decide whether its guards are wired to anything. The rest is hygiene, and hygiene is where this programme has actually lost rows.

The raw-bundle contract

Stage 1A’s minimal contract, in current formats, unabridged — the ten groups the implementation must emit. This is not the evidence schema; it exists so the first closed slice hands the schema work a real migration fixture instead of data scattered across logs. A missing field blocks exit.

  1. Property, subject and owners — the registry id SEC-FIDO-001, the invariant name, the statement as the registry words it, the subject class per §4.1 (requirement / abstract model / Rust source / FFI / binary / hardware / integration), and every production owner by repo path.
  2. Exact commit, build and features — the commit hash the evidence was produced at, the tree state (git status --short), the matrix column, the cargo feature set, the board knobs, and the target triple for each artifact.
  3. Method and scope/bounds — the method per §4.1 (review / model-check / bounded proof / deductive proof / exhaustive sweep / mutation / trace / measurement / accepted risk / KAT/differential), and for each obligation its bound as structured data: sequence length, symbolic byte count, cardinalities, unwind, cfg and feature set, and the relation between each bound and the shipped constant. KAT/differential is published vectors, or a reference implementation, run against this one; it is discharged by the #[test] or the tests/*.py that RAN them, never by the table they sit in — and the gate holds the second half as literally as the first, a .py outside tests/ needing to name a def of its own that a test runner collects, which in Python is the name and not an attribute. It is not measurement, which in this contract means a result taken off a board and owes the silicon revision it was taken on.
  4. Tool, version, invocation and execution environment — for every artifact: tool name, exact version, the full command line, the environment (WORKERS, HEAP, TIMEOUT), the machine, and the tool hash where one exists. Measured in the dev shell at this commit: rustc 1.96.0, cargo 1.96.0, cargo-kani 0.67.0, tlaplus 1.7.4, openjdk 1.8.0_492, mdbook 0.5.2, lychee 0.24.1. Six of the seven come from the flake; Kani does not — it is not packaged in nixpkgs and CI installs it with cargo install --locked kani-verifier, so its version is pinned by a workflow variable and not by flake.lock. A bundle that records the number without that provenance records a version nothing in the tree holds.
  5. Principal result — for each artifact the verdict, and for a TLC run the distinct-state count, the depth, the workers and the invariant actually checked; for a Kani run the harness name, the assertion set and each kani::cover! verdict.
  6. Raw artifact or log — the path to the unedited output of every run, kept whole. A summarized log is not an artifact.
  7. Assumptions and TCB / trust dependencies — the eight AS-AUTH-* rows above, each with its class, its discharger and whether it is expressible in assurance/assumptions.toml today; plus every solver, compiler and platform dependency on the path.
  8. Mutation verdicts — per mutant: the level, the patch anchor, the invocation, the verdict, the assertion that fell and its direction, and the reading that argues whether it describes the modelled defect or its inverse. A row whose direction is inverse is a finding about the mutant and not a result about the property, so it also carries a disposition: either superseded, naming in superseded_by another row of the group that corrects it — a chain that must end at a row which is not itself inverse, because a cycle corrects nothing — or kept-as-a-finding. Both arms owe the reading, and the success line counts the disposed rows apart from the verdicts so one cannot be read as a kill.
  9. Timestamp, freshness and revalidation inputs — when each run happened, and the triggers that expire it: toolchain bump, Kani or TLC version, RP2350 stepping, linker script, dependency change, a change to any named Rust owner, the feature set, or a trace schema change.
  10. Measured costs — human time, runner wall time, and peak memory, per artifact. These three are what item 11 exists to observe; an estimate in any of them voids the measurement.

The calibration counterpart

A cost taken at the strongest end of the scale is a floor, so the design names the other end too. The counterpart is the weak end: SEC-FIDO-007 RamNeverOutlivesFlashSeed and SEC-FIDO-008 NoLiveTokenWithoutPinRecord, each measured at 4 configurations, 1 model mutant, 0 Kani, 0 fuzz, 0 device tests and 1 production owner (crates/rsk-fido/src/seed.rs and crates/rsk-fido/src/clientpin.rs respectively). The co-refuted column read 0 when this was written and reads 1 now, which is the correction below carried out rather than described.

The correction, now made. What that co = 0 meant was never “no killed twin”: Both rows’ solo configurations set the same switch, BugStateResetAfterWipe — and that switch’s code twin is in formal/comutants.toml with status = "patch" and expect = "killed" against crates/rsk-fido/src/reset.rs. The 0 is an artifact of attribution: comutate.solo_invariant resolves a bug to the one configuration named Solo_<bug>.cfg, which here checks ResetNeverWeakensSurvivingState, so the kill is credited to SEC-FIDO-006. The weak end was weaker in the ledger than it is in the tree, and no amount of reading the column would have shown that. comutate.solo_index reads the invariant-named solo configurations too now, so the column says what the tree proves: in the launch tranche SEC-FIDO-004 moved 1→2 and 006A, 006B, 007 and 008 each moved 0→1, so the rows standing at co = 0 went from six to two. The prerequisite this section called a hard one is therefore discharged, and what the counterpart still owes is the measurement itself.

The estimate, stated as an estimate. Same bundle contract, applied to SEC-FIDO-007:

  • groups 1, 2, 4 and 9 cost the same on both rows — they are properties of the run, not of the property. That fixed part is what item 11’s floor measures honestly;
  • groups 3, 5 and 6 are cheaper: both invariants are single structural implications over B state with no ghost half, already model-checked on two configurations, and NoLiveTokenWithoutPinRecord maps to A almost directly as live => pinSet;
  • groups 7, 8 and 10 are more expensive, and that is the direction the intuition gets wrong. On SEC-FIDO-001 those fields are transcription — the assumptions are argued in the module, the mutation verdicts exist, the caller set is short. On SEC-FIDO-007 every one of them has to be produced from nothing: the keydev_dec RAM copy’s reachability argument spans crates/rsk-fido/src/seed.rs, the field’s home in state.rs and the load preference in crates/rsk-fido/src/lib.rs, so the caller audit is a three-file argument rather than one function with one call site;
  • and one field could not be filled at all without a decision outside the slice: a co-refutation verdict attributable to SEC-FIDO-007 needed either a dedicated Bug* switch per invariant or a change to how comutate.py attributes a bug to an invariant. Naming that blocker was this counterpart’s real deliverable, and the second option is the one taken — comutate.solo_index reads the invariant-named solo configurations, so the field is fillable and the prerequisite is spent rather than owed.

Estimate: 1.5× to 3× the human time of the strong row for the same contract, dominated by groups 7 and 8. The attribution decision was priced as a hard prerequisite rather than a cost, and it stayed one — it was discharged before the measurement rather than inside it. That range is an estimate and is labelled as one; the whole point of the exercise is that only the measurement replaces it.

Implementation

The token refinement page describes the implemented relation, its Rust checks and its scope. The implementation record contains the measurements and follow-up from the design exercise.

Token refinement pilot

Phase 5 connects three deliberately different descriptions of one narrow property: the per-boot lifecycle of the FIDO pinUvAuthToken and its persistent credential-management grant. It does not establish whole-firmware formal verification, cross-reset refinement, or liveness.

The three tiers

  • A is formal/RSKeyTokenAbstract.tla: 44 states and an outcome-labelled AllowedEventRel. Next is its existential closure, not a second relation.
  • B is formal/RSKeySecurityState.tla. TLC checks native INSTANCE refinement in TokenRefinement.cfg, and checks labelled outcomes separately in TokenRefinementOutcome.cfg.
  • C is (FidoState, TokenPersistentView). The persistent view contains exactly EF_PIN and EF_PAUTHTOKEN. EF_ALWAYS_UV is excluded: it decides when UV is required, but it is not token-lifecycle state. A therefore over-approximates the no-PIN state when the runtime flag is enabled.

The TLA+ module owns AStates, Ops, Outcomes, and AllowedRelation. scripts/export_token_relation.py only captures TLA+-serialized values; scripts/generate_token_edges.py generates the Rust enums, AState, and exact bitset. The exhaustive host test checks all 69,696 tuples. The current export is 44 states, 12 operations, 3 outcomes, and 1,039 allowed edges; these are printed facts, not hand-maintained requirements.

Concrete domain and boot boundary

InitC is the real boot shape relevant to this projection: FidoState::new, the valid BootState lock/warm restoration performed by AppletHandler::new, and clientPIN initialization. Initialization rerolls secret bytes but leaves the abstract token retired. ValidBootInput bounds the restored mismatch byte by PIN_MISMATCH_LIMIT; the board decoder clamps older or corrupt scratch values to that range.

ValidPersistent admits all four presence combinations of EF_PIN and EF_PAUTHTOKEN. This is intentional, including grant && !pinSet: since 0x09CB ensure_seed writes the grant record with no PIN behind it, so that shape is the factory state and the state after every completed reset, and firmware before 0x08BF or a torn reset could leave it too. Because A observes only record presence, not record contents, no older-firmware version assumption is needed for R0p. Every projected write and power cut remains inside those four states.

wf_concrete(F, P) requires the production permission shapes represented by B, live(F) => P.pin_set, a retired token to have no permission or rp binding, and an rp binding to imply a live token. R2a checks InitC; R2b checks inductiveness without kani::assume. R3a checks the initial map and R3b checks every bounded named concrete step against the generated relation.

Reset evidence table

Reset classRequired BootStateEvidence status
Cold power cyclewarm=false, lock clearDecoder and model agree; physical scratch2 clearing is M7-Q1
Host sys_resetwarm=true, whole lock restoredEncoded/decoded in firmware/src/pin_lock.rs; emulator boot tests cover the consumer
Return from BOOTSELCold semantics requiredM7-Q2: measure whether the ROM path clears watchdog scratch2 before relying on it

There is no Compatible premise. No additional boot restriction was found; R0a uses only ValidBootInput. M7-Q1 and M7-Q2 are hardware-evidence tasks, not assumptions silently added to the refinement theorem.

Outcomes and completeness

Outcomes are labels, not A variables. Authorized on a dead-token stutter is therefore still a distinct, forbidden tuple. R1o checks B action labels, while the emulator trace carries outcome_raw copied from the real CTAP response. The validator derives possible B outcomes independently and accepts only consensus: one singleton equal to δC. Multiple interpretations are AMBIGUOUS, never a selected witness; formal/floors.txt ratchets their count.

assurance/token_refinement.toml and scripts/token_refinement_gate.py enforce the three completeness axes across the tree: volatile writers of the token, persistent writers for the keys derived from TokenPersistentView, and authorization outcome producers. Every vocabulary the scan matches on is read out of the tree — the token’s own field list, the PERM_* constants, the Fs methods that reach a storage mutation, the fields and permissions abstract_token really reads, and the crate’s module graph — so a new field, permission or store method arrives as an unowned site rather than as silence. Each entry then carries its disposition: step names the abstract Step it implements, stutter moves security-visible state A does not observe, out-of-scope is a real gate outside A’s vocabulary, and the gate derives which of those a site can be from what it writes.

Three of them are configuration-conditional, and the column field names the docs/assurance-matrix.md column that makes them so. The panel’s set-PIN and PIN-check doors onto EF_PIN exist only where firmware-display pulls in rsk-display; the authenticatorLargeBlobs write gate — the one authorization decision on a permission bit A has no word for — is dead in the largeblob-ext column, because CTAP 2.3 §12.4 forbids serving both large-blob designs and the dispatch is guarded on it.

assurance-trace exposes verification artifacts to the host emulator and is never a firmware feature. check.sh poisons every assurance-only module in a throwaway tree, proves the poison reaches a host feature build but not firmware, and requires the pristine and poisoned firmware images to be byte-identical.

Reproduce

nix develop -c ./scripts/token_refinement.sh --check
nix develop -c ./formal/run-tlc.sh TokenRefinement.cfg
nix develop -c ./formal/run-tlc.sh TokenRefinementOutcome.cfg
nix develop -c ./scripts/kani.sh state

The state/outcome mutants, wrong generated edge tests, broken-stop test, dead-token authorized stutter test, and ambiguous-consensus test are part of the same tree. Cross-reset behavior remains phase 6.

Cross-reset refinement pilot

This is the phase-6 bridge for SEC-FIDO-006, ResetNeverWeakensSurvivingState. It joins the existing TLA+ reset machine to the concrete FIDO reset order, the rsk-fs power-cut contract, and a real-board test. RS-Key is not formally verified, and this page does not move that: the C→B step is bounded, the flash composition has an executable oracle rather than a deductive proof of the storage backend, and a HIL result witnesses only the cut that was run.

The property

The registry requirement is relational: no prefix of authenticatorReset, whether it returns, aborts, or loses power, may keep an owner’s usable secret after removing the gate that protected it. The three independently named clauses are:

IDClauseSurviving factGate that must still exist
SEC-FIDO-006AResetKeepsThePinGateowner credential + owner seedEF_PIN
SEC-FIDO-006BResetKeepsTheAlwaysUvGateowner credential + owner seedEF_ALWAYS_UV
SEC-FIDO-006CResetKeepsTheBackupSealowner’s pre-reset seedEF_BACKUP_SEALED

The last gate reads backwards: deleting the seal is permissive because it re-opens the one-time seed-export window. A newly provisioned seed after reboot is therefore not the owner’s surviving seed and does not violate the clause.

Evidence ladder

LayerOwnerWhat it establishes
Requirementassurance/properties.tomlStable IDs, statements, and the bounded evidence ceiling
TLA+ Bformal/RSKeySecurityState.tlaArbitrary ordering within the secret and gate phases; abort, real power cut, boot-time seed provisioning, and all three clauses
Rust refinementcrates/rsk-fido/src/reset_assurance.rsThe concrete phase machine and abstraction of the persistent/volatile facts observed by the clauses
Kanicrates/rsk-fido/src/reset_refinement_kani.rsInitialization and one-step induction across begin, every relevant delete, phase advances, abort, finish, reboot, and an unrelated FID
Power-cut fuzzfuzz/fuzz_targets/power_cut.rsThe real rsk_fido::reset::reset over SeqStorage, with byte-granular cuts inside writes/erases, fresh caches, Fs::scan, ensure_seed, and a second boot
Real boardtests/29_reset_power_cut.pyThe same owner seed/PIN/alwaysUv/resident-credential scenario with physical USB power removed while RESET is in flight

The generated table in formal/README.md derives the Kani, fuzz, and runtime columns by property name. A runtime column of one means that the HIL harness is owned and discoverable; it is not a stored claim that a particular board run passed.

Concrete projection C→B

ResetPersistentView observes both seed records, one representative resident credential, the PIN and alwaysUv gates, and the backup seal. The credential is usable only while the owner’s old seed is reachable. ResetVolatileView observes only the RAM seed copy and live token; all other FidoState buffers are irrelevant to this property.

The transition projection uses production’s own reset_phase(fid) classifier. That classifier delegates to the shipped is_fido_seed_fid, is_fido_fid, and is_fido_gate_fid predicates, so the proof cannot silently acquire a second hand-written gate list. Its phases match the implementation:

  1. retire volatile state;
  2. delete FIDO_SEED_FIDS;
  3. sweep non-gate FIDO secrets until enumeration completes;
  4. sweep gates until enumeration completes;
  5. provision the next identity epoch.

Step 2 is a fixed two-fid for with nothing to enumerate, so it cannot stop the wipe; step 3’s predicate is is_fido_fid && !is_fido_gate_fid, which covers the seed fids, so a seed the medium refused to remove is re-yielded there and stops the wipe before step 4 (0x098B). The projection follows that: the 2→3 boundary is unguarded and the seed holds the 3→4 boundary shut. Closing 2→3 instead — which is how the projection read until this was measured — makes “in the secret sweep with a live seed” unreachable, and every obligation about step 4 over a live seed is then discharged vacuously: merging steps 3 and 4 into one sweep, the audit run-36 defect itself, left all four harnesses green.

well_formed is the induction domain. It requires retired volatile state once a reset is active, the phase order above, and all three relational clauses. Kani proves that construction starts inside this domain and that every modeled concrete step preserves it. Each harness has a satisfiable kani::cover!; the ordinary unit tests also inject one early-gate mutant per clause and require its exact property to fail.

This is a finite Boolean projection and a one-step induction proof, not an unbounded proof of the sweep loop. Loop termination and truncated enumeration remain production tests; byte-level atomicity is composed below.

The rsk-fs composition and reboot seam

The projection treats one completed force_delete as a record transition. The lower contract is the existing rsk-fs::powercut oracle and its Kani rules: delete_landed allows the old record or a fully deleted record, never a value gone behind surviving metadata. The power_cut target now feeds a separate input class through the complete real FIDO reset on the same cuttable flash stack rather than adding another fuzz target.

After a cut the target drops the dead store, rebuilds SeqStorage with fresh caches over the surviving bytes, scans it, runs boot-time ensure_seed, and checks the three clauses. It then boots and scans once more so a verdict cannot depend on the recovery mount’s cache. The fuzzer samples sequences and fault positions.

Real-power HIL

The test is deliberately destructive and is not run by the emulator:

nix develop -c python tests/29_reset_power_cut.py

Use a throwaway board running the no-touch test image. The script exports and seals the owner seed, sets a PIN, enables alwaysUv, creates a resident credential, starts RESET, and asks for a real cable pull. A relay can be supplied through RSK_POWER_CUT_CMD; RSK_POWER_CUT_DELAY_MS moves the cut point. A RESET that finishes before power disappears is INCONCLUSIVE, not PASS.

A cut has to be shown to have landed in the wipe. The assertions after the reboot are all about a fail-closed device, and a board on which the reset never began is fail-closed for free — so a cut that arrives before the request does satisfies every one of them. The device settles it: rsk_usb::ctaphid enters run_with_keepalive only once the whole CBOR request is reassembled and writes its first CTAPHID_KEEPALIVE one KEEPALIVE_MS later, so a frame carrying STATUS_PROCESSING means the request arrived and the handler had been running that long. STATUS_UPNEEDED means the opposite — a touch ceremony that stands ahead of every flash write. Without a PROCESSING frame the run is INCONCLUSIVE. It does not prove an erase landed; nothing on this wire does.

A frame counts only on our channel id. Every open handle on a HID device sees every input report, so another host process’s slow CBOR command streams its own PROCESSING keepalives into this queue while our request is still unread in the OUT buffer — and unscoped, those frames say the wipe began when what began was somebody else’s command. The three INCONCLUSIVE worlds are told apart in the message: a board that ANSWERED (a RESET refused past the CTAP 2.1 §6.6 window comes back 0x30 well under the floor, and no later cut changes that), a board still waiting for a finger, and a cut that arrived before the request — only the last of which is cured by cutting later.

That puts the cut in a band rather than at an instant: above 100 ms, where the first keepalive is, and below the 487.2 ms the whole reset took on the board assurance/board/PLAT-FLASH-001.toml cites. The operator still cuts on the printed CUT POWER NOW line, not on the Enter: the line is printed at most 0.11 ms after the window opens — the widest value over every run measured, not a selection of them — so a 200–300 ms reaction to it lands in the band, where a yank riding the Enter lands at ~0 ms — under the floor, and indistinguishable from a cut that never reached the board. The relay’s default delay is 2 * KEEPALIVE_MS for the same reason.

What the band costs the row. reset() starts at 0 and the confirmable band opens at 100 ms, so the first KEEPALIVE_MS of the handler — where request_rescrub and the first tombstones land — is un-PASSable by construction: a cut there is INCONCLUSIVE whether or not it tore anything. Driven against a simulated board on a 1 ms grid the verdict flips at the floor exactly — the last unconfirmed is 100 ms, the first torn is 101 — and a real board adds USB and host latency that nothing here measures, so the false-red band starts at 100 ms and ends somewhere above it that this cannot name. The 200 ms default is 100 ms clear of the floor. The direction is the safe one — the instrument refuses a run it cannot confirm rather than passing it — but it means PLAT-FLASH-001’s sweep can never report on the earliest part of the window it is asked to sweep. Closing that needs a signal earlier than the first keepalive, and this wire has none.

Either way the cut is appended to a JSON-lines record, one object per cut, since one run is one cut and a sweep is a series of runs. It defaults outside the checkout and RSK_POWER_CUT_LOG moves it. Nothing in it is called “the delay”: the sender’s transfer death and the host-observed disappearance are upper bounds on the cut, the last frame that came back is a lower bound, the first PROCESSING keepalive says when the device was known to be inside the reset, and each is written under the bound it is with the error floor it carries. A transfer that died of ctaphid’s own read budget rather than of the handle failing bounds nothing, and says so instead of pretending to.

The line is the CUT’s verdict and says so in its own records field, because it is written before main’s post-reboot assertions run: a run that FAILED them leaves the same torn line a passing one leaves. What joins the two is run_id, printed beside PASS as well — read the exit code off that transcript, never off the record. run_id is also what separates our lines from anyone else’s in a shared file: the append refuses a symlink and nothing else, because the normal case for this path is one that already exists.

Flashing and operating the hardware remain maintainer actions. Consequently a fresh real-board PASS must be recorded separately before calling the roadmap’s hardware witness complete.

Verus / Creusot decision

No third verifier is added for this pilot. The decision is measured rather than based on modeling convenience:

  • a direct Kani run through the full FidoState::reset() was stopped after 72.45 s without a verdict while CBMC expanded zeroize loops through at least 398 iterations; the unrelated crypto buffers dominated the formula;
  • after projecting the two volatile facts the property actually observes, the parent harness solved in 0.52 s and the three clause harnesses in 0.45–0.48 s on Kani 0.67.0; all four covers were reachable;
  • the byte-level and full-state links are exercised by the real reset unit tests and power-cut fuzz, where the complete storage and FidoState are affordable.

This is a tractable bounded-proof boundary, not evidence that an unbounded loop or state-size limit prevents the required argument. Verus or Creusot would add a third toolchain without removing the abstraction obligation, so the decision is not now. Revisit it only if a later requirement needs an unbounded sweep or multi-step state space that cannot be reduced without dropping a security- visible fact.

Store refinement pilot

The third C→B pilot, and the smallest. It connects RSKeyStore’s cache half to the code that maintains it: the model’s present and decided variables, and the Fs primitives that write them. RS-Key is not formally verified: this is one half of one model bridged to the code that maintains it, and the statuses below are what that buys and no more.

Storage v2 adds authenticated authority and an automatic boot migration and authenticated recovery lifecycle below this cache contract. This pilot does not prove the MAC construction, replicated journal, import or root transition. Those mechanisms have concrete native and real-NOR fuzz controls; the model still assumes its backend append contract.

Why only half

RSKeyStore has seven variables. Five of them — val, meta, dead, metaAbsent and the FID map they range over — are the persistent side, and that side already has evidence: crates/rsk-fs/src/powercut.rs’s four *_landed predicates are what the module was lifted from, powercut_kani.rs proves them, and the power_cut fuzz target replays a real medium through them.

present and decided had none. They are in-RAM, so no power-cut oracle sees them; they are private to fs.rs, so no other crate’s test reaches them; and the model’s clauses about them are the ones a reader would call obvious. One of them — a faulted read cached as a decided absence — is audit run-36, and it shipped.

What the harnesses claim

Six, in crates/rsk-fs/src/store_refinement_kani.rs, each naming its model action. The projection they run against is store_assurance.rs: it reads the real bitmaps and calls the real primitives, hooked as a #[path] child of fs.rs so the private methods are reachable without widening them.

Model actionConcrete stepThe clause
Put(f, v)mark_presentf is decided live; no other FID moves
Delete(f)mark_absentf is decided absent; a live neighbour stays live
Confirm(f), fault = FALSErecord_unless_faultedthe backend’s answer is cached as decided
Confirm(f), fault = TRUErecord_unless_faultednothing is cached — audit run-36
Init / RebootFs::newnothing cached, nothing decided
—known_absenta clear present bit is trusted only once decided confirms it

Two more, in store_meta_kani.rs, are the EF_META fault sites rather than the cache clauses. They are described in the first bullet of “What this is not”, because they are what that bullet used to say could not exist.

Every harness carries a second symbolic FID. That is the content: the model’s clauses are [present EXCEPT ![f] = …] — one element moves, every other stands — while the code reaches its bit through fid >> 3 and 1 << (fid & 7). A shift that disagreed would alias two files onto one bit, and a mark_absent on one would then read as a decided absence for the other. That is NoFalseAbsent’s disaster reached through arithmetic rather than through a fault, and no single-FID harness can see it.

The scope, and what it cost

FID_PRESENT_BYTES is 3 under cfg(kani), against a shipped width of one bit per FID over the whole 0x0000..=0xFFFF space — 8 KiB. Measured at that full width, the writing harnesses cost 149 s, 273 s, 302 s, 520 s and 794 s — two of them over scripts/kani.sh’s 5-minute FAST cap, whose own rule is to move the crate to SLOW rather than raise the cap, and that would have taxed the four 0.5-second powercut rules for this pilot’s arithmetic. At three bytes every one of the six runs in 0.04–0.08 s and the whole rsk-fs set is under ten seconds.

Three bytes is not a round number: it is the smallest width at which both a within-byte neighbour and a cross-byte neighbour exist, which is what the aliasing clause needs. The harnesses take their domain from the constant (store_assurance::FID_LIMIT), so it follows the shrink instead of restating it.

What the shrink stops proving is that no FID can index past the map — at full width that fell out of the harnesses as a discharged bounds check. It is a compile-time assertion now:

#![allow(unused)]
fn main() {
#[cfg(not(kani))]
const _: () = assert!(((u16::MAX >> 3) as usize) < FID_PRESENT_BYTES);
}

which is the stronger form: it is about the shipped width, and a proof would only ever have covered the FIDs a harness enumerated.

EF_META is aliased for the same reason and costs something different. At 0x0017 it is bit 23 of the 24 the shrunk map has — the last bit of the last byte — so the metadata blob sits inside the symbolic FID domain rather than outside it, which is a different store topology and not the same one faster. Three things stop being proved:

  • that EF_META indexes within the shipped map. Shipped, fid >> 3 puts 0xE010 at byte 7170 of 8192, and the compile-time assert above owns that;
  • that EF_META is disjoint from every FID an applet writes. At 0xE010 it is outside every applet range; at 0x0017 it is inside the file space. That is an over-approximation the shrink INVENTS rather than one it hides — a meta_add whose subject is EF_META itself is a state the shipped store cannot reach — so store_meta_kani.rs assumes the collision away and says so;
  • that scan registers every file it is handed. Its fid == EF_META skip (fs.rs:287) is compiled under cfg(kani) too, so under the alias it refuses FID 23 — a FID the harnesses’ own domain draws from. Inert today, because no harness in the tree reaches scan; it is what the Scan bullet below would have to deal with.

VIEW_FIDS is untouched by all of it: at 0x0301 and up it does not land in the 24-bit map, it is read under cfg(test) only, and the seven-alternative measurement that chose it — including the triple “around EF_META” — was taken at 0xE010 and still stands.

What this is not

  • Not a Kani result for the persistent half — and the first version of this bullet was wrong about why. NoOrphanedMetadata, NoRecordLostToMetaWrite, NoFalseMetaAbsent and NoSilentOrphan have a bridge now — store_steps_tests.rs, below — but it is a host sweep, so the four stay MODELLED-ONLY: assurance_gate reads BOUNDED off a Kani harness name.

    A harness that does nothing but meta_add failed, before the alias below, and the message was the present map:

    ** 1 of 164 failed (34 unreachable)
    Failed Checks: index out of bounds: the length is less than or equal to the given index
     File: "crates/rsk-fs/src/fs.rs", line 140, in fs::Fs::<…>::decided_bit
    Verification Time: 0.110 s
    

    From which this page concluded “no metadata path can run under cfg(kani) at all” and “there cannot be one”. Both are false, and the review measured it. The blocker is EF_META’s VALUE (0xE010, index 7170), not the map’s WIDTH, and the value takes the same one-line alias FID_PRESENT_BYTES already has: with #[cfg(kani)] EF_META = 0x0017 and nothing else changed, the same harness is 0 of 164 failed, SUCCESSFUL, 0.223 s. Widening the map, which is what the old bullet argued about, was answering a question nobody asked.

    The alias and the two fault-site obligations are taken now, in store_meta_kani.rs, over the FaultBackend this page’s cache harnesses already use: meta_add refusing a FAILED EF_META read rather than rebuilding from an empty blob (0.317 s), and meta_delete never caching that same read as a decided absence (0.156 s), both measured by the pr tier that runs them. Each asserts BOTH directions as separate clauses, because a refusal alone is satisfied by a meta_add that refuses everything — and because Kani 0.67 reports every assert! message in this crate as “a placeholder message”, so the failing LINE is the only thing that tells a kill from its inverse. Driven: BugMetaAddDropsOnFault fails the first on the faulted arm, BugMetaDeleteDropsOnFault fails the second on the faulted arm.

    What did not move is the two statuses. SEC-STORE-003 and SEC-STORE-004 stay MODELLED-ONLY, and the two harnesses are named so that they stay there: assurance_gate FORCES BOUNDED from a harness function name containing the property’s, without looking at domain, bound or cfg, so a name is all it would have taken. A FaultBackend holds no blob, so meta[f] is not represented and what verifies is the GUARD at the fault site, not “no record was lost”; and the domain is the shrunk one. BOUNDED there would be a scalar going up while the domain went quietly down. The thing that would earn it is a theorem carrying the present/decided arithmetic to the whole shipped u16 domain, and that has no owner.

    What genuinely is out of reach is still the clauses over a MEDIUM. With the alias, a single-blob backend and META_MAX shrunk 1024 → 32, both blob obligations time out at 420 s — re-measured, CBMC timed out, at 419.9 s of solving for the record a meta_add may not drop and 420.7 s for the blob that may not read absent while one stands. That is the blob rebuild, not the bitmap, and it is the boundary of what the alias buys. The medium-backed clauses stay the host sweep’s.

  • Not Scan. The model’s truncated-walk clause needs a backend that can truncate, which is a medium, not a bitmap. fs_tests.rs carries it; Kani does not.

  • Not a whole-behaviour result. The Kani harnesses are one-step obligations at every FID, which is why SEC-STORE-002 is BOUNDED and not more; the host sweep below is bounded by sequence LENGTH, which is the same kind of claim.

  • And it cannot be a per-FID state projection either. The tempting move is to write the model’s per-FID steps as Rust predicates and hold them against powercut.rs; it was tried and measured, and each predicate comes out as the same boolean function as its *_landed twin — 0 disagreements over a five-valued domain, which is a copy compared to itself. Two of the three are STEP recorders (a meta-only file legally has metadata and no value, so the violation is a record outliving a delete rather than a state) and the third is CROSS-FID (a meta_add dropping ANOTHER FID’s record). formal/README.md’s phase 7 has the numbers.

The persistent half, exhaustively on the host

store_steps_tests.rs drives the REAL Fs over a REAL medium at three FIDs and reads, after every step, the recorders that step can violate — five of them over four properties. Three FIDs because NoRecordLostToMetaWrite is about the records a rewrite drops: with a subject and one neighbour, “the write kept everything else” cannot be told from “the write kept the one file we looked at”.

SweepWhat it coversSize
every three-step sequencethe clauses over a fresh store12³ = 1728 orderings, 5184 steps
the same, then a reboot with no scanEF_META UNKNOWN rather than confirmed — the 0x077C door1728 × 12 more steps
every two-step sequence over a failing mediumthe FAULT path three of the recorders are about144 orderings
each of the three helper predicates against the state its invariant forbidsthat a recorder can answer TRUE at all, and one state over that it does not3 × 2 assertions
the fifth recorderpairs a predicate with what Fs::delete ANSWERED, which no StoreView carries — so the sweeps above are where it is read—
a live-read counter per recorderthat the sweeps are not a loop over nothing5 counters, each > 0 in the sweeps that reach it

Two measurements decide whether this is worth anything.

It has teeth. comutants.toml’s BugDeleteMetaOnlyUnderPresent — the 0x077C databug verbatim — applied to fs.rs gives, in 0.00 s:

NoOrphanedMetadata: [MetaAdd(0)] then Delete(0) left a record over a gone value

which is the shortest witness there is: a meta-only file deleted. All three recorders have one now — BugMetaAddDropsOnFault gives NoRecordLostToMetaWrite: [] then MetaAdd(0) dropped a bystander's record and BugMetaDeleteDropsOnFault gives NoFalseMetaAbsent: [] then MetaDelete(0) cached absence over a live record. The first of those survived the first version of this sweep, because the faulting medium failed writes as well as reads and NoRecordLostToMetaWrite’s loss needs the read to fail while the rewrite LANDS. The counters are the reason that cannot happen twice: with put and meta_add made inert the sweeps used to pass ~26 000 dead steps in silence, and they now say NoOrphanedMetadata was never read from a state it could refuse.

And it does not have all of them. BugDeleteValueBeforeMeta — the two backend writes reversed — survives, and correctly. The tempting reason is that the completed end state is identical either way; measured, that is false — with a bystander’s record and a medium whose remove fails, Put(0), MetaAdd(0), MetaAdd(1), Delete(0) ends at meta=[false,true,false] shipped and meta=[true,true,false] reversed, no power cut involved. The narrow reason is the right one: NoOrphanedMetadata cannot separate them, because val[0] survives in both and an orphan is a record over a gone value. powercut.rs’s delete_landed is what owns the ordering, which is why both exist — and cargo test -p rsk-fs does kill this mutant, through powercut::tests::a_cut_never_leaves_metadata_behind_a_file_that_is_gone.

The one shape the sweep could not judge, and the defect behind it

A faulted Delete. MetaAdd and MetaDelete each carried a faulted disjunct in the model and Delete carried none — dead there is a power cut, not a medium error — so reading NoOrphanedMetadata at a faulted delete would have been judging a step nothing stated, and the fault was armed only for the two actions that had one. Both halves are closed now; the code’s is below, the model’s at the end of this section.

That was a modelling decision, and it was standing in front of something real. The first version of this paragraph described it as a meta-only-file curiosity. It is not. Fs::delete used to swallow meta_delete’s error (a let _ = in fs.rs, deliberately quoted without a line — the fix moved it) and then remove the value; over a medium whose EF_META read failed ONCE and then worked, a delete of a file that has data returned Ok(()) with the value gone and the record standing:

delete returned : Ok(())
after: meta=[true, false, false]  val=[false, false, false]

That is the 0x077C databug’s end state, on the shipped tree, with no power cut and no meta-only file. It is reachable on hardware — rsk-store’s read and size set last_err straight from sequential-storage’s fetch_item, so last_error() is a flash read error and not a modelling device. And the tree already treats the consequence as a defect in one place: rsk-piv’s crates/rsk-piv/src/files.rs:423-432 rewrites the management key’s head unconditionally, because after a force_delete “a stale AES-256 head left over a re-minted 24-byte DEFAULT_MGM wedges the slot on the length compare”. PIV’s other meta_add_slot sites have no such repair.

Closed in the code half, and not the way the first draft of this paragraph proposed. Propagating with self.meta_delete(fid)? before the value goes was the obvious repair and it is the wrong one: EF_META is one blob shared by every applet, a failed read of it means “cannot tell” rather than “no record”, and most callers spell the delete let _ = fs.delete(...). So a single flash-read fault would have stopped every delete on the device — a wipe included — while the callers that discard the result reported success, trading an orphaned record for a secret that outlives its erase.

What delete does now is remove the value regardless and return the metadata error, so Err names a state (the value is gone, a record may stand) instead of hiding it. The delete caller that reaches a fid carrying a head is PIV’s MOVE with to = 0xFF, the slot delete — heads are minted by rsk-piv alone — and it reads the answer: the head gets a retry, because one read can fault where the next lands, and the key is read back, because a remove that failed leaves the source holding a live key. Both directions answer 6581.

That was written as “the one caller in the tree”, and the audit of the delete family refuted it. There is a second, and it is the one all four applet reset sweeps go through: Fs::force_delete, whose metadata drop was a let _ =. PIV’s wipe_piv runs it over the same head-carrying fids, so RESET could answer 9000 over a head it could not drop — BugDeleteHidesFaultedDrop still standing at the third deleter, on the P0-launch reset path, after the delete half was closed. force_delete returns the metadata outcome now, and its contract names the three outcomes separately from delete’s because its callers need the distinction: value gone and record gone, value gone with a record possibly standing, or the medium refused and the value may be live. Held by a_faulted_metadata_drop_is_reported_by_force_delete_too at the Fs layer and a_reset_answers_for_the_heads_it_could_not_drop at the APDU layer.

What the card then shows over an orphan is measured, not assumed. PIV’s GET METADATA gates existence on the head alone — its has_key probe was dropped as a per-slot flash fetch on every call — so a slot whose head outlived its key answers 9000 with the head and the cached public point on an EC slot (the point rides in the head), 6400 on an RSA one (the modulus is loaded from the key), and never 6A88. The probe stays out: the state is rare, both producers report it at the moment they create it, and the cost is paid on every ykman piv info.

And the first shape of that repair was itself the wrong one, measured. Naming three outcomes in the prose while returning a type that carries two left every caller to collapse them, and the four sweeps collapsed them with ?: a faulted read of the shared EF_META blob then ended authenticatorReset after ONE file, at the same fid on every retry, so no retry made progress and EF_KEY_DEV_ENC — the soft lock’s wrapped copy of the seed — survived with every credential. That is the ?-before-the-value failure arriving through the callers instead of through the body. So the sweeps take Fs::force_delete_halves now, which hands the two answers back apart: a refused backend removal still stops the sweep, because for_each_key re-yields the fid it could not remove, while a faulted metadata drop is carried to the end of the range and answered for there. Both halves are the test, in all four applets — the range is empty AND the command answers the fault — because a test that read only the status word passed the aborting tree too.

Every caller now carries a written decision, in assurance/deleters.toml: 43 sites — 24 delete, 9 delete_key, 5 force_delete, 5 force_delete_halves — each classed, each saying whether its fid can carry a head, and each saying whether discarding the answer is an allowed best-effort wipe there or a device reporting success over something still in flash. The roster under those decisions is derived, not stored: scripts/deleter_gate.py reads the tree for the sites, the verbs and whether each statement reads or discards the Result, and holds the file to that in both directions, so a new caller arriving unaudited or a must-read site quietly becoming a let _ = reddens the delete-caller dispositions row. It derives the head-minting crates too, because every drops-head decision rests on that being rsk-piv alone.

And the model’s half landed with it, in 41c3b70. RSKeyStore!Delete carries a second disjunct now — the medium error, one backend write and no cut point — and it took two clauses rather than one weakened one: an orphaned record IS a state the shipped tree reaches, so NoOrphanedMetadata keeps every arm whose drop landed while NoSilentOrphan (SEC-STORE-006) forbids the one thing the code may not do, which is answer Ok from the arm that could not. StoreSolo_BugDeleteHidesFaultedDrop.cfg is what says the new arm is reachable rather than inert — RED on NoSilentOrphan in 43 distinct states at one worker, 61 at two and 74–76 at four. A counterexample search halts at the first violation, so the verdict and the invariant are the result and the count is only where this search happened to trip (formal/README.md’s rule for the column). The sweep’s fifth recorder asks the same question of the real Fs.

The PR gate carries the same clauses at concrete FIDs (a_cache_write_moves_one_fid_and_no_other_across_three_bytes and a_faulted_confirm_caches_nothing_and_a_clean_one_caches_the_answer), because a proof that only runs weekly is a proof a rename can take away on a Monday. That test walks a window of 24 consecutive FIDs rather than checking a pair: >> 3 mistyped as >> 2 and & 7 as & 3 alias different pairs, so a test naming two FIDs catches whichever of them its two happen to meet.

Verified compilation decision

Stage 11’s level 11C is a research question, not a work item: could a critical kernel of this firmware move to a language or a C subset with a verified compiler — CompCert, or an F*/Low* pipeline that extracts to C — and would that shrink the toolchain TCB more than the second language grows it.

The answer is no, and no pilot is scheduled. The reasons are measured below, each with the command that produced it, and the last section says what would overturn them.

RS-Key is not formally verified. This page is a decision about a research direction. It reports no verification result, moves no property status, and discharges nothing — PLAT-TOOLCHAIN-001, the row that says the compiler’s output is outside every proof this tree runs, is untouched by it and stays pending.

The decision

The compiler targets reviewed below lack Armv8-M Mainline support. Moving a Rust kernel to verified C would add tools and an FFI boundary. Level 11C is declined for the RP2350. The source-to-binary gap is recorded in assurance/platform.toml.

The candidate kernels

Stage 11B names five. Measured over the tree, one of them is portable to a C subset. RSA and three other candidates fall outside the verified C subset.

CandidateWhereSizePortable to a verified C subset?
gate / transition functionsthe ten concrete gates docs/authorization-slice.md lists, over crates/rsk-fido/src/state.rs856 lines in state.rs aloneNo. Half are generic over two traits (<S: Storage, R: Rng>); the other half take a Rust struct by reference, whose layout Rust owns
zeroization routines16 scrub / wipe_* sites across crates/ and firmware/, and rsk_secret’s drops16 sites, 49 files using zeroizeNo. Each is a method on a Rust type, and the drop glue that makes it sound is the compiler’s
RSA exponentiation and CRTRust with shared host and device Montgomery arithmetic349 lines in montgomery.rsMoving the kernels to C would require a source rewrite and a new FFI contract
ML-DSA reductionscrates/rsk-mldsa/src/reduce.rs, ntt.rs, round.rs256 linesYes, in principle. Branch-free integer arithmetic, no generic function in any of the three
linker-generated boundaries15 of the 32 [[boundary]] rows in assurance/toolchain.toml15 symbol importsNot code. The datum is a symbol’s address; a compiler has nothing to say about it

The genericity is the load-bearing number. Across the production modules of crates/rsk-fido/src/, 243 of 470 functions are generic and 177 of those carry <S: Storage. C has no traits and no monomorphisation, so “port the gate” means “hand-instantiate and rewrite it”, and the rewrite is the risk the verification was meant to remove.

The one candidate that would port cleanly is the smallest and the least exposed. crates/rsk-mldsa/src/round.rs already carries a Kani proof (round_kani.rs), which is evidence about the source — exactly the layer a verified compiler does not reach — so moving it to C would trade a proof this tree runs for one it cannot.

RSA and the remaining FFI boundary

The Rust RSA kernels have 0 RSA native imports. The Secure TrustZone gateway still uses C, with a calling convention and native source inventory recorded in assurance/toolchain.toml.

The TCB delta

scripts/check-assurance.sh:"toolchain TCB registry" prints the live roster, and assurance/toolchain.toml is what it prints from: 13 registered tools carrying 7 distinct roles, of which 12 name a file that pins them and 1 is unpinned against an open obligation. The registry records 32 boundaries, including 15 linker-symbol imports. The remaining 17 cover the TrustZone gateway, interrupt vectors, probe symbols and Secure fault entry. Of the six TCB categories the criterion counts, the registry reaches 4 and says why the other two are out of reach.

A verified-compiler pipeline moves that in one direction only.

It removes nothing. The intuition is that CompCert replaces LLVM for the kernel, but LLVM is not in the roster: it is one of the two categories assurance/toolchain.toml records as out of reach, because rustc’s LLVM version is written in no file of this tree and its pass pipeline is written nowhere at all. Replacing an unenumerated tool for one kernel does not enumerate it. And arm-none-eabi-gcc and arm-none-eabi-as both stay, because the Secure gateway still uses that toolchain.

It adds at least one tool and plausibly three. CompCert alone is a [[tool]] with role compiler and a provenance a gate must open on every run. An F*/Low* pipeline adds its checker and its extractor, and the extractor is the awkward one: the C it emits is what a C compiler verifies, so the extraction step is inside the TCB and is not itself what “verified compiler” refers to.

The enumerated-category count does not move. It would still reach the same four: LLVM stays out of reach for the reason above, and the bootrom is burned into the RP2350 with no version or hash recorded anywhere.

Net: +1 to +3 tools, 0 removed, +2 or more FFI boundary rows, and the category count unchanged.

Ecosystem and build

CompCert does not target this chip. Its manual lists “ARM v6, v7, and v8 in 32-bit mode, with VFP coprocessor”, and its configure script takes the ARM refinements armv6-, armv7a-, armv7r- and armv7m-. The firmware’s target is thumbv8m.main-none-eabihf — Armv8-M Mainline, Cortex-M33 — which no CompCert target names. The nearest, armv7m-, is a different architecture profile.

The pinned nixpkgs has CompCert and this project may not use it. The same nixpkgs revision assurance/toolchain.toml pins for arm-none-eabi-gcc carries compcert 3.17. Its meta.platforms names six host platforms and no 32-bit ARM among them, and its meta.license is the INRIA Non-Commercial License Agreement, with free = false and redistributable = false — evaluating its derivation path fails the unfree assertion outright. The tree is AGPL-3.0-only and the release publishes artifacts a third party is meant to rebuild bit-for-bit; a non-redistributable compiler in the build closure means only someone who has separately licensed it can do that.

The release pipeline has no place for a second language. From scripts/check-assurance.sh:"release manifest": 15 steps over 6 subjects. Three of the fifteen are touched, and the third is the one that fails quietly.

StepSubjectWhat a second language does to it
build the firmwarenonethe derivation must carry a second toolchain
reproducibility gatebit-for-bitthe second compiler must be deterministic, and reproducible by whoever holds its licence
CycloneDX SBOMinventorycargo cyclonedx (.github/workflows/release-build.yml:171) enumerates cargo packages; a non-Rust kernel is simply absent from the published inventory, with no error

The remaining twelve — checkout, the installers, the caches, tag admission, checksums, provenance, signing, notes, publication — are language-agnostic.

What it costs the gate

scripts/check.sh runs 109 rows: 61 invoke cargo, 18 are Python, 30 are neither. A kernel outside Rust is invisible to a measured nine of them, and would need a twin for many more.

Structurally blind, all nine: cargo-audit on three lockfiles, cargo-deny, cargo-vet, crate roster, crate graph, kani roster and kani shrink roster. Every one derives its subject from cargo metadata or from .rs source — scripts/crate_graph.py and scripts/roster_gate.py from the workspace manifests, scripts/kani_gate.py from files with an .rs suffix — so a C or extracted-C kernel is not a thing they can fail about.

Would need a twin: 24 clippy rows, 8 rustdoc rows, 5 fmt rows and 18 cargo test rows. A second language does not inherit -D warnings, a formatter the gate can run, a doc build, or a test harness whose empty selection is already caught.

That is the cost to a project the README opens by calling experimental, with one maintainer. It is the argument that decides this even where the technical ones are close, and here they are not close.

What would reverse this

A decision with no falsifier is a preference. Any one of these overturns it:

  • A verified compiler targets Armv8-M Mainline. A CompCert release whose configure script accepts a thumbv8m-class target, or a comparable verified backend for Cortex-M33, removes the first and largest reason.
  • The licence stops being a blocker. A verified compiler for this target under terms that let an AGPL project publish a reproducible build anyone can reproduce.
  • The ML-DSA reduction kernel gets a pilot that pays. It is the one candidate that ports: 256 lines, no generic function, branch-free integer arithmetic. A measured pilot showing the extracted C is byte-comparable in speed and that the proof obligations it discharges are ones Kani does not already reach on the Rust would reopen the question for that kernel alone — never for the whole firmware.
  • The gate stops being Rust-shaped. If the tree acquires a second language for an unrelated reason and pays the linting cost listed above anyway, the marginal cost of this decision falls to the toolchain delta alone.

None of these is close. The first two are outside this project’s control.

Reproduce

nix develop -c python scripts/toolchain_gate.py     # the roster and its FFI boundaries
nix develop -c python scripts/release_gate.py       # 15 steps over 6 subjects
nix develop -c python scripts/docs_constants.py     # MAX_MOD, held against the code

# the candidate kernels
wc -l crates/rsk-rsa/src/montgomery.rs
wc -l crates/rsk-mldsa/src/reduce.rs crates/rsk-mldsa/src/ntt.rs crates/rsk-mldsa/src/round.rs

# the FIDO gate surface: functions, generic functions, and the storage bound.
# `:(glob)` so `*` stops at a `/` — the plain pathspec is depth-blind and pulls
# in the conformance fixtures, which are not the surface a port would carry.
fn='^[[:space:]]*(pub(\([^)]*\))?[[:space:]]+)?(async[[:space:]]+)?fn[[:space:]]+[a-z_][a-z_0-9]*'
git grep -hE "$fn"  -- ':(glob)crates/rsk-fido/src/*.rs' ':!*kani*' ':!*tests*' | wc -l
git grep -hE "$fn<" -- ':(glob)crates/rsk-fido/src/*.rs' ':!*kani*' ':!*tests*' | wc -l
git grep -hE '<S: Storage' -- ':(glob)crates/rsk-fido/src/*.rs' ':!*kani*' ':!*tests*' | wc -l

# the gate's shape
grep -cE '^[[:space:]]*(run|run_tests)[[:space:]]+"' scripts/check.sh
grep -E '^[[:space:]]*(run|run_tests)[[:space:]]+"' scripts/check.sh | grep -c cargo

# the compiler this decision is about, in the nixpkgs this tree already pins
nix eval "github:NixOS/nixpkgs/331800de5053fcebacf6813adb5db9c9dca22a0c#compcert.meta.license" --json
nix eval "github:NixOS/nixpkgs/331800de5053fcebacf6813adb5db9c9dca22a0c#compcert.meta.platforms"

The CompCert target list is the manual’s, section 1.4.1 and the configure options beside it, at https://compcert.org/man/. It is the one measurement on this page that is not this tree’s to re-derive.

Architecture

RS-Key is a composite USB authenticator for the RP2350. The Non-secure firmware handles USB classes and framing. The Secure firmware owns the USB controller, runs the applets and decides whether a command may use a credential. See the threat model for security assumptions.

The big picture

The three interfaces are FIDO HID (usage page 0xF1D0), CCID (USB class 0x0B) and a HID keyboard. The keyboard interface types OTP values and carries OTP HID feature reports. The interface mask in EF_PHY can disable interfaces at boot.

flowchart TD
    host["USB host"] <--> controller
    subgraph ns["Non-secure on core0"]
      fido["FIDO HID<br/>CTAPHID"]
      ccid["CCID<br/>APDU and Secure PIN"]
      kbd["Keyboard HID<br/>OTP reports and typing"]
    end
    subgraph s["Secure on core0"]
      controller["USB controller and lifecycle"]
      gateways["CMSE gateways"]
      gateways <--> worker["Worker and applets"]
      worker <--> storage["Flash store"]
      presence["Button or trusted display"] --> worker
    end
    controller <-->|"Bounded endpoint operations"| ns
    ns <-->|"Copied commands and replies"| gateways
    worker <-->|"RSA prime search"| rsa["Secure core1"]

rsk-usb reassembles CTAPHID messages and handles CCID framing. The Secure worker dispatches the copied request through rsk-device, which applies applet availability and routing policy. USB interface availability and applet availability are separate settings. For example, CCID can carry FIDO commands as well as OpenPGP, PIV, OATH and management APDUs.

RSA on core1

Core0 runs the worker and USB. During RSA key generation it also tests prime candidates. Core1 uses a per-job HMAC-DRBG, seeded by core0, and returns primes through a Secure mailbox. Between jobs it waits in WFE. The Fermat-filter modular exponentiation runs from SRAM to keep both cores from competing for XIP instruction fetches on that path.

Once core0 has enough primes, it asks core1 to cancel. Core1 can stop at a Lucas-test progress boundary and scrubs its candidate and sieve. The result need not wait for that cleanup. A core1 that stops responding is marked faulted and subsequent key generation stays on core0. core1-stats exposes diagnostic counters in a test build.

There are two flash handshakes. Quad-read mode changes use a dedicated interrupt-masked SRAM park. The firmware changes the QMI mode before core1 starts or after it acknowledges that park, skips the change while core1 is busy, and restores the prior mode if the probe fails. For erase and program, embassy-rp uses pause_core1() and an SRAM flash routine. Its FIFO handler and pause loop are in flash-backed .text. PLAT-XIP-001 tracks whether the parked loop stays in cache throughout an erase.

TrustZone

Every authenticator build uses Secure (S) and Non-secure (NS) execution on core0. The worker runs on the Secure SWI_IRQ_0 executor. The NS USB executor uses the higher-priority SWI_IRQ_1 so it can send keepalives during Secure work. Core1 runs Secure code.

The boundary assumes arbitrary privileged NS code. That code can forge transport state, call the gateways directly, stop serving USB or read plaintext sent through it. A plaintext host PIN carried in an APDU is visible there. A PIN entered on the device screen is collected and checked in S. The applets decide which PIN, management authentication, presence or other policy a command requires.

The boot ROM, hardware access controls and Secure code are part of the trusted computing base. That includes the Secure USB driver and lifecycle observer, gateway validation, applet parsers, crypto, storage and board I/O. See Platform assumptions for dependencies and Testing for verification scope.

Resource ownership

ResourceSecure ownerNon-secure access
MemoryS flash, SRAM and stacks. The Secure gateway veneers occupy the NS-callable (NSC) region.Its own code, vector table, stack and SRAM. Calls to S enter through NSC veneers.
Core1 and cross-core controlsRSA engine, DRBG, mailbox, stack, launch and flash-pause handshakesNo access to the RSA engine or its reserved SIO resources
USB hardwareUSBCTRL, DPRAM, physical endpoints, interrupt and bus lifecycleBounded endpoint operations and copies of packets and events
USB classesS supplies the boot identity and interface mask, and checks endpoint allocation.USB descriptors, CTAPHID and CCID framing, keepalives, OTP HID and keyboard reports
TimersTIMER0, tick generation, clocks and reset controlsTIMER1 for the NS executor
Flash and keysKV store, QMI and XIP controls, OTP and TRNGApplet operations through the worker
Board I/OPresence button, panel and touch, LED and their GPIO, PWM, PIO, SPI and I²CStatus and cancellation through the gateways
Access policySAU, MPU setup, ACCESSCTRL, DMA channel security, interrupt routing and watchdogOnly the resources granted to NS

Before starting NS, S sets up the Security Attribution Unit (SAU), memory protection and interrupt routing. Peripheral permissions are written and read back. DMA channels are locked to Secure privileged access, and NS receives no raw DMA or GPIO controls. The linker reserves 448 KiB of main SRAM for S and 64 KiB for NS. Secure scratch SRAM has a separate region for code that must run off flash.

Gateway and data contract

rsk_usb::worker_abi defines the worker exchange. The gateway checks the whole NS buffer span, and the worker checks the command kind and length before copying it into Secure memory. S parses and authorizes the copied command. It retains no pointer into the caller’s memory.

The worker issues a ticket for the copied job. Channel IDs, CCID sequence numbers and job tickets route traffic. Authorization remains applet state in S. Polling a valid ticket can copy a reply back to NS. The USB gateway separately checks endpoint allocation and the current bus epoch before it arms a physical transfer. S observes EP0 setup packets before the NS USB stack handles them.

USB reset and authorization

The Secure USB controller path observes reset, suspend and loss of configuration. A detected power removal also revokes the session. S checks lifecycle events at the boundaries where it admits or dispatches work and publishes a reply. On revocation it advances the bus epoch, invalidates old transfers and revokes the worker’s transport session. NS cannot mask the physical interrupt or clear the hardware reset latch.

A queued command can be discarded. A synchronous command already in progress can finish and commit changes, but its old reply cannot be published after revocation. Replies already copied to NS remain visible there. Before admitting another command the worker clears the affected transport buffers, PIN/UV tokens, applet authentication and presence state. Resume can restore traffic, but the host must authenticate again. Persistent keys, configuration and retry counters survive a USB reset. CCID card reset has its own narrower scope.

A fatal fault handled in S disconnects USB and clears endpoint buffers before halting. That path uses Secure USB registers directly so it can run even if the fault interrupted the driver.

TrustZone build and boot

scripts/build.sh links S to create the CMSE import library, links NS against that library and its generated memory map, then embeds the NS binary in the final S link. The script compares the two import libraries so the gateway addresses agree. The first link halts at startup because it contains no NS payload. The builder adds the partition table before converting the final ELF to UF2.

nix build .#firmware produces the combined image under result/. The local builder defaults to target/trustzone/combined.elf and combined.uf2. The combined ELF is the input to production signing. Updates to a provisioned key must preserve its flash geometry and KV layout. See Build options for board and feature settings.

TrustZone controls access after boot. Enforced Secure Boot authenticates the image before execution. OTP provisioning supplies the fused storage roots. rsk-wipe is a separate SRAM-resident recovery utility.

Boot sequence

  1. The boot ROM selects the image and verifies it when Secure Boot is enforced. Secure startup copies the scratch code and starts the Secure executor.
  2. Secure boot code initializes the board, reads the chip ID, validates the OTP provisioning state and sets the Non-secure software lock for page 58. It seeds the DRBG from the TRNG and uses it to draw a storage epoch for initialization.
  3. A Secure storage task binds the root-key source and mounts the KV backend. The boot task scans file records and reads EF_PHY to choose the USB identity and interface mask. If storage is unavailable, it selects CCID only for recovery.
  4. Secure code runs the applicable provisioning, seal migration and at-rest scrub passes. Automatic page-58 sealing waits for the remaining pre-OTP records and scrub to clear. Some legacy records need a successful PIN entry before they can migrate. A newly closed latch requests a scrubbed reboot.
  5. S stores the selected USB identity and brings up board I/O and core1. The worker task constructs the applet handlers in their static cells. If a sealing reboot was requested, the worker scrubs and reboots here. Otherwise it prepares the Secure USB front-end.
  6. S installs the TrustZone policy and enters the NS reset vector. NS reads the prepared identity and builds the USB classes. Building the USB device calls the Secure driver to assert the pull-up. NS then starts the tasks that answer the host.

The backend, applet handlers and large transport buffers live in static owners. Boards with at most 2 MiB of flash construct the backend at runtime to keep its zero-filled arrays out of the image. NS exchanges borrow a shared reply buffer and clear it on release.

The firmware rejects entropy draws containing an all-zero 192-bit TRNG block. Boot halts before USB after three failed draws and wipes the failed seed and dead stack. The DRBG attempts a reseed after 64 KiB of output. If the draw fails, it keeps using the checked DRBG state until the worker runs a scrubbed reboot.

Crates

firmware and firmware-ns are the two halves of the authenticator. rsk-wipe builds separately. The applet and supporting crates have host tests. The diagram and its dependency counts are checked against the workspace manifests.

CrateRole
firmwareSecure board startup, USB controller, worker, OTP, storage, presence and RSA core1
firmware-nsUSB descriptors and classes, CTAPHID and CCID framing, OTP HID, keyboard and TIMER1
rsk-wipeSRAM-resident flash erase utility that reboots to BOOTSEL
rsk-deviceApplet composition, dispatch and capability gates, transport sessions, presence arbitration and reboot requests
rsk-sdkAPDU and BER-TLV codecs, applet dispatch, status words, RNG and presence traits
rsk-usbCTAPHID and CCID transport state, USB identity and the shared worker ABI
rsk-fidoCTAP2 and U2F, credential and PIN/UV policy, extensions, attestation and seed management
rsk-openpgpOpenPGP card data, PIN state, key lifecycle, crypto and attestation
rsk-pivPIV slot policies, PIN and management authentication, key and certificate lifecycle and private operations
rsk-oathYKOATH TOTP and HOTP credentials, access codes and touch policy
rsk-otpFour Yubico OTP slots, CCID commands, OTP HID reports and keyboard tickets
rsk-mgmtYubiKey management commands, including reading and writing the device configuration
rsk-rescueRecovery and provisioning commands for board config, flash, attestation, reboot and OTP sealing
rsk-vendorVendor AID commands for LED settings, reboot and diagnostics
rsk-fsFile IDs, metadata, applet storage APIs and record lifecycle over the Storage trait
rsk-storeNOR flash backend, authenticated directory and counter banks, legacy import, fault recovery and compaction
rsk-devconfEF_DEV_CONF codec, application capability masks, config lock and updates
rsk-phyEF_PHY codec and boot policy for USB identity, interface mask and board settings
rsk-ledEF_LED_CONF codec for status LED behavior
rsk-cryptoHashes, MACs, KDFs, symmetric crypto, DRBG and post-quantum primitives
rsk-ecEC and Edwards key formats, public-key derivation, signing and key agreement
rsk-rsaRSA key generation and sealed CRT key layout, blinded and fault-checked private operations, with Rust Montgomery arithmetic shared by the host and device
rsk-mldsaStack-bounded ML-DSA for the three parameter sets
rsk-sha256SHA-256 compression and digest implementation
rsk-sha512Compact SHA-512 and SHA-384 implementations for XIP
rsk-secretSecret and WipeGuard for wiping key material
rsk-x509DER and certificate construction shared by the card applets
rsk-benchCold sample, median and median absolute deviation for on-device benchmarks
rsk-bip39BIP-39 mnemonic encoding for the display’s recovery screen
rsk-slip39SLIP-39 share encoding for the display’s recovery screen
rsk-uiDisplay layout, prompt text and sanitization, retained scenes and rasterization
rsk-displayTrusted-display flows for confirmation, PIN entry and local applet screens over panel and touch traits

Flash layout

The builder generates the memory map from the board’s flash geometry. The default 4 MiB Waveshare RP2350-One layout is below. End addresses are exclusive.

RegionStartEndContents
Secure image region0x100000000x1026F000Secure firmware and boot blocks
NSC0x1026F0000x10270000CMSE gateway veneers
NS image0x102700000x10280000Embedded NS firmware
KVMAIN0x102800000x103E00001408 KiB main payload store
KVCNT0x103E00000x10400000128 KiB for authenticated directories and counter banks

The last 64 KiB of the firmware region holds the NS image, with a 4 KiB NSC window immediately below it. A 16 MiB part reserves its final 4 KiB sector for the RP2350-E10 workaround. The storage regions end below that sector.

The partition table groups KVMAIN and KVCNT into one RS-Key Store partition. The TrustZone builder reads __kvmain_start and __kvcnt_end from the combined ELF. The table grants Secure read and write and denies both to NS and BOOTSEL. The firmware region remains available for an update. With Secure Boot enforced, the signature also covers the table. See Flash snapshot rollback for the limits of this fence.

Files use 16-bit IDs. The applets’ reset paths select the records they own. Shared records have explicit reset rules. The payload ring uses sequential-storage, while the authenticated directories and counter banks use their own journal formats.

Keys and credential IDs

The FIDO seed and enterprise attestation key use ChaCha20-Poly1305 at rest. AES-CBC seed records are a legacy format that the loader can migrate. PIV private keys use AES-256-GCM. OpenPGP private keys use a separate PIN-wrapped data-encryption key. The pre-OTP device root derives from the chip identity. Provisioning the OTP MKEK adds a fused secret to the root derivation for the applicable seals. Boot and PIN-verify paths migrate eligible old records, and the scrub reclaims the superseded copies.

A current non-resident FIDO credential ID is a ChaCha20-Poly1305 box. The relying party stores it. The device seed derives the encryption key and the RP ID hash is associated data. Its format is a 12-byte nonce, encrypted CBOR, a 16-byte Poly1305 tag and a 16-byte silent tag. Current boxes have no cleartext prefix. The loader also accepts the legacy prefixed format. The advertised maxCredentialIdLength of 748 bytes includes that four-byte overhead.

A resident credential returns a separate 42-byte lookup ID. The full box stays on the device. New v4 IDs are derived from the randomized box without the old fixed header, then stored and returned verbatim. Current resident credentials and legacy v2/v3 credentials derive keys from that stable ID, so changing user metadata can reseal the box without changing the credential’s key. Legacy v1 credentials retain their original derivation.

Capacity — why the flash is mostly empty

The standard KV layout totals 1.5 MiB. Larger boards with the standard KV settings use the extra space for the firmware region. The supported 2 MiB layout reduces KVMAIN to 896 KiB. The logical limits are MAX_RESIDENT_CREDENTIALS (256 passkeys), MAX_DYNAMIC_FILES (1280 files across the applets) and OATH_SLOTS (255 OATH credentials). MAX_VALUE_BYTES is 4078 bytes. File size, shared slots and available flash can limit a workload before it reaches an applet’s slot count.

Storage authority and recovery

KVMAIN holds payloads. KVCNT holds two 44 KiB main-directory journals and two 20 KiB counter banks. The authenticated directory binds the live file set and the partition, epoch, generation, length and content of each value. A missing expected payload or a failed authentication returns a storage error. The directory can also authenticate absence.

A main-store mutation reserves space, records an intent, verifies the candidate and publishes the new directory to both journals. On mount, recovery can finish the candidate or retire its reservation before garbage collection. Counter updates publish and verify both copies. The routed PIN retry and HOTP values are bound to their owner’s publication generation. Replacing or deleting the owner invalidates that binding.

A warm read checks the current root and authenticates the requested payload against the mounted authority. Caches hold metadata and authentication tags. Mutation checks fresh fingerprints of physical journals and erased tails before it reuses cached positions. The board’s SHA-256 peripheral can hash public journal bytes, and bulk flash reads use the Secure core0 XIP FIFO. Root-key HMACs run in software. Invalidating a cache hint leaves the live authenticated generation floor in place. A full flash snapshot replay after cold boot remains subject to the rollback limitation.

Boot initializes blank media or imports a readable legacy store. Import verifies its backups before it erases the old counter partition and can resume after interruption. Read faults, damaged authority and malformed legacy layouts take the CCID rescue path. See storage initialization and upgrades for attended recovery.

Device identity

The default USB VID:PID is 0x1209:0xF1D2, with manufacturer RS-Key and product RS-Key Security Key. The optional VIDPID=Yubikey5 preset uses 0x1050:0x0407 for tools that recognize the Yubico reader name. See Build options for identity overrides.

A valid EF_PHY can override VID/PID, manufacturer, product and the interface mask. S resolves the effective identity before NS builds its descriptors. The effective VID also selects the default reader strings and the CCID ATR variant. The USB serial descriptor is rs-key-0001. Chip-derived identifiers used by the applets are separate from that descriptor. FW_VERSION sets the reported applet firmware version. USB bcdDevice is the build counter described in Versions.

User presence

Headless boards use BOOTSEL or a configured PRESENCE_PIN. A display build uses the touchscreen as its presence source. Both go through rsk_sdk::UserPresence, shared by the Secure applets.

request serves a touch policy such as OpenPGP UIF, a PIV slot or an OATH credential. request_ceremony handles host ceremonies such as WebAuthn registration and assertion and the gate before PIN-pad entry. The display shows an operation prompt, with a save action for registration and a hold when the ceremony requires it. A scoped CTAPHID cancel can end the waiting FIDO ceremony without approving it. Idle button clicks can select OTP keyboard slots. A press used for a ceremony is consumed before the idle watcher can count it.

The trusted display can collect PINs in Secure code. This is user verification, separate from approving a request. A host-entered PIN follows the protocol’s own transport path. The no-touch test feature can auto-confirm button requests. See Trusted display for the available flows.

Without a board

tools/emu offers two backends. The applet backend runs the shared applets, dispatch and store on the host, with its own transport and board hooks. The --image backend boots the combined firmware ELF through the RP2350 boot ROM on picoem. It executes the Secure and Non-secure firmware against modeled USB, flash, OTP and other peripherals. A display build can also use the modeled panel and touch controller in the image backend.

Both backends can serve CTAPHID and CCID over TCP or expose a USB device through USB/IP on Linux. See Testing for which cases each backend can exercise.

Provenance

RS-Key reimplements applet behavior and protocol surfaces from pico-keys. The firmware uses Embassy for the runtime and USB stack, RustCrypto and in-tree crypto crates, and minicbor for CBOR. Embedded RSA arithmetic and CMSE entry code also use C and ARM assembly. See NOTICE for upstream components and licenses.

RS-Key host protocol reference

This document specifies the host-facing protocol of the RS-Key firmware: how a configuration/management tool talks to the device, what commands exist, the exact byte layout of each request and response, and what authenticates each one.

It exists so that third-party tooling (e.g. PicoForge) can configure and manage RS-Key devices. The rsk Python CLI is a runnable reference for the management operations it exposes. Firmware source paths accompany the wire formats.

Audience & scope. This is a wire spec, not a tutorial. It documents the commands a host sends and the bytes it gets back. It does not cover the on-device storage format, the crypto internals, or the build system. Those live in architecture.md and the crate sources.

Licensing. RS-Key firmware is AGPL-3.0-only. This protocol description is published as part of the same repository; you are free to implement a client against it under any license. Interop implementations do not inherit AGPL by talking to the device.

Stability. The transports and the standard applets (FIDO2, U2F, PIV, OATH, OTP, OpenPGP, Yubico Management) are stable. They follow public specs. The RS-Key-specific surface (Rescue applet, Vendor/LED applet, CTAP authenticatorVendor 0x41) is versioned by bcdDevice and may grow; new tags/subcommands are added, existing ones are not silently repurposed. Probe the version handshakes (§3, §6.1) and treat unknown tags as skippable.


1. Transports

RS-Key is a USB composite device. Its default interface set is:

TransportCarriesHost API
Keyboard HIDYubico OTP feature reports and typed OTP outputOS HID stack / Yubico OTP libraries
CTAPHID (FIDO HID, usage page 0xF1D0)CTAP1/U2F, CTAP2, and native HID DeviceInfo commandshidapi
CCID (PC/SC smart-card)ISO-7816 applets selected by AID, including CTAP over CCIDpyscard / PC/SC

On the default build, keyboard HID also carries the ykman OTP-HID admin writes (SET_DEVICE_INFO 0x15, DEVICE_CONFIG 0x11, SCAN_MAP 0x12, NDEF 0x08/0x09). SET_DEVICE_INFO shares the DeviceInfo store with CCID WRITE CONFIG (§6). SCAN_MAP remaps typed OTP output. DEVICE_CONFIG and NDEF have no effect on USB operation. An accepted admin write advances the status frame’s program-sequence byte. Under strict-config these slots leave it unchanged, which ykman/yubikit treat as a rejected command.

The interfaces are presented in the stock YubiKey order — keyboard/OTP, FIDO HID, CCID — because some hosts address the OTP interface by index instead of by descriptor: the libusb backend ykpers/ykcore ships (KeePassXC, ykchalresp, pam_yubico) claims interface 0 and sends the OTP frame reports there whatever the descriptors say. An interface switched off in ENABLED_USB_ITF (§7) is omitted and the rest keep that relative order, so a host that assumes a fixed index only holds where the same interface set is enabled.

The OTP frame protocol answers HID feature GET/SET_REPORT on the keyboard interface only. On macOS, access to the keyboard interface can require Input Monitoring. The FIDO interrupt endpoints carry CTAPHID, and their report descriptor declares no feature report.

A slot programmed to require a touch answers its challenge only after a button press, and reports the wait in the status byte (0x20) meanwhile. Two things end that wait early, both matching a YubiKey: the host’s dummy write — a report whose sequence byte is out of range, 0x8f, which also resets the read mode after a response — and any new frame, which supersedes the pending challenge. A host that does neither waits out the touch timeout (§7 PRESENCE_TIMEOUT), during which the transport reports only that it is waiting.

Once announced, 0x20 holds for the rest of the command — the press itself does not clear it, only the response frame or the idle status frame does. ykpers reads a byte carrying neither the pending nor the waiting bit as a touch timeout, so a device that dropped the wait between the press and its answer would lose challenges it had in fact completed.

1.1 CCID APDU framing

CCID ABORT has two phases (CCID 1.1 §4.1). Send an EP0 class request with bmRequestType=21, bRequest=01, wValue=bSlot | bSeq<<8 at the CCID interface, followed by PC_to_RDR_Abort (72) with the matching slot/sequence. Slot 0 is the only slot. Until the matching bulk command arrives, commands fail with CMD_ABORTED (FF); the bulk acknowledgement is RDR_to_PC_SlotStatus (81). An unmatched bulk sequence is refused with field offset 06. An aborted transfer returns a failed DataBlock with bError=FF in place of its APDU reply. Cancellation can end a presence wait. Synchronous work reaches its normal safe point, and committed writes remain in effect.

USB reset, deconfiguration or suspend invalidates pending replies and clears transient applet authorization in Secure before new work is accepted. Persisted keys and the FIDO per-boot PIN mismatch budget survive a bus event. The same event discards partial CTAPHID messages and clears the channel lock. Continuation frames from the old session cannot resume an interrupted message.

CCID accepts ISO-7816 short and extended APDUs. Use 00 A4 04 00 Lc <AID> 00 to select by AID. RS-Key also accepts the P2 = 04 form used by PicoForge. The selected applet then receives CLA INS P1 P2 [Lc <data>] [Le]. There is no ISO master file, so the master-file SELECT (00 A4 00 0C …, GnuPG’s 3F00 probe) answers 6D00 like a YubiKey. The power-on ATR is T=1, its historical bytes labelled YubiKey when the effective USB VID is 1050 and RS-Key otherwise (identical card capabilities). The reference transport is tools/rsk/ccid.py:

def select(conn, aid):
    return transmit(conn, [0x00, 0xA4, 0x04, 0x00, len(aid)] + list(aid) + [0x00])

The class byte is judged before the command, for every applet, GET RESPONSE aside (below). Bit 0x10 marks a command-chaining segment and is looked at first, so 10, 1C, 90 and FF are all ordinary segments. Otherwise only 00, 04, 80 and 84 reach an applet. Every other class gets an empty answer: a data block with no body and no status word, which a client library that expects one raises on (pyscard: Card returned no valid response). Under 04 and 84, the secure-messaging classes, SELECT works as under 00 and any other command to a selected applet is 6E00 — no applet here implements secure messaging, and OpenPGP’s Extended Capabilities says so. With no applet selected, as after a card reset, every command but a SELECT is 6D00 whatever its class, a SELECT by file id or with P2 0C included, and a SELECT of an AID the device lacks is 6A82. All of that is a YubiKey 5.8.0’s, read class by class over raw USB. RS-Key’s own: an unanswered command changes nothing, so an open chain still takes its final segment and a held tail its GET RESPONSE. An XfrBlock of one or three bytes, too short for CLA INS P1 P2, is refused by the reader as a YubiKey 5.8.0 refuses one, measured with the slot powered: a failed RDR_to_PC_SlotStatus, bStatus 40, whose bError 01 names dwLength, and no APDU runs. RS-Key’s own: none and two bytes are refused the same way, and a powered-off slot keeps its ICC status (bStatus 41). An empty block is no response continuation here: RS-Key never chains a response across CCID messages (bChainParameter stays 00). Applets that additionally name a class of their own reject anything else themselves: OATH, management and OTP take 00 and 80 alike, both of which a YubiKey 5.8.0 serves there, U2F wants 00 and rescue 80. A chain can carry at most 3072 bytes of command data. A non-final segment must leave room below that limit. The final segment may fill it exactly. On overflow, the device returns 6700 and drops the chain. Segments must match on (CLA & ~0x10, INS, P1, P2). A mismatch returns 6883 and clears the chain. A SELECT-by-AID discards the old chain before looking up the AID.

A single XfrBlock fits a 3062-byte APDU after the 10-byte CCID header. An extended APDU can therefore carry up to 3055 bytes of data without Le, or 3053 with Le. Use ISO-7816 command chaining for larger inputs within the reassembly limit.

The lengths have to describe the command exactly, short or extended (00, then a two-byte Lc or Le): a byte past the Le, or an Lc its data does not fill, is 6700 before any applet sees the command, as a YubiKey 5.8.0 answers it over raw USB. Two shapes outside ISO 7816-4 are read as that YubiKey reads them: a two-byte body 00 xx is the extended Le 00xx, and an extended Le followed by two more bytes is a case 4 with Lc 0000, those two bytes its Le. RS-Key’s own: the selection, an open chain and a held tail stay as they were.

PIV, OpenPGP and CTAP over CCID answer a success body longer than the request’s Le with ISO-7816 response chaining: the first chunk ships with status 61 XX (XX = further bytes available, 00 = 256+), and the host issues GET RESPONSE (00 C0 00 00 <Le>) until 9000. A short command with no Le (Case 1 or Case 3) is capped at 256; an extended one with no Le is not, and gets the whole body in one frame, as a YubiKey 5.8.0 answers it. One frame carries 3060 bytes of body; a longer one chains from there whatever the Le, where a YubiKey’s PIV cuts the frame and loses its status word. GET RESPONSE is cut by its own encoding the same way. A certificate object over 256 bytes chains when it is read with a short GET DATA, so a host that sends a short GET DATA without an Le must still follow 61xx. A 00 C0 with nothing left to serve is 6A80 on PIV and 6D00 on OpenPGP, OATH, management, OTP and FIDO. While a tail is owed, a GET RESPONSE without the chaining bit serves it whatever its class, since that answer already began in the clear: a YubiKey 5.8.0 does so under 00, 80, 04, 84 and 0C, a class it answers nothing otherwise, and RS-Key under every class. With the chaining bit (10, 90, 1C), owed tail or not, it is a 9000 that opens no chain and leaves any tail for the next one; inside an open chain it is 6883, like any command outside that chain, both as on a YubiKey 5.8.0. With nothing owed, a GET RESPONSE under 04 or 84 is 6E00 to a selected applet and 6D00 with none, like any command but SELECT there, and under a class no applet is reached by it gets the empty answer.

OATH LIST (0xA1) and CALCULATE ALL (0xA4) responses that outgrow the command’s Le chain the YubiKey-OATH way instead: 61 XX followed by SEND REMAINING (00 A5 00 00) rather than GET RESPONSE, matching what ykman / Yubico Authenticator send. A short command with no Le gets 256 bytes a frame and an extended one as much as a CCID frame holds. Frames are cut at the byte, so an entry can straddle two of them: join the frames before parsing. SEND REMAINING never judges its P1-P2, and with no page owed it answers 6D00, as a YubiKey 5.8.0 does.

OATH PUT. PUT (0x01) is strict about the credential body — KEY TLV 16..=66 bytes (a secret shorter than 14 bytes is refused, not padded: zero-pad it first, as ykman does, and the codes do not change), digits 6/7/8, type 0x10/0x20, algorithm 1/2/3, name 1..=64 bytes, the initial moving factor on HOTP only and exactly 4 bytes, the PROPERTY byte as the bare 78 vv pair, the four YKOATH tags in that order, no duplicate, no unknown tag and no trailing byte. Anything else is 6A80 with nothing stored, so a rejected PUT leaves an existing credential of that name working. RS-Key also stores the password-safe fields 0x83/0x84/0x85, up to 255 bytes each, anywhere in the body.

OATH access code. SET CODE (0x03) holds its key to the same measured rule: the 73 TLV is one algorithm byte plus 14..=64 bytes of key material, or empty to remove the access code — anything else is 6A80 and whatever code was installed is left exactly as it was. Its proof travels over an exactly 8-byte 74 challenge (os.urandom(8), as ykman sends it); any other width is 6A80, and removing a code needs no challenge at all. VALIDATE (0xA3) then refuses a proof that does not match with 6A80 as well; 6984 from it means something else entirely — no access code is installed to match against.

OATH only-increasing property. A TOTP credential with PROPERTIES bit 0 computes only for a challenge strictly greater than the highest one it has served, comparing the raw challenge bytes zero-extended on the right — plain numeric > for the usual 8-byte counter. A challenge at or below that mark is 6A80, and in CALCULATE ALL one such credential fails the whole command with an empty body. The one exception is a credential a build before this rule stored: its body can leave no room for the mark, and CALCULATE ALL then reports it with 77 (no response) and computes the rest of the store rather than failing — its own CALCULATE still answers 6A80.

The bulk preflight refuses a flash read fault with 6581 and no response body, before a code can be emitted without its mark. Marks committed before the failing slot remain advanced; the operation is not atomic across credentials.

OATH challenge length. CALCULATE (0xA2) and CALCULATE ALL (0xA4) take an opaque byte string of 0..=64 bytes in the 74 TLV and HMAC all of it; 65 or more is 6A80, judged before the credential is looked up and whatever the credential’s type, so a HOTP account that ignores the challenge refuses an over-wide one too. Both read paths therefore answer the same code for the same challenge at every accepted width — including across a SEND REMAINING page — and the usual 8-byte TOTP counter is simply the common case.

OATH TLV order. CALCULATE, VALIDATE and SET CODE are parsed by position: exactly the documented TLVs, in the documented order, with nothing before, between or after them — 71 then 74 for CALCULATE, 75 then 74 for VALIDATE (the response comes first, as ykman sends it), 73 then 74 then 75 for SET CODE, or a lone 73 00 to remove the code — that spelling and no other, so a SET CODE carrying no body at all is 6A80 and the standing code goes on opening the applet, as on a YubiKey. A reordering, a repeated tag, an unknown tag or a trailing byte is 6A80, with nothing stored. CALCULATE ALL is the one exception the card makes: its 74 must be the first TLV, and whatever follows it is ignored.

OATH truncation. With P2 = 0x01 the 76 TLV is [digits][code(4)], and the four bytes are the RFC 4226 dynamic truncation already reduced to that credential’s digit count — big-endian, so a 6-digit account never exceeds 000F 423F. A host must not reduce a second time expecting a different answer, and VERIFY CODE (0xB1) compares exactly the value CALCULATE sent. The untruncated form (P2 = 0x00, tag 75) is unaffected: it carries the whole HMAC.

OATH parameter bytes. Default to P1 = 00, P2 = 00. The 01 that selects the truncated form belongs to CALCULATE and CALCULATE ALL and to nothing else — on PUT, DELETE, SET CODE, RENAME and LIST it is refused like any other stray byte. RESET alone takes DE AD, and VALIDATE is the card’s own exception: it refuses only when both bytes are non-zero. Anything else is 6B00, judged before the command’s body and before the access-code gate so nothing is written; an instruction the applet does not implement still answers 6D00 first.

1.2 CTAPHID framing

64-byte HID reports. Init frame: CID(4) | CMD(1) | BCNT_HI | BCNT_LO | data[:57]; continuation frames: CID(4) | SEQ(1) | data[:59]. CTAPHID_INIT = 0x86, CTAPHID_CBOR = 0x90, CTAPHID_KEEPALIVE = 0xBB. A CTAP2 message is command_byte | CBOR_payload. A CTAP2 response starts with a one-byte status. Native HID DeviceInfo commands use their own HID command byte (§6.1). Reference implementation in tools/rsk/ctaphid.py.

While a CBOR command runs, the device sends CTAPHID_KEEPALIVE every 100 ms with status 01 (processing) or 02 (waiting for user presence). A zero-length CTAPHID_CANCEL (wire command 0x91) on the active CID gets no separate reply. The original CBOR request returns 2D (CTAP2_ERR_KEEPALIVE_CANCEL) at a safe point. A committed write stays committed.

Take the channel id from the CTAPHID_INIT response and use that one: every INIT on the broadcast CID allocates a fresh id, so an id hardcoded or cached across sessions will not be yours. CTAPHID_LOCK is honoured for the 1–10 seconds it asks for, though no INIT capability bit says so: CTAP defines none for it, and 0x02 — a pre-standard U2FHID header’s LOCK bit — stays clear, as on a YubiKey 5.8.0. Meanwhile every other channel gets ERR_CHANNEL_BUSY — including one sending CTAPHID_INIT to resynchronise itself. The exception is an INIT on the broadcast CID, which still gets through: a client arriving mid-lock is given an id, then turned away on it.

1.3 CCID secure PIN entry (pinpad) — display builds only

A trusted-display build advertises bPINSupport = 0x01 (VERIFY) in its CCID class descriptor (body byte 50 / full descriptor byte 52), so a host driver treats it as a pinpad reader and sends PC_to_RDR_Secure (0x69) instead of a plaintext VERIFY; the PIN is then typed on the device’s own screen. A standard (no-screen) build leaves bPINSupport = 0x00 and rejects 0x69. No control transfer is involved. The host CCID driver reads bPINSupport straight from the descriptor; the device only has to handle 0x69. The validated trigger is GnuPG’s internal CCID driver (keys solely off bPINSupport); PC/SC + libccid and macOS CryptoTokenKit also expose pinpad from the descriptor, but their FEATURE_VERIFY_PIN_DIRECT coverage varies, so treat the GnuPG-internal path as the reliable one.

The host must use pinpad mode to keep the PIN off the wire. A normal XfrBlock VERIFY (00 20 P1 P2 Lc <PIN>) still carries a plaintext PIN.

Whatever the host driver, the bytes on the wire follow the CCID structure below, not the PC/SC v2 Part 10 IOCTL structure (the driver drops that structure’s bTimeOut2 and ulDataLength when it builds the 0x69), so the VERIFY template is always at abData offset 15. The 0x69 payload is the CCID abPINDataStructure for VERIFY:

bPINOperation(1)=0x00 verify | bTimeOut(1) | bmFormatString(1) | bmPINBlockString(1) |
bmPINLengthFormat(1) | wPINMaxExtraDigit(2 LE) | bEntryValidationCondition(1) |
bNumberMessage(1) | wLangId(2 LE) | bMsgIndex(1) | bTeoPrologue(3) |
abPINApdu = CLA INS=0x20 P1 P2 …   (the VERIFY template, at offset 15)

Select an enabled OpenPGP or PIV applet first. The display asks “Allow host PIN entry?” before opening the PIN pad. The device reads the template’s P2 (OpenPGP 0x81/0x82/0x83 = PW1-sign / PW1-other / PW3-admin; PIV 0x80 = application PIN), collects the PIN on the pad, builds the real VERIFY APDU (00 20 P1 P2 Lc <ASCII PIN>; PIV pads with 0xFF to 8 bytes), runs it through the selected applet, and replies with a normal RDR_to_PC_DataBlock (0x80) carrying only the status word:

  • success → 90 00, bStatus = 0, bError = 0.
  • wrong PIN → the card’s real answer: PIV’s 63 Cx (tries left, reported saturated at x = F so a larger configured retry total cannot wrap into 63 C0 = blocked), OpenPGP’s 69 82 as a YubiKey 5.8.0 answers (its tries are on an empty VERIFY) / 69 83 (blocked), bStatus = 0, bError = 0 (the command succeeded; the card said wrong).
  • user cancel → bStatus = 0x40 (failed), bError = 0xEF → SCARD_W_CANCELLED_BY_USER.
  • initial approval declined or timed out → bStatus = 0x40, bError = 0xEF.
  • pad timeout → bStatus = 0x40, bError = 0xF0 → SCARD_E_TIMEOUT.
  • unsupported pinpad request or no eligible applet selected → bStatus = 0x40, bError = 0x00.

The transport sends CCID time extensions while the device waits on the screen. The device ignores the host’s PIN format and offset bits when assembling VERIFY. With GnuPG’s internal CCID driver, run gpg-connect-agent "scd checkpin OPENPGP.1" /bye. The parser and VERIFY assembly are in crates/rsk-usb/src/secure_pin.rs.


2. Status words & error codes

2.1 CCID status words (ISO-7816 SW1 SW2)

Source: crates/rsk-sdk/src/sw.rs.

SWNameMeaning
9000OKsuccess
63C0—WRITE CONFIG (§6) with a configuration lock code that is not the one set, as a YubiKey 5.8.0 answers it
6400EXEC_ERRORexecution error (internal)
6285TERMINATEDOpenPGP after TERMINATE DF: every command, SELECT included, until ACTIVATE FILE (§5.1)
6581MEMORY_FAILUREa storage failure, including Rescue READ phy or a DeviceInfo merge. Storage recovery also uses this status for unavailable Rescue operations (§7). OpenPGP uses it for undecipherable RSA ciphertext, an unusable ECDH peer point, oversized RSA signing input, reading an empty key slot, or importing correctly sized RSA primes that fail key construction
6700WRONG_LENGTHbad Lc/Le for this command
6883LAST_CHAIN_EXPECTEDan APDU arrived that neither continues nor closes the open command chain
6982SECURITY_STATUS_NOT_SATISFIEDauth/precondition missing
6983PIN_BLOCKEDPIN verification is blocked
6984DATA_INVALIDmalformed payload (e.g. bad guard magic)
6985CONDITIONS_NOT_SATISFIEDstate precondition unmet (e.g. RTC unset); a WRITE CONFIG setting a configuration lock where none is set without its touch (§6.2); OpenPGP PSO:CDS, the RSA and ECDH arms of PSO:DECIPHER and INTERNAL AUTHENTICATE with no key in the slot, and ATTEST of an empty slot or an imported key, as a YubiKey 5.8.0 answers them
6986COMMAND_NOT_ALLOWEDWRITE CONFIG (§6) with no lock code while a configuration lock is set, as a YubiKey 5.8.0 answers it; a phy (§7) or LED (§8) write while one is set
6A80WRONG_DATAbad data field; PIV MOVE KEY onto a slot that holds a key or takes none, or onto itself; PIV PUT DATA with a P1-P2 other than 3FFF; OpenPGP GENERATE and IMPORT with a control-reference template they cannot read or whose key reference 84 01 xx names another slot, and GENERATE P1 = 80 and IMPORT under Yubico’s attestation-key template B6 { 84 01 81 }; OpenPGP ATTEST with a P1-P2 or a body it does not take; OpenPGP SELECT DATA with any body but 60 04 5C 02 7F 21
6A82FILE_NOT_FOUNDthe requested AID or file is unavailable
6A84FILE_FULLthe applet’s storage limit is exhausted
6A86INCORRECT_P1P2unsupported P1/P2
6A88REFERENCE_NOT_FOUNDthe object, key or PIN the request names is absent (PIV GET METADATA, MOVE KEY, the PIN commands’ key reference)
6B00WRONG_P1P2P1/P2 outside what this command takes — including a DO that P1P2 addresses and the command does not serve (OpenPGP GET DATA, PUT DATA), and an OpenPGP SELECT DATA occurrence past the third or P2 other than 04, judged before its body
6D00INS_NOT_SUPPORTEDunknown INS for this applet; OpenPGP and PIV answer it to any SELECT but the one by AID, as a YubiKey 5.8.0 does
6E00CLA_NOT_SUPPORTEDwrong CLA for this applet (OpenPGP ATTEST takes class 80 only)

2.2 CTAP2 errors

Standard CTAP2 status bytes (0x00 = success), returned by CTAP2 and by the 0x41 vendor command. Source: crates/rsk-fido/src/error.rs. The ones the vendor surface returns:

ByteNameMeaning here
0x00OKsuccess
0x02INVALID_PARAMETERinvalid field or public key, unknown vendor subcommand, or invalid encrypted key for UNLOCK/ATT_IMPORT
0x03INVALID_LENGTHa request exceeds a command’s input limit (for example, the DeviceInfo config blob)
0x12INVALID_CBORthe body is not exactly one CBOR item (trailing bytes)
0x14MISSING_PARAMETERrequired field absent (e.g. blob/pinUvAuthParam)
0x27OPERATION_DENIEDpresence declined or timed out, wrong config lock code on a DeviceInfo write, or CBOR disabled by USB_ENABLED
0x2DKEEPALIVE_CANCELthe host cancelled the active CTAPHID CBOR request
0x2FUSER_ACTION_TIMEOUTon-device PIN entry timed out, or a CCID FIDO poll/cancel found no pending operation
0x30NOT_ALLOWEDprecondition unmet (a CONFIG_WRITE of EF_DEV_CONF with no lock code, or of the phy or LED record, while a lock is set (§6.2), no MSE channel, one already spent or owned by another CTAPHID channel, an MSE while one is live (§9.1), sealed, soft-locked, or an authenticatorReset outside the §5.1 power-up window)
0x31 / 0x32PIN_INVALID / PIN_BLOCKEDwrong PIN or exhausted retries
0x33PIN_AUTH_INVALIDpinUvAuthParam MAC or acfg permission wrong
0x36PUAT_REQUIREDthe request requires a PIN token or on-device PIN entry (§9.2)
0x39REQUEST_TOO_LARGEsubCommandParams over the limit
0x3DINTEGRITY_FAILUREblob failed authenticated decryption
0x3EINVALID_SUBCOMMANDunknown vendorCommandId under authenticatorConfig’s 0xFF. A 0x41 subcommand this build does not implement is 0x02, matching a YubiKey
0x7FOTHERinternal failure, for example an unreadable CONFIG_READ record

3. Device identity & discovery

3.1 USB identity

The build picks a VID/PID preset (firmware/build.rs):

PresetVID:PIDManufacturer / Product stringsNotes
RSKey (default)1209:F1D2RS-Key / RS-Key Security Keypid.codes allocation
Yubikey5 (opt-in interop)1050:0407Yubico / YubiKey RSK OTP+FIDO+CCIDso ykman/Yubico Authenticator derive PID from the PC/SC reader name
othersNitroHSM, NitroFIDO2, GnuPG, Pico, Dev—local interop only

The VID/PID, the product string and the manufacturer string can all be overridden at runtime via the phy record (§7), taking effect at the next boot: VID/PID (tag 0x00), product (tag 0x09) and manufacturer (tag 0x0F). If a runtime product looks like a YubiKey (yubikey, any case) but omits the smartcard CCID token, the firmware appends OTP+FIDO+CCID before enumerating — a token-less Yubico YubiKey reader name otherwise crashes ykman / Yubico Authenticator on Windows (_pid_from_name → PID.of → KeyError('YK4_'), which aborts the whole PC/SC scan). Source: normalize_usb_product in crates/rsk-phy/src/lib.rs.

Each string is resolved in precedence order: an explicit phy tag (0x0F / 0x09) wins; otherwise the effective VID picks a default — a Yubico VID (0x1050) yields Yubico / YubiKey RSK OTP+FIDO+CCID plus the Yubico OpenPGP AID vendor, so setting only the Yubico VID/PID makes the whole identity “just work” for ykman / Yubico Authenticator; otherwise the build const. The OpenPGP AID vendor id stays keyed on the effective VID (a registered number, not a free string). ⚠️ so a phy-repointed default key can present a full Yubico identity at runtime; the USB/smartcard identity is cosmetic and host-configurable, never a security or anti-counterfeiting control (see docs/threat-model.md).

For PC/SC discovery, rsk looks for RS-Key, RSK or the appended USB serial (rs-key-0001) in reader names. Linux pcscd may use the driver’s friendly name in place of the USB product string. Probe the applet you need on a candidate reader. See RSK_READER_TOKENS in tools/rsk/ccid.py.

3.2 Firmware version & bcdDevice

FieldValueWhere
firmwareVersion5.8.0 → 0x00050800CTAP getInfo 0x0E; Management/OTP DeviceInfo TAG_VERSION; Management SELECT ("Virtual mgr - FW version 5.8.0" ASCII, a YubiKey 5.8.0’s words)
bcdDeviceFirmware build counterUSB device descriptor (firmware/src/main.rs device_release)
AAGUID2479c7bf-6b30-5683-9ec8-0e8171a918b7CTAP getInfo 0x03; one value across every VID/PID flavor of a build, overridable at build time with AAGUID=<uuid>

The build accepts FW_VERSION=X, X.Y or X.Y.Z. The default is 5.8.0 for compatibility with Yubico tooling. Read bcdDevice from the USB descriptor when checking for an RS-Key protocol change.


4. AID registry

SELECT an applet with 00 A4 04 00 Lc <AID> 00.

How an AID is matched (RS-Key 0x088C+): ISO 7816-4 truncated select — the AID you send must be a prefix of a registered one, and the first applet it matches wins. So a shortened AID selects (PIV answers to A0 00 00 03 08), an AID with anything appended does not (earlier builds selected on registered AID ‖ junk, which let PIV answer to A0 00 00 03 08 00 00 00 00 — the AID SP 800-85A-4 C.1.1.2 names as invalid), and an empty AID is refused rather than treated as “select the default application”. Two consequences worth planning for: OpenPGP is selected by the 6-byte AID below, not by the 16-byte value it reports in DO 4F (that one carries the device serial and is longer, so it is not a prefix — a real YubiKey refuses it too); and a prefix short enough to match several applets resolves in dispatch order among selectable applets (Vendor, OpenPGP, Management, OATH, OTP, PIV, Rescue, FIDO). Use the full AID when probing for an applet. OATH and OTP are registered by their full 8-byte instance AIDs, as a YubiKey registers them: Yubico’s Android SDK selects by all 8 bytes, while ykman sends the 7-byte prefix, and both select (0x09D4+; from 0x088C to 0x09D3 only the 7-byte form did).

Where that SELECT works. The recipe above is CCID’s (§1.1), and two of the ten rows below are not CCID applets: the FIDO2 backup id and the standalone U2F AID answer 6A82 (FILE_NOT_FOUND) — registered identifiers rather than anything this build dispatches to. The FIDO2 AID is selectable over CCID and carries CTAP2 and U2F there (§5.3). Over HID, send CTAP2 directly in CTAPHID_CBOR and U2F in CTAPHID_MSG. Only the Vendor AID can be selected in CTAPHID_MSG. Use a fresh CTAPHID_INIT before switching that channel back to U2F. An INIT or a change of CID clears the MSG applet selection.

AppletAIDTransportSpec statusConfig-relevant?
FIDO2 / U2FA0 00 00 06 47 2F 00 01CCID (§5.3) + CTAPHID (no SELECT)Standard (CTAP2 + CTAP1)identity only
FIDO2 (backup id)B0 00 00 06 47 2F 00 01none — unregisteredRS-Key—
U2F (standalone id)A0 00 00 05 27 10 02none — unregistered; U2F rides the FIDO2 AIDStandard (CTAP1/U2F)—
ManagementA0 00 00 05 27 47 11 17CCIDYubico-compatibleyes — §6
OATHA0 00 00 05 27 21 01 01CCIDYubico OATHdata only
OTPA0 00 00 05 27 20 01 01CCIDYubico OTPdata only
PIVA0 00 00 03 08 00 00 10 00 01 00CCIDNIST SP 800-73data only
OpenPGPD2 76 00 01 24 01CCIDOpenPGP card 3.xdata only
RescueA0 58 3F C1 9B 7E 4F 21CCIDRS-Key-specificyes — §7
Vendor / LEDF0 00 00 00 01CCID + CTAPHID_MSGRS-Key-specificyes — §8

Sources: crates/rsk-fido/src/consts.rs, crates/rsk-mgmt (+ crates/rsk-devconf for the DeviceInfo record), crates/rsk-oath, crates/rsk-otp, crates/rsk-piv, crates/rsk-openpgp/src/consts.rs, crates/rsk-rescue, firmware/src/vendor.rs. Which AID each transport actually offers is not in any of those: it is the applet list crates/rsk-device/src/ccid.rs builds for CCID and the one-entry list in crates/rsk-device/src/ctap.rs for CTAPHID_MSG.


5. Standard interfaces (pointers, not re-specified)

For the base command formats, see the CTAP specification, Yubico OATH protocol and PIV card command specification.

Resident FIDO discovery returns at most 16 distinct credentials per getAssertion/getNextAssertion walk, newest first. Equal creation times use descending storage-slot order. With more than 16 visible matches, the queue retains the newest 16; the first reply is the first entry in that same queue.

RS-Key implements:

  • FIDO2 / CTAP2 (versions advertises FIDO_2_0, FIDO_2_1 and FIDO_2_3): getInfo, makeCredential, getAssertion, getNextAssertion, clientPIN, reset, selection, credentialManagement, authenticatorConfig, largeBlobs (writable without a pinUvAuthParam until a PIN is set or alwaysUv is on, per §6.10.2 — a --features largeblob-ext build serves the CTAP 2.3 §12.4 largeBlob extension in its place and answers 0x0C with CTAP1_ERR_INVALID_COMMAND, because §12.4 forbids supporting both; detect it from getInfo, which drops largeBlobs, maxSerializedLargeBlobArray and the largeBlobKey extension in that build). options.perCredMgmtRO is true, so a tool may request the pcmr permission (0x40, alone) and get the persistent pinUvAuthToken: it drives getCredsMetadata / enumerateRPs / enumerateCredentials, never the two writers, and survives replugs until a PIN change or a reset — a credential list can be refreshed without re-prompting for the PIN. The enumerate walk it opens is not that durable: the cursor behind getNextRP / getNextCredential retires after 30 s idle, and after any command that is not one of those two continuations (CTAP 2.3 §6), so draw a list in one uninterrupted pass and restart from the Begin if it stalls. The same 30 s applies between the fragments of a largeBlobs set; there an abandoned transfer answers CTAP2_ERR_INVALID_SEQ and the previously stored array is left intact. maxMsgSize = 7609. Both transportsForReset (0x1A) and transports (0x09) are ["usb", "smart-card"]. These lists describe the supported protocol transports (§5.3). Interface configuration and host driver binding determine whether the smart-card interface is reachable. pinComplexityPolicy (0x1B) reports the effective PIN complexity policy. strong-pin and fips-profile enable it by default; other builds start with false. An authenticated setMinPINLength request can enable it with subCommandParams key 4: true. A false or absent key leaves it unchanged; only authenticatorReset restores the build default. The policy rejects periodic PINs, ascending/descending runs, at most two distinct code points, and the keypad-pattern denylist, on both host and trusted-display PIN changes. Under forcePINChange, an unread current verifier returns CTAP2_ERR_OTHER (0x7F) and leaves the change pending; it cannot establish a different PIN. The optional pinComplexityPolicyURL (0x1C) is never emitted. longTouchForReset (0x18) is false: a reset takes the same touch as any other presence check — CTAP 2.3 cut the long-touch hold from 2.2’s 10 s to 5 s, and RS-Key implements neither gesture. encIdentifier (0x19) is present from provisioning — boot, authenticatorReset and a seed BACKUP_LOAD mint the persistent pinUvAuthToken it is keyed by; setting or changing the PIN, or forcing a change, revokes that grant until the next boot or pcmr request, and a soft-locked key omits it — and carries iv ‖ AES-128-CBC(k, id) — 32 bytes — where id is a 128-bit device identifier and k = HKDF-SHA-256(salt = 32 zero bytes, IKM = that token, info = "encIdentifier", L = 16). The IV is regenerated on every getInfo, so the bytes differ each time while the identifier under them does not: a tool holding the token recognises the device across sessions, and one without it learns nothing. The identifier is derived from the device seed, so authenticatorReset changes it. encCredStoreState (0x1E) is that same construction under the label encCredStoreState, over a 128-bit tag that takes a new random value whenever the set of discoverable credentials changes — a create, a deleteCredential, an updateUserInformation, or a delete driven from the trusted display. Reads never move it. A platform holding the token caches the plaintext and re-enumerates only when it differs; one without the token sees bytes that change every call and learns nothing. The tag is stored, not counted in RAM, so a power cycle does not reset it — and it is written ahead of the change it describes, so what a torn write leaves is a tag that over-reports (one wasted re-enumeration) rather than one that under-reports (a stale cache). A tag the flash cannot serve omits the member rather than publishing the zero one: zero is what a device an older build provisioned carries until its first change, so a platform can be holding it, while an absent member matches no cached tag at all and costs only the walk. A new store starts with a new tag, as unpredictable as its seed — provisioning and authenticatorReset derive it from the new seed, a BACKUP_LOAD draws one — so a reset changes it even over a store nothing had changed (CTAP 2.3 §6.6). makeCredential accepts attestationFormatsPreference (request 0x0B): a list of exactly ["none"] is answered with fmt:"none" and an empty — but present — attStmt, and nothing is signed. Any other list, an empty one, or an absent field leaves the usual packed statement, because choosing by lowest supported index needs more than one supported format and attestationFormats (0x16) stays ["packed"]. An enterprise attestation that was actually performed outranks the preference and is still returned in full. None is performed over an org key whose stored chain is missing or does not read back whole (RS-Key 0x0A6A+): the device’s own certificate attests, without ep, and the preference holds. Vendor-facilitated (type 1) enterprise attestation reads a stored RP list. enterpriseAttestation: 1 returns ep and the org certificate only for an RP on that list; any other RP gets the ordinary packed statement with the device’s own certificate and no ep. The list holds up to 8 sha256(rpId) entries and is empty until written, so a device upgraded from firmware without it behaves exactly as before; authenticatorReset clears it. Write it with authenticatorConfig (0x0D) subCommand vendorPrototype (0xFF) and subCommandParams {1: 0x0e6841934e719be7, 4: [rpId…]} — the ids as text, hashed on the device — gated by an acfg pinUvAuthToken and no touch, the same authorization enableEnterpriseAttestation itself takes. An empty array clears the list; more than 8 entries is refused with CTAP2_ERR_KEY_STORE_FULL, never truncated. Type 2 (platform-managed) is unaffected — it applies to any RP once enterprise attestation is enabled. Supported COSE algorithms: ES256 -7, ES384 -35, ES512 -36, ES256K -47, EdDSA -8, ML-DSA-44 -48, ML-DSA-65 -49, ML-DSA-87 -50 (all three negotiable via pubKeyCredParams; advertised in getInfo only under the advertise-pqc build, in descending security order). ML-DSA-87’s 2592-byte public key and 4627-byte signature are the widest the device mints, and the org attestation chain cap (ATT_CHAIN_MAX) is derived so the worst-case makeCredential still fits the 7609-byte maxMsgSize. The curve-explicit ids ESP256 -9, Ed25519 -19, ESP384 -51 and ESP512 -52 are negotiable and unadvertised on the same terms, and the attested key carries the id the request selected rather than the classic spelling of the same curve. (crates/rsk-fido/src/consts.rs.)
  • CTAP1 / U2F 1.1/1.2.
  • PIV: NIST SP 800-73 (Yubico PIV extensions for metadata). GET DATA answers 6A82 to a tag list it cannot read and to a P1-P2 other than 3FFF, the answer for an object the card does not hold, as a YubiKey 5.8.0 does. Key replacement and MOVE retire the prior per-slot public-point cache before committing a key; failed cache retirement answers 6581. Missing or refused cache refreshes fall back to the current metadata point or that key’s scalar. SELECT compares F9’s stored certificate point and public cache with its sealed P-384 key. It repairs absent, empty, truncated or preceding-key certificates under that key and retires stale caches from older builds. Recreating an absent F9 key removes its preceding certificate before committing the replacement; a failed read, retirement or repair answers 6581. An existing F9 key that the current root cannot open, or that names another curve, also makes SELECT answer 6581, preserving the key. A later boot retries unfinished root migration. Selection remains current after refusal, so subsequent raw APDUs still reach PIV’s command handlers and their gates. PUT DATA answers 6982 without the management key, then 6A80 to a P1-P2 other than 3FFF and to a body that is not 5C 03 <id> followed directly by 53 with its length in the shortest form; bytes after the object are ignored. It stores any 5Fxxxx but 5FFF01 (the attestation certificate, which no host may write), as a YubiKey does: 5FC100–5FC1EF and 5FFF00 each in its own file, every other id in a pool of 256 objects and 32 KiB of bodies, whose next write answers 6A84 once either is spent, as a full YubiKey does; an empty 53 deletes the object, answering 9000 for one not held. An object is up to 3063 bytes, 6700 past it, as on a YubiKey 5.8.0: the 3072 bytes a command chain reassembles less the 5C 03 id 53 82 LL LL header. With an extended Le, a single APDU has room for 3044 object bytes. Without Le it has room for 3046. GET DATA for the CHUID (5FC102) returns a synthesized default (non-federal FASC-N + a device-stable GUID = sha256(serial)[..16]) when the host has not written one, so the Windows minidriver can enumerate the card; a host-written CHUID overrides it. The Card Capability Container (5FC107, mandatory per SP 800-73-4 pt1 §3.1.1) is served on the same terms: with no host-written object the card answers a 9-byte synthesized default (F0 00 F1 00 F2 00 F5 01 10 — zero-length mandatory elements plus the PIV data model number 0x10) instead of 6A82, a host PUT DATA overrides it, and an empty PUT DATA falls back to the default again.
  • OATH: Yubico OATH (TOTP/HOTP).
  • OTP: Yubico OTP / HOTP keyboard + CCID.
  • OpenPGP card 3.x. An unreadable variable GET DATA child or password-status record makes the complete response fail with 6581 and no body. PUT DATA C1/C2/C3 changes a slot’s algorithm attribute; when the value changes, RS-Key invalidates that slot’s existing private/public key pair before the new attribute becomes visible. An idempotent same-value write preserves the pair. RSA attributes carry a 17-bit exponent length, as a YubiKey’s do: DO 0xFA lists 01 nnnn 0011 00, PUT DATA takes any length from 17 bits and stores 17, and two attributes that differ only there are the same value. Yubico’s attestation is there too: ATTEST (80 FB <key ref> 00, PW1 in mode 81, the touch D9 sets; past the touch it spends a one-shot PW1 as PSO:CDS does) writes an X.509 statement for a key the card generated into its 7F21 occurrence, signed by a P-384 attestation key (reference 81) whose self-signed certificate is DO FC. The key reads through GENERATE P1 = 81 under B6 { 84 01 81 } and is listed in DE, DA (inside 73 and in FA), C5/C6/CD and D9, where a YubiKey lists its own; no host can import it, generate it or write FC. So is Yubico’s SET PIN RETRIES (00 F2 00 00 03 <PW1> <RC> <PW3>, what ykman openpgp access set-retries sends), as a YubiKey 5.8.0 answers it: 6982 without PW3, then 6A80 for a body that is not three bytes, P1 and P2 not judged. A byte from 1 to 255 becomes that PIN’s maximum and its tries left, unblocking it with its value kept; 0 leaves the PIN as it is. The resetting code’s maximum is kept while none is set (C4 shows 00 for it), and PUT DATA D3 starts a new one there. The PINs and PW3’s status stay, the maxima survive a power cycle, and TERMINATE DF + ACTIVATE FILE put back 3, 3, 3.

The management extensions are in §6 (DeviceInfo), §7 (Rescue), §8 (Vendor/LED) and §9 (CTAP 0x41).

5.1 Where a standard command answers differently

Places where a host that works against other authenticators sees a status byte it may not expect. All are spec-permitted strictness, not extensions, and each says where it matches the YubiKey this project is measured against.

authenticatorReset has a power-up window. CTAP 2.1 §6.6 lets an authenticator with no display refuse a reset that does not follow a fresh power-up. RS-Key does: more than 10 s after the device attached, command 0x07 answers 0x30 CTAP2_ERR_NOT_ALLOWED before the touch prompt, so a host waiting on a press gets an immediate refusal instead. Four properties a host implementation has to plan for:

  • The origin is the USB attach, not power-on. Boot spends seconds before the bus pull-up goes up (TRNG seeding, seal migrations, the one-shot at-rest hardening lap), and none of it is time a host could have used.
  • A warm reset closes the window, it does not reopen one. The vendor REBOOT (§8 INS 1F P1=0), its rescue twin, and the auto-reboot after a phy CONFIG_WRITE are all host-requestable without a credential, so a window a host can restart at will would be no window at all. Only a real power cycle opens one.
  • Trusted-display builds are exempt. Their prompt names the operation on screen, which is what the window substitutes for; a reset is accepted at any time there and still needs the on-screen confirmation.
  • The touch is unchanged. Inside the window the reset still requires user presence, and a decline or timeout answers 0x27 OPERATION_DENIED.

Practically: prompt the user to replug, then send the reset. rsk offboard does exactly that — it sends the reset, and only on 0x30 prints the unplug/replug prompt and retries in the new window (tools/rsk/offboard.py), so it stays correct against a display build and against pre-0x0854 firmware, which both accept the first attempt.

PIV refuses a one-byte command body, whatever the instruction. A PIV APDU carrying Lc = 1 answers 6A80 before anything else — before the PIN or the management key, before P1/P2, and before the instruction is looked up, so even an unimplemented INS answers 6A80 rather than 6D00. No PIV command takes a one-byte body, and a YubiKey 5.7.4 does the same on every instruction. The rule is PIV-only: OATH’s LIST takes a legitimate Lc = 1, and SELECT-by-AID with a one-byte AID prefix is served by the transport before any applet sees it.

U2F AUTHENTICATE rejects a reserved P1. U2F Raw Message Formats §7.2 assigns three control bytes; RS-Key accepts exactly those and answers 6A86 (INCORRECT_P1P2) to anything else, before parsing the request body.

P1NameBehaviour
03enforce-user-presence-and-signtouch required; TUP flag set in the response
07check-onlyvalid handle → 6985, unknown handle → 6A80; never touches
08don’t-enforce-user-presence-and-signsigns with no touch, TUP flag clear; rejected with 6A86 under --features strict-up, which promises a touch on every assertion

U2F over CTAPHID_MSG takes the extended encoding alone. U2F HID v1.2 §2 frames every raw message in extended-length encoding, and a U2F request over CTAPHID is read as a YubiKey 5.8.0 reads it: the class first (6E00 past 00), then either the bare four-byte header or 00 Lc Lc and at least that many data bytes, with anything after them, an Le included, ignored. A short Lc or Le is 6700 whatever the instruction. Over CCID (§5.3) both encodings stay open, as there. On either transport a VERSION that carries data is 6700, since U2F Raw Message Formats §6.1 has it take none; its P1 and P2 are not judged, as on a YubiKey.

OpenPGP GET DATA reads a nested DO only through its template. OpenPGP 3.4 §4.4.1 lists 5B, 5F2D and 5F35 only inside 65, 93 only inside 7A, and 73 — with the C0–C3, C5, C6 and CD it carries — only inside 6E; the fixed-width C7–D0 are readable only as the slices of C5/C6/CD. Each of those 21 answers 6B00 to a GET DATA of its own, and PUT DATA still takes the writable ones. A YubiKey 5.8.0 answers the same, with keys and a name set. The Gnuk-derived suite in third_party/openpgp-card-tests reads them one by one; a host written that way has to read the template instead.

GET DATA answers 6581 with no response body if its construction buffer cannot hold the complete object. A constructed template keeps BER’s shortest length form; fixed-width fingerprint and timestamp fields still truncate older long records and pad short records with zeroes. The 7A security-support template requires its three-byte DS-Counter (93); an absent, unreadable or wrong-width counter answers 6581 with no body.

OpenPGP TERMINATE DF leaves the applet terminated until ACTIVATE FILE. As on a YubiKey 5.8.0, TERMINATE DF (00 E6 00 00, PW3 verified or blocked, 6982 otherwise) wipes the applet and then every command answers 6285, SELECT included, until ACTIVATE FILE (00 44 00 00) answers 9000 and leaves the factory state: C4 = 01 7F 7F 7F 03 00 03, PW1 123456, PW3 12345678. The state survives a reset and a power cycle; a PW1 or PW3 verified before TERMINATE is still verified after ACTIVATE, now against the factory password. ACTIVATE FILE on an applet that is not terminated answers 9000 and changes nothing. RS-Key 0x0A83+; an older build answered TERMINATE with the factory state at once, and a host that sends ACTIVATE right after it, as ykman and gpg-card do, works with both.


5.2 FIDO extension outputs and PIN policy

The uvm extension accepts a boolean on makeCredential and getAssertion. When requested with true, signed authData reports the ceremony factors as [method, keyProtection, matcherProtection] entries: presence (0x0001), external PIN (0x0800), device-local PIN (0x0004), or no interaction (0x0200). Key and matcher protection are 0x0002 (hardware) and 0x0004 (on-chip). getNextAssertion carries the originating ceremony’s methods. A false input produces no output.

The pinComplexityPolicy extension takes a boolean on makeCredential and returns the effective policy only to an RP on the minPinLengthRPIDs list; unlisted RPs receive no output. It has no getAssertion output. Both extensions reject an input of the wrong type. An omitted or empty minPinLengthRPIDs config parameter preserves the existing list; a non-empty list replaces it.

The persisted EF_MINPINLEN layout remains [minimum: u8, flags: u8, rpIdHash…]. Flag bit 0 means forceChangePin; bit 1 enables complexity. Older records with flags 0 or 1 load unchanged, and clearing forceChangePin preserves bit 1 and all RP hashes. Older firmware interprets any nonzero flags byte as a pending PIN change, so downgrading a key with complexity enabled keeps authentication blocked until reset. The upgrade itself requires no migration or reset.

5.3 CTAP over CCID

The FIDO applet answers on the CCID interface as well as on CTAPHID, as ISO 7816 APDUs — the encoding CTAP 2.1 §11.2.1 defines for ISO7816 readers, which python-fido2’s CtapPcscDevice (and therefore ykman over PC/SC) speaks unchanged. PC/SC does not distinguish an NFC reader from the device’s own CCID interface, so this is reachable over plain USB.

StepAPDUAnswer
Select00 A4 04 00 08 A0000006472F0001 009000 with body U2F_V2, or FIDO_2_0 while alwaysUv has U2F off (below)
CTAP280 10 00 00 Lc <cmd ‖ CBOR> 009000 (or 61xx, below) with <status ‖ CBOR>
U2F00 01/02/03 …the CTAP1 answer; 6E00 under class 80; 6986 while alwaysUv has U2F off
Poll, cancel80 11 00 00, 80 11 11 009000 with body 2F, whatever the P1-P2. Use CCID ABORT to cancel in-flight work
Control80 12 01 009000, then 6986 to every command until the next Select; any other P1-P2 6A86

The three CTAP2 instructions (10, 11, 12) are taken under class 00 as under 80, as on a YubiKey 5.8.0. Anything else under 80 is 6D00, under 00 it is U2F’s, under 04 and 84 it is refused 6E00, and no other class reaches it (above).

alwaysUv switches U2F off on both transports (CTAP 2.1 §7.2.4) unless a built-in UV method is configured, the display build’s pad with a PIN: REGISTER, AUTHENTICATE and VERSION answer 6986 over CCID and CTAPHID alike, getInfo drops U2F_V2, and the Select above answers FIDO_2_0, the version string CTAP 2.3 §11.3.3 gives an authenticator with CTAP2 alone. A YubiKey 5.8.0 answers each of these the same.

Control’s END ends the FIDO session on this interface (CTAP 2.3 §11.3.4). CTAP2 and U2F alike answer 6986 until the next Select, by the AID or a prefix of it. A chain’s segments are still acknowledged, and CTAPHID is not affected. A YubiKey 5.8.0 answers each of these the same.

Chaining runs in both directions. Send a CTAP2 command longer than 255 bytes in an extended APDU or in CLA|0x10 segments. A response longer than the short Le ships its first chunk with 61xx and the rest through GET RESPONSE (00 C0 00 00 <Le>). A bare getInfo is already ~520 bytes, so a client that does not follow 61xx sees nothing useful. An extended-length APDU with no Le, or Le 0000, gets up to 3060 bytes in one exchange, and a longer response chains from there.

No 91 00 keep-alive is ever returned. A touch wait blocks inside the exchange while the CCID transport streams T=1 time extensions, exactly as an OATH touch-flagged CALCULATE and an OpenPGP UIF signature already do, so the NFCCTAP_GETRESPONSE poll loop never runs. The poll and cancel APDUs both return 2F 90 00. To abort the in-flight CCID exchange, use the two-phase CCID ABORT (§1.1).

The transport is smaller than CTAPHID. A command chain reassembles 3072 bytes and a response is built in as many, so that is the ceiling on a command and on a response here, against the 7609 that getInfo’s maxMsgSize reports for CTAPHID. Commands stay well inside it; a response that does not fit comes back as a CTAP error rather than truncated. An ML-DSA credential’s attestation does not fit and is CTAPHID-only in practice.

CCID and HID share FIDO state, but CCID uses reserved CID 00000000. Keep CID-bound operations such as MSE and its consumer on the same transport.

Both applications are gated separately. One AID serves CTAP2 and U2F, and ykman config usb --disable fido2 / --disable u2f name them apart, so the commands are gated rather than the SELECT: disabling one leaves the AID selectable for the other and answers the disabled half 6986 — for CTAP2 its MSG, since a poll or a control carries nothing to gate. With neither enabled the AID is gone (6A82).

Some CCID drivers bind only to recognized VID/PID pairs. If such a driver omits the default 1209:F1D2, use the repository’s ccid-rs-key overlay or a VIDPID=Yubikey5 build.

6. Management applet (Yubico-compatible) — applet enable/disable

AID A0 00 00 05 27 47 11 17. CLA 00 or 80. This is what ykman / Yubico Authenticator SELECT first to identify the key and to read/write which applications are enabled. Source: crates/rsk-mgmt/src/lib.rs for the command surface, crates/rsk-devconf/src/lib.rs for the EF_DEV_CONF record it reads and writes.

SELECT returns the firmware version in a YubiKey 5.8.0’s ASCII words, "Virtual mgr - FW version 5.8.0"; take the version from its last word.

INSNameRequestResponse
1DREAD CONFIG—DeviceInfo TLV (see below)
1CWRITE CONFIGdata[0] = inner length n, then n bytes of enabled-apps TLV (n ≤ 128)— (gated by the configuration lock once a code is set, §6.2; presence-gated as well under strict-config)
1E—anything9000 with no body, and nothing is done — as a YubiKey 5.8.0 answers it

6.1 DeviceInfo TLV (READ CONFIG 0x1D)

Response = one leading overall-length byte, then concatenated TAG LEN VALUE:

TagNameLenValue
01USB_SUPPORTED2capability bitmask (BE16) of applications the firmware implements
02SERIAL48-digit serial (chip-id[0..4], MSB masked & 0x03)
04FORM_FACTOR101 = USB-A keychain
05VERSION3major, minor, patch (default 05 08 00)
03USB_ENABLED2currently-enabled capability bitmask (BE16)
08DEVICE_FLAGS180 = touch-eject, 40 = remote wakeup; 00 unless a host set them
0ACONFIG_LOCK100 = unlocked, 01 = a lock code is set (§6.2)

Native FIDO HID READ CONFIG uses command 0x42 (wire byte 0xC2) with an empty request. Its reply is the same length-prefixed DeviceInfo blob, without a CTAP status byte. Native WRITE CONFIG uses 0x43 (wire byte 0xC3) with the same length-prefixed body as the write APDU. Success is an empty reply. A refused or unsupported write returns CTAPHID_ERROR with ERR_INVALID_CMD. The native write is unavailable under strict-config. Neither native command uses the CTAP CBOR vendor envelope (§9). The corresponding OTP feature-report slots are READ CONFIG 0x13 and SET_DEVICE_INFO 0x15.

When no host config has been written, the device returns the defaults: USB_ENABLED = all-supported, DEVICE_FLAGS = 00, CONFIG_LOCK = 00. Once WRITE CONFIG has stored a blob, READ CONFIG echoes that blob after the fixed USB_SUPPORTED/SERIAL/FORM_FACTOR/VERSION prefix, adds DEVICE_FLAGS = 00 after it when the blob carries none (a YubiKey 5.8.0 reports the tag in every DeviceInfo; the stored blob itself is not changed), then always appends CONFIG_LOCK.

A stored blob is echoed only if it still satisfies the WRITE CONFIG rules — each tag at most once, USB_ENABLED exactly two bytes. One that does not (a record an older, laxer build accepted) is not echoed verbatim; the response instead carries a synthesised USB_ENABLED equal to the mask the device actually enforces. So READ CONFIG is always parseable and never contradicts enforcement, whatever is in flash (audit run-34 #25). The config-lock tags (0A set-code, 0B unlock) are write-only: a code is never stored in EF_DEV_CONF or echoed (audit run-30), and 0A on read is the 1-byte lock state (§6.2). A code a build before 0.4.5 stored in the record is dropped at boot and never honoured as a lock.

6.2 Configuration lock

ykman config set-lock-code locks the configuration as it does a YubiKey 5.8.0. While a code is set, every write of EF_DEV_CONF — CCID WRITE CONFIG, OTP-HID SET_DEVICE_INFO 0x15, CTAPHID 0x43 and the FIDO vendor CONFIG_WRITE target 0 (§9) — lands only if it carries that code in 0B (UNLOCK). Without one it is refused (6986; 0x30 over CONFIG_WRITE), with another code likewise (63C0; 0x27), and nothing is stored either way, even for a write that would change nothing. OTP-HID refuses by leaving the program-sequence byte where it was, and CTAPHID 0x43 answers CTAPHID_ERROR. There is no retry counter, as there is none on a YubiKey.

  • Set: 0A with a 16-byte code, on an unlocked device or with the current code in 0B. Clear: 0A of 16 zero bytes, with the current code (ykman’s --clear). A code of any other width, in either tag, is refused as malformed (6A80; 0x02 over CONFIG_WRITE).
  • Who can set one: a host that can reach one of the four writers, on a device with no code yet, and only with a touch of the key, which a YubiKey does not ask for: a code its owner does not hold would keep every config change behind a factory wipe (threat-model.md §1). Declined or timed out, the write is refused whole (6985, 0x27 over CONFIG_WRITE, or the native HID refusal described above). Changing or clearing a code still requires the current code. It needs no extra confirmation beyond the write’s usual gate.
  • At rest: EF_DEV_LOCK (0x1124) holds 01 ‖ SHA-256("RS-Key/CONFIG-LOCK" ‖ serial ‖ code), the serial being DeviceInfo’s four bytes; absent is unlocked. A record in any other form reads locked and opens for no code.
  • Scope: it survives authenticatorReset, like EF_DEV_CONF. The display build’s factory reset or an rsk-wipe erase clears it, which is how a lost code is recovered. It gates the RS-Key phy and LED records (§7, §8) as well, which have no YubiKey counterpart, and no code opens them: while a code is set, every host write of either (rescue 1C/01, vendor SET LED 10, CONFIG_WRITE targets 1 and 2 over either transport, the authenticatorConfig phy ids) is refused as a DeviceInfo write without its code is (6986; 0x30 over CTAP), a replay included, and changes nothing. Clear the lock to change them. The trusted display’s own settings (the touch timeout, for one) are not a host write and stay open.

Capability bits (USB_SUPPORTED / USB_ENABLED):

BitApplication
0x0001OTP
0x0002U2F
0x0008OpenPGP
0x0010PIV
0x0020OATH
0x0200FIDO2

USB_SUPPORTED is fixed at 0x023B (all six). To enable/disable applications, WRITE CONFIG a TAG_USB_ENABLED(03) TLV with the desired mask, e.g. enable only FIDO2+U2F → inner blob 03 02 02 02, full APDU 00 1C 00 00 05 04 03 02 02 02.

USB_ENABLED is enforced, not merely reported: a cleared bit makes that application’s applet stop answering. PIV/OpenPGP/OATH/OTP return 6A82 on CCID SELECT. Disabling FIDO2 makes CTAPHID_CBOR return 27, including authenticatorVendor. Disabling U2F makes CTAPHID_MSG return 6985, including attempts to select the Vendor AID. The OTP keyboard stops typing OTPs. The change takes effect on the next command. Bits outside USB_SUPPORTED are ignored.

To re-enable an application, use CCID Management. On a default build, you can also use a native DeviceInfo write on an available HID interface. The configuration lock still applies. On a strict-config build with CCID omitted, keep the FIDO2 capability enabled so the CTAP config path stays reachable. Restoring an omitted USB interface requires a PHY update and reboot (§7.1).

WRITE CONFIG validates the inner blob (6A80 otherwise): it must be well-formed TLV, carry only tags a host may write (03, 06, 07, 08, 0A, 0B, 0C, 0E, 17 — ykman’s DeviceConfig set), and fit the smallest transport’s response buffer. The device-owned identity tags (01 supported, 02 serial, 04 form factor, 05 version) are emitted by the card and refused on write: READ CONFIG echoes the stored blob after them, and host parsers take the last occurrence, so a stored duplicate would override the real identity and a malformed one would make the whole DeviceInfo unparseable — permanently, since this record survives authenticatorReset. On the default build the write is ungated until a lock code is set (§6.2) — full ykman parity: any USB host can rewrite the reported config, matching a stock YubiKey with no config-lock code. Building --features strict-config restores an on-device user-presence confirmation (Approve on the trusted-display build, a BOOTSEL press otherwise), so a hostile host cannot rewrite it unattended (declined/timed-out → 6985). Either way the identity is cosmetic, never an authenticity signal (see docs/threat-model.md §1/§3).

There is no device-wide reset here. 1F, ykman’s device_reset (sent only when DeviceInfo reports a blocked reset or a Bio with PIV), is 6D00, as on a YubiKey 5.8.0; 1E is acknowledged and does nothing. Both were a presence-gated factory reset before 0x0A01, and the rescue and vendor applets’ own 1E/1F, sent while Management was selected, reached it. The trusted display’s menu keeps a factory reset, and each applet its own. A host written for pico-fido, whose Management 1E resets FIDO, gets 9000 here with nothing erased: reset FIDO with CTAP authenticatorReset instead.


7. Rescue applet (RS-Key configuration conduit)

AID A0 58 3F C1 9B 7E 4F 21. CLA 80 for every INS below (SELECT itself is the standard 00 A4 …). This applet carries the phy device-config record (USB identity + LED hardware), RTC, flash/secure-boot status, the device attestation key, and the one-way OTP fuses. Source: crates/rsk-rescue/src/lib.rs.

SELECT response (identity): MCU(1) | PRODUCT(1) | SDK_MAJOR(1) | SDK_MINOR(1) | serial(8) = 01 02 08 06 <8-byte chip serial>. (MCU 1 = RP2350, PRODUCT 2 = FIDO, SDK 8.6 is the applet SDK version, distinct from the 5.8.0 firmware version.) Use this to identify a Rescue applet. A successful SELECT does not imply that every selector is supported. Probe read-only selectors individually.

INSP1P2Request dataResponsePurpose
10010032-byte SHA-256 digest64-byte secp256k1 signatureKEYDEV: sign a digest with the device attestation key
100200—65-byte uncompressed pubkey (04 ‖ X ‖ Y)KEYDEV: read the device attestation pubkey
100300X.509 DER cert—KEYDEV: store the device end-entity cert
1C0100phy TLV blob (§7.1)—WRITE phy record. 6986 while a configuration lock is set (§6.2), before asking for presence. 6400 if the merge or write fails
1C0201YYYY(BE2) Mon Day Wday Hour Min Sec (8 B)—SET RTC (civil). January is month 0. Wday is ignored
1C0202epoch seconds (BE4)—SET RTC (Unix)
1E0100—phy TLV blob (§7.1)READ phy record; 6581 if the record cannot be read (never the never-written default — the host RMWs on this answer)
1E0200—free ‖ used ‖ kv_total ‖ nfiles ‖ flash_size (5×BE4 = 20 B)READ flash usage
1E0300—enabled(1) ‖ locked(1) ‖ bootkey_slot(1) (FF = none)READ secure-boot status; locked requires one trusted key, all other slots revoked, both debug disables, complete hardening and page-1/2 BL/NS lock copies
1E0401—YYYY(BE2) Mon Day Wday Hour Min Sec (8 B)READ RTC (civil). January is month 0, Sunday is weekday 0. 6985 if unset
1E0402—epoch seconds (BE4)READ RTC (Unix); 6985 if unset
1E0600—required(1) ‖ version(1) ‖ capacity(1)READ anti-rollback state
1E0700—left(2) BE16This boot’s outstanding seal work. Bits 0001 FIDO seed/attestation key/grant, 0002 device key, 0004 PIV, 0008 OATH (including legacy OTP PIN), 0010 OTP, 0020 storage authority. FFFF means no fused key was provisioned. FFFE means the fused key was unreadable and the seal pass did not run
1E0900—version(1) ‖ status(1) ‖ left(2) BE16Read-only automatic page-58 seal result; version 01, status values below
1B5800"LOCK58"—⚠️ IRREVERSIBLE legacy service command — attempt 3D3D3D into page-58 lock row 0xFF5, over a blank row or a subset of the latch. ROM refuses completion once the Secure read-only majority is set (6400). 9000 with nothing burnt when the full latch is there; 6985 over foreign bits, unfinished migration (1E/07 != 0000), or declined presence. From the next boot on no device-sealed record opens under the pre-burn key or in the clear
1B4800"ROLLBK"—⚠️ IRREVERSIBLE — set ROLLBACK_REQUIRED fuse (user-presence-gated)
1F0000——REBOOT (warm; device drops off bus)
1F0100——REBOOT to BOOTSEL bootloader
1E0800—format(1) ‖ ready(1)Storage state: 02 01 means active v2 authority; 02 00 means recovery required
200000"INITV2"—Initialize wholly erased storage; physical confirmation required, occupied/active media refused; success queues a warm restart
200100"IMPORTV2"—Explicitly trust and import readable legacy records; physical confirmation required; success queues a warm restart

For 1E/06, version is the fused minimum epoch. capacity counts the 48 OTP rollback bits. The highest epoch accepted by the signing workflow is 47. The ROM can set ROLLBACK_REQUIRED when installing a versioned signed image. Rescue 1B/48 only sets that flag and checks that Secure Boot is enabled. It does not inspect the running image’s rollback metadata. An already-set flag returns 9000 without another burn or touch. Follow the production sequence for image signing and provisioning.

Storage recovery mode exposes CCID with the Rescue AID only. It permits READ selectors 03, 04, 06, 07, 08, 09, reboot and storage setup. Normal boot automatically initializes wholly blank media or migrates readable legacy storage; neither setup command nor physical confirmation is required for a firmware upgrade. Other rescue operations answer 6581; other applets cannot be selected. Normal FIDO/U2F, OTP and management dispatch stay closed. Setup returns 6985 for declined confirmation or incompatible state, 6581 for a storage failure, 6A86 for invalid selectors and 6A80 for a wrong magic payload. READ 1E/07 includes bit 0020 while storage authority remains under the pre-OTP root. Storage setup performs no OTP operation.

The firmware automatically completes page-58 sealing at boot, including devices previously fused without locking. Secure code validates keys/chaff, waits for left=0000 and performs a fresh successful flash scrub. It first completes and reads back every 0x3C3C3C access-lock bit, preserving any existing latch bits, then burns 0x3D3D3D. This ordering keeps the first step resumable and prevents a torn latch from stranding an unfinished BOOTSEL/Non-secure access lock. A newly closed latch causes a scrubbed restart before command dispatch; TrustZone has not started Non-secure code yet. No APDU or physical touch is required for this boot step. Explicit 1B/58 keeps its existing presence and migration guards for compatibility; READ 1E/09 performs no writes and needs no presence.

1E/09 status: 00 unchecked, 01 unprovisioned, 02 sealed, 03 migration pending, 04 scrub incomplete, 05 incomplete/invalid provisioning, 06 OTP read failure, 07 foreign lock bits, 08 lock write/readback failure, 09 fake-key firmware (real sealing disabled), 0A majority already seals access but the raw latch has incomplete redundancy. For 0A, ROM refuses further writes because Secure is already read-only; boot keeps the migration arms closed and does not retry the burn. 0B means Secure writes closed before the access lock was complete: ROM cannot repair it, root reads and migration are blocked, and storage stays in recovery. left has the 1E/07 meaning. Status is this boot’s result: after a required PIN use, restart to retry migration and sealing. Only 02 confirms a complete latch; unknown versions/statuses must not be interpreted as sealed.

Build 0x0BA8 extends v2 with private, owner-bound PIN/HOTP counter records; APDUs and the 02 01 state response are unchanged. Migration occurs on the first counter update. Earlier builds report recovery and refuse normal applets on this store. Reinstalling a compatible build resumes it; storage initialization is not an upgrade or downgrade procedure.

Every P1 this applet implements is in that table. A P1 outside it answers 6A86 (RS-Key 0x088E+; earlier builds answered 9000 to an unimplemented 1C selector without writing anything, so a newer client could not tell a too-old firmware from a completed write). Use that, and the SELECT handshake above, to detect a firmware that predates a selector you send.

⚠️ Irreversible operations — handle with explicit confirmation

1B/58 ("LOCK58") permanently locks OTP page-58; 1B/48 ("ROLLBK") permanently sets the anti-rollback-required fuse. Both are one-way fuse burns that cannot be undone and can brick a device if misapplied. The firmware triple-guards each (exact P1, exact magic payload, and a provisioning precondition; for 1B/58 also a boot that left nothing under the pre-burn key, as 1E/07 reports), both are idempotent, and the firmware now also requires an on-device user-presence confirmation before the burn (the magic payload is a source-visible constant, not authentication). A config tool must still put these behind an explicit, clearly-worded user confirmation: never a default action, never a bulk “apply”. Most management tools should not expose them at all. 1F/01 (BOOTSEL) drops the device into the bootloader for reflashing; also confirm.

In BOOTSEL, the KV store is fenced off

Since bcdDevice 0x0871 the image carries an RP2350 partition table: the bootloader is denied read and write over the KV store, so picotool save, load and erase across that range answer permission failure. A tool that offers “back up / restore the device’s flash” must expect that and must not present the failure as a device fault. Whole-image flashing is unaffected — the firmware partition stays bootloader-writable. Rationale, and why this is not a substitute for secure boot: threat-model.md.

User-presence gate (runtime)

The runtime-reachable privileged commands require an on-device user-presence confirmation (a button touch, or an Approve on the trusted-display build) before the firmware acts, and return 6985 (CONDITIONS_NOT_SATISFIED) if the operator declines or the wait times out. This gates 10/01 (attestation sign), 10/03 (store cert), 1C/01 (WRITE phy record), the irreversible OTP fuse burns 1B/58 and 1B/48, and 1F/01 (reboot to BOOTSEL) against a hostile USB host. Read-only status (1E/*), the pubkey read (10/02), SET RTC (1C/02) and a warm reboot (1F/00) stay ungated.

The Management applet’s WRITE CONFIG (§6, INS 1C) is gated the same way only under strict-config; the default build ungates it (§6). The rescue phy WRITE (1C/01), OTP-fuse burns and BOOTSEL reboot above stay gated in both builds — they are not part of the ykman admin-write flip.

The vendor applet (§8) exposes the same reboot verb, reachable over both the CCID and CTAPHID transports; its 1F/01 (BOOTSEL) is gated identically, so the gate cannot be bypassed via the vendor AID. Its warm reboot (1F/00) is ungated. Its test-counter write (01) is gated in every build — see §8.

7.1 The phy record (EF_PHY) — PicoForge-compatible

The phy record is the device-config TLV blob. It is the same format PicoForge already writes, so an existing PicoForge config path largely works as-is. Source: crates/rsk-phy/src/lib.rs.

Wire format: a flat sequence of TAG(1) LEN(1) VALUE(LEN) records, any order, all optional. An unknown tag is skipped; a record whose length runs past the buffer ends the parse. The firmware applies the record at boot (USB identity + LED hardware).

A write (Rescue 1C/01, or CTAP vendor CONFIG_WRITE 0x0C target 1, §9) is a read-modify-write merge: only the tags the blob carries are updated; every untouched tag keeps its stored value. So a host may send just the fields it changed without wiping the rest. The meaning of zero depends on the tag. To clear either USB string, send a length of 01 with one NUL byte as the value. A zero-length string TLV is ignored.

TagNameLenValue
00VIDPID4VID(BE2) ‖ PID(BE2)
04LED_GPIO1data-pin GPIO 0..=29
05LED_BRIGHTNESS1global channel max 0..=255
06OPTS2flags (BE16): WCID 0x1, DIMM 0x2, DISABLE_POWER_RESET 0x4, LED_STEADY 0x8
08PRESENCE_TIMEOUT1touch-wait timeout in seconds, bounding the whole ceremony on a button build — the press wait and the release debounce that follows a confirm share it; a trusted-display ceremony may add up to 3 s absorbing a resting finger (0/absent ⇒ firmware default 30 s; a non-zero value below 10 is raised to 10). Matches PicoForge PresenceTimeout.
09USB_PRODUCT1..33up to 32 string bytes. A NUL ends the string and counts toward the TLV length. A 33-byte value with no NUL leaves the stored string unchanged. 09 01 00 clears the override
0AENABLED_CURVES4FIDO curve bitmask (BE32)
0BENABLED_USB_ITF1interface mask: CCID 0x1, WCID 0x2, HID 0x4, KB 0x8, LWIP 0x10
0CLED_DRIVER11 = gpio, 2 = pimoroni, 3 = ws2812 (follows PicoForge LedDriverType)
0DLED_ORDER1WS2812 wire order: 0 = rgb, 1 = grb
0ELED_NUM1RS-Key extension — addressable LEDs actually connected (1..=255; 0/absent = the build’s MAX_LEDS). Firmware saturates a value above its compiled MAX_LEDS ceiling.
0FUSB_MANUFACTURER1..33iManufacturer string with the same encoding as USB_PRODUCT. 0F 01 00 clears the override and restores the default described in §3.1

Notes for a host implementation:

  • Read-modify-write. READ the record, change only your tags, WRITE it back. This is exactly what rsk hw does (tools/rsk/hw.py). Preserving tags you don’t recognize costs you nothing, but note the device does not: merge_save overlays your blob onto the parsed record and re-serializes only the tags this firmware knows, so a tag it does not recognize is dropped at the first write whatever the host sends.
  • PicoForge recognizes ENABLED_USB_ITF, LED_ORDER, LED_NUM and USB_MANUFACTURER in its RS-Key config path.
  • PRESENCE_TIMEOUT has a floor. The record is host-writable and the touch wait reads it live, so a one-second window could expire in the middle of a press and let the next queued request inherit that same hold. The firmware raises any non-zero value below 10 seconds. The floor is applied at boot, on the way to the wait. The stored record keeps the value as written, so a read-modify-write round-trip is lossless; CONFIG_READ’s effective map (§9) reports the floored value, because that is the window the device actually waits.
  • ENABLED_USB_ITF defaults to all interfaces. The firmware instantiates CCID, FIDO HID and keyboard HID. WCID and LWIP have reserved mask bits. A mask without either CCID or FIDO HID falls back to the default at boot, including a keyboard-only mask. An unreadable PHY record gives CCID and FIDO HID only, unless storage recovery restricts the device to CCID.
  • A never-written record reads back as the single zero-OPTS TLV 06 02 00 00.

8. Vendor / LED applet — per-status LED color & effects

AID F0 00 00 00 01. CLA 00. Live LED customization (color/brightness/effect per device status), persisted in flash and applied immediately. Source: crates/rsk-vendor/src/lib.rs, firmware/src/led.rs. Reference client: tools/rsk/led.py.

INSP1P2RequestResponsePurpose
01———counter (BE4)INCREMENT test counter, return new value. User-presence-gated (6985 if declined)
02———counter (BE4)GET test counter
10brightness 0..255color | steady | status<<4[effect[, speed]] opt.—SET LED for one status; 6986, before any touch, while a configuration lock is set (§6.2)
110000—17-byte config blockGET LED config
1F00/0100——REBOOT (warm / BOOTSEL). 01 is user-presence-gated (6985 if declined; see §7)

INS 12 (CORE1_STATS), INS 13 (KEYGEN_BENCH), INS 14 (BENCH) and INS 15 (STACK_RESIDUE, the dead-stack probe tests/55_stack_residue.py drives) exist only in the measurement builds that ask for them (--features core1-stats / keygen-bench / bench, which carries the last two); a shipped image answers 6D00, and none is part of the stable surface.

SET LED 0x10 requires presence under strict-config. A decline or timeout returns 6982. The configuration lock applies in all builds.

SET LED 0x10 is idempotent. A request whose resulting 17-byte block already matches the stored EF_LED_CONF answers 9000 without a flash write. The LED config is still applied live. The next write upgrades a stored 13-, 9-, 3- or 2-byte block to the current layout.

INCREMENT 0x01 always goes through the presence gate. The diagnostic no-touch build confirms automatically. A CTAPHID caller sees KEEPALIVE(UPNEEDED) while the device waits for confirmation. GET 0x02 requires no presence.

Touch-status normalization. The awaiting-touch indicator is the only consent signal on a build without the trusted display, so the EF_LED_CONF codec — not any one command handler — normalizes it on every decode: the vendor SET LED, the FIDO CONFIG_WRITE LED target (§9), and the boot reload of the stored record alike. Four rules, in that order:

  • color 0 (off) on the touch status becomes the default touch colour (yellow).
  • its brightness is raised to 8.
  • a non-zero speed is raised to 2 (speed 1 makes the breathing effect render an all-black frame every tick while the brightness byte still reads compliant).
  • the touch colour is the touch status’s alone. Any other status configured in that colour is reset to its own factory look — whatever its effect, brightness or speed. Uniqueness deliberately keys on colour rather than on the whole (effect, color, brightness, speed) quad: brightness and speed are continuous bytes, so a one-unit nudge is byte-unequal and eye-identical; steady mode renders a solid frame for every effect; and on a one-LED board bounce and flow both collapse to the same solid frame, so the effect byte carries no signal there.

The give-way case. If the status wearing the touch colour has that colour as its factory colour, resetting it would not resolve the clash, so the touch status reverts to its factory look (bounce / yellow) instead. Only boot (red) and idle/processing (green) can trigger this. A red touch status therefore sticks only while boot is not red, and a green one only while neither idle nor processing is green. Yellow is nobody else’s factory colour, which is what makes the fallback converge: enforcing twice is enforcing once.

What this does not guarantee. Two statuses in different colours can still be hard to tell apart. The gpio backend has no hue at all — the indicator is lit or unlit; red, green and yellow are mutually confusable under red-green colour blindness; and on a one-LED board the effect adds nothing. What separates the states there is the per-status blink timing (touch 1000/100 ms vs idle 500/500 ms), which is compile-time fixed and cannot be reconfigured — but the global steady toggle suppresses blinking altogether, and on a single-colour backend that leaves nothing at all to tell the states apart. A build with the trusted display remains the strong answer for consent signalling.

SET LED 0x10 persists the normalized block. GET LED 0x11 returns the live configuration for all statuses. The FIDO CONFIG_WRITE LED target (§9) stores the supplied 17-byte block before normalization. Use CONFIG_READ to retrieve the stored bytes.

SET LED 0x10 P2 layout: bits [2:0] = color, bit 3 (0x08) = steady (solid, no blink, a global toggle), bits [5:4] = status. P1 = per-channel brightness. The command data field is optional: data[0] sets the status’s effect, data[1] its speed (0 = the effect’s built-in default). They are independent: send no data to leave both unchanged, one byte to set only the effect (the current speed is kept), two bytes to set both.

GET LED 0x11 response (config_block, 17 bytes): steady(1) | (effect, color, brightness, speed) × 4 for statuses idle, processing, touch, boot in that order. (block[0] = steady; status s → effect block[1+4s], color block[2+4s], brightness block[3+4s], speed block[4+4s].) Read the response length: older firmware returns a 13-byte (effect, color, brightness) or 9-byte (color, brightness) block. The stride is (len − 1) / 4.

ColorCodeStatusCode
off0idle0
red1processing1
green2touch2
blue3boot3
yellow4
magenta5
cyan6
white7

Effects (the effect byte, ws2812 backend only; gpio/pimoroni always use the classic on/off blink). legacy reproduces the original blink; the rest animate across the connected LEDs and reduce gracefully on a single LED:

EffectCodeEffectCode
legacy (classic blink)0flow3
vapor (breathing)1sparkle4
bounce2

Example. Set the idle status to solid blue at brightness 0x20: P2 = color 3 | steady 0x08 | status 0<<4 = 0x0B, APDU 00 10 20 0B. Example. Set touch to yellow bounce at brightness 0x10, speed 0x0F: P2 = color 4 | status 2<<4 = 0x24, data = effect 2 ‖ speed 0x0F, APDU 00 10 10 24 02 02 0F.


9. CTAP authenticatorVendor (0x41) — seed backup, attestation, audit

A CTAP2 vendor command with command byte 0x41 followed by a CBOR map. Send it inside CTAPHID_CBOR or over CTAP on CCID (§5.3). It can export the device master seed. Source: crates/rsk-fido/src/vendor.rs, constants in crates/rsk-fido/src/consts.rs.

Request map: {1: subcommand(uint), 2: subCommandParams(map), 3: pinUvAuthProtocol(uint), 4: pinUvAuthParam(bstr)}. Encode key 1 before key 2 so the parser knows how to read the parameters. Omit key 2 for a command without parameters. Keys 3 and 4 carry the host PIN token authentication when the gate requires it (§9.2).

SubNameParams (key 2)ResponseGate
01MSE{1: COSE_Key, 2: mlkem_ek?}{1: COSE_Key, 2: ct?}none (establishes channel)
02BACKUP_EXPORT—{1: blob(60)}MSE + presence + PIN gate. Refused if sealed or on a fips-profile build
03BACKUP_LOAD{1: blob(60)}—MSE + presence + PIN gate. Refused while soft-locked. Without a host PIN, also asks “Replace device seed?”. A new seed makes credentials sealed to the old seed unreadable
04BACKUP_FINALIZE——Presence + PIN gate. No MSE
05BACKUP_STATE—{1: sealed, 2: has_seed, 3: locked, 4: unlocked, 5: rescrub_refused}ungated
06UNLOCK{1: blob(60)}—MSE (the lock key is the auth)
07AUDIT_READ—Journal window (§9.3)PIN gate. Also requires presence if no host PIN is set
08AUDIT_CHECKPOINT{1: nonce(bstr, 0–32 bytes)}Signed checkpoint (§9.3)PIN gate + presence. Requires a provisioned DEVK
09ATT_IMPORT{1: blob(60), 2: chain(bstr)}—MSE + presence + PIN gate. The DER certificates are concatenated, leaf first. Without a host PIN, also asks “Replace this identity?”
0AATT_CLEAR——MSE + presence + PIN gate. Without a host PIN, also asks “Erase this identity?”
0BATT_STATE—{1: present, 2: sha256(packed_chain)?}Ungated. Key 2 hashes the device’s packed record. It can be absent even when 1 is true if the chain is missing, unreadable or oversized
0CCONFIG_WRITE{1: target(uint), 2: blob(bstr)} — target 0=DEV_CONF, 1=PHY, 2=LED—The configuration lock applies to all targets (§6.2). strict-config also requires presence and the PIN gate. No MSE
0DCONFIG_READ{1: target(uint)} — target 1=PHY, 2=LEDPHY {1: blob(bstr), 2: {phy_tag: uint}}, LED {1: blob(bstr)}Ungated. An absent record gives an empty blob. A read failure returns 7F
0EAUDIT_CONFIG{1: op(uint)} — 0=disable, 1=enable, 2=status{1: enabled(bool)}Setting requires PIN gate + presence. Status (2) is ungated
0FCONFIG_COMMANDS—{1: [vendorCommandId(uint), …]}Ungated. Lists the authenticatorConfig vendorPrototype (0xFF) IDs this build serves (§11). Older builds before bcdDevice 0x0A80 answer 0x02

After MSE, an invalid BACKUP_LOAD blob length returns 14, and an invalid authentication tag returns 3D. UNLOCK and ATT_IMPORT return 02 for an invalid encrypted key blob.

ATT_IMPORT accepts up to four concatenated DER certificates. To compare the ATT_STATE digest with a known chain, hash the packed form count(1) ‖ (length(2 LE) ‖ certificate DER)*.

rescrub_refused (BACKUP_STATE key 5, bcdDevice ≥ 0x09C5)

Flash health for this power cycle, and nothing more. After the one-shot at-rest hardening lap has run, any command that supersedes a record still sealed to the pre-OTP root must re-arm that lap by clearing its marker. The wipe paths — authenticatorReset and the applet factory resets — take that re-arm best-effort and go on regardless, because refusing there would mean leaving the secrets live, and they answer 0x00 whatever the flash said. Key 5 is true when a re-arm this power cycle could not be shown to have landed, so a stuck medium is reported somewhere other than in the answer to a reset that did succeed.

It does not say the hardening marker is wrong, or that hardening failed. Away from the wipe paths the re-arm gates the write that follows it, so a refusal stops that write: nothing is superseded, and the command either errors or skips a lazy migration and leaves the older record in force. Read key 5 as “this device’s flash refused a write it was asked for”, and nothing stronger.

Coverage is lost in one arm only, a wipe whose refusal was persistent. A wipe tries more than once — ahead of its sweep and again after it — and a refusal the retry recovers still sets key 5 even though the marker is then gone and the next boot laps as it should. When no attempt lands, the marker stays latched over the records the wipe superseded, no later boot ever laps, and those copies stay recoverable from a physical flash dump while the reset answered 0x00. Key 5 does not say which arm it is, and repeating the reset does not recover what that one already exposed, so a device that keeps reporting it has a failing medium and should be retired rather than trusted at rest. It is RAM state, so it clears on the next power cycle whether or not the flash recovered, and an older build simply omits the key.

Device configuration over FIDO (CONFIG_WRITE 0x0C)

The pcscd-free twin of the CCID device-config writes (§6 WRITE CONFIG and the §7/§8 phy/LED records): a host that cannot reach the CCID interface writes the same config over CTAPHID. target selects the record: 0x00 = the management enabled-apps TLV (EF_DEV_CONF, the §6 blob, ≤ 128 bytes → the same CTAP1_ERR_INVALID_LENGTH 0x03 cap, under the §6.2 lock); 0x01 = the phy record (EF_PHY, §7.1: VID/PID, USB interfaces, LED wiring, presence-timeout; a read-modify-write merge — only the TLV tags in the blob are updated, the rest preserved (the same merge_save the CCID path uses), effective on the next boot); 0x02 = the LED config block (EF_LED_CONF, §8, CONF_LEN bytes), persisted and then applied live by the firmware. Send at least 17 bytes for the LED target. The device stores the first 17 bytes and ignores any suffix. CONFIG_READ target 2 returns the stored block verbatim, so it can differ from the live configuration after §8’s normalization. With the configuration unlocked, the default build permits these writes without presence or PIN authentication. strict-config adds both the presence gate and the PIN gate (§9.2). The CCID and CTAP management paths use the same DeviceInfo record, so a later CCID READ CONFIG reports the change.

Replays and the audit journal. A write whose result equals what is already stored returns 0x00 and writes nothing — no flash write, no journal entry, and for PHY no auto-reboot latch. An LED replay is still applied live, as SET LED’s is. The comparison is against the merged record for PHY, so a partial blob that changes nothing is also a no-op; an absent or unreadable EF_PHY is never “unchanged”, so a host writing the default values to repair one is not answered 0x00 with nothing stored.

A write that does change something is journalled, and a run of them costs a single ring entry. CONFIG_WRITE is one of three journalled events an ungated host can drive on demand — the others are a getAssertion carrying up:false and a U2F AUTHENTICATE with P1=0x08, both of which take the spec-mandated silent path — so appending one per call would let any of them evict the 128-entry window. All three coalesce. For CONFIG_WRITE, when the newest entry is already a config write the device folds into it. The entry keeps its seq, its timestamp (the first write of the run) and its aux (the target that opened it), and its detail becomes repeats(2 LE) ‖ targets(1) — the number of further writes absorbed (saturating) and a 1 << target mask of every record the run touched. A run never folds across a power cycle, so the BOOT entry between two runs is never swallowed.

The two silent FIDO events use a different encoding: the entry keeps the detail of the first occurrence (the rpIdHash shown is the run’s first site) and the count of further folded occurrences is a saturating LE u16 in the entry’s trailing two bytes — previously reserved and always zero, so an older build’s entries decode as a single occurrence. That fold scans the whole window, not just the newest entry, so interleaving two silent classes does not defeat it. A gestured assertion never folds. For a host re-checking the chain: a fold changes the head without advancing seq_next, so the same seq_next with a different head is legitimate and is not a tamper signal (start, seq_next and the epoch are untouched, so the window still folds to the head exactly as before).

CONFIG_READ 0x0D PHY key 2 (RS-Key 0x0852+): the PHY read returns a 2: map of boot-effective values keyed by phy tag: 4 = LED GPIO pin, 12 = LED driver, 8 = presence timeout (seconds) — resolved to the build default when the record has no override. Tag 8 reports the window the wait actually uses, i.e. with the 10 s floor of §7.1 already applied. It is for display by the host. The key 1 blob remains the raw override record for read-modify-write. When the firmware has no effective LED configuration, key 2 is an empty map.

⚠️ Seed export hands out a normally non-exportable key

BACKUP_EXPORT (0x02) returns the device’s 32-byte master seed (encrypted over the MSE channel). It is gated by a one-time setup window (re-opened only by an authenticatorReset) and requires presence and the PIN gate (§9.2). Ask for explicit confirmation before exporting the seed. BACKUP_FINALIZE closes the export window. The fips-profile build refuses export entirely.

9.1 The MSE channel (0x41 / 0x01)

Establishes an encrypted channel for the seed-moving subcommands.

  • Request subCommandParams = {1: COSE_Key} where the COSE key is the host’s P-256 public key {1:2, 3:-25, -1:1, -2:X, -3:Y}. X and Y are each exactly 32 bytes — a coordinate whose leading zero your bignum dropped is 0x02 INVALID_PARAMETER, not left-padded (RS-Key 0x089C+; the same rule the clientPIN and hmac-secret COSE parses apply, and what a YubiKey 5.7.4 does). Optional key 2 = the host’s ML-KEM-768 encapsulation key (1184 B) to make the channel hybrid PQC.
  • Response {1: COSE_Key} = the device’s ephemeral P-256 public key (same COSE shape, -2:dx, -3:dy). If the request included an ML-KEM ek, the response adds key 2 = the 1088-byte ML-KEM ciphertext.
  • Channel key (32 bytes):
    • classical: HKDF-SHA256(salt="", ikm = ECDH_x(32), info = dev_pub(65))
    • hybrid: HKDF-SHA256(salt="RSK-MSE-PQ-v1", ikm = ECDH_x(32) ‖ ss_mlkem(32), info = dev_pub(65) ‖ ct(1088))
    • dev_pub is the 65-byte uncompressed device key 04 ‖ dx ‖ dy.

Blob format (the 60-byte blob in EXPORT/LOAD/UNLOCK/ATT_IMPORT): nonce(12) ‖ ciphertext(32) ‖ tag(16), ChaCha20-Poly1305 under the channel key with AAD = dev_pub (65 bytes).

The device has one live MSE slot. Run MSE immediately before the protected command on the same transport and CID. Once a vendor consumer request parses, it takes the slot before checking the remaining gates, including presence and decryption. A CID mismatch empties the slot without giving the caller its key. For authenticatorConfig AUT_ENABLE, the slot is taken after the config authentication check.

A second valid MSE request while the slot is live clears the slot and returns 30. Start a fresh handshake after that response. A CTAPHID CID is a host-supplied routing value. Refusing an in-place rekey prevents a second MSE from replacing a live recipient key for BACKUP_EXPORT.

9.2 PIN gating

With a host clientPIN configured, commands marked PIN gate require pinUvAuthProtocol (key 3) and pinUvAuthParam (key 4). The token must carry the acfg permission (0x20).

HMAC-SHA256(pinUvAuthToken, FF × 32 ‖ 41 ‖ subcommand ‖ rawSubCommandParams)

Use the first 16 MAC bytes with protocol 1 and all 32 with protocol 2. rawSubCommandParams is the verbatim CBOR encoding of the key-2 map, or zero bytes if key 2 is absent. The reference client is tools/rsk/backup.py.

An unsupported protocol (including 0) returns 02. Missing key 4 returns 36. If key 4 is present and key 3 is missing, the device returns 14. A bad MAC or missing acfg permission returns 33.

Without a host PIN, a configured device PIN is collected on the trusted display. If the current build cannot collect it, the request returns 36. Decline, timeout and cancellation during PIN entry return 27, 2F and 2D respectively. A wrong PIN consumes a retry. With neither PIN configured, the PIN gate passes and any separate presence checks still apply.

An unsupported one is judged before the algorithm, the extensions and the remaining options — makeCredential and getAssertion included, where it used to be judged after all of them, so a request that got two things wrong was told about the wrong one (bcdDevice 0x08B6). Two things still outrank it, both because a YubiKey 5.7.4 puts them there:

  • the request map’s own shape — keys 1..=4 of makeCredential and 1..=2 of getAssertion are read in order, and an absent, empty or over-long one is answered before any value is validated;
  • the option values of §6.1.2/§6.2.2 step 4: up:false on makeCredential, and uv:true with no pinUvAuthParam on a build without built-in user verification, are 0x2C INVALID_OPTION whatever pinUvAuthProtocol says. options.rk is not in that class and loses to the protocol, on that card and here.

9.3 Audit journal format

AUDIT_READ returns {1: start, 2: seq_next, 3: epoch, 4: entries}. The sequence numbers are CBOR unsigned 32-bit values. epoch is a 32-byte byte string. entries is a byte string of 20-byte records in sequence order.

seq(4 LE) ‖ uptime_ms(4 LE) ‖ event(1) ‖ aux(1) ‖ detail(8) ‖ repeats(2 LE)

Start with the exported epoch and compute SHA-256(previous_hash ‖ entry) for each record. The final hash is the chain head. Event IDs and detail layouts are defined in crates/rsk-fido/src/journal.rs.

AUDIT_CHECKPOINT returns {1: head, 2: seq_next, 3: signature, 4: public_key}. The head is 32 bytes. The signature is DER-encoded ECDSA-SHA256 and the public key is a 65-byte uncompressed P-256 point (04 ‖ X ‖ Y). Verify the signature over the following bytes, using the DEVK-derived audit public key.

ASCII("RSK-AUDIT-CKPT-v1") ‖ head(32) ‖ seq_next(4 LE) ‖ nonce(0–32)

A journal entry can change in place when events coalesce. Compare the computed head as well as seq_next when checking whether the export and checkpoint cover the same snapshot.


10. Worked examples

All bytes hex; → shows the response (status word omitted when 9000).

Identify the device (Management DeviceInfo):

SELECT  00 A4 04 00 08 A0 00 00 05 27 47 11 17 00
READ    00 1D 00 00 00
→  1C 01 02 023B 02 04 <serial> 04 01 01 05 03 050800 03 02 023B 08 01 00 0A 01 00

Read the phy record (Rescue):

SELECT  00 A4 04 00 08 A0 58 3F C1 9B 7E 4F 21 00
→  01 02 08 06 <8-byte serial>            # identity handshake
READ    80 1E 01 00 00
→  <phy TLV blob>                          # e.g. 06 02 00 00 on a virgin device

Switch USB identity to 1209:F1D2 by sending a patch for tag 00 to the selected Rescue applet. Confirm the write on the device, then reboot after 9000.

WRITE   80 1C 01 00 06 00 04 12 09 F1 D2 00
REBOOT  80 1F 00 00 00

Set processing-status LED to red, brightness 64 (Vendor/LED):

SELECT  00 A4 04 00 05 F0 00 00 00 01 00
SET     00 10 40 11        # P1=0x40 brightness, P2 = color 1 | status 1<<4 = 0x11

Read backup state over CTAPHID. Send CTAP2 message 41 A1 01 05 (0x41 + CBOR {1: 5}) → on a fresh provisioned device 00 A5 01 F4 02 F5 03 F4 04 F4 05 F4. After the 00 status byte, the map sets has_seed to true and sealed, locked, unlocked and rescrub_refused to false.


11. Integration notes for PicoForge

PicoForge can reuse its PHY TLV codec (§7.1) with the RS-Key Rescue AID A0 58 3F C1 9B 7E 4F 21 and CLA 80. Send only the tags to update. Skip unknown tags while reading. An unsupported CTAP vendor subcommand returns 02. Use the read-only probes in §6.1, §7 and §9 to discover capabilities.

For the legacy hardware-config path, send authenticatorConfig (CTAP 0x0D) with subcommand vendorPrototype (0xFF) and parameters {1: vendorCommandId(u64), 3: value(uint)}. The four PHY writes require an acfg token and do not ask for presence. A configuration lock returns 30.

PHY commandIDValue
PhysicalVidPid0x6fcb19b0cbe3acfa(vid << 16) | pid
PhysicalLedGpio0x7b392a394de9f948GPIO number
PhysicalLedBrightness0x76a85945985d02fdGlobal brightness
PhysicalOptions0x269f3b09eceb805fPHY OPTS bitmask (§7.1)

getInfo lists 0xFF in authenticatorConfigCommands (0x1F) and returns an empty vendorPrototypeConfigCommands array (0x15). Use authenticatorVendor CONFIG_COMMANDS (41 / 0F) to retrieve the 64-bit IDs. The list includes soft-lock enable and disable (0x03e43f56b34285e2 and 0x1831a40f04a25ed9) and the enterprise-attestation RP list (0x0e6841934e719be7, RP IDs at key 4). Soft-lock enable also uses MSE.

Use the Rescue PHY commands or authenticatorVendor CONFIG_READ/WRITE for fields beyond the four legacy PHY IDs, such as product name, touch timeout, LED driver and curves. PHY changes take effect at boot. A changed FIDO PHY write normally queues a reboot. Setting DISABLE_POWER_RESET keeps the device attached until the host or operator reboots it.

Use DeviceInfo for applet enable/disable (§6), and require explicit confirmation before fuse burns (§7), rebooting to BOOTSEL (§7/§8) or exporting a seed (§9). Reference client paths under tools/rsk include ccid.py, ctaphid.py, hw.py, led.py, backup.py, status.py and inventory.py.

Testing

RS-Key tests command handling in Rust, drives the same protocols through an emulator and a real USB device, and boots the combined firmware ELF on picoem’s RP2350 model. A test of one layer can pass while another fails. For example, a host test can verify that a USB reset clears a PIN token. To find out whether Secure firmware sees that reset when Non-secure code ignores it, run the image suite. For actual USB timing, use a board.

The two commands

Run from the repository root. Nix supplies the pinned tools.

nix develop -c ./scripts/check.sh
nix develop -c ./scripts/check-assurance.sh

check.sh is the per-commit gate. It builds and checks firmware, runs host tests across feature sets, checks the final image and tests the supporting tools. check-assurance.sh checks the model wiring, assurance registries, citations, test rosters and published evidence. Pull requests also run bounded proofs and emulator jobs. See CI parity for the split.

HarnessWhat executesExample failure it finds
Cargo testsRust crates and test backends on the hostA PIN retry counter changes after a rejected request
Applet emulatorShared applet and store crates, with host transport and device hooksA malformed CCID exchange leaves a selected applet in the wrong state
picoem library testsRP2350 CPU and peripheral models on the hostA write clears a programmed OTP bit in the model
Image emulatorSecure and Non-secure firmware ELF running on picoem through rsk-emu --imageA reply from an old USB epoch reaches a new session
USB/IPAn emulator backend and a Linux USB host stackA client rejects a descriptor or fails to open a HID interface
BoardFirmware on RP2350 silicon, driven over USB or through board inputsA real reset, panel gesture, OTP access or cache behavior differs from the model
Independent client or oracleA protocol client, test vector, reference implementation or second deviceA signature passes an internal round trip but fails independent verification

Host tests

The firmware is no_std. Parsers, applet state machines, record codecs, cryptography and much of the transport and recovery logic live in crates/rsk-* so Cargo can test them on the host. The host suite exercises request parsing and response encoding, PIN and token policy, applet selection and state changes, flash recovery, and crypto against known answers. The firmware supplies the hardware implementations of the traits those crates use.

The workspace defaults to the embedded target. Select the host explicitly.

nix develop
host_target="$(rustc -vV | sed -n 's/^host: //p')"
cargo test -p rsk-fido -p rsk-store --target "$host_target"

Feature sets change behavior. For example, always-uv changes which FIDO requests require user verification, fips filters algorithms, and storage profiles change which records can appear on flash. The gate exercises the declared host configurations and builds firmware for multiple flash sizes and a display board. See Build options for feature constraints and the configuration matrix for assurance scope.

Boundary values and regression tests

Tests cover empty and truncated requests, exact buffer limits, excessive lengths, wrong tags, invalid enum values and counter boundaries. The stateful cases follow a command across retries, cancellation, applet changes, reboot or interrupted writes. For an authorization bug, the expected result includes what did and did not change. A rejection status is insufficient if the device also consumes a retry, retains a token or leaves a partially updated record.

Regression tests use the narrowest harness that can reproduce the fault. Host tests can fix the order of a read failure and a retry. Image tests can place a reset between dispatch and reply. USB tests check observable protocol behavior such as framing and status words through the ordinary client path.

Without a board — the emulator

The default rsk-emu backend runs the real applet and store crates on the host. Its NOR model uses the same flash geometry and storage code as the device. It has its own worker sequencing and device hooks. CTAPHID and CCID travel over sockets. tests/emu.py supplies compatible HID and smart-card modules to the numbered Python tests and can request an emulator replug. It refuses tests that need raw USB or physical effects, with a reason and exit status 77.

nix develop -c ./scripts/emu-suites.sh

That runner starts clean stores for separate sessions, runs applicable numbered suites, runs upstream card tests, and compares selected public descriptors and capabilities against the checked-in YubiKey baseline. For single-test commands and emulator options, see the emulator README.

picoem model tests

The picoem fork supplies the RP2350 model for the image backend. tools/emu/Cargo.toml pins its revision. check.sh runs rustfmt, Clippy and the library tests for rp2350-emu and picoem-common at that revision. These tests check the model itself, including instruction execution, interrupts and peripheral behavior. picoem fork

The image itself — --image

The image backend uses picoem to boot the combined Secure/Non-secure ELF through the RP2350 boot ROM. Firmware talks to models of the USB controller, OTP, flash, SHA-256, TRNG and other peripherals. Its USB host controller enumerates the firmware and sends endpoint traffic. These tests execute the linked worker, its applets, the NS transports, interrupt routing and the gateway ABI. Loading an ELF this way leaves production signature enforcement and physical bus behavior for board tests.

nix develop -c ./scripts/image-suites.sh

The runner builds an ordinary no-touch image and separately builds diagnostic images. It keeps their logs and reports apart. Its checks include startup, crypto keepalives, gateway spans and tickets, hostile NS loads and stores, reset and reconfiguration, presence, core1 failure, and recovery after a Secure or Non-secure fault. The inspection port gives selected tests access to modeled SRAM, stack pointers and power cuts.

The image tools in tools/emu also drive operation and persistence matrices. They verify signatures, inspect per-command stack high-water marks, search for known secret bytes after an operation, and cut power with writes in flight. Dedicated runners exercise backup and restore, RSA key generation, OTP provisioning and BOOTSEL/PICOBOOT traffic.

Run an individual image scenario after the full runner has built its inputs, using a fresh output directory. The example below reruns power cuts. Set emu to the native emulator binary and elf to the runner’s ordinary partitioned ELF.

python tools/emu/image_assurance.py --emulator "$emu" --image "$elf" \
  --work target/image-cuts --only cuts

basic covers startup and the boundary probes with the corresponding diagnostic ELFs. stack exercises stack-heavy operations, including ML-DSA and RSA. operations checks the command matrix against the applet and image backends. In CI, operations-core includes PIV key generation, and OpenPGP RSA generation runs in rsa-openpgp (2048/3072) and rsa-openpgp-4096, each with its own emulator sessions and time budget. The separate upgrade scenario needs an older release image and checks persistence across the firmware change. Reports identify the emulator and images by hash.

USB/IP

rsk-emu --usbip exports a USB device to Linux. A guest using vhci_hcd can run libusb, HID and PC/SC clients through the normal OS stack. scripts/usbip-suites.sh runs the USB-dependent suites in that setup. This covers host enumeration and client binding that the socket shim bypasses. The controller and link are still modeled. Use a physical device for electrical behavior, real power cycles and on-device timing.

Display image testing

tools/emu/image_display.py runs a CST328 (V1) or CST3530 (V2) display image with the modeled panel and touch input. Its ceremony cases check approve, deny, cancel, and a hold too short to approve. Other cases exercise stale touch, press and release behavior, deadlines, and on-device PIN entry for FIDO and CCID. The driver checks both the visible prompt and the host reply. The PIN cases distinguish digits shown on the device from the result returned through the transport.

SelectorAssertion
ceremoniesDeny and cancel produce their host statuses. A short hold cannot approve sign-in. Approval returns a usable credential or assertion.
staleA queued touch from an earlier prompt cannot approve a new one.
physicalA slide, lift or cancel from another channel does not authorize the pending request.
timeoutThe image clock expires the prompt and the host receives the terminal response.
pinDevice PIN setup, mismatch, cancellation, retries and recovery across reboot follow policy.
fido-pinClientPIN obtains a token via the display and uses it in an authenticated command.
ccid-pinCCID Secure PIN operations reach the applet with the expected PIN handling.

Run a single case from the Nix shell with a combined image built for the display board and a native rsk-emu binary. For example, for a denial:

python tools/emu/image_display.py --emulator "$emu" --image "$elf" \
  --work target/display-deny --only ceremonies --case deny

The headless test feeds events to the emulator’s input queue. A physical panel run still checks its controller, touch alignment, hold timing and the browser’s behavior after the authenticator answers.

Storage and failure injection

The unit-test store and the emulated NOR flash let the suite choose where a write fails. Tests exercise the same storage invariants from different places.

FailureWhat the test looks for
Read, program or erase errorThe operation reports the right error. An unreadable record does not silently become an empty slot or a default authorization state.
Silent lost or torn writeRecovery recognizes what actually reached flash, including an incomplete record or a write that returned success without persisting.
Corrupt, truncated or substituted recordLength checks and record authentication reject the data. A record for another key or role cannot stand in for the requested one.
Reset during mutationOn reopen, committed data is coherent and any accepted pre- or post-operation result satisfies the operation’s recovery contract.
Second failure during recoveryThe next mount can recover again. Interrupted cleanup cannot make a deleted credential or an old authorization usable.
Full store, wrap or reclamationCapacity errors and compaction preserve live records and counter ordering.

The stateful fs_ops fuzzer compares sequences of storage operations with an independent model. power_cut adds cuts and remounts across record and recovery boundaries. The image tests take the same question to the delivered ELF by interrupting a modeled program or erase and rebooting with the flash left behind. Each result is tied to the fault positions and profile exercised. Endurance, brownouts and the XIP behavior of real flash during an erase need hardware measurements.

Independent result checks

A round trip can preserve the same error in its writer and reader. Crypto tests include known-answer vectors from ACVP and Wycheproof, and command tests verify outputs with host implementations where possible. The ML-DSA tests include independent client or cross-verification paths. Signature checks verify the message and the key as well as the return status. Storage tests compare with an independent state model or reopen persisted bytes and query through the normal command path.

AppletExamples exercised through commands
FIDO2 and U2FRegistration, assertions, PIN/UV token scope, retries, resident credentials, extensions, reset and attestation
PIV and OpenPGPPIN and management authentication, private operations, key and certificate lifecycle, command chaining and reset
OATH and OTPTOTP/HOTP calculations, counters, authorization, HID and keyboard reports, touch waiting and cancellation
Management and recoverySettings, soft lock, backup and restore, OTP migration and factory reset

On-device tests

Numbered scripts under tests/ drive a key over USB. Use a disposable board or a dedicated test state. Some suites change credentials, counters and configuration or request reset. Read the script’s arguments before selecting a board. Most automation uses a test build with no-touch. Presence, trusted-display and timing tests need their stated hardware and build settings.

nix develop -c python tests/10_fido_getinfo.py
nix develop -c python tests/80_piv.py

The test groups cover CTAPHID and CCID transport, applet lifecycles, persistence, PIN pad and button behavior, and hardware-related TrustZone checks. The USB reset suites use the real host stack when they require raw USB. A software reboot is a separate case from removing power, particularly for the CTAP Reset window and tests that require cold boot.

TrustZone on hardware

tests/108_trustzone_hardware.py builds disposable diagnostics in a separate checkout and runs a model or physical case against the matching image. It checks that a hostile NS access faults with the expected status, that the fault fences USB and clears pending work, and that PIV is usable after recovery. Read and write matrices cover selected protected resources. The board runner identifies the image and board and records the observed fault rather than treating a lost USB connection as success. A positive control must complete an ordinary NS access. For a protected peripheral load or store, the diagnostic compares the captured fault address and status with the expected access and checks that USB has been fenced. Removing the fence in a control image must fail the latter check.

nix develop -c python tests/108_trustzone_hardware.py build --work target/tz-hw-image

After the maintainer loads the matching diagnostic onto a test board, the physical subcommand takes --image-dir, --serial and a fresh --work directory. Pass --matrix read or --matrix write to select a resource sweep. verify-record checks a saved capture. These images are laboratory artifacts.

tests/101_trustzone_otp_status.py checks the public OTP-status protocol and access policy through the host paths it exercises. A privileged NS load from page 58 is a separate test from reading OTP in BOOTSEL. Its negative result needs a positive control, such as a successful read of ordinary NS RAM. Results before and after sealing, and results with enforced Secure Boot, describe distinct configurations. The TrustZone verification record and board evidence give the scope of recorded runs.

The vendored upstream suites

tests/third_party.py runs upstream tests using the client’s own stack. The OpenPGP suites exercise card commands and status words. Yubico’s ykman tests cover PIV, OATH, OTP, OpenPGP and management. Over the card socket they can see CCID only. The pico-fido suite and selected python-fido2 suites use an appropriate USB path. A runner records cases outside the interface or advertised feature set separately.

nix develop -c python tests/third_party.py openpgp
nix develop -c python tests/third_party.py ykman

FIDO conformance

The FIDO Alliance tools, the vendored pico-fido tests and the native Rust conformance tests have different case lists. Compare case IDs under the same tool, profile, attestation fixture and presence policy. Keep failures and pending reasons with the pass count. In particular, optional extension advertisement, enterprise credentials and HID behavior affect applicability. Recorded runs are in the testing evidence.

Real-world interop

The interop report records the clients, operations and results on real hosts. The emulator sweep checks getInfo, ATR and management DeviceInfo against a frozen YubiKey baseline. Two-device differential tests and browser, desktop, or touch ceremonies need the actual clients and devices. The comparison rules record accepted differences explicitly.

Fuzzing

fuzz/ uses libFuzzer with the pinned nightly. Some targets feed bytes to a parser or record decoder. Stateful targets generate related operations over one session or one flash image. These can find a bad transition after several individually valid commands. Oracles check properties such as whether a rejected command changed state or recovery exposed an object that had already been removed.

nix develop .#fuzz -c ./scripts/fuzz-all.sh
nix develop .#fuzz -c ./scripts/miri-all.sh --smoke
nix develop .#fuzz -c ./scripts/miri-all.sh

The fuzz workflow runs every target for 30 seconds on each push to develop. Four shards run in parallel for each of the default and flavours builds. Daily deep-checks uses the same runner with 120 seconds per target. Failing jobs upload crash inputs as artifacts.

The miri-smoke job on each develop push runs the APDU framing tests under a single Miri seed. Daily deep-checks runs the full multi-seed matrix.

Committed seeds, generated dictionaries and external corpora reach inputs that random bytes seldom produce. For example, a seed can get through CTAPHID reassembly, CBOR decoding and PIN authorization before a mutation changes a later operation. A frame fuzzer and a session fuzzer reach different classes of bugs.

Target or groupInput and oracle
apdu_frame, ccid_frame, ctaphid_roundtripFrames and reassembly. Check bounds, length handling and valid round trips.
fido_cbor, fido_session, fido_session_tokenRequest bytes and command sequences. Check dispatch, authorization and state after refusals.
cross_applet and OATH variantsSwitch applets between commands. Check that one applet’s authentication and capabilities do not authorize another.
fs_ops, power_cut, authenticated_store_v2Mutations and damaged or partially written media. Check recovered state and authenticated record handling.
otp_hid, ccid_secure_pin, display_labelHost reports and display input. Exercise length, copy and presentation boundaries.
Crypto targetsValid and malformed encodings, known invariants and implementation comparisons where available.

For a focused run use cargo fuzz run power_cut -- -max_total_time=60 from nix develop .#fuzz. fuzz-coverage.sh reports source coverage from corpus replay. fuzz-dimensions.py reports which fault and operation ranges a corpus actually visits. A coverage report describes the inputs retained for that run. Minimized failing inputs can be replayed, then pinned as regression tests when the expected behavior is known.

Branch and condition measurements

Line coverage counts executed source lines. Branch coverage counts the control-flow outcomes recorded by the compiler. Condition coverage counts the true and false outcomes of individual Boolean conditions.

Recorded coverage

These are recorded measurements. The source reports identify the revisions, toolchains and feature configurations. The host unit-test totals cover the host workspace without the embedded firmware and wipe images. Keep the denominators separate across runs and instrumentation modes.

SuiteMetricMeasuredScope and evidence
Host unit testsLines42,688 / 43,370 (98.43%)Default host profile. Host-profile audit
Host unit testsFunction groups3,607 / 3,609 (99.94%)Same default profile and run. Host-profile audit
Host unit testsBranch outcomes6,509 / 7,646 (85.13%)Default host profile in a separate, earlier LLVM branch run. Branch measurement
Host unit testsCondition outcomes8,207 / 8,723 (94.08%)Default host profile with LLVM condition instrumentation. Host-profile audit
Fuzz corpus replay, defaultSource lines23,062 / 36,301 (63.53%)Union across 53 targets. Crates alone reached 21,490 / 32,983 (65.15%). Fuzzing report
Fuzz corpus replay, flavoursSource lines22,699 / 36,182 (62.74%)Separate union across 53 targets. Crates alone reached 21,127 / 32,864 (64.29%). Fuzzing report
Host MC/DC campaignConditions with witness pairs4,806 / 5,029 (95.57%)Default host profile with the extended Supercov frontend and lab adapters. 223 measured conditions remain unpaired. Source-decision report
MC/DC CI recipeConditions with witness pairs201 / 371 (54.18%)Local run of the CI command. 400 tests and seven instrumented source files, targeting six security decision groups. Decision selection

Across the 18 audited host profiles, unit-test coverage ranged from 98.34–98.43% of lines, 99.86–99.94% of function groups and 93.90–94.09% of condition outcomes. The separate 18-profile MC/DC matrix recorded 95.31–95.57% of measured conditions with pairs. Both reports retain the counts and missing conditions for each profile.

The fuzz union counts each repository source line once when any target reaches it. The denominator includes vendored code. With the reports from one profile in fuzz/coverage/, run python scripts/fuzz-union.py to recompute it. Individual target reports also record region coverage.

Firmware and native components

These measurements have their own build and input scopes. The firmware source inventory contains 675 conditions across configurations. Each runtime result below comes from its own measured component or image.

ComponentMeasured resultEvidence
Secure worker, button and Non-secure ABI image29 / 31 compiled conditions with pairsARM worker measurements
Secure USB and display PIN worker62 / 71 Secure USB conditions and 8 / 9 in a separate display worker imageSecure USB campaign, display and bench decisions
Display panel and WS2812 driver39 / 40 panel conditions and 32 / 44 LED conditions in separate component imagesFirmware component report
Runtime PIN codec and diagnostics5 / 5 PIN codec conditions, 4 / 4 stack sweep and 3 / 3 vendor benchmark conditions in separate imagesPIN codec, display and bench decisions
Native C8 / 8 RSA and 4 / 4 gateway compound conditions with pairs. Both outcomes observed for 31 / 31 C predicates in the measured revision, before exponentiation and CRT moved to RustC and assembly correspondence
Native assemblyBoth outcomes observed for 19 / 19 compiled predicatesC and assembly correspondence

Host tools

The host-tool campaign measured these separately from the firmware crates.

ToolLines or statementsDecision outcomes
Rust TUI1,637 / 3,424 lines (47.81%)192 / 302 condition outcomes (63.58%)
Rust emulator3,882 / 6,878 lines (56.44%)690 / 1,216 condition outcomes (56.74%)
Python rsk CLI3,640 / 4,618 statements (78.82%)560 / 1,012 branch outcomes (55.34%)
Python test runners under scripts/13,007 / 28,171 statements (46.17%)2,001 / 6,988 branch outcomes (28.63%)

Coverage in CI

MeasurementScope and scheduleWhat CI enforcesWhere to read it
Line coverageDefault host workspace in deep-checks / coverage, daily and on full runsAt least 80% aggregate line coverage. firmware, firmware-ns and rsk-wipe are excludedcargo llvm-cov summary in the job log
Condition outcomesDefault host profile daily, every declared host profile on full runsTests and coverage export must succeed and produce evidence. No percentage floorunit-coverage-* artifacts with JSON, LCOV and resolved features
MC/DCSelected security decisions in the default host profile in deep-checks / mcdc, on full runsTests must pass and the report must contain valid, current witness evidence. No percentage floorJob summary and mcdc-* artifact with the raw evidence and logs
Fuzz corpus coveragePer-target corpus replay in deep-checks / fuzz-coverage, daily, on dispatch and on matching pushesAdvisory measurementJob summary and per-target coverage artifacts

Full runs include the Sunday schedule, manual dispatch and pushes to main that match the workflow’s path filters. The 80% line floor applies to the default host workspace as a whole. The individual crates and alternate profiles have their own results in the reports.

Run the line floor locally from nix develop.

host_target="$(rustc -vV | sed -n 's/^host: //p')"
cargo llvm-cov --summary-only --fail-under-lines 80 \
  --target "$host_target" --workspace \
  --exclude firmware --exclude firmware-ns --exclude rsk-wipe

Use the nightly shell for a separate branch report.

nix develop .#fuzz
host_target="$(rustc -vV | sed -n 's/^host: //p')"
CARGO_TARGET_DIR=target/coverage-branch cargo llvm-cov --branch \
  --target "$host_target" --workspace \
  --exclude firmware --exclude firmware-ns --exclude rsk-wipe

For condition outcomes, run nix develop .#fuzz -c ./scripts/metrics.sh --coverage. Set COVERAGE_PROFILE to a declared feature profile for a separate report. The host-profile audit records measured counts and accounts for uncovered outcomes, lines and functions.

MC/DC

Modified condition/decision coverage asks whether each Boolean condition can independently change the enclosing decision. For pin_valid && presence, (true, true) and (true, false) form a witness pair for presence. With an invalid PIN, short-circuiting skips presence. A skipped operand gives no observed value for that operand.

nix develop -c ./scripts/mcdc.sh

The script builds the pinned, patched Supercov in a fresh source copy and runs the tests for six groups of decisions. They cover FIDO assertion authorization and token expiry, PIV signing policy, OpenPGP DEK selection, presence and cancellation, and flash read and verification failures. The scoped run keeps the per-test traces within the CI runner’s disk budget. The denominator includes all instrumentable conditions compiled from the seven selected files, including conditions outside those six groups. Logs, the JSON summary and raw evidence go under target/mcdc.*/.

The source reviews explain coupled conditions where an invariant constrains possible pairs. The wider profile experiments, const and macro adapters, worker image measurements, C and assembly have separately recorded scope. See the witness review and source-decision report.

Mutation and negative controls

A mutation deliberately changes a condition or removes a check. A surviving mutation prompts a review of whether the changed behavior is observable, whether a case is missing, and whether the relevant target even ran. scripts/mutants-container.sh runs the host mutation suite. For a crate change, --in-diff HEAD limits the run to the working diff. CI divides large diffs into round-robin shards over the same candidate list. The deep workflow compares the broad run with the accepted survivor list.

A recorded in-diff mutation run caught 20 / 20 mutants in the storage oracle and USB changes. Each verdict applies to that diff’s mutation set. The mutation report also records the separate manual fault controls.

Image tests also use deliberate faults, for example an NS attempt to write USBCTRL or DMA registers. The corresponding normal operation serves as a positive control. Gate tests make an invalid change and check that the row which runs in CI rejects it. A build error, an unrelated assertion or a skipped test gives no evidence about the intended defect.

Kani proofs

Kani checks bounded Rust harnesses for specific properties such as codec round trips, buffer bounds, arithmetic or allowed transitions. The harness fixes the input domain and unwind limits. The proof applies within that domain. The tier runner checks the proof roster and tracks the checks and covers each tier is expected to execute.

Install the Kani version pinned in CI with cargo install --locked kani-verifier --version <pin>, then run cargo kani setup outside the Nix shell. Setup fetches the model checker bundle. Run the pull-request tiers from the repository root.

./scripts/kani.sh pr
./scripts/kani.sh state

A harness for the APDU dispatcher checks pairs of short APDUs for command-chaining isolation. Crypto and record helpers check properties such as modular reduction and encoded-length bounds. Some harnesses use smaller buffers under cfg(kani). See the proof roster for those bounds and the weekly tiers. Cover statements exercise required paths so a proof cannot pass simply because its setup excludes the interesting inputs.

The security-state model (TLA+)

TLC explores finite models of authentication, reset and storage state. Safety checks look for forbidden states. Liveness checks ask whether modeled progress eventually occurs under the stated assumptions. The checked-in runners apply deliberate model mutations. A model mutant must violate the expected property. Co-refutation carries selected defects into Rust and expects a named test to fail for the matching reason.

nix develop -c ./formal/run-tlc.sh safety
nix develop -c ./formal/run-tlc.sh liveness
nix develop -c python scripts/comutate.py run

Formal claims — what is and is not verified

The formal model explains what each model abstracts. Platform assumptions covers dependencies the models take as inputs, including hardware behavior and tool fidelity. A Kani proof of a codec and a TLC result about a session apply to their specified scopes. Trace and refinement checks connect some of those scopes to Rust. RS-Key has no whole-firmware proof.

Dynamic analysis and resource limits

Miri replays supported host code to find Rust undefined behavior, including invalid memory accesses and aliasing. The image suite samples embedded stack use and searches SRAM for known test secrets after commands and reset. These tests can find leftover state at the points they inspect. The unsafe audit and the constant-time audit cover implementation details outside those observations.

Host and image cases exercise maximum frames, APDU chaining, crypto scratch space and concurrent activity such as USB keepalives during RSA. Most buffers have fixed bounds. The RSA path also uses a bounded heap that wipes freed blocks. The build checks the final section placements, flash fences and declared resource limits. The board-only residue diagnostics and latency harness measure the physical device.

Optimized and unoptimized images

Run the ordinary release ELF for firmware behavior, timing and layout checks. The separate Rust opt-level=0 image campaign checks that selected operations also complete and fit when Rust optimization is disabled. The campaign uses domain-specific build settings, and C and assembly remain separately compiled. The image campaign record lists the exact profiles and observed outcomes.

Host tools

The Python rsk CLI and Rust TUI have their own tests. They cover command arguments, status parsing and presentation, and transport behavior. The TUI is a separate Cargo workspace and has a separate Nix shell. The gate runs its format, lint and test rows alongside the firmware and emulator checks.

Latency harness

rsk bench uses a diagnostic firmware feature to time operations with the RP2350 timer, excluding USB round trips. It reports a cold sample, warm median and median absolute deviation. Save both runs and use rsk bench --compare to compare builds in the same setup. A linker layout change can move hot code relative to the XIP cache. The image backend does not model physical cache misses, so suite 105 measures getInfo on a board.

CI parity

WhenWhat runs
Per commit locallycheck.sh, including builds, host tests, static checks and picoem library tests
Pull requestThe gate and assurance jobs, bounded proofs, and emulator jobs that include firmware image tests on picoem
ScheduledLine and condition coverage, MC/DC, longer proof and TLC tiers, fuzzing and corpus reports, Miri, mutation and reproducibility checks
ReleaseClean build and reproducibility checks, artifact manifests, signing and verification. Board runs have separate records.

Static checks include Clippy, dependency and supply-chain checks, an audit of executable sections, image composition and storage boundaries, and constant-time and owner-binding checks on the built code. Read ci.yml, emulator.yml and deep-checks.yml for the current triggers and profiles.

Reproducing a result

Use Reproducing the evidence to choose a tier. For a result you intend to compare, keep the commit, image hash, feature and board configuration, tool versions, exact command and outcome. For a failure-injection result, keep the failing phase and fault position. For a fuzz result, keep the minimized input and the oracle that failed. Keep skipped and refused cases with their reasons. A board report also needs the silicon stepping, boot policy and whether the run started from cold power.

Long run logs, coverage catalogues, mutation reviews and hardware scope records live under assurance/reports.

Reproducing the evidence

This page is for someone who did not write the code and is checking what the project claims: a reviewer with a clean checkout, no board, and no reason to take anybody’s word for a number.

Everything below the hardware fence is reproducible from source alone. The hardware half is not, is destructive, and is the maintainer’s — it is fenced off at the end of this page and no instructions for it are given here.

The one command

git clone https://github.com/TheMaxMur/RS-Key && cd RS-Key
nix develop -c ./scripts/reproduce.sh quick     # start here

scripts/reproduce.sh runs the evidence-producing commands in tiers, prints the command and the exit code of each, and ends on a verdict line. It also prints, every time and whether or not the run passed, the classes of evidence it did not attempt. That block is the point of the script: a wrapper that quietly omits what it cannot do is worse than the list of commands it replaced.

nix develop -c ./scripts/reproduce.sh --list        # the phases and what each reproduces
nix develop -c ./scripts/reproduce.sh --refusals    # what this checkout cannot produce, by name
nix develop -c ./scripts/reproduce.sh quick merge   # minutes, then both gate layers
nix develop -c ./scripts/reproduce.sh model         # the TLA+ tiers, hours
nix develop -c ./scripts/reproduce.sh deep          # the weekly rows, most of a day

Tiers exist so the cheap half can be run first. quick is a couple of minutes and re-derives the generated assurance pages from the tree; merge is what every pull request runs; model is the model checker, which is hours and wants the machine to itself; deep is the weekly matrix. Any phase can also be named on its own, and phases can be combined — a repeated phase runs once.

One run at a time. Two gate runs collide on the build tree and two TLC runs collide on the model checker’s per-configuration logs, so a second copy refuses to start rather than interleaving with the first.

What a clean checkout does not have

Three preconditions are real, and the script says so rather than failing obscurely two minutes in:

  • A built firmware image. Three gate rows disassemble the image the tree builds — the constant-time audit, the segment and allocator map, and the registered-owner binding — and their mutation tables inject a machine-code defect into it. With no image they fail rather than skip, on purpose: a table that stops running is indistinguishable from one that passes. Inside scripts/check.sh the image is built by an earlier row, so the gate phase is self-contained; run one of those gates on its own and build the firmware first. Note which image you are auditing — the gate builds several flavours in sequence and the last one wins, which is why those rows sit where they do in the file rather than at the end.
  • Kani. The proof runner is rustup-based and deliberately outside the pinned dev shell, so CI installs it out of band and so must you. The proofs phases refuse by name, with the install command, when it is absent.
  • Network, once. The dev shell, the crate registry and the advisory database are fetched on first use. After that a run is offline apart from the supply-chain rows.

What cannot be reproduced from software

--refusals prints this list at every run; it is repeated here so the page and the script cannot come apart on which half is which. Nothing on it is a shortcoming of the script — each is evidence about something a checkout is not.

  • On-device suites. The numbered scripts under tests/ drive real USB and real flash. Most of them run against the software emulator instead, and the emu phase is exactly that; the rest need a board.
  • The USB-stack suites. They run the emulator’s USB/IP mode inside a Linux guest with vhci_hcd and KVM. A macOS checkout has neither.
  • Two-key interop. The RS-Key/YubiKey differential cells need both keys attached. The allow-list that separates an expected divergence from a fidelity gap is held by the gate; the cells themselves are not run.
  • Fuzz-corpus coverage. The coverage report measures the corpus the weekly job accumulates across runs, which is a CI cache and not a property of any checkout.
  • CodeQL. Advisory, runs on GitHub’s infrastructure, no local entry point.
  • Release provenance. Signing, attestation and the published-artifact half of the release manifest need a tag and the maintainer’s signing identity. The gate checks the recipe; only a release exercises it.
  • Board measurement. Latency, SRAM residue, side-channel and secure-boot measurements are taken off silicon.

Where the numbers come from

No count on this page, because a count typed here is a second copy of a truth that lives somewhere else and rots on its own schedule. What each tier covers and what the last recorded run of it produced is derived and published in Testing and the formal model; the model checker’s own matrix is kept per run in formal/runs.toml, and the assurance pages under Security are regenerated by the quick phase and diffed against what is committed.

Keeping the script honest

scripts/reproduce.sh --self-test holds the phase table against the tree: every gate row, every shell runner under scripts/ and formal/, and every job of the three workflows that produce evidence must be claimed by a phase or excluded with a reason, in both directions. A new evidence runner, a new weekly job, or a gate row that starts needing something a checkout has not got lands unclaimed and fails the self-test, which is the only thing that stops this page and that script from slowly describing a tree that no longer exists. Its mutation table is scripts/test_reproduce.py.


Maintainer-only: the hardware half

Do not attempt any of the following, and do not ask an agent to. They are irreversible, key-dependent, or both, and they belong to the maintainer alone:

  • flashing an image to a board,
  • secure-boot signing and sealing an image,
  • writing OTP fuses, including the anti-rollback epoch,
  • any destructive hardware-in-the-loop run: factory resets on a provisioned key, the SRAM-residue scan, and anything that leaves the board in BOOTSEL.

Each already has a page written for the person who owns the keys — Production setup, Signing keys, OTP fuses and Anti-rollback — and the procedures live there, not here. A reviewer who wants the hardware evidence should ask the maintainer to run it and publish the log, not run it themselves: a wrong fuse is not recoverable, and a test board that has been sealed to somebody else’s key cannot be reflashed back.

scripts/reproduce.sh has no hardware phase and never will. It refuses the whole class up front, names this page, and never flashes, signs, or writes a fuse.

Versions

What the firmware advertises itself as, per protocol: the place to look when a host tool gates a feature on a version number. The build knobs that change any of this are documented in Build options; what has actually been checked against real host software is in the interop report.

Firmware version

5.8.0 (rsk_sdk::FIRMWARE_VERSION) is reported everywhere a tool reads a device firmware version: FIDO getInfo and CTAPHID INIT, the YubiKey Management DeviceInfo (ykman info), the OATH / OTP / PIV version fields, and OpenPGP’s vendor VERSION command (INS 0xF1). It mimics a current YubiKey 5 so Yubico tooling unlocks its feature gates. Override it with the FW_VERSION build variable. It is not the OpenPGP card version and not the USB bcdDevice.

SurfaceAdvertised versionSpec implemented
FIDO / CTAPHIDgetInfo versions = U2F_V2, FIDO_2_0, FIDO_2_1, FIDO_2_3; device version 5.8.0CTAP2 (FIDO2) + CTAP1 (U2F)
OpenPGP card3.4OpenPGP Smart Card Application 3.4
PIV5.8.0NIST SP 800-73-4 (command subset)
OATHSELECT version 5.8.0YKOATH (Yubico OATH over CCID), AID A0 00 00 05 27 21 01 01
ManagementDeviceInfo version 5.8.0YubiKey Management over the FIDO / CCID transports
USB bcdDevicea four-digit hex counter (current value: the top of the changelog)internal build counter — bumped on every behaviour change, not a protocol version

U2F_V2 drops out of versions on a build with alwaysUv enabled (CTAP 2.1 §7.2.4 disables U2F there). FIDO_2_2 is deliberately absent: CTAP 2.3 §6.4 says that string “MUST not be present”, and the 2.2 surface is discovered through option ids and getInfo members instead.

Which build is on this device?

Not the firmware version — 5.8.0 is a compatibility constant, identical on every build of a release (5.7.4 before bcdDevice 0x09CC), so it answers “what will Yubico tooling unlock”, never “what is flashed here”. The build identity is the bcdDevice counter:

rsk-tui --once          # prints "bcdDevice 0x…" alongside the applet state
lsusb -v -d 1209:F1D2 | grep bcdDevice          # Linux
ioreg -p IOUSB -l | grep -i bcdDevice           # macOS

Map that value to a release through the changelog; each entry names the counter it shipped at. A host tool that shows bcdDevice and calls it “the version” is reading the right field — it is the only number that changes between builds.

The image file itself carries no version. nix build output is unsigned and unstamped, so nothing distinguishes two .uf2s but their bytes. If you need a version readable from the file, picotool seal --major/--minor stamps one into the RP2350 boot metadata that picotool info reads back without flashing (production.md); that is part of the signing path, not the plain build.

Algorithms, by build knob

The default algorithm menu and the two feature flags that change it (full mechanics in Build options):

Default--features advertise-pqc--features fips-profile
FIDO signature algorithms (COSE)ES256 (−7), ES384 (−35), ES512 (−36), ES256K (−47), EdDSA / Ed25519 (−8)ML-DSA-87 (−50), ML-DSA-65 (−49) and ML-DSA-44 (−48) prepended to the getInfo algorithms listES256K (−47) removed from the menu
Post-quantumall three ML-DSA sets negotiable from pubKeyCredParams (capability always on); not advertisedadvertised in getInfosame as default
Minimum PIN length446
Vendor seed exportallowedallowedrefused
PIV3DES management keys + RSA-1024 import allowedsamenew 3DES management keys + RSA-1024 refused
  • PQC capability is on in every build. advertise-pqc only controls whether the three ML-DSA sets appear in the getInfo algorithms list, in descending security order. It is off by default because released Firefox aborts the entire getInfo parse on an unknown COSE id. makeCredential negotiates −50 / −49 / −48 from the request’s pubKeyCredParams regardless — the RP lists the one it wants first, since the first supported entry is selected (CTAP 2.1 §6.1.2).
  • fips-profile is a locked policy, not a FIPS validation. See the FIPS-style profile guide.

Toolchain

The project tracks the latest stable Rust, pinned hermetically rather than to a declared MSRV. nix develop / nix build take the toolchain from the flake (fenix stable, frozen in flake.lock, currently rustc 1.99.1), on Rust edition 2024. rust-toolchain.toml (channel = "stable") is only the fallback for the non-Nix rustup path. “Which Rust built this image” is answered by the committed flake.lock, so there is no separate minimum-version commitment to drift.

Motivation

The short version

Commercial security keys are excellent, and closed. The firmware is a black box. The capacity limits are product-segmentation choices. When a key dies or a vendor discontinues a line, your enrolled identity dies with it. RS-Key exists to see how far an open, auditable, memory-safe implementation can get on a $5 board.

The honest long version is a story about how one open-source project first amazed me, then demonstrated, very concretely, what trust in a security project actually rests on.

The story

I came across pico-fido, a firmware that turns a Raspberry Pi Pico into a FIDO2 key. A five-dollar board passed for a YubiKey. The ecosystem tooling (browsers, ssh-keygen -t ed25519-sk, ykman) worked with it like with the real thing. Next to it lived pico-openpgp. Together they looked like a small miracle: a complete security key you assemble yourself and can read down to the last byte.

I was hooked and got involved right away. WebAuthn was broken in Firefox on Linux. Chromium worked, Firefox silently refused. I dug in with RUST_LOG=authenticator=debug and traced it down: Firefox’s strict CTAP2 parser was rejecting the device’s responses over garbage zero bytes trailing the CBOR payload (pico-fido#129). The fix was accepted and everything worked. For the next year the key was simply part of my daily life.

The turn

Then the project changed its licensing model. “Update license models and add ENTERPRISE.md”.

Point by point, without emotion:

  • The project split into a “Community Edition” and a proprietary “Enterprise Edition”, priced on request.
  • The list of paid enterprise options includes post-quantum cryptography support. Protection from a quantum adversary became a premium feature.
  • The combined firmware, pico-fido2 (FIDO + OpenPGP), moved into a repository consisting of three markdown files. There is no source code. Releases v7.0 and v7.2 exist, with zero attached files. The README, meanwhile, lists “Open source” among the features, and its build instructions begin with git clone https://github.com/youruser/pico-fido2, an address with nothing behind it to clone.
  • There is exactly one way to get the firmware: through the companion app, under a per-device license: €29.49 for a single key, €49.49 for “Primary + Backup”. A firmware license for a five-dollar board, priced in the range of an entry-level commercial key (which at least ships with a secure element and audits behind it).

I am not arguing the maintainer has no right to earn money. He does; it is his code and his time. A security key is a special case. The only thing separating a DIY key from a no-name dongle off AliExpress is that you can read the firmware down to the last byte. A binary-only security-key firmware is a “trust me” from a single person: no source, no audit, no guarantees, exactly the thing this project had been an escape from. That day I understood the project was over for me, and that I would have to write the replacement myself.

The principle

The irony is that Raspberry Pi themselves champion the opposite approach for the RP2350: security through transparency. Open hacking challenges against their own chip, public write-ups of the attacks that succeeded, and a second round on fixed silicon. TROPIC01 does the same at the secure-element level: an open, auditable architecture instead of an NDA. That is the right side of this story, and RS-Key intends to stay on it.

What RS-Key does differently

  • AGPL-3.0-only, irreversibly. RS-Key is a derivative work of the AGPL-licensed pico-keys (see NOTICE), so the “relicense it proprietary” trick is legally impossible here, for anyone, me included. There is no CLA; contributors keep their copyright. This is not a promise of good behaviour. It is how the licensing is built.
  • Post-quantum in the open tree. ML-DSA-44, ML-DSA-65 and ML-DSA-87 credentials work today, for free, with the source in front of you.
  • The “enterprise” features live in the public tree. Attestation, secure boot, backup, audit: the things usually kept behind a paywall land in the open repository.
  • Transparency as artifacts, not as a slogan. Every external-facing parser has a fuzz target, every unsafe is documented and justified, and the threat model was written down before anyone is asked to trust the key with something real.
  • Accessibility. A Trezor or a Nitrokey is hard and expensive to get in Russia. An RP2350 board is 500 rubles and a friend with a 3D printer.

And yes, this is still a love letter to writing real systems software in Rust on a ten-dollar board. Only now it comes with a moral: the openness of a security project is tested not by years of honest work, but by a single commit. RS-Key is built so that the relicensing in that commit cannot happen here.

Roadmap

  • Conformance. Close protocol differences case by case. Compare applicable FIDO cases against pico-fido under the same tool and profile, and record accepted differences in the interop report.
  • Trusted display. Extend physical coverage for gestures, device PIN entry and browser behavior. See the display guide.
  • Testing and formal models. Extend decision coverage, test recovery under compound failures and connect more modeled security properties to the firmware paths that implement them. See Testing for the current checks.
  • Post-quantum protocols. Follow the standards and client support for key exchange. The existing ML-DSA signing paths have their own command and vector tests.
  • Host tooling. Improve board setup and ordinary use through the CLI, TUI and platform setup guides.
  • Release verification. Make it easier to check the exact artifacts users download. See Releases & verification.

The project supports the tip of main. See Limitations for certification and other scope limits, and CHANGELOG for release history.