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 is | Firmware. A .uf2 file you drop onto a board. Nothing here is for sale. |
| What you need | Any RP2350 board (from about $5) and a USB cable. No soldering, no programmer, no toolchain. |
| What you get | A 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
- Quick start: flash a released image, set a PIN, enroll something. No toolchain needed; the images are on the releases page and releases.md says which one to take
- No board yet? The emulator runs the same applet code over sockets, and its
--displaymode opens the trusted screen in a window — the Approve/Deny ceremony can be tried with a mouse before buying anything (testing.md) - Hardware: supported boards and the knobs for them
- Build options: every compile-time flag and environment knob
- Using the device: per-feature guides for FIDO2, SSH, OpenPGP, PIV, OATH, OTP, seed backup, soft-lock, and more
- Production hardening: OTP master key + secure boot (irreversible fuses; read it end to end first)
- Security: threat model, limitations,
and the
unsafeaudit - Project: Contributing · Security policy · Licensing & compliance
What it is, plainly
- It aims to behave like a USB security key and to work with the host software
people already use:
ssh,gpg, browsers, libfido2, andykman(which needs the opt-inVIDPID=Yubikey5build, 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/ PID0xF1D2, from pid.codes), presenting as “RS-Key Security Key”. An opt-inVIDPID=Yubikey5build instead borrows a YubiKey’s identity (VID0x1050/ PID0x0407) so thatykmanand 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-<version>-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:
-
Hold the BOOT button while plugging the board in (or hold BOOT, tap RESET). A mass-storage drive named
RP2350appears. -
Flash it, either way (
firmware.uf2here is whichever.uf2you 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): putSHA256SUMSandSHA256SUMS.sigstore.jsonfrom the same release next to the image, and runrsk flash rs-key-<version>-default.uf2It checks the signature (it needs cosign), the checksum and, with the GitHub CLI installed, the build provenance. Only then does it run the
picotoolcommand above. What each check proves is in supply-chain.md.
The
RP2350drive 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 loadspeaks the bootrom’s PICOBOOT protocol directly, so reach for it whenever the drive never appears or the copy fails. -
-
The board reboots itself and enumerates as
RS-Key Security Key. (The default build uses the project’s own USB identity, VID:PID0x1209:0xF1D2from pid.codes; the PC/SC reader name contains “RS-Key”. For a build that presents the YubiKey USB identity soykman/Yubico Authenticator auto-recognize it, build the opt-inVIDPID=Yubikey5flavor; 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.
3. Set a PIN (recommended)
rsk fido set-pin
Without the host tools, your browser does the same job: it offers to set a PIN the first time you register a passkey.
Browsers and ssh-keygen will prompt for it when enrolling. 8 wrong attempts
lock the PIN until a reset. Standard security-key behaviour.
4. Enroll something
A passkey: go to any WebAuthn site (or https://webauthn.io to try), register a security key, touch the button when the LED asks.
An SSH key:
ssh-keygen -t ed25519-sk -f ~/.ssh/id_ed25519_sk # touch twice, enter PIN
ssh-copy-id -i ~/.ssh/id_ed25519_sk you@server
ssh -i ~/.ssh/id_ed25519_sk you@server # one touch to log in
The id_ed25519_sk file is a handle, not a key. It is useless without the
board. Copy it to other machines you ssh from.
macOS note: Apple’s
/usr/bin/sshhas no FIDO support. Use Homebrew OpenSSH (brew install openssh, then the absolute path/opt/homebrew/opt/openssh/bin/sshor put it first inPATH). 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.
![]() |
![]() |
![]() |
![]() |
| 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.
| Knob | Default | When to change it |
|---|---|---|
FLASH_SIZE | 4M | Match the flash capacity, up to 16 MiB. The linker derives the firmware and storage layout from it. |
KVMAIN | 1408K | Use 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_KIND | ws2812 | ws2812 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_PIN | 16 | Data GPIO for ws2812 or output GPIO for gpio. |
LED_ORDER | rgb | Set grb if the addressable LED’s red and green are swapped. |
LED_POWER_PIN | none | GPIO to hold high for an LED power gate, such as GPIO23 on the Seeed XIAO RP2350. |
USR_LED_PIN | none | GPIO 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_LEDS | 1 | Compiled capacity of the addressable LED chain, up to 64. Set the active count at runtime. |
PRESENCE_PIN | bootsel | Use 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_HIGH | 0 | Set 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.
- Waveshare RP2040-One / RP2350-One case by Patrick van der Leer. Sized for the reference board.
- RP2350 USB case by Vladimir Varzaru (a remix of Patrick’s design). A slimmer USB-stick form.
- Pico 2 Zero FIDO2 case (RP2350) on MakerWorld. Fits the RP2350-Zero.
- Waveshare RP2350 2.8-inch case by @cofob. Designed for RS-Key and recommended for the RP2350-Touch-LCD-2.8. PETG is the recommended print material.
- Waveshare RP2350 2.8-inch case by Mono. Designed for RS-Key on the RP2350-Touch-LCD-2.8.
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.
| Argument | Effect |
|---|---|
--config KEY=VALUE or --config PATH | Merge Cargo configuration. Options can repeat, and file paths are relative to the calling directory. |
--jobs N, -j N, --offline, --frozen, --locked | Cargo concurrency and dependency resolution. The builder always passes --locked. |
--verbose, -v, -vv, --quiet, -q, --color, --message-format, --timings, --keep-going, --future-incompat-report | Cargo output and build controls |
--release, -r | Accepted for compatibility. The builder always uses the release profile. |
--target-dir DIR | Set the output directory as described below |
--no-partition-table | Build both artifacts without the BOOTSEL storage fence |
--help, -h | Print 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.
DIR/trustzoneif you pass--target-dir DIR.RSK_TZ_OUTif set.CARGO_TARGET_DIR/trustzoneif set.target/trustzonein 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.
| Feature | Effect |
|---|---|
advertise-pqc | Advertises ML-DSA-87, -65 and -44 in FIDO getInfo. makeCredential can negotiate the algorithms with the flag off. |
strong-pin | Raises 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-profile | Applies the strong PIN policy, removes FIDO secp256k1, refuses seed export, and restricts PIV management keys and algorithms. See FIPS-style profile for scope. |
always-uv | Compiles 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-up | Requests 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-config | Requires 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-ext | Selects 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. |
display | Enables the trusted display, on-device PIN entry and local screens. Use a compatible display board and LED_KIND=none. See Trusted display. |
preview-sign | Enables the experimental previewSign extension. |
no-touch | Auto-confirms button-based presence for automated tests. Use a presence-enabled build for deployment. |
fido-conformance | Enables the conformance profile, including strict-up, and suppresses EdDSA advertisement. |
ea-conformance-rpid | Adds the conformance RP ID to the vendor-facilitated enterprise attestation list and enables fido-conformance. |
bench, keygen-bench, core1-stats | Test-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.
| Variable | Default | Accepted values and effect |
|---|---|---|
BOARD | unset | abrobot-4m, abrobot-16m, waveshare-one, waveshare-touch-lcd, tenstar-usb, seeed-xiao. Use the file stem, without .toml. |
VIDPID | RSKey | USB 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_PID | from preset | 16-bit IDs in decimal or 0xHHHH form. Either half can override the preset independently. |
USB_MANUFACTURER, USB_PRODUCT | RS-Key, RS-Key Security Key for the default identity | Descriptor strings. An effective Yubico VID uses the built-in Yubico reader strings unless EF_PHY supplies a string override. |
FW_VERSION | 5.8.0 | X, X.Y or X.Y.Z, with components from 0 to 255. Sets the reported applet firmware version. |
XOSC_DELAY_MULT | 128 | 1..=1024. Crystal oscillator startup delay multiplier. |
FLASH_SIZE | 4M | Physical flash size, in bytes, hex, or with a K or M suffix. Must be 4 KiB aligned and at most 16 MiB. |
KVMAIN | 1408K | Main-store capacity. Same size syntax as FLASH_SIZE, 4 KiB aligned, at least 128 KiB. Preserve the layout when updating a provisioned device. |
LED_KIND | ws2812 | ws2812, gpio, pimoroni or none. Sets the boot default. none omits the status LED support and is required by the display build. |
LED_PIN | 16 | GPIO 0–29 for the WS2812 data line or GPIO status LED. Pimoroni PWM uses its fixed pins. |
LED_ORDER | rgb | rgb or grb wire order for addressable LEDs |
LED_POWER_PIN | none | none or GPIO 0–29, held high to power a gated LED rail. Use a pin distinct from the status LED and presence input. |
MAX_LEDS | 1 | 1..=64. Compiled addressable LED capacity. The runtime LED count must fit it. |
USR_LED_PIN | none | none 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_HIGH | 0 | 1 for an active-high user LED. 0 holds an active-low LED off. |
PRESENCE_PIN | bootsel | bootsel or GPIO 0–29. Display builds use touchscreen presence and reject a GPIO presence pin. |
PRESENCE_ACTIVE_HIGH | 0 | 1 for an active-high GPIO presence button. 0 selects an active-low button with a pull-up. |
WAKE_PIN | 25 | Display wake button. Use none for touch-only wake or a free GPIO 0–29. |
WAKE_ACTIVE_HIGH | 0 | 1 for an active-high wake button. 0 selects active-low. |
FAKE_MKEK, FAKE_DEVK | unset | Test-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.
| Variable | Fallback | Setting |
|---|---|---|
PK_DISPLAY_SPI_FREQ_HZ | 80000000 | Panel PIO serial clock. The firmware requires half its fixed 160 MHz system clock. |
PK_DISPLAY_CS, PK_DISPLAY_DC, PK_DISPLAY_RST | 13, 14, 15 | Panel control GPIOs |
PK_DISPLAY_BL_PIN, PK_DISPLAY_BL_PWM_SLICE, PK_DISPLAY_BL_PWM_CHANNEL | 16, 0, 0 | Backlight GPIO, PWM slice and channel. Use a supported tuple from the board wiring. |
DISPLAY_TP_CHIP | cst328 | Use cst328 for Waveshare V1 or cst3530 for V2. |
PK_DISPLAY_TP_RST, PK_DISPLAY_I2C_FREQ_HZ | 17, 400000 | Touch controller reset GPIO and I²C clock |
PK_DISPLAY_INVERT_COLORS, PK_DISPLAY_COLOR_ORDER | 1, 0 | Panel 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.
| Geometry | Firmware region | KVMAIN | KVCNT |
|---|---|---|---|
FLASH_SIZE=2M KVMAIN=896K | 1024 KiB | 896 KiB | 128 KiB |
FLASH_SIZE=4M KVMAIN=1408K | 2560 KiB | 1408 KiB | 128 KiB |
FLASH_SIZE=16M KVMAIN=1408K | 14844 KiB | 1408 KiB | 128 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 firmware | Settings |
|---|---|
| none | Default configuration |
-2mb, -16mb | 2 MiB with KVMAIN=896K, or 16 MiB with the default KV size |
-display, -display-v2 | Trusted display on Waveshare V1 (CST328) or V2 (CST3530). Both use 16 MiB flash and LED_KIND=none. |
-pico | VIDPID=Pico |
-pqc | advertise-pqc |
-fips, -strong-pin, -always-uv, -strict-up | Corresponding feature, also available with an added -pqc suffix |
-strict-config | strict-config |
-no-touch, -no-touch-pqc, -no-touch-fips, -no-touch-fips-pqc | Test 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
Yubikey5preset is intended for clients such asykmanthat 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; theno-touchtest builds are never released (a signed presence-bypass asset would remove the consent gate):flavor flags use defaulttouch the normal build; start here pqc+ advertise-pqc advertises all three ML-DSA sets in getInfo (breaks old Firefox) fips+ fips-profile the locked FIPS-style policy (guides/fips.md) fips-pqc+ both strong-pin+ strong-pin 6-code-point PIN floor + trivial-PIN block (build.md, threat-model.md) strong-pin-pqc+ both always-uv+ always-uv bakes CTAP 2.1 alwaysUvon: user verification (a PIN) for every operation, U2F disabled. Set a PIN after flashing (build.md)always-uv-pqc+ both strict-up+ strict-up not spec-conformant: a touch on every assertion, so a WebAuthn allowCredentialslogin asks for two touches (build.md). Pick it only if you want that stricter stancestrict-up-pqc+ both display+ display experimental 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-config the historical strict admin-write posture: config writes stay presence/PIN-gated and the ungated transport writes are refused (build.md, threat-model.md). The defaultbuild is now the permissive full-ykman admin surfaceAll fourteen present the default RS-Key USB identity:
0x1209:0xF1D2from build0x0A8A; older images use the test PID0x1209:0x0001. For the YubiKey-interop identity, buildVIDPID=Yubikey5yourself (build.md). -
SHA256SUMS: a checksum for every image and the SBOM. -
SHA256SUMS.sigstore.json: a keyless cosign signature ofSHA256SUMS(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 nameSHA256SUMS.cosign.bundle— identical bytes, and.sigstore.jsonis 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.jsonandrs-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 .#flashdoes 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
| Layer | Artifact | What it proves |
|---|---|---|
| Reproducible build | the 14 .uf2 flavors | the 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 + signature | SHA256SUMS + SHA256SUMS.sigstore.json | the 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 provenance | a GitHub attestation, plus rs-key-<tag>.intoto.jsonl on the release | which 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 |
| SBOM | rs-key-<tag>-sbom.cdx.json | the CycloneDX bill of materials for the firmware crate |
| Dependency audit | supply-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.
| Tool | Role | Pinned by | Pin |
|---|---|---|---|
arm-none-eabi-as | assembler | flake.lock:nixpkgs | 31ecbaca1bdefa45dffc409f0250bd8039ea0010 |
arm-none-eabi-gcc | compiler | flake.lock:nixpkgs | 31ecbaca1bdefa45dffc409f0250bd8039ea0010 |
arm-none-eabi-nm | packager | flake.lock:nixpkgs | 31ecbaca1bdefa45dffc409f0250bd8039ea0010 |
cargo | packager | flake.lock:fenix | cf57f8966c3c129e31caaf29790caf8a6a93e0a6 |
cargo-kani | prover | workflow:.github/workflows/ci.yml:KANI_VERSION | 0.67.0 |
cbmc | checker | nothing | open obligation PLAT-TOOL-003 |
cortex-m | assembler | Cargo.lock:cortex-m | 8ec610d8f49840a5b376c69663b6369e71f4b34484b9b2eb29fb918d92516cb9 |
flip-link | linker | flake.lock:nixpkgs | 31ecbaca1bdefa45dffc409f0250bd8039ea0010 |
jre8 | runtime | flake.lock:nixpkgs | 31ecbaca1bdefa45dffc409f0250bd8039ea0010 |
picotool | packager | flake.lock:nixpkgs | 31ecbaca1bdefa45dffc409f0250bd8039ea0010 |
rust-lld | linker | flake.lock:fenix | cf57f8966c3c129e31caaf29790caf8a6a93e0a6 |
rustc | compiler | flake.lock:fenix | cf57f8966c3c129e31caaf29790caf8a6a93e0a6 |
tlaplus | checker | flake.lock:nixpkgs | 31ecbaca1bdefa45dffc409f0250bd8039ea0010 |
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.
| Boundary | Kind | Derived from | Foreign side produced by |
|---|---|---|---|
rsk_tz_fault_stop | export | firmware/src/trustzone/fault.rs, #[unsafe(no_mangle symbol, unconditional | rustc |
rsk_tz_readable_impl | export | firmware/src/trustzone/mod.rs, #[unsafe(no_mangle symbol, unconditional | arm-none-eabi-gcc |
rsk_tz_writable_impl | export | firmware/src/trustzone/mod.rs, #[unsafe(no_mangle symbol, unconditional | arm-none-eabi-gcc |
rsk_tz_usb_impl | export | firmware/src/trustzone/usb.rs, #[unsafe(no_mangle symbol, unconditional | arm-none-eabi-gcc |
rsk_tz_control_impl | export | firmware/src/worker.rs, #[unsafe(no_mangle symbol, unconditional | arm-none-eabi-gcc |
rsk_tz_poll_impl | export | firmware/src/worker.rs, #[unsafe(no_mangle symbol, unconditional | arm-none-eabi-gcc |
rsk_tz_submit_impl | export | firmware/src/worker.rs, #[unsafe(no_mangle symbol, unconditional | arm-none-eabi-gcc |
SWI_IRQ_1 | export | firmware/trustzone/nonsecure/src/main.rs, #[unsafe(no_mangle symbol, unconditional | rustc |
SWI_IRQ_4 | export | firmware/trustzone/nonsecure/src/notify.rs, #[unsafe(no_mangle symbol, unconditional | rustc |
RSK_NS_PROBE_PROGRESS | export | firmware/trustzone/nonsecure/src/probe.rs, #[unsafe(no_mangle symbol, unconditional | rustc |
RSK_NS_PROBE_TARGET | export | firmware/trustzone/nonsecure/src/probe.rs, #[unsafe(no_mangle symbol, unconditional | rustc |
TIMER1_IRQ_0 | export | firmware/trustzone/nonsecure/src/time.rs, #[unsafe(no_mangle symbol, unconditional | rustc |
__kvcnt_end | import | firmware/src/main.rs, extern "C", unconditional | rust-lld |
__kvcnt_start | import | firmware/src/main.rs, extern "C", unconditional | rust-lld |
__kvmain_end | import | firmware/src/main.rs, extern "C", unconditional | rust-lld |
__kvmain_start | import | firmware/src/main.rs, extern "C", unconditional | rust-lld |
_stack_end | import | firmware/src/main.rs, extern "C", unconditional | flip-link |
__rsk_ns_image_len | import | firmware/src/trustzone/mod.rs, extern "C", unconditional | rust-lld |
__rsk_scratch_exec_end | import | firmware/src/trustzone/mod.rs, extern "C", unconditional | rust-lld |
__rsk_scratch_exec_load | import | firmware/src/trustzone/mod.rs, extern "C", unconditional | rust-lld |
__rsk_scratch_exec_start | import | firmware/src/trustzone/mod.rs, extern "C", unconditional | rust-lld |
rsk_tz_enter_ns | import | firmware/src/trustzone/mod.rs, extern "C", unconditional | arm-none-eabi-gcc |
__rsk_exec_end | import | firmware/src/trustzone/mpu.rs, extern "C", unconditional | rust-lld |
__rsk_exec_start | import | firmware/src/trustzone/mpu.rs, extern "C", unconditional | rust-lld |
__rsk_scratch_exec_start | import | firmware/src/trustzone/mpu.rs, extern "C", unconditional | rust-lld |
rsk_tz_control | import | firmware/trustzone/nonsecure/src/main.rs, extern "C", unconditional | arm-none-eabi-gcc |
rsk_tz_poll | import | firmware/trustzone/nonsecure/src/main.rs, extern "C", unconditional | arm-none-eabi-gcc |
rsk_tz_submit | import | firmware/trustzone/nonsecure/src/main.rs, extern "C", unconditional | arm-none-eabi-gcc |
rsk_tz_usb | import | firmware/trustzone/nonsecure/src/usb.rs, extern "C", unconditional | arm-none-eabi-gcc |
__rsk_scratch_exec_end | import | tests/tz_hardware/secure.rs, extern "C", unconditional | rust-lld |
__rsk_scratch_exec_load | import | tests/tz_hardware/secure.rs, extern "C", unconditional | rust-lld |
__rsk_scratch_exec_start | import | tests/tz_hardware/secure.rs, extern "C", unconditional | rust-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 -vVwould 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-001inassurance/platform.tomlowns it and ispending; it writes the same gapsource-to-binaryin 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.
| Subject | What claiming it means |
|---|---|
admission | which commits may become a release at all |
bit-for-bit | the same inputs produce the same output bytes |
integrity | the bytes you have are the bytes that were published |
inventory | what went into the artifact |
none | produces or publishes an artifact; establishes nothing on its own |
origin | which workflow, at which commit, on which runner built it |
The steps a release runs
| # | Step | Subject | What it settles |
|---|---|---|---|
| 1 | actions/checkout | none | Fetches the tagged tree, deep enough that the tag gate below can read origin/main out of it. |
| 2 | DeterminateSystems/nix-installer-action | none | Installs Nix. The build’s determinism rests on the sandbox this provides, not on the runner image. |
| 3 | nix-community/cache-nix-action | none | A 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. |
| 4 | actions/cache | none | The cargo registry cache. Outside the Nix sandbox, so it feeds no shipped byte — nix build vendors from Cargo.lock. |
| 5 | sigstore/cosign-installer | none | Installs the signer. Its pin is part of the trust base: this is the code that holds the OIDC token. |
| 6 | resolve tag | admission | Shape, 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. |
| 7 | build the 14 reproducible firmware flavors | none | Produces the images. A build alone establishes nothing — it is the rebuild below that turns it into evidence. |
| 8 | reproducibility gate — rebuild all 14, require bit-identical | bit-for-bit | Recompiles 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. |
| 9 | generate the CycloneDX SBOM | inventory | The firmware crate’s dependency tree, scoped to the shipped target. |
| 10 | checksums | integrity | A 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. |
| 11 | attest build provenance | origin | GitHub 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. |
| 12 | attach the provenance bundle as a release asset | none | An offline copy of the attestation. The API and Rekor stay authoritative; immutable releases forbid adding it later, so it is attached at create time. |
| 13 | sign SHA256SUMS (keyless cosign) | integrity | Keyless cosign over the checksum file. No private key exists: the signer is this workflow’s OIDC identity. |
| 14 | extract release notes from CHANGELOG | none | Extracts the version’s CHANGELOG section. Cosmetic, and capped because an oversized body fails the job after the tag is already pushed. |
| 15 | create the GitHub Release | none | Publishes 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.
| Flavor | Published as | Build selection |
|---|---|---|
firmware | rs-key-<tag>-default.uf2 | no flags, no knobs |
firmware-pqc | rs-key-<tag>-pqc.uf2 | --features advertise-pqc |
firmware-fips | rs-key-<tag>-fips.uf2 | --features fips-profile |
firmware-fips-pqc | rs-key-<tag>-fips-pqc.uf2 | --features fips-profile,advertise-pqc |
firmware-strong-pin | rs-key-<tag>-strong-pin.uf2 | --features strong-pin |
firmware-strong-pin-pqc | rs-key-<tag>-strong-pin-pqc.uf2 | --features strong-pin,advertise-pqc |
firmware-always-uv | rs-key-<tag>-always-uv.uf2 | --features always-uv |
firmware-always-uv-pqc | rs-key-<tag>-always-uv-pqc.uf2 | --features always-uv,advertise-pqc |
firmware-strict-up | rs-key-<tag>-strict-up.uf2 | --features strict-up |
firmware-strict-up-pqc | rs-key-<tag>-strict-up-pqc.uf2 | --features strict-up,advertise-pqc |
firmware-display | rs-key-<tag>-display.uf2 | --features display, flashSize = "16M", ledKind = "none" |
firmware-2mb | rs-key-<tag>-2mb.uf2 | flashSize = "2M", kvmain = "896K" |
firmware-16mb | rs-key-<tag>-16mb.uf2 | flashSize = "16M" |
firmware-strict-config | rs-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.
| File | sha256 |
|---|---|
.github/workflows/release.yml | 9f4218cfb9869bc458be8076f2185af6bdb734598db9b49167557dca30324a05 |
.github/workflows/release-build.yml | dfe836938a828195cbf05b84d963d2cea735b9acbcdb616dfd30f91ef3a9da2a |
nix/firmware.nix | 24ade38891f82bdc18bffc560affc3666f45b9cf7b1c148c1535c8c883fd9e7c |
scripts/build.sh | 48059de27f8d63748ab2aeb23cca71e84e93d281330be219e7b7a7130f923db4 |
The CI code that runs them, pinned by commit:
| Action | Pin | Release |
|---|---|---|
actions/checkout | 3d3c42e5aac5ba805825da76410c181273ba90b1 | v7.0.1 |
DeterminateSystems/nix-installer-action | 3138316df39ed29be04236d7ffc686fa525866aa | v23 |
nix-community/cache-nix-action | 7df957e333c1e5da7721f60227dbba6d06080569 | v7.0.2 |
actions/cache | 55cc8345863c7cc4c66a329aec7e433d2d1c52a9 | v6.1.0 |
sigstore/cosign-installer | 756fe2d284c7292c4e9b62c8a28f1e5629c59532 | v4.1.3 |
actions/attest-build-provenance | 4d101475d8b20a2381f78447822ac1eab6504dd8 | v4.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:andenv: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-depthandCOSIGN_YESare 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
subjectcolumn 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 arelease-build.ymlrun: the tag, the commit, the runner, the per-.uf2sha256 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->binaryis established by nothing here.PLAT-TOOLCHAIN-001inassurance/platform.tomlowns it and is stillpending. 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-Keyat a release tag that was pushed: a release, expected.TheMaxMur/RS-Keyat 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-vetof 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:
| Transport | Used by | Out of the box? |
|---|---|---|
FIDO HID (0xF1D0) | WebAuthn, ssh ed25519-sk, fido2-token, python-fido2 | yes, 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
getInfoworks as a plain user over SSH once the udev rule below is in place, andgpg --card-statusworks withdisable-ccid.ykman infoworks the same way on the opt-inVIDPID=Yubikey5build (it gates on theYubico YubiKeyreader 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) presents0x1050: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.txtbefore the build; on an FHS distro, edit/usr/lib/pcsc/drivers/ifd-ccid.bundle/Contents/Info.plist, which holdsifdVendorID,ifdProductIDandifdFriendlyNameas three parallel arrays — add one entry to each, at the same position, or the mapping shifts. Restartpcscdand 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)
-
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
- Debian/Ubuntu:
-
Enable pcscd:
sudo systemctl enable --now pcscd.socket -
udev rules. The stock yubico rules that ship with
libfido2/yubikey-personalization/libu2f-hostmatch VID0x1050only, 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 triggerand re-plug. (Alternatively, buildVIDPID=Yubikey5to reuse the stock yubico rules unchanged.) If your user still can’t open the device, confirm you’re in the right group (plugdevon Debian/Ubuntu). -
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 ofsubject.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(orykman, on theVIDPID=Yubikey5build) says no reader, or “Failed to connect”:scdaemon(from a priorgpg) is holding the reader exclusively.gpgconf --kill scdaemon, then retry. Thedisable-ccid+pcsc-sharedconfig above prevents the recurrence.ykmandoes not see the device at all:ykmanderives the device purely from the PC/SC reader name, which must containYubico YubiKey. The default RS-Key build names the readerRS-Key Security Key, soykmanwill not recognize it. Build the opt-inVIDPID=Yubikey5flavor (reader nameYubico YubiKey RSK OTP+FIDO+CCID) to useykman(see build.md).- Everything hangs after heavy USB debugging: the
pcscd+scdaemon+ kernel USB stack can wedge in a way that survivingpcscd/scdaemonrestarts 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(oropensc-tool -l) should listRS-Key Security Keyon the default build (orYubico YubiKey RSK OTP+FIDO+CCIDon the opt-inVIDPID=Yubikey5build). On that opt-in build,ykman infoshould report5.8.0with 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:
| Transport | Used by | Out of the box? |
|---|---|---|
FIDO HID (0xF1D0) | WebAuthn, ssh ed25519-sk (see ssh.md), browser passkeys | yes — Windows drives it through the built-in webauthn.dll, no driver install |
| CCID (PC/SC) | OpenPGP (gpg / Kleopatra), PIV, OATH, Yubico-OTP | yes — 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
scdaemonclaims 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:
-
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. -
Let
scdaemonshare the reader. By defaultscdaemoncan 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-ccidThen reload it from a terminal:
gpgconf --kill scdaemonpcsc-sharedis the key line (share the reader instead of taking it exclusively);disable-ccidforcesscdaemononto the Windows PC/SC stack rather than its own internal CCID driver. Re-plug the board afterwards. -
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 throughykcs11and 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, useykman piv objects generate chuidorykman piv objects generate cccto 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 scdaemonreleases agpg-held handle. gpg --card-statusand another PC/SC tool cannot coexist: apply thepcsc-shared+disable-ccidconfig above, thengpgconf --kill scdaemon.ykmandoes not see the device:ykmanmatches on the PC/SC reader name containingYubico YubiKey, which the default RS-Key build does not present. Build the opt-inVIDPID=Yubikey5flavor (reader nameYubico YubiKey RSK OTP+FIDO+CCID) to useykman(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
| Group | What it does | Guide |
|---|---|---|
status | one-shot device overview (FIDO getInfo + secure-boot + backup) | quickstart |
inventory | fleet enumeration (list) + identity proof (verify) | Fleet tooling |
identify | blink a key’s indicator so you can tell it from the others plugged in | LED |
backup | wallet-style seed export / restore / finalize (BIP-39, SLIP-39) | Seed backup |
pair | guided primary + backup (two independent keys) enrollment | Backup key |
lock | at-rest soft-lock of the FIDO seed (enable/unlock/disable) | Soft-lock |
flash | check a release image (signature, checksum, provenance), then write it over BOOTSEL | Supply chain |
secure-boot | secure-boot provisioning + key rotation (irreversible) | Production, OTP fuses |
otp | burn and verify keys, automatically seal at boot; otp status reads the result (burn/seal irreversible) | OTP fuses |
fido | FIDO2 management: set-pin, list-passkeys, attestation | FIDO2, Attestation |
led | LED color / brightness per device state | LED |
openpgp | OpenPGP applet utilities (e.g. reset to factory PINs) | OpenPGP card |
reboot | reboot to the app or to BOOTSEL, over CCID | — |
audit | read + cryptographically verify the tamper-evident journal | Audit journal |
offboard | guided full wipe + signed receipt; prompts for a replug (destructive) | Fleet tooling |
Note the two distinct “OTP“s:
rsk otpburns 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 withykman. 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 restoreaudit log/audit verifylock enable/lock disableinventory verifyfido list-passkeys,fido attestation import/clearfido set-pin:--pinis the current PIN when changing.--new-pinsets 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
- A linear first-run walkthrough: Quick start.
- The read-mostly TUI companion: Terminal cockpit.
- Each task in depth via the Command groups table above.
For contributors
The CLI lives in tools/rsk/: one module per group, each exposing a
register(sub) that adds its argparse subparser, wired together in
__main__.py. Shared helpers (error exit, the --pin flag + PIN resolution,
the picotool runner, the FIDO HID connect) live in common.py. The raw CTAPHID
transport and CBOR codec are in ctaphid.py.
PIN entry goes through one chokepoint, common.resolve_pin (flag-or-prompt)
and common.add_pin_arg (the shared flag), so consistency is structural, not
per-command discipline. The pure-logic unit tests need no device:
# from tools/ (or: uv run --extra test python -m pytest …)
nix develop -c bash -c 'cd tools && python -m pytest rsk/'
Host-tool changes like these do not bump the firmware bcdDevice. See
Versions.
FIDO2 / WebAuthn / U2F
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 | |
|---|---|
| Length | 4–63 characters (6–63 on the fips-profile build), counted in Unicode code points — 密码 is two, not six |
| Per-power-cycle | 3 wrong attempts → PIN_AUTH_BLOCKED (0x34), re-plug to retry |
| Retry budget | 8 wrong attempts (across power cycles) |
| On exhaustion | PIN 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 alg | Curve / scheme | Notes |
|---|---|---|
-7 ES256 | NIST P-256 | the universal default |
-8 EdDSA | Ed25519 | |
-35 ES384 | NIST P-384 | slow keygen/sign (pure-Rust arithmetic) |
-36 ES512 | NIST P-521 | slow keygen/sign |
-47 ES256K | secp256k1 | dropped 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:
| Extension | What it does | Limit |
|---|---|---|
hmac-secret | per-credential secret keyed by a salt (the WebAuthn PRF maps onto it) | 32-byte output |
hmac-secret-mc | the same evaluation at registration time | |
credProtect | UV-gated credential visibility (levels 1–3) | |
credBlob | small opaque blob stored with the credential | 128 bytes |
largeBlobKey + large blobs | per-credential key into a device blob store | 4 KB store |
largeBlob (CTAP 2.3) | the blob itself, per credential, inside the assertion | 4046 B/credential; replaces the row above, largeblob-ext build only |
minPinLength | the device hands its PIN-length policy to an authorized RP | |
pinComplexityPolicy | tells an authorized RP whether trivial PINs are refused | registration only |
uvm | signed record of the presence and PIN methods used | registration and authentication |
thirdPartyPayment | the 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 answersfmt: "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. Arsk rebootdoes 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 withykman fido credentials delete(needs theVIDPID=Yubikey5build) or your browser/OS passkey manager. rsk fido …says “missing dependency: python-fido2”. Runrskfrom insidenix develop. The management commands need thepython-fido2library.- 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-keygenPIN / 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 type | Algorithm | Use it when |
|---|---|---|
ed25519-sk | Ed25519 (EdDSA) | the default: smallest, fastest |
ecdsa-sk | NIST P-256 (ES256) | a server or old client rejects ed25519-sk |
Requirements
- OpenSSH 8.2+ for
-skkeys (8.3+ to download resident keys with-K). - A FIDO middleware: distro OpenSSH links
libfido2; check withssh -Q key | grep sk. - macOS: Apple’s
/usr/bin/sshships without FIDO support and fails withPermission deniedbefore touching the device. Use Homebrew OpenSSH:brew install openssh export PATH="/opt/homebrew/opt/openssh/bin:$PATH" # ahead of /usr/bin - Linux: OpenSSH links
libfido2almost everywhere; you only need the FIDO udev rules (see linux.md). FIDO is local to whereversshruns, so logging in to a remote box needs nothing special there. - Windows: OpenSSH for Windows routes
-skkeys through the Windows WebAuthn API (webauthn.dll), which only offers algorithms the device advertises in its FIDOgetInfo.ed25519-skneeds firmware that advertises EdDSA: RS-KeybcdDevice 0x077Dor newer (seersk status). On older firmwareed25519-skfails at create with a generic error whileecdsa-skstill works, so either reflash or useecdsa-sk. macOS and Linux talk tolibfido2directly 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, forauthorized_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 option | Effect |
|---|---|
resident | store the key on the device so it can be downloaded later (see below) |
verify-required | demand the FIDO PIN on every login, not just a touch |
application=ssh:NAME | tag the credential (default ssh:); a distinct string is a distinct key |
user=NAME | user handle stored with a resident key (for listing/telling them apart) |
no-touch-required | mark the key as not needing a touch; see the note below |
write-attestation=FILE | save the enrollment attestation for later verification |
challenge=FILE | use 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-requireddoes nothing useful on RS-Key. The default (touch) build always polls the button on every assertion. The firmware does not honorup: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.
| Action | PIN | Touch |
|---|---|---|
Enroll (ssh-keygen -t …-sk) | once | once* |
| Log in, normal key | — | once |
Log in, verify-required key | once | once |
* 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 deniedinstantly on macOS → you are on/usr/bin/ssh; use the Homebrew binary (above).Key enrollment failed: requested feature not supported→ the client lacksed25519-skmiddleware; installlibfido2/ Homebrew OpenSSH, or fall back to-t ecdsa-sk.device not found/ no prompt → FIDO udev rules missing (linux.md), or a browser /gpg-agentis 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-pinand retry. sign_and_send_pubkey: signing failedon login → the wrong device is plugged in, or the key is resident on a device you reset. Re-plug the right key, orssh-add -Kagain.- After a factory FIDO reset, old
id_*_skfiles 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 signing | OpenPGP signing | |
|---|---|---|
| Key | your -sk SSH key (ssh.md) | a key on the OpenPGP card (openpgp.md) |
| Needs | git 2.34+, nothing else | gpg + scdaemon |
| Trust model | an allowed_signers file you curate | the OpenPGP web of trust |
| Touch / PIN | touch per signature | PIN once, then touch per signature (UIF) |
| Best when | you only want commit signing, no GPG | you 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 falsefor 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-signskips signing for a one-off commit.
Troubleshooting
error: gpg failed to sign the data(SSH mode) →gpg.formatisn’tssh, oruser.signingkeypoints at a missing file. Re-check both.git verify-commitsays “No signature” but the commit is signed → theallowed_signersfile isn’t configured (above).- OpenPGP:
No secret key/selecting card failed→scdaemonlost the reader (often afterykman/another tool grabbed it):gpgconf --kill scdaemonand 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 pushsaysPermission 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 withgit remote -vandssh -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
| Default | Length | Unlocks | |
|---|---|---|---|
| User PIN (PW1) | 123456 | 6–127 | signing, decryption, authentication |
| Admin PIN (PW3) | 12345678 | 8–127 | key import/generation, card settings |
| Reset Code (RC) | unset | 8–127 | unblocking 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-retriesgave 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 hand123456to 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
passwdoption 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 RETRYthen answers6A80whatever 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):
| Family | Choices | Notes |
|---|---|---|
| ECC (sign/auth) | Ed25519, NIST P-256 / P-384 / P-521, secp256k1, brainpoolP256r1 / P384r1 | EdDSA on Ed25519; ECDSA on the Weierstrass curves |
| ECC (encrypt) | Cv25519 (X25519), NIST P-256 / P-384 / P-521, secp256k1, brainpoolP256r1 / P384r1 | ECDH; the DEC slot only |
| RSA | 2048 / 3072 / 4096, plus 1024 | exponent 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:
| Size | Typical on-card keygen |
|---|---|
| RSA-2048 | ≈ 4–6 s |
| RSA-3072 | ≈ 22 s |
| RSA-4096 | ≈ 50 s |
| any EC curve | instant |
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’sdisable-ccid, thengpgconf --kill scdaemon.ykmanstops seeing the device after gpg used it → same fix; gpg’s scdaemon holds the reader.gpgconf --kill scdaemonreleases it.- A card refusal on
keytocard/generate(gpg may report “Function not supported”, “Wrong data”, or “Security status not satisfied”) → the slot’skey-attrdoesn’t match the key, or you skippedadmin(no PW3 session). gpg --card-statusshowsPIN retry counter : 0 …→ that PIN is blocked; see Recovery and reset.- RSA
generateseems 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-inVIDPID=Yubikey5build:ykmanonly sees the device when the reader name contains “Yubico YubiKey”) →ERROR: Incorrect TLV lengthon firmware before0x0759: the GET DATA6Ereply was missing its constructed-DO wrapper, which ykman’s strict parser requires (gpgtolerated it). Fixed in0x0759; 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
| Default | Notes | |
|---|---|---|
| PIN | 123456 | 6–8 chars; padded to 8 with 0xFF on the wire |
| PUK | 12345678 | 6–8 chars; unblocks a blocked PIN |
| Management key | 010203040506070801020304050607080102030405060708 | AES-192, the well-known YubiKey 5.7-era default |
| PIN / PUK retries | 3 / 3 | resets 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 --protectre-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 rawSET MANAGEMENT KEYAPDU,yubico-piv-tool): the card then holds a key only the hex string opens, andykman piv inforeports 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 aPRINTED-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
0x08D1aCHANGE REFERENCE DATA/RESET RETRY COUNTERbody 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 byykman piv access unblock-pin(the PUK still works), and a shortened PUK alone byykman 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 runykman 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
| Slot | Role | Typical use | Default PIN policy |
|---|---|---|---|
9a | PIV Authentication | system / domain login, SSH, client TLS | once per session |
9c | Digital Signature | document & email signing | every operation |
9d | Key Management | decryption, key agreement (ECDH) | once per session |
9e | Card Authentication | physical-access / contactless | no PIN |
82–95 | Retired Key Management | 20 slots for old decryption keys | once per session |
9b | Management Key | admin auth (not an asymmetric key) | — |
f9 | Attestation | signs 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-policy | Effect |
|---|---|
NEVER | no PIN to use the key (default for 9e) |
ONCE | PIN once per session (default for 9a/9d/retired) |
ALWAYS | PIN 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-policy | Effect |
|---|---|
NEVER | no button press — the default, for slot keys and the 9b management key alike |
ALWAYS | a physical touch before every private-key operation |
CACHED | treated 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.
CACHEDis treated asALWAYS. 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 setCACHED, expectALWAYSbehaviour.
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:
| Object | Name |
|---|---|
5FC103 | Cardholder Fingerprints |
5FC108 | Cardholder Facial Image |
5FC109 | Printed Information |
5FC121 | Cardholder 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’sopensc-pkcs11.so, found at/usr/lib/x86_64-linux-gnu/opensc-pkcs11.soon Debian,/usr/lib/opensc-pkcs11.soon 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-skhardware 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. -
ageencryption:age-plugin-yubikeydrives PIV slots directly for identity files but, likeykman, keys off the “Yubico YubiKey” reader name, so it wants the opt-inVIDPID=Yubikey5build; on the default RS-Key build use any PKCS#11-awareagebuild againstopensc-pkcs11.so. age.md covers the other route, over FIDO2, which needs neither. -
ECDH / key agreement (
9dand retired slots, P-256/P-384 and X25519):ykman piv ...exposes it (ykman piv keys calculate-secretfor X25519); at the wire level it is GENERAL AUTHENTICATE with tag0x85, the operationyubico-piv-tooland OpenSC use for decryption. -
Windows / macOS native smart-card stacks pick the PIV applet up as-is; macOS CryptoTokenKit binds its
pivtoken.appexto 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
ykmancan’t connect → linux.md (pcscd + polkit + thedisable-ccidscdaemon note).ykmanstops seeing the card aftergpgused it →scdaemongrabbed the raw CCID interface; applydisable-ccidandgpgconf --kill scdaemon(openpgp.md).- PIN blocked →
ykman piv access unblock-pin(needs the PUK). PUK blocked too → onlyykman piv resetrecovers, and it wipes the slots. ykman piv keys attestfails withINCORRECT PARAMS→ the key in that slot was imported, not generated; attestation is generated-keys-only.change-management-keyrejects 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-secretunwraps anageidentity 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:
- finds the token (it waits up to 50 s, so plug in whenever),
- asks for the FIDO PIN, but only if one is set on the device,
- asks for a touch, and mints the credential,
- asks whether to require the PIN for decryption — again only if a PIN is set, otherwise decryption is touch-only,
- 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:
-a | COSE | On RS-Key |
|---|---|---|
es256 | −7 | the default, works |
eddsa | −8 | works on every shipped build |
rs256 | −257 | refused. 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
| Action | FIDO PIN | Touch |
|---|---|---|
-g enrollment, no PIN on the device | — | once |
-g enrollment, PIN set | once | once |
Encrypt (age -R) | — | — |
| Decrypt, require-PIN answered no | — | once |
| Decrypt, require-PIN answered yes | once | once |
On an
always-uvbuild, answer yes. The shipped image leavesalwaysUvoff, so the touch-only path above is the default. Build with--features always-uv(or flip it withykman fido config toggle-always-uv) and amakeCredentialcarrying no PIN token is refused whatever else it asks for — seetests/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. Itsrequire_reasonpolicy defaults to"agents", and every command above is refused in an environment it reads as one until you pass--reason "<why>"or setSECRETSPEC_REASON. Putrequire_reason = falsein[project]to switch it off. - Everyone on the roster reads the whole blob.
agerecipients 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 | |
|---|---|---|
| Transport | CTAPHID | CCID / PKCS#11 |
| Stock build | works | wants the VIDPID=Yubikey5 build, or opensc-pkcs11.so — the plugin matches on the reader name |
| Key at decryption | identity in host RAM | private key stays on the card |
| Device state | none — non-discoverable credential | occupies a PIV slot |
| Recipients per token | unlimited | one 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 partyage-encryption.org, non-discoverable,hmac-secret) is served fores256andeddsaand refused forrs256. Credential ids came back at 131 and 135 bytes.getAssertionreturns a 32-bytehmac-secretoutput, identical across calls for one salt and different for another — the contract the plugin checks before it will unwrap anything.tests/24_extensions.pyasserts the same thing as part of the suite.- secretspec’s
ageprovider round-tripsset/get/run/checkwith a plain identity and the provider declared insecretspec.tomlas above, and it spawnsage-plugin-fido2-hmac --age-plugin=identity-v1when 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(oraccounts uriif they give the fullotpauth://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:
| Option | Effect | Default |
|---|---|---|
--touch | computing this account’s code needs a button press | off |
--oath-type {TOTP,HOTP} | counter-based vs time-based | TOTP |
--algorithm {SHA1,SHA256,SHA512} | HMAC hash | SHA1 |
--digits {6,7,8} | code length | 6 |
--period N | TOTP step in seconds | 30 |
--counter N | HOTP starting counter | 0 |
--force | overwrite 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--touchare for. - There is no recovery for a forgotten access password short of
ykman oath reset, which wipes every account with it. --touchper 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
6A80and nothing is stored — in particular, a rejectedaddover an existing account leaves that account working instead of replacing it with one that can never produce a code.ykmanand 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 oathand Yubico Authenticator) is tracked in the OATH interop results.
Troubleshooting
ykmanfinds no reader / “Failed to connect”: on Linux this is almost alwaysscdaemonholding the CCID interface after agpgcall. Apply thedisable-ccidline from linux.md and rungpgconf --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 (ykmandoes), or pad a 16-character secret yourself: remove the spaces and appendAAAAAAA. That is the same key zero-padded to 14 bytes, so the codes do not change. A client that sends the touch property as78 01 02instead of the bare78 02pair 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 resetis 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 otpneeds the opt-in Yubico flavor.ykmangates on the “Yubico YubiKey” reader name. Only the opt-inVIDPID=Yubikey5build presents it. The defaultRSKeybuild (VID:PID0x1209: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 overykmanneeds 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.
| Clicks | Slot | ykman otp |
|---|---|---|
| 1 (short) | 1 | yes |
| 2 | 2 | yes |
| 3 | 3 | slot-offset APDU only |
| 4 | 4 | slot-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:
| Type | On button press | Over USB (ykman otp calculate) |
|---|---|---|
| Yubico OTP | types a 44-char modhex OTP | — |
| Static password | types the stored password | — |
| OATH-HOTP | types the 6/8-digit code | — |
| Challenge-response (HMAC-SHA1) | nothing | answers the challenge |
| Challenge-response (Yubico mode) | nothing | answers 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-iduses the device serial as the public id,-g/--generate-private-idrandomises the private id,-G/--generate-keyrandomises the AES key. All three together give a self-contained random credential.--lengthon a static slot is the typed-password length, max 38 characters (the slot stores 38 password bytes).--length 38fills it. By defaultstaticonly 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, orrsk-wipeflashed 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
0x1209build is invisible to it — build the firmware withVIDPID=Yubikey5(see build.md). - libusb access to the device. Install Yubico’s udev rules
(
69-yubikey.rules/70-yubikey.rules, packaged asyubikey-personalizationon 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 andykchalresp -Halready 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-keyprints 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 infohangs 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 infoshows 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 statusshows it); a key whose store is genuinely failing needs re-provisioning. ykman otp calculatereturnsCONDITIONS_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 otponly enumerates 1 and 2. - A configure / update / swap /
set-scan-mapfails 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 aswapwrites 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 infoshows which case you are in; re-run the command from there. - KeePassXC on Linux says
Hardware key USB error: Pipe error, orykchalrespfails whileykman otp calculateworks → firmware older than bcdDevice0x0859enumerated 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
--touchslot works fromykmanbut not from KeePassXC, and afterwards evenykinfofails for half a minute → firmware older than bcdDevice0x085Bstayed 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
calculateon 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:
- Give each device its own PIN (in your browser / OS security-key settings).
- Back up each seed separately. Two independent seeds means two different
mnemonics (seed-backup.md). Do
rsk backup exportwith each device, thenrsk backup finalize. - 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.
- Store the backup key somewhere separate from the primary (a different building is ideal, since fire and theft take whatever is in one place).
- 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 paircan’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 exportboth 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:
- Sign in with the surviving key. It is already enrolled everywhere.
- 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.
- Get a new key and make it the new backup.
rsk pairagain 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 pair | Seed-backup mnemonic | |
|---|---|---|
| What it protects | live access, a second key already enrolled | one identity, recoverable later |
| Recover by | grabbing the backup key (no steps) | restoring the phrase onto a new board |
| Secret exposure | none shared, two independent seeds | the seed passes through the host at export |
| Covers passkeys / PIV / OpenPGP | enroll them on each key | no (sealed to the chip) |
| Cost | register both keys everywhere | write 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:
--scheme | What it prints | Reconstruct with |
|---|---|---|
bip39 (default) | 24 words | the same 24 words |
slip39 | Shamir shares (--threshold/--shares, default 2-of-3) | any threshold shares |
hex | 64 hex characters | the 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:
| Flag | Meaning |
|---|---|
sealed | the one-time backup-export window is closed (seed-backup.md) |
has_seed | a plaintext-sealed seed is on flash (false while locked) |
locked | the wrapped blob is what’s stored — an unlock is required |
unlocked | a 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(firmwareBACKUP_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 exportserves 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.
| Knob | Default | When to change it |
|---|---|---|
LED_KIND | ws2812 | ws2812 (addressable RGB, default), gpio (plain on/off), pimoroni (3-pin PWM RGB), or none (no indicator). See build.md. |
LED_PIN | 16 | A board whose addressable LED is on a different GPIO (0..=29). |
LED_ORDER | rgb | A WS2812 board with swapped red/green: set grb (the WS2812B standard). The Waveshare RP2350-One is rgb; most other parts are grb. |
MAX_LEDS | 1 | A 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.
| Effect | ID | What you see | Suits |
|---|---|---|---|
legacy | 0 | Classic on/off blink (TIMING table) | Original blink behaviour |
vapor | 1 | All LEDs breathe together, smooth triangle-wave brightness | Idle (default) |
bounce | 2 | A wide hump of light glides back and forth with half-step interpolation | Touch (default) |
flow | 3 | Yellow→red gradient flowing left to right with a trailing wake | Processing (default) |
sparkle | 4 | Each LED flashes an independent random colour | Boot (default) |
Default mapping (multiple LEDs)
| State | Default effect | Default colour | Means |
|---|---|---|---|
| idle | vapor: gentle breathing | green | ready, nothing in flight |
| processing | flow: warm-colour flow | yellow→red gradient | handling an APDU / crypto op |
| waiting for touch | bounce: smooth bounce | yellow | press the button to confirm |
| boot | sparkle: random sparkle | red | the 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
touchcannot 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 offon--status touchbecomes the default yellow.--brightness 0on--status touchis raised to8.--speed 1is raised to2. At1the 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
--steadymode or on a one-LED board.Every other state still goes fully dark on
--brightness 0.rsk led --getshows what the device is actually rendering, so read it back after a write that hits one of these rules.
There is one case where touch gives way instead. If the state wearing the touch
colour has that colour as its own factory colour, resetting it would not resolve
the clash, so touch reverts to its factory look (yellow, bounce). Only boot
(red) and idle/processing (green) can trigger that:
rsk led --status touch --color red # sticks — unless boot is red
rsk led --status touch --color green # sticks — unless idle or processing is green
rsk led --status boot --color blue # …then a red touch is legitimate and kept
What this does not promise. Two states in different colours can still be
hard to tell apart. On a single-colour (gpio) build hue collapses to lit or
unlit; red, green and yellow are mutually confusable under red-green colour
blindness; and on a one-LED board bounce, flow and steady mode all render the
same solid frame. What separates the states there is the per-state blink timing
(touch 1000/100 ms vs idle 500/500 ms), which no host write can change — but
--steady suppresses blinking altogether, so on a single-colour build it leaves
nothing to distinguish them. If the consent signal has to be unambiguous, use a
trusted-display build, which names the operation on screen.
Effect & speed
Each state’s effect and animation speed are configurable the same way:
rsk led --status idle --effect vapor # change the effect
rsk led --status touch --effect bounce --speed 15 # custom speed (ticks per step)
rsk led --status processing --effect legacy # revert to classic on/off blink
--speed 0 (or omitting --speed) uses the effect’s built-in default.
Steady / blink
--steady and --blink are global, not per-state: the firmware keeps each
state’s timing internally, but a single flag decides whether any of them
blink. --steady makes the whole indicator a solid lamp whose colour tracks
the current state. --blink brings the blink patterns back.
rsk led --status idle --color cyan --steady # solid cyan at idle, no pulse
rsk led --blink # back to the blink patterns
rsk-tui has a “cycle idle color” action that steps the idle state through
the palette, plus “Read LED state”. For per-state colour, brightness, or the
steady toggle, use rsk led.
Identify (CTAPHID wink)
A host can ask the key to point at itself — CTAPHID_WINK — which is how you tell
two identical keys apart when both are plugged in. The indicator answers with four
fast blinks over about half a second in the touch colour, then goes back to
whatever it was showing.
rsk identify # wink every attached key in turn, naming each
rsk identify --repeat 3 # three bursts each, if you looked away
rsk-tui has the same thing as “Identify this key” in Overview — that one winks
the device the dashboard is showing, rather than walking them all.
The burst deliberately overrides the configured effect and --steady: the
command is only useful if the key visibly flashes. It also uses the touch
colour because that is the one state rsk led keeps above a visibility floor,
so a key dimmed everywhere else still answers something you can see.
Two bounds follow from borrowing that colour. Repeated WINKs do not extend a burst already running — it always ends 600 ms after the first one — and a WINK arriving while the key is waiting for a touch shows the real prompt, not the burst. Without both, a host could hold the awaiting-touch indicator lit and forge the one consent signal a build without the display has.
A build with no indicator (LED_KIND=none, which includes the display build)
does not advertise the wink capability at all, rather than accepting the command
and doing nothing.
Selectors and values
| Flag | Values |
|---|---|
--status | idle, processing, touch, boot (default idle) |
--color | off, red, green, blue, yellow, magenta, cyan, white |
--brightness | 0–255 per channel (0 = off, except --status touch, see above) |
--effect | legacy, vapor, bounce, flow, sparkle |
--speed | 0–255 (0 = effect’s built-in default; 1 is raised to 2 on --status touch) |
--steady | solid colour, no blinking, global, affects every state |
--blink | the 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 intoP1and colour + the steady bit + the target state intoP2. 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 rightLED_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 withLED_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 withMAX_LEDS=<n>. rsk ledcan’t reach the device. It needs the CCID interface up (pcscdon Linux). Ifgpg --card-status/rsk statusalso 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 revision | Touch controller | I²C address | Nix package |
|---|---|---|---|
| V1 | CST328 | 0x1A | firmware-display |
| V2 | CST3530 | 0x58 | firmware-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 --signit 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:
| Tab | What it shows |
|---|---|
| Home | A calm “Ready” and a status card: USB, whether a device PIN is set, and the resident-passkey count (cached, refreshed only at modal boundaries). |
| Passkeys | The resident credentials, one row per relying party. |
| Apps | A read-only browser for the OpenPGP / PIV / OATH applets. |
| Settings | Display, 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 apinUvAuthTokenviaclientPIN(getPinUvAuthTokenUsingUvWithPermissions), checked against the sameEF_PINthe hostclientPINpath uses. A platform can also skip the token:makeCredential/getAssertioncarryingoptions: {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 setsupwithout 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. WithalwaysUvon, a request that brings nopinUvAuthParamtakes the same route instead of being refused withPUAT_REQUIRED. Declining on the pad ends the operation withOPERATION_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
bPINSupportand handlesPC_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
alwaysUvis 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. TurningalwaysUvon 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_DISPLAYflash record; the touch timeout inEF_PHY’sPresenceTimeout, the same fieldrsk hw --touch-timeoutwrites, 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
changePINcheck: a wrong entry spends a retry and ends anypinUvAuthTokena 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--protectscheme, 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 hostPivmanData(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
bcdDevicebuild 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-NSLIP-39 share set on the trusted screen, derived on the device, never crossing USB, behind a hold + warning, wiped the instant they’re shown. Seal backup closes the window for good (until a factory reset). See seed-backup.md.
- Factory reset: erases every applet’s data (FIDO, PIV, OpenPGP, OATH), scrubs the flash, and reboots to a blank device (gated by the device PIN, then a hold). Only the org attestation and the fused OTP / secure-boot state survive.
A display build is also exempt from the power-up window
that makes a screenless key refuse a host authenticatorReset more than ten
seconds after it was plugged in. That window exists to stop a wipe being approved
by a press collected under some other pretext; here the panel names the operation,
so a host reset is accepted whenever you confirm it on screen — no replug.
Security model
The device PIN (EF_DEVICE_PIN, its own sealed record + retry counter) gates the
on-device UI (unlock, on-device delete, factory reset) independently of FIDO.
The device boot-locks when a device PIN is set. A forgotten device PIN is
cleared only by a host authenticatorReset (the sole recovery, since the lock
gates on-device Settings). Every device-driven ceremony (a granted Approve, an
on-device delete, a factory wipe) ends on a brief success confirmation.
This is an experimental variant. Read threat-model.md and limitations.md for what the trusted display does and does not defend against.
See also
- Build options: the
displayfeature and its knobs. - Hardware: boards and flashing.
- Host protocol §1.3: CCID pinpad secure PIN entry.
- FIDO2 / WebAuthn · PIV · OpenPGP · Seed backup.
rsk-tui — the terminal cockpit
rsk-tui is a host-side dashboard for an RS-Key. It talks to the device
directly (CTAPHID over hidapi and the CCID applets over PC/SC), so it does not
shell out to rsk or any other process. It lives in its own workspace
(tools/tui), separate from the firmware, and links the host PC/SC and HID
stacks.
It is a companion to the rsk CLI, not a replacement: the cockpit covers the
safe, day-to-day reads and a few in-band actions (LED, seed backup, reboot,
audit, identity verify). Irreversible production rituals (secure-boot staging,
OTP fuses, factory resets, soft-lock, attestation import) stay in the CLI on
purpose. The cockpit points you at the exact command instead of doing them.
flowchart LR
tui["rsk-tui (host process)"] -->|hidapi / CTAPHID| fido["Device — FIDO"]
tui -->|PC/SC / pcscd| ccid["Device — CCID applets<br/>OpenPGP · PIV · OATH · OTP"]
Running it
In the dev shell rsk-tui is on PATH:
nix develop .#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
| Flag | Effect |
|---|---|
| (none) | interactive cockpit |
--demo, --mock | interactive cockpit against a simulated device, no hardware needed |
--once | print the gathered status once (human-readable) and exit |
--json | one-shot machine-readable status (JSON) and exit |
--identify | blink this key’s indicator and exit (the Overview action, scripted) |
--selftest [PIN] | native backup export/restore round-trip (needs a no-touch build) |
-h, --help | usage |
--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
| Key | Action |
|---|---|
Tab / Shift-Tab, ← / → | switch section |
↑ ↓ or j k | move selection in the action list |
Enter | run the selected action |
r | refresh device status |
/ | search actions across all sections |
? | jump to Help |
Esc | cancel a modal / input |
q or Ctrl-C | quit (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
| Section | Reads (safe) | In-band actions |
|---|---|---|
| Overview | identity (serial, fw, bcdDevice, sdk, aaguid), transports, backup/lock/secure-boot/rollback/attestation/flash | Refresh, Verify identity |
| FIDO | CTAPHID presence, versions, clientPIN, options | Count resident passkeys (PIN · credMgmt) |
| OpenPGP | applet presence, card serial, PIN retries, populated key slots (from 6E) | — |
| PIV | applet presence, PIN retries + default-PIN flag (from GET METADATA) | — |
| OATH / OTP | applet presence | — |
| Backup | seed / sealed / lock state | Export (BIP-39 · SLIP-39 2-of-3), Restore, Finalize |
| LED | LED mode + per-state color/brightness, with a live colour swatch | Read state, Cycle idle color |
| Audit | journal head + checkpoint key hint | Read journal, Verify identity |
| Reboot / Maintenance | device summary | Reboot → app, Reboot → BOOTSEL |
| Help | key 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 reseton theVIDPID=Yubikey5build, 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, …). Theykmancommands gate on the “Yubico YubiKey” reader name, so they only see the device on the opt-inVIDPID=Yubikey5build;gpgandrskwork 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-treersk-slip39crate); 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-Cwipes 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--jsonserialization. No I/O.device.rs: native CTAPHID + PC/SC I/O behind aDeviceProvidertrait, withHardwareProvider(real) andMockProvider(--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
| event | detail |
|---|---|
BOOT | first journal touch of each power cycle |
MAKE_CREDENTIAL / GET_ASSERTION / U2F_REGISTER / U2F_AUTH | first 8 bytes of the rpIdHash (only weakly pseudonymous, see Gating). A run of the two silent variants folds — see below |
RESET | factory reset (survives it — see below) |
PIN_SET / PIN_CHANGE / PIN_LOCKOUT | lockout aux: 0 = retries exhausted, 1 = per-boot block |
CFG_MIN_PIN | aux = new minimum; detail[0] = forceChangePin |
CFG_ENTERPRISE_ATT | no aux/detail (flag-only) |
CFG_EA_RPIDS | the vendor-facilitated enterprise RP list was rewritten; aux = how many RPs it now holds, 0 = cleared |
LOCK_ENGAGE / LOCK_RELEASE | soft-lock engage/release |
BACKUP_EXPORT / BACKUP_LOAD / BACKUP_FINALIZE | seed-backup lifecycle |
ATT_IMPORT / ATT_CLEAR | org attestation provisioning |
CFG_ALWAYS_UV | alwaysUv toggled; no aux/detail (flag-only) |
CONFIG_WRITE | a 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_CFG | journalling itself: aux 1 = turned on, 0 = turned off (that entry is the last one written, so the trail shows when it stopped) |
CHECKPOINT | every 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_ASSERTIONfrom agetAssertioncarryingup:false— the spec-mandated silent pre-flight, which needs a credential but no gesture;U2F_AUTHfrom anAUTHENTICATEwithP1=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
BOOTentry between two runs is never swallowed. - A fold moves the chain head without advancing
seq_next. Seeing the sameseq_nextwith a different head is legitimate, not a tamper signal;verifyre-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
| command | open device | PIN set |
|---|---|---|
audit log / AUDIT_READ | touch | pinUvAuthToken with the acfg permission |
audit verify / AUDIT_CHECKPOINT | touch | touch + acfg pinUvAuthToken |
AUDIT_READ(export). With a PIN set it needs a pinUvAuthToken carrying theacfg(authenticator-config) permission. With no PIN it needs a physical touch. The entries are only weakly pseudonymous. Adetailis 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 isAUDIT_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
| symptom | meaning / 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 window | the journal changed between the read and the checkpoint. Rerun; if it persists, treat it as TAMPER |
checkpoint SIGNATURE INVALID — do not trust this journal | the signature did not verify under the returned key. Do not trust the log |
export length does not match the window | the 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.
verifyregularly 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
seqandBOOTmarkers 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 as | Holds | Sealing |
|---|---|---|
EF_ATT_KEY (0xCE10) | the org attestation P-256 private scalar | kbase-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:
| Limit | Value |
|---|---|
| Curve | P-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
enterpriseAttestation2 (platform-managed, sent by managed platforms) returns a full attestation: signature by the org key,x5c= your chain (leaf first), and theepresponse 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 noep. - 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
enterpriseAttestationrequest field andenableEnterpriseAttestationis 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 level | Without org key | With org key |
|---|---|---|
| (absent / 0) | basic, device cert | basic, device cert |
| 1 — vendor-facilitated, RP listed | basic, device cert, ep flag | full org attestation |
| 1 — vendor-facilitated, RP not listed | basic, device cert, no ep flag | basic, device cert, no ep flag |
| 2 — platform-managed | basic, device cert, ep flag | full 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:
| State | Survives 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--keyPEM 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 inx5c; leaf + one intermediate is usually enough, and the leaf alone is all U2F can carry.device requires a PIN — pass --pin(status0x36): import/clear are gated; set a FIDO PIN first (rsk fido set-pin) and pass it.- An EA
makeCredentialcomes back self-attested (nox5c, noep). EitherenableEnterpriseAttestationwas never issued (checkoptions.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 theacfgpermission. 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 buildbakes a custom AAGUID (build.rsvalidates it,consts.rsconst-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).
| Field | RS-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 |
legalHeader | Standard MDS3 text, matching the official tool’s Metadata P-36; the statement remains self-published |
authenticationAlgorithms | secp256r1 / 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 |
upv | 1.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 inauthenticationAlgorithms. They are visible only inside the embeddedauthenticatorGetInfo(and only on theadvertise-pqcbuild). A strict MDS consumer will not see the PQC capability. - One profile per statement. The build features
advertise-pqc(adds COSE-48to the algorithm list),fips-profile(drops secp256k1, raises the PIN floor to 6) andlargeblob-ext(swaps thelargeBlobKeyextension, thelargeBlobsoption andmaxSerializedLargeBlobArrayfor the CTAP 2.3largeBlobextension) changegetInfo. 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 policy | What 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 enforced | A 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:
| Command | Question it answers | Gates |
|---|---|---|
rsk inventory list | what is this key? | none — touch-free, PIN-free |
rsk inventory verify | is this the key we enrolled? | touch; --pin if set |
rsk offboard | wipe a returned key, keep proof | typed 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:
| Field | Meaning |
|---|---|
transport | ccid, hid, or ccid+hid (merged) |
serial | RP2350 OTP chip id (CCID only) |
sdk | RS-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_device | firmware version string, build counter (HID) |
versions, client_pin | FIDO CTAP versions, PIN-set flag |
aaguid | the 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 |
error | populated 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:
| Symptom | Status | Meaning |
|---|---|---|
device requires a PIN — pass --pin | 0x36 | a FIDO PIN is set; add --pin |
refused — no OTP DEVK provisioned | 0x30 | blank board, no device key (production.md) |
denied — no touch within 30 s | 0x27 | press 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:
| Step | What it does | Records on success |
|---|---|---|
| OTP | writes an all-zero config to slots 1–4 (the protocol’s “delete”) | ok |
| OATH | sends the OATH RESET command | ok |
| PIV | exhausts PIN + PUK retry counters with two distinct wrong values, then factory RESET | ok |
| OpenPGP | rsk openpgp reset (TERMINATE + ACTIVATE) | ok |
| FIDO | CTAP authenticatorReset — replug, then touch | ok |
| org attestation | clears the chain if one was installed — touch | cleared / none |
| receipt | signs a checkpoint over the post-wipe journal — touch | signed |
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’shost_observations.steps.otprecords exactly which slots stayed (e.g.slots [2] protected by access codes — NOT wiped). A follow-uprsk offboardafter recovering the code, or a fullrsk-wipeflash nuke, covers that case. - The CCID wipes are idempotent. A failed FIDO reset is recorded in
stepsand the run still writes the receipt for what was destroyed, then exits non-zero. Re-runrsk offboard; the applet wipes already done are harmless to repeat. no-sessioninnotesmeans 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 andfido_resetrecording 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": falseand ano-devknote. That is expected on dev boards, not a fault. no-reset-eventinnotesmeans the signed window did not contain theRESET, so the receipt does not certify a wipe (reset_attestedis 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 theRESETpast the export window.head-mismatchinnotesmeans 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 asinventory verify. - attestation.md: the org-attestation chain that
offboardclears andlistreports. - 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
verifyand the signed receipt possible. - linux.md:
pcscd/scdaemonsetup 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.
| Area | Default build | fips-profile build | Gate |
|---|---|---|---|
| FIDO algorithms | ES256, EdDSA, ES384, ES512, ES256K, (ML-DSA-44/-65/-87) | drops ES256K (secp256k1 — never NIST-approved) from both the advertised list and credential negotiation | getinfo.rs, makecredential.rs |
| FIDO minimum PIN | 4 | 6 (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 backup | one-time export window | export refused — non-exportable key material; restore (BACKUP_LOAD) still works, so keys may migrate into a profile device, never out | vendor.rs |
| PIV management key | 3DES or AES | no new 3DES keys (SP 800-131A); an existing 3DES key still authenticates so a reflashed device can migrate itself to AES | piv/lib.rs |
| PIV RSA | 1024 / 2048 | no RSA-1024 generation or import | piv/keygen.rs |
Two things worth reading carefully:
- ES256K leaves on both sides.
getInfo’salgorithmslist no longer carries-47, so a relying party never offers it. Even if a client asks for-47anyway,makeCredentialmaps 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 neitherykman piv keys generate ... RSA1024nor importing an external 1024-bit key onto a slot succeeds. Both return6A 80(incorrect data).
What deliberately stays
- Ed25519 / X25519: approved by FIPS 186-5 (EdDSA) and SP 800-186.
ssh ed25519-skkeeps 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
getInfois the separateadvertise-pqcflag. 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 ongetAssertion(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.
ykmanneeds the opt-inVIDPID=Yubikey5build. It gates on the “Yubico YubiKey” reader name, which the default RS-Key build (0x1209:0xF1D2) does not present. Build that flavor for theykmancommands here and under Verifying below, or drive the device withrsk/rsk-tuion the default build.
There is no “convert” command. You generate a new approved key and retire the old one through normal applet flows. The old 3DES/RSA-1024/secp256k1 material lingers only as long as you let it.
Verifying a device runs the profile
ykman fido info # Minimum PIN length: 6
ykman info # firmware version, applet capabilities
A profile build shows Minimum PIN length: 6. The absence of -47 (ES256K)
is not something ykman fido info prints. It lists the AAGUID, options,
PIN retries and minimum PIN length, but not the COSE algorithms array. To
confirm secp256k1 is gone you need a raw getInfo dump (e.g. fido2-token -I
or python-fido2): read the 0x0A array and confirm -47 is absent.
That advertisement is evidence, not proof on its own. A default build can have its minimum PIN raised to 6 by hand, which makes the PIN field alone ambiguous. The proof is the image signature. Combined with secure boot, the firmware’s own signature is the policy attestation: the fuses boot only your signed profile image, and that image is the only code present, so “the device enforces the profile” reduces to “the device booted, and your signature is the only one it accepts.”
flowchart TD
src["Source (one tree)"] --> def["Default image"]
src --> fips["fips-profile image"]
fips --> sign["Sign + flash"]
sign --> sb["Secure boot fuses<br/>boot only your key"]
sb --> dev["Device runs only<br/>the signed profile"]
dev --> att["getInfo + signature<br/>= the attestation"]
Why compile-time, not a runtime switch
A runtime “FIPS mode” toggle is one admin command away from not being FIPS mode, and one malware-driven APDU away from being turned off without you noticing. A compile-time profile under secure boot is a different object: the restricted menu is the only code in the image, the image is signed, and the fuses only boot your signatures. Changing the policy means signing and flashing a different image. That is exactly the auditable, physical event you want a policy change to be, rather than a silent state flip.
This mirrors how the rest of RS-Key’s hardening works: every knob is compile-time, and the irreversible posture lives in OTP fuses, not in mutable runtime state.
Honest limits
- No CMVP certificate, no validated boundary. Read the first callout again: this is an algorithm policy, not a validation. The limitations and threat model pages apply unchanged.
- The entropy source is the RP2350’s, untested against SP 800-90B. A validated module needs a validated RNG. This profile does not provide one.
- OpenPGP and OATH are not narrowed by the flag. If your policy needs
approved-only algorithms there too, you enforce that through the applets’
own configuration, not through
fips-profile. - “Approved algorithm” ≠ “approved usage.” The profile keeps you from negotiating a disapproved primitive. It does not audit key sizes, rotation, or how you use the device. That part is on you.
Related
- build.md: all compile-time flags, including the
.#firmware-fipsNix 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_MKEKorFAKE_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 statusin BOOTSEL andrsk otp statusin 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-runand 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.
| Step | Where | Action |
|---|---|---|
| Prepare | Host | Generate 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 image | BOOTSEL, then running firmware | Load the signed firmware and check that the application starts before changing the boot policy. |
| Stage A | BOOTSEL | rsk secure-boot load-key writes the signing-key fingerprint and sets KEY_VALID. Reboot and check the signed image again. |
| Stage B | BOOTSEL | rsk secure-boot harden sets both debug disables and configures glitch detection. Cold-boot and verify debug denial. |
| Stage C | BOOTSEL, then normal flash boot | rsk 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 D | BOOTSEL | rsk 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 storage | BOOTSEL, then running firmware | rsk otp burn writes DEVK and MKEK. Secure startup migrates storage, scrubs flash and seals page 58. Check rsk otp status. |
| Change rollback policy | Host, then device | For 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-pukor the panel’s Change PUK and supply the current PUK as both values. - OpenPGP. In
gpg --card-edit,verifypresents PW1. For PW3, useadminandpasswdoption 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
| Situation | Action |
|---|---|
| The new firmware fails to start | Enter 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 lost | Keep 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 unexpectedly | Read the new floor in BOOTSEL and prepare both signed images at it. OTP keeps the higher floor. |
| The signed wipe image fails to start | Check its SRAM layout, board geometry, trusted signing key and rollback version against Stage 1b. |
| BOOTSEL refuses a read of page 58 | This 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 partition | This 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 board | Provision 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-xselects 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
| Key | Where it lives | Purpose |
|---|---|---|
| Secure Boot signing key | Private PEM on the signing host. Public-key fingerprint in OTP page 2. | Authorizes firmware and recovery images |
| MKEK and DEVK | Generated by the host provisioning tool and written to OTP page 58 | Storage sealing and device attestation. See OTP master key. |
| Applet secrets | Device storage | FIDO, 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.
-
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 andrsk-wipewith that key at the board’s current policy. Name the new outputsfirmware-next-signed.elf/.uf2andrsk-wipe-next-signed.elf/.uf2so the previous artifacts stay available. Write the firmware seal’s JSON to~/.rs-key-secrets/next/otp_secureboot.json. -
Enter BOOTSEL and preview provisioning into the free slot.
rsk secure-boot rotate ~/.rs-key-secrets/next/otp_secureboot.json --slot 1 --dry-runIf the slot and fingerprint are correct, provision it and read back the state.
rotateperforms the same slot write asload-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 -
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 -
Return to BOOTSEL only after proving that boot. Revoke the old slot and verify the readback.
revokerefuses to remove the last trusted slot.rsk secure-boot revoke 0 && rsk secure-boot statusCheck 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
| Situation | What to do |
|---|---|
Lost the PEM before load-key | Generate a new key and prepare new signed firmware, wipe and OTP JSON. |
Lost the PEM after load-key, before enable | With 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 enable | Restore 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 PEM | Recover the passphrase or an accessible copy of the same key. Otherwise follow the lost-key case for the board’s current state. |
| Key compromised | Rotate and revoke the compromised slot, or replace the board if rotation is unavailable. The board trusts signatures from that slot until revocation. |
| Replacing the board | Generate 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-runfor 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.
| Encoding | How to read it | Used here |
|---|---|---|
| RBIT-3 | Bitwise majority across three consecutive rows | BOOT_FLAGS0/1, rollback floor |
| RBIT-8 | A bit takes effect once three of its eight copies are set | CRIT1. The harden command verifies its hardening bits in all eight copies. |
| ECC | Each raw row has 16 data bits, six ECC bits and two polarity bits | Boot-key fingerprints, DEVK and MKEK |
| Page-lock word | Bitwise majority across three copies of the policy byte within one raw row | PAGEn_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
picotoolOTP 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-requirecommand asks the Secure rescue applet to setROLLBACK_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
| Region | Rows | Contents | Writer |
|---|---|---|---|
| Boot policy, page 1 | 0x040–0x047 | CRIT1: Secure Boot enable, both debug disables, glitch detector enable and sensitivity | rsk secure-boot harden and enable |
| Boot policy, page 1 | 0x048–0x04A | BOOT_FLAGS0: ROLLBACK_REQUIRED at bit 11 | Boot ROM, or rsk otp rollback-require through Secure firmware |
| Boot policy, page 1 | 0x04B–0x04D | BOOT_FLAGS1: KEY_VALID and KEY_INVALID slot masks | rsk secure-boot load-key, rotate, revoke, lock |
| Rollback floor, page 1 | 0x04E–0x050, 0x051–0x053 | DEFAULT_BOOT_VERSION0/1: 48 logical bits across two triplicated words | Boot ROM |
| Boot keys, page 2 | 0x080–0x0BF | Four ECC-encoded SHA-256 fingerprints, 16 rows per slot. Starts: 0x080, 0x090, 0x0A0, 0x0B0. | rsk secure-boot load-key and rotate |
| Device keys, page 58 | 0xE80–0xEBF | DEVK, MKEK and their paired chaff | rsk otp burn |
| Page-lock words | 0xF83, 0xF85 | Page 1 and 2 LOCK1, 0x141414 | rsk secure-boot lock |
| Page-lock word | 0xFF5 | PAGE58_LOCK1, completed value 0x3D3D3D | Secure 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
- In BOOTSEL,
rsk otp burnchecks 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 forpicotool, preferring RAM-backed storage when available and overwriting the files before unlinking them. - At startup, Secure firmware validates the OTP key material before
migrating storage. Before entering Non-secure it sets the page’s
SW_LOCKto deny Non-secure access and configuresACCESSCTRLto 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 separateLOCK_BLtakes effect. - Once the remaining pre-OTP records have migrated and a fresh flash
scrub succeeds, Secure startup completes and verifies all copies of
the
0x3C3C3Caccess lock. That closes BOOTSEL and Non-secure access while Secure access remains read-write. - 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 contents | Key rows | Paired chaff rows |
|---|---|---|
| DEVK | 0xE80–0xE8F | 0xEA0–0xEAF |
| MKEK | 0xE90–0xE9F | 0xEB0–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 sealis 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:
| Number | Where it lives | What it means |
|---|---|---|
| Release version | Git tag and release notes | Identifies the RS-Key source release |
| Image version | picotool seal --major … --minor … | Helps the boot ROM choose between candidate images |
| Rollback version | picotool seal --rollback N | Compared 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-wiperecovery 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 image | Expected boot result |
|---|---|
| Trusted signature at the current floor | Boots without advancing the floor |
| Same trusted key, rollback version below the floor | Rejected by the version check |
Same trusted key, versionless, with ROLLBACK_REQUIRED set | Rejected because the version is missing |
| Untrusted or revoked signing key at the current floor | Rejected 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
unsafeRust and C, including the CMSE veneers and RSA arithmetic. See theunsafeaudit. - 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
Fswrites, 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 tornauthenticatorResetmay not drop the PIN oralwaysUvrecord while leaving a credential usable. Write ORDER is what buys that, chosen per operation and stated where the code does it:Fs::deletedrops the metadata before the value, registration writes theEF_RPentry 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-001remains 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::readandStorage::sizereturnNonefor 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 refusedEF_PINprobe on an unauthenticated PIVSELECTre-seeded the factory PIN over the owner’s, after whichVERIFY 123456answered9000— 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 backError::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 asCorrupted, 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 —enumerateRPsand the trusted-display Passkeys view — reach them throughEF_RP. So a credential whoseEF_RPentry is missing is onegetAssertionsigns with happily and neither surface will show you.enumerateCredentialsanddeleteCredentialscanEF_CREDdirectly, 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: theEF_RPentry 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 reachesEF_RPbeforeEF_CRED— a torn wipe can still strand a credential whose seed has already been removed. A power cut can also leave anEF_RPentry 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 DATAaway for anyone holding PW3, and the card reads that record again at the moment of every private-key operation:PSO:CDS, the asymmetric arm ofPSO:DECIPHERandINTERNAL AUTHENTICATEtake 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: aPSO:DECIPHERbody opening0x02and everyPSO:ENCIPHERroute toEF_AES_KEYand 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 whileGET DATApublishes 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: aPUT DATAofC1/C2/C3that 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 answer6581without 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 DATAanswers6B00to it even under PW3 — so theC1/C2/C3tags 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 inC5until something overwrites it.TERMINATE DFsweeps 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 the6581it returns rather than an order. And the binding at the other end —GENERATEandIMPORTreading 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 → 1write sits beside it inticket.rsand cannot reach the ceiling.UPDATEand the boot seal migration carry a slot’s record forward and leave the counter alone.SWAPleaves 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:CONFIGUREwrites 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:SWAPwrites 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 answers6581with 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 plainykman otp swapreaches 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 vendorCONFIG_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 anrsk-wipeerase, 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/flashfirmware-strict-config, which restores the presence/PIN gates and refuses the ungated transport writes (build.md). It is not the runtime flash flagEF_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
pcscdcan 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 sameFidoState— one PIN/UV token, one credential-management walk, and crucially one per-boot PIN-mismatch budget. A second session state would have handed a hostPIN_MISMATCH_LIMITguesses 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 byboth_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 useykman 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:falseassertions 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,
kbasederives 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. SeePLAT-THREAT-002and 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/07asFFFE. -
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
pcmrgrant, 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 theEF_HARDENEDmarker 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.
- The OTP-burn migration supersedes the pre-OTP seed, which was sealed
under the chip-serial-only root (no fuse secret), and the persistent
-
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_REQUIREDfused, 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-configre-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 saveandpicotool loadover that range answerpermission failure— enforced by the bootrom, not by us — while the running firmware keepssecure: rwand full access to its own data. The default BOOTSEL path rejects those direct store reads and writes. The diagnostic--no-partition-tablebuild 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-profilebuilds (opt-in). Raise the clientPIN floor to six code points and reject common patterns such as repeated digits and123456. 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_VDDrail, 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.shrunscargo audit,cargo denyand 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 ownpicoempin. - Advisory exceptions.
deny.tomllists exceptions for unmaintained or deprecated dependencies. The firmware usesrsk-rsafor 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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
| Attacker | Position | Treatment |
|---|---|---|
| Hostile host | Drives every byte over USB, picks when the power dies | Defended: memory safety, protocol gates, write ordering |
| Thief with the powered-off device | Full flash image, no PIN | Defended after the OTP burn: at-rest sealing |
| Attacker who can flash firmware | Replaces the image | Defended by secure boot + anti-rollback; undefended on an unfused board |
| Physical / lab attack | Decapping, glitching, probing | Out 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
| Weakness | Why it does not happen here | Evidence |
|---|---|---|
| Memory corruption (CWE-119/125/787) | Safe no_std Rust; every unsafe site enumerated and justified | unsafe.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 empty | testing.md |
| Authentication / authorization bypass (CWE-287/862/863) | Gates spent before use; retry counters and lockout; sequence properties model-checked | formal.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 image | threat-model.md |
| Cleartext storage of secrets (CWE-312) | One seal chokepoint before anything reaches the store | architecture.md |
| Timing side channels (CWE-208) | Constant-time comparisons and blinded private-key paths, audited against the built image | ct-audit.md |
| Secrets left in memory (CWE-226) | Zeroization on the paths that hold key material | threat-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 reset | store-refinement.md, reset-refinement.md |
| Downgrade and rollback (CWE-757) | Secure boot plus the OTP anti-rollback epoch; bcdDevice names the build precisely | anti-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 skip | build.md |
| Vulnerable dependencies (CWE-1395) | cargo audit, cargo deny and cargo vet in the gate; pinned lockfiles; git dependencies restricted | threat-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-rsauses 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 inPLAT-CRYPTO-002andPLAT-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-002in 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:DECIPHERwith 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-pqcenables 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 inauthenticator-rsand 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-profilebuild blocks seed export. See the seed backup guide. - Flash geometry is part of the upgrade contract. Keep
FLASH_SIZEandKVMAINwhen 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 inPLAT-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-001is 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_REQUIREDrequires 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:0xF1D2with the RS-Key reader name.ykmanand Yubico Authenticator look for the Yubico reader name and use the opt-inVIDPID=Yubikey5build 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
f9and replacement of object5FFF01are refused after management authentication, with6A80.ATTESTuses the device’s identity. See the PIV guide. - OpenPGP attestation uses a device-generated identity. Its
certificate is self-signed. Host writes to attributes
DAor certificateFCreturn6B00. Import and generation requests for the attestation slot return6A80. See the OpenPGP guide. - PIV retry budgets must be nonzero. With PIN and management
authentication in place,
SET RETRIESreturns6A80for a zero PIN or PUK budget and leaves the counters intact. - SELECT by AID accepts
P2 = 04. RS-Key accepts it alongsideP2 = 00for 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 andunsafe extern "C"on the linker-symbol/FFI declaration blocks. These mark declarations the compiler cannot check. The symbols are addresses read viaaddr_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_stepforIncrementalSieve::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.
- Hand-rolled constant-time comparator definitions.
- Secret-vs-attacker comparisons that bypass the comparator.
- Secret-dependent control flow / variable work between match and mismatch.
- Secret-indexed memory access / data-dependent arithmetic.
- Crypto-primitive usage (are the CT-by-design RustCrypto primitives wrapped non-CT? is the hand-written modexp safe?).
- Status-word / error-path / response-latency oracles.
Constant-time confirmed
The assurance result. Sites checked and found correct:
- The canonical comparator
rsk_crypto::ct_eqis 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 atopt-level=sandopt-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
pinUvAuthTokenMAC 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-rsadraws a freshraround 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 offrsa0.9.10’s ownblind/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.
| Site | Class | Verdict | Surfaces that inline it |
|---|---|---|---|
rsk_crypto::mac::ct_eq | comparator | constant-time | OATH 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
rsacrate 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-rsamodexp secret-indexed window lookup: the window index is a secret nibble — of the candidate in the keygen prime search, and ofdP/dQinsign_crt. Both reachprivexp::backend::powon 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 tomul).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 incrates/rsk-rsa/src/privexp.rs, and every stack it can sit on is SRAM: core0’s, which the linker bounds with_stack_endand_stack_start, and — for the keygen half, which core1 runs too — core1’sCORE1_STACK(firmware/src/core1.rs), a.bssstatic 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_hlwith 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-liveddP/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-002in 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 aretemp + k·halfwithhalfa 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 byCONSTANT_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_boxbarrier 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 itsSolo_*.cfgrun 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.
| Disposition | Code | Means |
|---|---|---|
covered | cov | the 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 |
equivalent | equ | this 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 |
conditional | cnd | claimed only under a stated condition |
out-of-scope | oos | the claim is not made here — the code it is about is absent, or the gate it is about is compiled out |
gap | gap | nobody 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.
| # | Configuration | Kind | Published | Cargo features | Build mode / knobs | Compiles unlike the comparison baseline |
|---|---|---|---|---|---|---|
| 01 | firmware | package | yes | — | trustzone=true | — |
| 02 | firmware-no-touch | package | no | no-touch | trustzone=true | firmware +no-touch |
| 03 | firmware-fips | package | yes | fips-profile | trustzone=true | firmware +fips-profile, rsk-fido +fips-profile, rsk-piv +fips-profile |
| 04 | firmware-pqc | package | yes | advertise-pqc | trustzone=true | firmware +advertise-pqc, rsk-fido +advertise-pqc |
| 05 | firmware-fips-pqc | package | yes | advertise-pqc, fips-profile | trustzone=true | firmware +advertise-pqc +fips-profile, rsk-fido +advertise-pqc +fips-profile, rsk-piv +fips-profile |
| 06 | firmware-no-touch-pqc | package | no | advertise-pqc, no-touch | trustzone=true | firmware +advertise-pqc +no-touch, rsk-fido +advertise-pqc |
| 07 | firmware-no-touch-fips | package | no | fips-profile, no-touch | trustzone=true | firmware +fips-profile +no-touch, rsk-fido +fips-profile, rsk-piv +fips-profile |
| 08 | firmware-no-touch-fips-pqc | package | no | advertise-pqc, fips-profile, no-touch | trustzone=true | firmware +advertise-pqc +fips-profile +no-touch, rsk-fido +advertise-pqc +fips-profile, rsk-piv +fips-profile |
| 09 | firmware-strong-pin | package | yes | strong-pin | trustzone=true | firmware +strong-pin, rsk-fido +strong-pin |
| 10 | firmware-strong-pin-pqc | package | yes | advertise-pqc, strong-pin | trustzone=true | firmware +advertise-pqc +strong-pin, rsk-fido +advertise-pqc +strong-pin |
| 11 | firmware-always-uv | package | yes | always-uv | trustzone=true | firmware +always-uv, rsk-fido +always-uv |
| 12 | firmware-always-uv-pqc | package | yes | advertise-pqc, always-uv | trustzone=true | firmware +advertise-pqc +always-uv, rsk-fido +advertise-pqc +always-uv |
| 13 | firmware-strict-up | package | yes | strict-up | trustzone=true | firmware +strict-up, rsk-fido +strict-up |
| 14 | firmware-strict-up-pqc | package | yes | advertise-pqc, strict-up | trustzone=true | firmware +advertise-pqc +strict-up, rsk-fido +advertise-pqc +strict-up |
| 15 | firmware-pico | package | no | — | trustzone=true, vidpid=Pico | — |
| 16 | firmware-display | package | yes | display | trustzone=true, flashSize=16M, ledKind=none | firmware +display, rsk-bip39 (added), rsk-device +display, rsk-display (added), rsk-slip39 (added), rsk-ui (added) |
| 17 | firmware-display-v2 | package | no | display | trustzone=true, flashSize=16M, ledKind=none, tpChip=cst3530 | firmware +display, rsk-bip39 (added), rsk-device +display, rsk-display (added), rsk-slip39 (added), rsk-ui (added) |
| 18 | firmware-2mb | package | yes | — | trustzone=true, flashSize=2M, kvmain=896K | — |
| 19 | firmware-16mb | package | yes | — | trustzone=true, flashSize=16M | — |
| 20 | firmware-strict-config | package | yes | strict-config | trustzone=true | firmware +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 |
| 21 | keygen-bench | feature | n/a | keygen-bench | trustzone=true | firmware +keygen-bench |
| 22 | core1-stats | feature | n/a | core1-stats | trustzone=true | firmware +core1-stats |
| 23 | bench | feature | n/a | bench | trustzone=true | firmware +bench, rsk-bench (added), rsk-fido +bench |
| 24 | fido-conformance | feature | n/a | fido-conformance | trustzone=true | firmware +fido-conformance, rsk-fido +fido-conformance +strict-up |
| 25 | ea-conformance-rpid | feature | n/a | ea-conformance-rpid | trustzone=true | firmware +ea-conformance-rpid, rsk-fido +ea-conformance-rpid +fido-conformance +strict-up |
| 26 | largeblob-ext | feature | n/a | largeblob-ext | trustzone=true | firmware +largeblob-ext, rsk-fido +largeblob-ext |
| 27 | preview-sign | feature | n/a | preview-sign | trustzone=true | firmware +preview-sign, rsk-fido +preview-sign |
| 28 | abrobot-16m | board | n/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 | — |
| 29 | abrobot-4m | board | n/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 | — |
| 30 | seeed-xiao | board | n/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 | — |
| 31 | tenstar-usb | board | n/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 | — |
| 32 | waveshare-one | board | n/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 | — |
| 33 | waveshare-touch-lcd | board | n/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.
| Property | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
SEC-FIDO-001 | gap | oos | gap | gap | gap | oos | oos | oos | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-FIDO-002 | gap | oos | gap | gap | gap | oos | oos | oos | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-FIDO-003 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-FIDO-004 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-FIDO-005 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-FIDO-006 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-FIDO-006A | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-FIDO-006B | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-FIDO-006C | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-FIDO-007 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-FIDO-008 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-SEAM-001 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-SEAM-002 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-SEAM-003 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-SEAM-006 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-STORE-001 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-STORE-002 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-STORE-003 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-STORE-004 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-STORE-005 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-STORE-006 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-LAT-001 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-LAT-002 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-LAT-003 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-LAT-004 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-POL-001 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-POL-002 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-POL-003 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-POL-004 | gap | oos | gap | gap | gap | oos | oos | oos | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-POL-005 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-POL-006 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-ADM-002 | gap | oos | gap | gap | gap | oos | oos | oos | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-ADM-004 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-DISP-001 | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | gap | gap | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos |
SEC-DISP-002 | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | gap | gap | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos |
SEC-DISP-003 | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | gap | gap | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos | oos |
SEC-BOOT-001 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-BOOT-002 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-TRANS-001 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-TRANS-002 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
SEC-TRANS-003 | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap | gap |
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-displayowns the ceremony andrsk-uithe screen model, and both aredep:-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-lcdis 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-touchreplaces 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.tomlsays “Never ship a no-touch build”, andrelease-build.ymlrefuses 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.
| Configuration | gap rows | of which the owner crate moves | Owed by | Settled by | The question that would settle them |
|---|---|---|---|---|---|
firmware | 38 | 0 | contributor | evidence | Which 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-touch | 34 | 1 | contributor | absence | Beyond 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-fips | 38 | 17 | contributor | evidence | fips-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-pqc | 38 | 11 | contributor | evidence | advertise-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-pqc | 38 | 17 | contributor | evidence | As firmware-fips, on the combination with advertise-pqc; the pair is published and nothing measures the two features together. |
firmware-no-touch-pqc | 34 | 10 | contributor | absence | As firmware-no-touch, plus: does advertising ML-DSA-44 in getInfo change any authorization path, or only the algorithm list? |
firmware-no-touch-fips | 34 | 16 | contributor | absence | As 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-pqc | 34 | 16 | contributor | absence | The 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-pin | 38 | 11 | contributor | evidence | A 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-pqc | 38 | 11 | contributor | evidence | As firmware-strong-pin, on the combination with advertise-pqc. |
firmware-always-uv | 38 | 11 | contributor | evidence | always-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-pqc | 38 | 11 | contributor | evidence | As firmware-always-uv, on the combination with advertise-pqc. |
firmware-strict-up | 38 | 11 | contributor | evidence | strict-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-pqc | 38 | 11 | contributor | evidence | As firmware-strict-up, on the combination with advertise-pqc. |
firmware-pico | 38 | 0 | contributor | evidence | Which 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-display | 41 | 6 | contributor | evidence | This 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-v2 | 41 | 6 | contributor | evidence | The 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-2mb | 38 | 0 | contributor | evidence | 2 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-16mb | 38 | 0 | contributor | evidence | 16 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-config | 38 | 15 | contributor | evidence | The 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-bench | 38 | 1 | contributor | evidence | A 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-stats | 38 | 1 | contributor | evidence | As 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. |
bench | 38 | 11 | contributor | evidence | As 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-conformance | 38 | 11 | contributor | evidence | Built 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-rpid | 38 | 11 | contributor | evidence | Adds 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-ext | 38 | 11 | contributor | evidence | The 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-sign | 38 | 11 | contributor | evidence | Yubico’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-16m | 38 | 0 | contributor | evidence | The 16 MB geometry question of firmware-16mb, plus a GPIO presence source instead of BOOTSEL. |
abrobot-4m | 38 | 0 | maintainer | evidence | The 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-xiao | 38 | 0 | contributor | evidence | 2 MB with KVMAIN at 896 K — the firmware-2mb question on a board that also gates the LED behind a power pin. |
tenstar-usb | 38 | 0 | contributor | evidence | The 16 MB geometry question of firmware-16mb; presence is BOOTSEL, as on the default image (issue #125). |
waveshare-one | 38 | 0 | contributor | evidence | Which 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-lcd | 38 | 0 | maintainer | ruling | The 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
| ID | Invariant | Tranche |
|---|---|---|
SEC-FIDO-001 | NoAuthorizationBypass | p0-launch |
SEC-FIDO-002 | NoCrossTransportTouchConsumption | p0-launch |
SEC-FIDO-003 | NoTokenAfterInvalidation | p0-launch |
SEC-FIDO-004 | NoAccessibleSecretWithoutGate | p0-launch |
SEC-FIDO-005 | NoUnmanageableCredential | p0-launch |
SEC-FIDO-006 | ResetNeverWeakensSurvivingState | p0-launch |
SEC-FIDO-006A | ResetKeepsThePinGate | p0-launch |
SEC-FIDO-006B | ResetKeepsTheAlwaysUvGate | p0-launch |
SEC-FIDO-006C | ResetKeepsTheBackupSeal | p0-launch |
SEC-FIDO-007 | RamNeverOutlivesFlashSeed | p0-launch |
SEC-FIDO-008 | NoLiveTokenWithoutPinRecord | p0-launch |
SEC-SEAM-001 | NoStatusOutsideItsSelection | p0b |
SEC-SEAM-002 | NoStatusAfterARefusedAuth | p0b |
SEC-SEAM-003 | NoKeyOpOnTheAdminStatus | p0b |
SEC-SEAM-006 | AccessCodeRemovalNeedsTheCode | p0b |
SEC-STORE-001 | NoOrphanedMetadata | p0-launch |
SEC-STORE-002 | NoFalseAbsent | p0-launch |
SEC-STORE-003 | NoRecordLostToMetaWrite | p0-launch |
SEC-STORE-004 | NoFalseMetaAbsent | p0-launch |
SEC-STORE-005 | CacheHonest | p0-launch |
SEC-STORE-006 | NoSilentOrphan | p0-launch |
SEC-LAT-001 | NoAuthWhenBlocked | p0b |
SEC-LAT-002 | WrongAttemptIsCharged | p0b |
SEC-LAT-003 | BudgetRisesOnlyWithItsSecret | p0b |
SEC-LAT-004 | CountWithinMaximum | p0b |
SEC-POL-001 | PivOperationNeedsSlotPolicy | p0b |
SEC-POL-002 | PivAlwaysSpendsFreshness | p0b |
SEC-POL-003 | AttributeChangeInvalidatesTheKey | p0b |
SEC-POL-004 | OathCredentialNeedsItsGates | p0b |
SEC-POL-005 | OtpSlotMutationNeedsItsCode | p0b |
SEC-POL-006 | OtpCounterNeverRepeats | p0b |
SEC-ADM-002 | PrivilegedOpNeedsPresence | p0b |
SEC-ADM-004 | DisabledAppletNeverDispatches | p0b |
SEC-DISP-001 | ConfirmNamesTheOperation | p0b |
SEC-DISP-002 | StaleTouchApprovesNothing | p0b |
SEC-DISP-003 | OnlyAllowConfirms | p0b |
SEC-BOOT-001 | MarkerNeverLies | p0b |
SEC-BOOT-002 | TheWholeLockRides | p0b |
SEC-TRANS-001 | NoCrossChannelSplice | p0b |
SEC-TRANS-002 | NoSequenceGap | p0b |
SEC-TRANS-003 | NoBufferOverrun | p0b |
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.
| Property | Invariant | Bundle | Method rows | Bounds | With a per-bound consequence |
|---|---|---|---|---|---|
SEC-FIDO-001 | NoAuthorizationBypass | assurance/bundle/SEC-FIDO-001.toml | 8 | 33 | 33 |
SEC-FIDO-002 | NoCrossTransportTouchConsumption | assurance/bundle/SEC-FIDO-002.toml | 8 | 41 | 41 |
SEC-FIDO-003 | NoTokenAfterInvalidation | assurance/bundle/SEC-FIDO-003.toml | 9 | 46 | 46 |
SEC-FIDO-004 | NoAccessibleSecretWithoutGate | assurance/bundle/SEC-FIDO-004.toml | 7 | 32 | 32 |
SEC-FIDO-005 | NoUnmanageableCredential | assurance/bundle/SEC-FIDO-005.toml | 7 | 33 | 33 |
SEC-FIDO-006 | ResetNeverWeakensSurvivingState | assurance/bundle/SEC-FIDO-006.toml | 9 | 42 | 42 |
SEC-FIDO-006A | ResetKeepsThePinGate | assurance/bundle/SEC-FIDO-006A.toml | 7 | 32 | 32 |
SEC-FIDO-006B | ResetKeepsTheAlwaysUvGate | assurance/bundle/SEC-FIDO-006B.toml | 7 | 33 | 33 |
SEC-FIDO-006C | ResetKeepsTheBackupSeal | assurance/bundle/SEC-FIDO-006C.toml | 8 | 37 | 37 |
SEC-FIDO-007 | RamNeverOutlivesFlashSeed | assurance/bundle/SEC-FIDO-007.toml | 5 | 26 | 26 |
SEC-FIDO-008 | NoLiveTokenWithoutPinRecord | assurance/bundle/SEC-FIDO-008.toml | 8 | 42 | 42 |
SEC-STORE-001 | RSKeyStore!NoOrphanedMetadata | assurance/bundle/SEC-STORE-001.toml | 4 | 24 | 24 |
SEC-STORE-002 | RSKeyStore!NoFalseAbsent | assurance/bundle/SEC-STORE-002.toml | 4 | 24 | 24 |
SEC-STORE-003 | RSKeyStore!NoRecordLostToMetaWrite | assurance/bundle/SEC-STORE-003.toml | 4 | 24 | 24 |
SEC-STORE-004 | RSKeyStore!NoFalseMetaAbsent | assurance/bundle/SEC-STORE-004.toml | 4 | 24 | 24 |
SEC-STORE-005 | RSKeyStore!CacheHonest | assurance/bundle/SEC-STORE-005.toml | 4 | 24 | 24 |
SEC-STORE-006 | RSKeyStore!NoSilentOrphan | assurance/bundle/SEC-STORE-006.toml | 4 | 24 | 24 |
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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_states | 44 | nothing 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_ops | 11 | any 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_outcomes | 3 | the 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_tuples | 63888 | nothing 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_states | 22 | anything 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_pairs | 31 | nothing 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | an 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_channels | 2 | a three-channel interleaving, at B |
bound_max_retries | 8 | nothing 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_limit | 3 | nothing individually — see stops_max_retries; the pair is what is bounded, not either constant |
bound_max_clock | 1 | anything 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_window | 0 | the 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_permutations | permutations of RPs and Channels | soundness under liveness. Safety configurations only |
bound_credentials_per_rp | 1 | anything 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).
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | an rpId-binding defect needing a third relying party, on the alwaysUv arm |
bound_channels | 2 | a three-channel interleaving, on the alwaysUv arm |
bound_max_retries | 2 | the 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_limit | 1 | the 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_sequence | 5 | any defect needing a sixth dispatch — Begin, Next, unrelated command, Begin, Next, Next is already six |
bound_channels | 2 | a three-channel interleaving. Two is the measured model minimum for BugCmWalkIgnoresChannel; it has never been measured at the code level |
bound_clock_values | 2 | a 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_totals | full symbolic u16 — not a shrink, and saying so is the point | nothing — 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_sequence | 1 | any 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_channels | 2 | a three-channel interleaving at the call site |
bound_symbolic_bytes | 1 | every 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_totals | full symbolic u16 | nothing — 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_ctap_max_message | 3 | a 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_size | 16 | any 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_cap | 16 | any chained response over 16 bytes; shipped is 3072 |
bound_cfg_not_kani_assertions | 2 | the 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_actions | 21 | nothing 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_routes | 24 | the 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_guards | 11 | any 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | nothing 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_channels | 2 | nothing 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_retries | 8 | nothing 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_limit | 3 | nothing 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_clock | 1 | nothing 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_window | 0 | nothing 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 namespres.granted,pres.cancelBy,pres.scopeand 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:Ownersis 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_arms_run | 3 | the 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_rps | 2 | a falsifying state that first arises over a third relying party, on all three arms |
bound_channels | 2 | a falsifying state that first arises over a third concurrent channel, on all three arms |
bound_max_retries | 2 | nothing — 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_limit | 1 | nothing, 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 assumptionsscripts/assumption_gate.pytracks, 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_invariants_checked | 2 | anything 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_switches | 1 | any 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_rows | 5 | a 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_max | 7 | nothing — 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 informal/gen-configs.sh:105-107’s ALL_INV, so the fiveMut_twins that check the whole set report THIS name too — measured, all ten, and that is theb_mut_twinsrow. 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_budget_polls | 3 | any 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_unwind | 6 | nothing 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_scopes | 4 | an 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_producers | 2 | a 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_arm | 1 | the 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.scopeis 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 nocfg(kani)constant shrink on this path:git grep -n 'cfg(kani)' crates/rsk-device/srcoutside the harness files is one hit, themod proofshook 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_CAPlives 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_ceremonies | 2 | a 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_polls | 3 | any defect that first appears on a fourth poll of either ceremony, the same shrink as the cancel row |
bound_unwind | 6 | nothing beyond the poll budget it covers; at 6 against 3 polls the unwinding is slack on this row too |
bound_scopes | 4 | a 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 anassume, 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:spentcarries no owner, so a still-held press confirms for nobody — including the same transport again — while the model’susedByonly 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_tagged_owners | 3 | any 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_writers | 2 | nothing 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_writers | 4 | any 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_files | 2 | the 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_files | 1 | any 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_file | 7 | the 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_counted | 2 | any 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 insiderequest_cancel’s SCOPE_FIDO test and :131 insidecancel_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 fourset_wait_scopecall sites are firmware/src/worker.rs:484, :795, :934 and :938. Two files are credited to therustcolumn 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_patch_hunks | 1 | any 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_files | 1 | a 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_tests | 3 | which 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_pairs | 6 | the 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_property | 5 | any 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.BugUnscopedCancelandBugPanelCancelableshare 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 recordedexpect = "killed", which thecomutantsjob of.github/workflows/deep-checks.ymlre-drives WEEKLY as a gating row and thescripts/check-assurance.sh:"comutants lint"row lints on every pull request. The six pairs arew4c’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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_columns_total | 31 | any 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_scope | 4 | nothing 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_claimed | 3 | twenty-seven of the thirty-one. Three columns carry a claim, so the invariant is asserted for three builds and for no other |
bound_columns_gap | 24 | everything 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_presence | 3 | the 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 without-of-scopecells, and the disposition is DECIDED rather than open: on the fourno-touchimagesButtonWait::wait— the sole caller ofset_up_pending(true)on a non-display build — is never called, becauseButtonPresence::waitiscfg(not(feature = "no-touch"))andrequest/request_ceremonyreturnPresence::Confirmedoutright (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.gapwould say nobody has judged;out-of-scopesays the claim is not made, which is the true state — and the tree already treats those builds that way,firmware/Cargo.tomlsaying ‘Never ship a no-touch build’ andrelease-build.ymlrefusing to release one. NOTE WHAT SURVIVES:Arbiterand all three tagged functions ARE compiled into those images; what is absent is the wait, not the arbitration. The 24gapcells are the honest remainder and three of them are board columns that movepresence.sourceoff 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | an rpId-binding defect that needs a third relying party; two is what the ghost’s binding half is checked over |
bound_channels | 2 | a three-channel interleaving of the invalidators — two channels is every concurrency this row searches |
bound_max_retries | 8 | nothing 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_limit | 3 | nothing 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_clock | 1 | every 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_window | 0 | the 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:BugWrongPinKeepsTokenandBugLocalPinKeepsTokenare 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_tokenis 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 theresetinvalidator 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).
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | an rpId-binding defect needing a third relying party, on the alwaysUv arm |
bound_channels | 2 | a three-channel interleaving, on the alwaysUv arm |
bound_max_retries | 2 | the 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_limit | 1 | the 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_clock | 1 | every 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_window | 0 | the 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_perm_subsets | 16 | nothing — 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_rps | 1 | the 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_channels | 2 | a three-channel interleaving of the invalidators, on the wide-permission arm |
bound_max_retries | 2 | the six rungs between two and the shipped eight, so the two ladder-walking mutants are shallower here than on the shipped row |
bound_mismatch_limit | 1 | the two mismatches between one and the shipped three, on the wide-permission arm |
Row note (
shipped_relation). WidePerms = TRUE drawspsfrom SUBSET Perms — all sixteen subsets of {mc, ga, cm, acfg} instead of the fivePermSetsnarrows 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 1 | the rpId-binding half of the ghost, which this arm drops to one relying party the same way the wide-permission arm does |
bound_channels | 2 | a three-channel interleaving, on the forced-change arm |
bound_max_retries | 2 | the six rungs between two and the shipped eight; a retry-shaped defect is not what this arm is for |
bound_mismatch_limit | 1 | the two mismatches between one and the shipped three, on the forced-change arm |
Row note (
shipped_relation). ForceChangeModelled = TRUE turns ongate.forceChange, EF_MINPINLEN byte 1, whichclientpin.rsreads at the two get_pin_token doors andchange_pinclears. 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 — andassurance/platform.tomlPLAT-MODEL-010 isdischargedon 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_invariants | 2 | anything 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_switches | 1 | any defect needing two switches at once. One armed switch is what attributes the kill to the defect that was injected |
bound_configurations | 7 | an 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_falsified | 3 | nothing — 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’sbuild.commit, which stays where it is becausescripts/evidence_gate.py:515-546dates 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 = 7IS this set:assurance_gate.solo_target_countscounts 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_sequence | 5 | any 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_opcodes | 8 | any 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_bytes | 6 | nothing — 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_values | 2 | a 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_clauses | 4 | the 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 persistentpcmrgrant, 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_sequence | 4 | any 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_opcodes | 3 | any invalidator outside the three this run can issue; the walk harness above is the row that carries the eight-opcode alphabet |
bound_symbolic_permission_bytes | 1 | every 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_payloads | 1 | anything 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_clauses | 2 | the 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 realverify_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 zeroingpermissionsis not defence in depth — it is the only defence. One concrete payload, so this says nothing aboutpinproto::verifyas a MAC (TCB-2). Only thecmpermission and only this one of the four token gates: the other three are inline in functions that need aCtx, and aCtxdragsp256into 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_tagged_owners | 6 | any 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_files | 3 | anything 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_conjuncts | 3 | the 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_sites | 4 | coverage 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_read | 23 | any citation the review never opened. Twenty-three OCCURRENCES were read, which is a count of readings and not of sources |
bound_citations_wrong | 5 | how 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 therustcolumn is 3 becauseassurance_gate.grep_wordreturns 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, becausewrite_pin_verifieris untagged. Two more invalidators the statement names by word,resetandpower 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_patched_files | 3 | a 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_crates | 2 | any invalidation door outside the two crates these patches reach |
bound_patch_hunks | 9 | the 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_killed | 6 | anything about the seventh switch. Six carry a killed patch, so the co-refutation column covers six of the model’s seven defects |
bound_unreachable | 1 | the 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 withexpect = "killed", which that file’s own status vocabulary (:20-22) defines as a RECORDED verdict and not a plan; the hunk count is thefind/find2/find3blocks summed over the six. Two crates, because BugLocalPinKeepsToken patchesrsk-display— the only co-refutation entry for this property outside rsk-fido, and the door the model calls the fourth. The seventh, BugSetPinKeepsPpuat, isstatus = "unreachable"and itsevidencefield is a CODE-level measurement, not a model one: there is no site whose removal reproducessetPIN keeps the grantalone, because the authoritative revoke is the chokepoint changePIN shares. That asymmetry is whymutis 7 andcois 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | a 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_channels | 2 | a falsifying state that first arises over a third concurrent channel — reach again, for the same reason |
bound_max_retries | 8 | nothing 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_limit | 3 | nothing by shrinking, for the same reason as the ladder it pairs with — three IS the shipped mismatch limit |
bound_max_clock | 1 | any falsifying state that needs a second unit of elapsed time. One Tick is the whole clock here |
bound_reset_window | 0 | the 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.setnames 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | a 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_channels | 2 | a falsifying state that first arises over a third concurrent channel, on all three arms |
bound_max_retries | 2 | the 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_limit | 1 | the two mismatches between one and the shipped three, on all three arms |
bound_configurations | 3 | any 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_invariants | 2 | anything 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_switches | 1 | any defect needing two switches at once. One armed switch is what attributes the red to the defect that was injected |
bound_counterexample_states | 11 | nothing — 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_depth | 11 | nothing, 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_clauses | 3 | two 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_rows | 5 | nothing 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_counterexamples | 2 | any 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_observed | 1 | non-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 asRED: NoAccessibleSecretWithoutGatewithout 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_tagged_owners | 2 | any 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_sites | 1 | a 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_sites | 3 | a 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_sites | 2 | any 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_argument | 5 | anything in a sixth file. Five files carry the argument, two of them only through cfg-gated projections that reach no image |
bound_crates | 2 | a 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_patch_hunks | 1 | any 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_files | 1 | a defect that has to span two files |
bound_tests_fallen | 1 | which 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_crates | 1 | any 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-darwinagainst 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_variants | 4 | nothing 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_tags | 2 | which 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_configurations | 9 | any 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 throughcheck_tags, the gate’s own entry point, withproduction_rustpointed 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | every 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_channels | 2 | a falsifying state that first arises over a third concurrent channel |
bound_max_retries | 8 | nothing 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_limit | 3 | nothing by shrinking, for the same reason as the ladder it pairs with |
bound_max_clock | 1 | any falsifying state that needs a second unit of elapsed time |
bound_reset_window | 0 | the 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.credandstore.rpentare 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_arms | 3 | any 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_rps | 2 | every interleaving needing a second credential for one relying party, on the three arms as on the shipped row |
bound_channels | 2 | a falsifying state that first arises over a third concurrent channel, on all three arms |
bound_max_retries | 2 | the 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_limit | 1 | the 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, whilestore.cred \subseteq store.rpentnames 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 the4 of 40numerator, 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_invariants | 2 | anything about the rest of the invariant set. TypeOK and this name alone is what tells these kills from a neighbour’s |
bound_armed_switches | 1 | any defect needing two switches at once |
bound_solo_configurations | 3 | a 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_depths | 14 | nothing — 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 — theFIDO_SEED_FIDSloop 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-187puts 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_invariants | 7 | clause 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_switches | 1 | any 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_searched | 986872269 | anything 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— atShipped.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.cfgwas EMPTY when this row was written, both emitted with the same four arguments, so the two files were one configuration under two names and thecfgs = 40denominator counted 39 distinct ones.formal/gen-configs.sh:322now passes TRUE for the repair —emit Historical_E76.cfg BugSeedDoesNotLead TRUE TRUE— where theMut_loop at:329still passes FALSE, sodiffis the single hunk48c48onFixSweepDropsCredsBeforeRpEntriesand 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, hasHistorical_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 withFixSweepDropsCredsBeforeRpEntries = 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_tagged_owners | 4 | any 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_sites | 10 | a 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_sites | 3 | anything 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_conditions | 3 | the 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_argument | 4 | anything in a fifth file |
bound_crates | 1 | a 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 whenn < RP_PREFIX \|\| buf[0] == 0(credmgmt.rs:401, passkeys.rs:116) and whenunseal_rp_idfails (credmgmt.rs:436, passkeys.rs:121) — andstore.rpentis 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_rpsanswersCtapError::Otherfor the WHOLE walk, so one unsealable record hides every other relying party from the host, whilefor_each_rpskips 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_open_sites | 5 | any 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_direction | 0 | nothing 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_fail | 0 | every 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_producers | 2 | a 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 herenames 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_credentialremoving EF_CRED and then answeringNotAllowedwhen the EF_RP write fails;decrement_rp’s ownlet _ = fs.delete(EF_RP + j); the trusted-display delete swallowing the same failure; andlargeblobext::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 directioncred \subseteq rpentdoes 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 ofRSKeySecurityStatecan FAIL a flash write (the two tear producers arePowerCut, RSKeySecurityState.tla:1522, andResetAborts, :1484, and both act between two writes that succeeded), so anErrreturned byFs::putand a best-effort rollback that itself fails are outside every configuration. AS-CRED-3 is the row that owns it, andSEC-STORE-006 NoSilentOrphanis 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_registered_twins | 3 | any 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_hunks | 2 | any 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_files | 1 | a defect that has to span two files |
bound_driven_here | 1 | the 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_configurations | 3 | what 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 carryexpect = "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 deferbump_rppast 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 becausecomutate.solo_indexreads 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | a 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_channels | 2 | a torn prefix that first goes wrong over a third concurrent channel |
bound_max_retries | 8 | nothing by shrinking — eight IS the shipped ladder, and no clause of this conjunction names a retry count |
bound_mismatch_limit | 3 | nothing by shrinking, for the same reason as the ladder it pairs with |
bound_max_clock | 1 | any 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_window | 0 | the 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.InResetWindowGuardissys.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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 on AlwaysUv.cfg, 1 on PermWide.cfg and ForceChange.cfg | a 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_channels | 2 | a torn prefix that first goes wrong over a third concurrent channel, on all three arms |
bound_max_retries | 2 | nothing this conjunction can express: no clause names a retry count, so six rungs off the ladder is nearly free here |
bound_mismatch_limit | 1 | nothing this conjunction can express, for the same reason |
bound_arms | 3 | clause 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 andsnap.survneeds only one member to be non-empty. What the three arms buy is the other value ofAlwaysUvShipped,WidePermsandForceChangeModelled— and the first of those is not free at all in the other direction, because all three arms takeAlwaysUvShipped = 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_invariants | 2 | anything about the rest of the invariant set; TypeOK and one clause is the whole of what each row checks |
bound_clauses | 3 | any 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_switches | 2 | isolation 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_configurations | 3 | a fourth clause-isolating row. Three configurations are three clauses, so a conjunct nobody wrote a row for would have no isolated verdict |
bound_depths | 16, 18 and 8 | nothing — 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 armBugResetGatesFirstand the third armsBugBackupSealedNotAGate— which dragsBugSeedDoesNotLeadin with it throughcompanion_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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_steps | 1 | every 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_actions | 13 | any 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_booleans | 14 | every 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_values | 5 | nothing by omission — five is the whole ResetProgress enum and the pre-state draws every variant, so this axis is not a shrink |
bound_covers | 1 | every 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_stepselects one of 13 actions byraw % 13and 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 —ResetVolatileViewobserves two fields of aFidoStatethat has dozens, and docs/reset-refinement.md records why: a direct run through the realFidoState::reset()was stopped after 72.45 s with CBMC still expandingzeroizeloops 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_harnesses | 3 | nothing 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_steps | 1 | every reachability question, exactly as on the parent row: one step is an induction and not a walk |
bound_covers | 3 | anything 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_precondition | 1 | every 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 assumewell_formed(pre), apply the same one symbolic step, and the parent assertswell_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 akani::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’sthe parent conjunction loses a conjunctrow
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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_tagged_sites | 5 | any 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_files | 3 | anything 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_sites | 3 | the 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_records | 5 | the 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_steps | 5 | the 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_crates | 1 | a 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 becauseassurance_gate.grep_wordreturns 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,ResetConfirmedfolding step 1 and step 2 into one. Every site is in one crate, which is what makesrust = 3a count of three files ofrsk-fidoand 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_twins | 3 | any model switch with no code twin, and any defect of the same shape nobody registered |
bound_patch_hunks | 4 | the 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_files | 1 | a defect that has to span two files |
bound_slice_crates | 1 | any 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:BugResetGatesFirstswaps the twosweepcalls (1 hunk),BugBackupSealedNotAGatedropsEF_BACKUP_SEALEDfrom the gate match arm (1 hunk),BugStateResetAfterWipemovesctx.state.reset()behindensure_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 weeklycomutate runrather than by any row ofcheck.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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_oracle_asserts | 1 | any 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_folded | 3 | which 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_valuations | 1 | the 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_bytes | 1048575 | a 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 REALrsk_fido::reset::resetover the realSeqStorageon a mock NOR that can lose power inside a write, then mounts a freshFs, scans, runsensure_seedand 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_holdsfolds 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, sosnap.pin,snap.auvandsnap.sealedare TRUE by construction and the 2^3 the Kani harnesses draw symbolically is never explored. The cut budget isdata[1] & 0x0fover 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_recorded_runs | 0 | everything 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_asserts | 2 | any 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_localised | 1 | clauses 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 whosetestcolumn 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 ispending
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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | a 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_channels | 2 | a torn prefix that first goes wrong over a third concurrent channel |
bound_max_retries | 8 | nothing 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_limit | 3 | nothing this clause can express, for the same reason as the ladder it pairs with |
bound_max_clock | 1 | any 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_window | 0 | the 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_invariants | 12 | nothing 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, withResetKeepsThePinGateamong them. This is the only GREEN configuration in the tree that names this clause:grep -lover 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_invariants | 2 | anything 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_switches | 1 | any 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_clauses | 1 | the other two conjuncts of the parent. This row is about one third of ResetNeverWeakensSurvivingState and is silent on the rest |
bound_depth | 16 | nothing — 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_states | 918170 | nothing 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_configurations | 2 | any 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_switch | 1 | every other defect. This row compares three verdicts of ONE switch and says nothing about a defect no switch in the tree builds |
bound_depths | 11 and 8 | nothing — 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.cfgarmsBugResetGatesFirstalone and checks TypeOK plusNoAccessibleSecretWithoutGate;Solo_BugResetGatesFirst.cfgarms 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 falsifiesNoAccessibleSecretWithoutGate, 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 hassnap.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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_steps | 1 | every 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_actions | 13 | any 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_booleans | 14 | every 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_values | 5 | nothing by omission; five is the whole ResetProgress enum and the pre-state draws every variant |
bound_covers | 1 | MORE 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_covered | 3 | the 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 assumeswell_formed(pre)at crates/rsk-fido/src/reset_refinement_kani.rs:125, applies exactly one step, and assertsreset_keeps_the_pin_gate(&volatile)under the messageResetKeepsThePinGateat :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 samewell_formed, take the same step, and the parent assertswell_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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_arms | 4 | any 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_harness | 1 | the 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_named | 3 | nothing this row proves; three of four is the count the arms are about, and the missing one is named |
bound_solver_seconds | 0.90 to 1.08 | nothing — 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 inbuild.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.credentialis 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_tagged_sites | 1 | any 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_records | 5 | the 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_records | 1 | everything but EF_PIN = 0x1080. One record is the whole of what this clause is about at the FID level |
bound_destroying_sites | 2 | any 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.sweepat reset.rs:141 is batched at 64 with a progress backstop and returnsErrwhen 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_oracle_conjuncts | 1 | any 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_assertions | 1 | the 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_runs | 0 | everything 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | a 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_channels | 2 | a torn prefix that first goes wrong over a third concurrent channel |
bound_max_clock | 1 | any 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_window | 0 | the 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_invariants | 12 | nothing 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_bases | 1 | any 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 isAlwaysUvShipped = FALSE, and it is the shipped image’s own value: firmware/Cargo.toml’s default feature set does not namealways-uv. On that value the record exists exactly when the flag is on, so the model’s consequentgate.alwaysUvand the firmware’sEF_ALWAYS_UVpresence 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_invariants | 2 | anything 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_switches | 1 | every 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_deltas | 1 | any 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_depth | 18 | nothing — 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_states | 2063890 | nothing 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_mutantat formal/gen-configs.sh:321-328 mapping the first two clauses ontoBugResetGatesFirstwith 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 counterexamplepin.setis TRUE, so clause A holds there; in clause A’s,snap.auvis 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_arms | 3 | this 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_states | 0 | the 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_rps | 2 on AlwaysUv.cfg, 1 on PermWide.cfg and ForceChange.cfg | a 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_retries | 2 | nothing this clause can express: it names no retry count, so six rungs off the ladder is free here |
bound_configurations_arming_the_mutant | 0 | the 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,WidePermsandForceChangeModelled— 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-225states the consequence in the generator itself and is the reasonclauses=1is 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_steps | 1 | every 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_actions | 13 | any 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_booleans | 14 | every 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_covers | 1 | every witness but the one. This harness’s single kani::cover! says its own antecedent is satisfiable and nothing about any other valuation |
bound_feature_arms | 1 | the 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 assumewell_formed(pre), take the same one symbolic step, andwell_formedends in the conjunction (crates/rsk-fido/src/reset_assurance.rs:267), sowell_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 ispersistent.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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_tagged_sites | 1 | every 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_records | 5 | the 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_writers | 2 | any 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_sites | 2 | any 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 atb185fc3withcrates/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, andtoggle_always_uvis what makes the two coincide — it deletes the record when the new value equalsDEFAULT_ALWAYS_UVand 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_oracles | 2 | any 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_clauses | 1 | this 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_runs | 0 | everything 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_asserts | 2 | any 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 (getInfooptions.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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_patched_lines | 2 | every 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_slices | 1 | any 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_controls | 1 | any 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_flavours | 2 | nothing, 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’sfindiscrates/rsk-fido/src/reset.rs:127-128verbatim, and itsreplaceis 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | a 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_channels | 2 | a torn prefix that first goes wrong over a third concurrent channel |
bound_max_retries | 8 | nothing by shrinking, and eight IS the shipped ladder at crates/rsk-fido/src/consts.rs:371. This clause names no retry count |
bound_mismatch_limit | 3 | nothing by shrinking, for the same reason as the ladder it pairs with |
bound_max_clock | 1 | any 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_window | 0 | the 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_names | 12 | any 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 againstsed -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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_invariants | 2 | anything about the rest of the invariant set; TypeOK and this one clause is the whole of what the row checks |
bound_armed_switches | 2 | isolation 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_depth | 8 | nothing 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_states | 5359 | any 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:358emits exactly that inside the loop overCLAUSE_INVatformal/gen-configs.sh:121, andclause_mutantatformal/gen-configs.sh:348is what pairs this clause withBugBackupSealedNotAGate. Its constants are Shipped.cfg’s, verbatim, except the two armed switches.formal/floors.txt:SoloClause_*.cfggives the family a wildcard RED row with no invariant column, so the runner does not compare the reported name for these; the name informal/runs.toml:138is 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_configurations | 3 | a 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_reported | 1 | which 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_depths | 8, 8 and 13 | nothing — the three are MEASURED trace lengths. Read against the two sibling clauses’ 16 and 18, they are the whole localisation argument |
bound_switches | 2 | the 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-1830claims 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.cfgandSolo_BugResetGatesFirst.cfgboth end atResetAbortswithsnap.survempty,snap.pinFALSE,snap.seedTRUE,snap.sealedTRUE andgate.backupSealedFALSE — 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.cfgfalls onNoUnmanageableCredentialat a state withsnap.sealedFALSE, 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_steps | 1 | every 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_actions | 13 | any 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_booleans | 14 | every 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_values | 5 | nothing 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_covers | 1 | every 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_rebootassumes the samewell_formed(pre), applies the same one step, and assertswell_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:statusis rebuilt from the derivation andkani > 0is what selects it. The α is WIDER than the TLA+ clause in one place and that widening belongs to this clause alone — seec_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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_tagged_sites | 1 | every 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_records | 5 | the 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_consumers | 2 | a 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_writers | 2 | any 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_crates | 1 | the 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 — thematches!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_sealedat crates/rsk-fido/src/vendor.rs:1073 answerstruefor 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_twins | 1 | any 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_hunks | 1 | the 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_files | 1 | a defect that has to span two files — which the two-consumer shape above makes plausible and no comutant covers |
bound_slice_crates | 1 | any 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_killers | 1 | the 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:194carriesstatus = "patch"andexpect = "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 weeklycomutate runand by no row ofscripts/check.sh. THE ROW ALSO CARRIES ITS OWN CORRECTION, and it is the longest note in that file: it wasstatus = "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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_oracle_conjuncts | 2 | any 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_asserts | 1 | the 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_valuations | 1 | the 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_bytes | 1048575 | a 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 REALrsk_fido::reset::resetover 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] & 1loadsstate.keydev_decat fuzz/fuzz_targets/power_cut.rs:291-293, which is what makesowner_reachablein 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_recorded_runs | 0 | everything 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_asserts | 1 | nothing 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_flavours | 1 | the 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 readsBACKUP_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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | nothing 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_channels | 2 | nothing 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_retries | 8 | nothing 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_limit | 3 | nothing at all, for the same reason as the ladder it pairs with |
bound_max_clock | 1 | nothing 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_window | 0 | nothing 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.seednames 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | a falsifying state that first arises over a third relying party, on the alwaysUv arm — reach again, since the invariant names no relying party |
bound_channels | 2 | a falsifying state that first arises over a third concurrent channel, on the alwaysUv arm |
bound_max_retries | 2 | nothing 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_limit | 1 | nothing this invariant can express, for the same reason |
bound_max_clock | 1 | any falsifying state needing a second unit of elapsed time, on this arm as on the shipped one |
bound_reset_window | 0 | the 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 inram => 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_invariants | 2 | anything 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_switches | 1 | any 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_rps | 2 | a falsifying state that first arises over a third relying party, on the one row where this invariant is seen to fail |
bound_channels | 2 | a 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 goingRED: 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_tagged_owners | 1 | any 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_sites | 4 | a 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_sites | 4 | anything 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_sites | 2 | nothing 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_argument | 6 | anything 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_crates | 2 | a 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 nokeydev_decat 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_patch_hunks | 2 | any 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_files | 1 | a defect that has to span two files |
bound_slice_crates | 1 | any test outside the one crate the slice runs |
bound_credited_configurations | 1 | what 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 movesctx.state.reset()from ahead of the flash work to behindensure_seed(formal/comutants.toml:373-386) — the E76 regression, in the shipped file, not a model edit — andexpect = "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, whichcomutate.solo_indexreads 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 theco = 0docs/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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | nothing this invariant can express — tok.live => pin.set names two booleans and no relying party. What two costs is reach alone |
bound_channels | 2 | nothing 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_retries | 8 | nothing 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_limit | 3 | nothing 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_clock | 1 | any falsifying state that needs a second unit of elapsed time |
bound_reset_window | 0 | the 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.setnames 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, andGetPinToken(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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 2 | a falsifying state that first arises over a third relying party, on the alwaysUv arm |
bound_channels | 2 | a falsifying state that first arises over a third concurrent channel, on the alwaysUv arm |
bound_max_retries | 2 | the 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_limit | 1 | the two mismatches between one and the shipped three, on the same approach path |
bound_max_clock | 1 | any falsifying state needing a second unit of elapsed time, on this arm |
bound_reset_window | 0 | the 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 reachestok.liveover 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 wheregate.alwaysUvis 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 1 | the 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_channels | 2 | a falsifying state that first arises over a third concurrent channel, on the wide-permission arm |
bound_max_retries | 2 | the six rungs between two and the shipped eight, on the approach to the antecedent |
bound_mismatch_limit | 1 | the two mismatches between one and the shipped three, on that same approach |
bound_perm_subsets | 16 | nothing — 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 drawspsfromSUBSET Permsrather 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, andGetPinToken’sr \in RPs \cup {NoRp}only decides which credential a token is bound to. The permission set is likewise off the implication —tok.liveis 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_rps | 1 | the second relying party, dropped on this arm as on the wide-permission one and harmless for the same reason |
bound_channels | 2 | a falsifying state that first arises over a third concurrent channel, on the forced-change arm |
bound_max_retries | 2 | the six rungs between two and the shipped eight, on the approach to the antecedent |
bound_mismatch_limit | 1 | the two mismatches between one and the shipped three, on that same approach |
bound_gate_bits | 5 | any 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 putsgate.forceChangein 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 reachtok' = [live \|-> TRUE, …]. The five gate bits are the record fieldsgatecarries (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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_invariants | 2 | anything 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_switches | 1 | any 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_states | 12 | nothing — 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_rps | 2 | a falsifying state that first arises over a third relying party, on the one row where this invariant is seen to fail |
bound_channels | 2 | a 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_countover 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_tagged_owners | 1 | any 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_sites | 4 | an 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_sites | 5 | anything 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_callers | 1 | coverage 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_argument | 5 | anything 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_crates | 2 | a 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_wipeat crates/rsk-fs/src/fs.rs:543 and the overwriting writer at clientpin.rs:914-915. Five files over two crates, against the ONE filedocs/authorization-slice.md:462-467estimated (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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_patch_hunks | 2 | any 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_files | 1 | a defect that has to span two files |
bound_credited_configurations | 1 | the 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_half | 0 | everything 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_crates | 1 | any 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 movesctx.state.reset()from ahead of the flash work to behindensure_seed(formal/comutants.toml:373-386) — the E76 regression, in the shipped file — andexpect = "killed"is a RECORDED verdict in that file’s own status vocabulary. The one credited configuration is Solo_NoLiveTokenWithoutPinRecord.cfg, reached only becausecomutate.solo_indexreads 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 assertsstate.keydev_dec.is_none(); the only test that asserts both!fs.has_data(EF_PIN)andpaut.permissions == 0tears nothing, so the mutant leaves it green. This row was NOT re-run here —comutate.py runpatches 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_dependent_model_sites | 3 | any 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_conjuncts | 1 | the 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_removal | 0 | anything 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_removal | 0 | the 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:ConfigGuardat :1091 carries nopin.setconjunct 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_fids | 2 | any 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_fid | 3 | nothing 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_variables | 7 | every 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_invariants | 6 | whatever 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_switches | 9 | any 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_disjuncts | 7 | any 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 isFsover aStorage, 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_bug_switches_for_this_invariant | 2 | the 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_tiers | 2 | nothing 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_runs | 4 | every run not in the [[artifact]] rows below. A verdict with no log beside it is a sentence, and this bundle carries none |
bound_killed | 4 | whether 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_configurations | 22 | any 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_green | 364 | everything 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 everyBug*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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_refinement_markers | 5 | every 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_sites | 4 | removals 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_lines | 895 | everything 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_reviewers | 1 | independence. 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_read | 3 | the rest of the crate. rsk-fs is fifteen source files and this row opened the ones the subjects name |
bound_crate_kani_proofs | 13 | whether 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_view_fids | 3 | any 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_predicates | 3 | the 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_crate | 13 | every 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_run | 5 | the 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_fids | 24 | the 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_properties | 2 | whether 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_fids | 2 | any 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_fid | 3 | nothing 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_variables | 7 | every 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_invariants | 6 | whatever 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_switches | 9 | any 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_disjuncts | 7 | any 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 isFsover aStorage, 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_bug_switches_for_this_invariant | 2 | the 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_tiers | 2 | nothing 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_runs | 4 | every run not in the [[artifact]] rows below. A verdict with no log beside it is a sentence, and this bundle carries none |
bound_killed | 4 | whether 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_configurations | 22 | any 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_green | 364 | everything 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 everyBug*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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_refinement_markers | 2 | every 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_sites | 4 | removals 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_lines | 895 | everything 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_reviewers | 1 | independence. 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_read | 2 | the rest of the crate. rsk-fs is fifteen source files and this row opened the ones the subjects name |
bound_crate_kani_proofs | 13 | whether 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_view_fids | 3 | any 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_predicates | 3 | the 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_crate | 13 | every 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_run | 5 | the 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_fids | 24 | the 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_properties | 2 | whether 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_fids | 2 | any 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_fid | 3 | nothing 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_variables | 7 | every 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_invariants | 6 | whatever 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_switches | 9 | any 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_disjuncts | 7 | any 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 isFsover aStorage, 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_bug_switches_for_this_invariant | 3 | the 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_tiers | 2 | nothing 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_runs | 4 | every run not in the [[artifact]] rows below. A verdict with no log beside it is a sentence, and this bundle carries none |
bound_killed | 4 | whether 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_configurations | 22 | any 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_green | 364 | everything 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 everyBug*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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_refinement_markers | 2 | every 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_sites | 4 | removals 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_lines | 895 | everything 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_reviewers | 1 | independence. 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_read | 3 | the rest of the crate. rsk-fs is fifteen source files and this row opened the ones the subjects name |
bound_crate_kani_proofs | 13 | whether 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_view_fids | 3 | any 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_predicates | 3 | the 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_crate | 13 | every 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_run | 5 | the 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_fids | 24 | the 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_properties | 2 | whether 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_fids | 2 | any 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_fid | 3 | nothing 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_variables | 7 | every 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_invariants | 6 | whatever 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_switches | 9 | any 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_disjuncts | 7 | any 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 isFsover aStorage, 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_bug_switches_for_this_invariant | 1 | the 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_tiers | 2 | nothing 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_runs | 2 | every run not in the [[artifact]] rows below. A verdict with no log beside it is a sentence, and this bundle carries none |
bound_killed | 2 | whether 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_configurations | 22 | any 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_green | 364 | everything 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 everyBug*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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_refinement_markers | 2 | every 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_sites | 4 | removals 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_lines | 895 | everything 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_reviewers | 1 | independence. 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_read | 4 | the rest of the crate. rsk-fs is fifteen source files and this row opened the ones the subjects name |
bound_crate_kani_proofs | 13 | whether 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_view_fids | 3 | any 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_predicates | 3 | the 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_crate | 13 | every 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_run | 5 | the 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_fids | 24 | the 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_properties | 2 | whether 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_fids | 2 | any 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_fid | 3 | nothing 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_variables | 7 | every 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_invariants | 6 | whatever 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_switches | 9 | any 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_disjuncts | 7 | any 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 isFsover aStorage, 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_bug_switches_for_this_invariant | 1 | the 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_tiers | 1 | nothing 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_runs | 1 | every run not in the [[artifact]] rows below. A verdict with no log beside it is a sentence, and this bundle carries none |
bound_killed | 1 | whether 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_configurations | 22 | any 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_green | 364 | everything 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 everyBug*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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_refinement_markers | 1 | every 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_sites | 4 | removals 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_lines | 895 | everything 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_reviewers | 1 | independence. 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_read | 2 | the rest of the crate. rsk-fs is fifteen source files and this row opened the ones the subjects name |
bound_crate_kani_proofs | 13 | whether 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_view_fids | 3 | any 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_predicates | 3 | the 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_crate | 13 | every 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_run | 5 | the 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_fids | 24 | the 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_properties | 2 | whether 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_fids | 2 | any 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_fid | 3 | nothing 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_variables | 7 | every 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_invariants | 6 | whatever 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_switches | 9 | any 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_disjuncts | 7 | any 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 isFsover aStorage, 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_bug_switches_for_this_invariant | 1 | the 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_tiers | 2 | nothing 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_runs | 2 | every run not in the [[artifact]] rows below. A verdict with no log beside it is a sentence, and this bundle carries none |
bound_killed | 2 | whether 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_configurations | 22 | any 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_green | 364 | everything 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 everyBug*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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_refinement_markers | 4 | every 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_sites | 4 | removals 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_lines | 895 | everything 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_reviewers | 1 | independence. 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_read | 2 | the rest of the crate. rsk-fs is fifteen source files and this row opened the ones the subjects name |
bound_crate_kani_proofs | 13 | whether 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.
| Bound | Value | What stops being proved |
|---|---|---|
bound_view_fids | 3 | any 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_predicates | 3 | the 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_crate | 13 | every 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_run | 5 | the 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_fids | 24 | the 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_properties | 2 | whether 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.
| Artifact | Discharges | Does not |
|---|---|---|
formal/RSKeyTokenAbstract.tla | tier A: 44 abstract token states, 11 Ops, 3 Outcomes, one four-argument AllowedEventRel, outcomes as labels so an unauthorized success stays distinguishable from a stutter | state NoAuthorizationBypass at all — A carries no invariant, and has no presence, channel, retry, soft-lock or reset-window vocabulary |
formal/RSKeyTokenRefinement.tla, RSKeyTokenView.tla | native INSTANCE refinement B→A over TokenGamma, plus R1oStep’s outcome obligation and R1oOutcomeCoverage’s equality guard on 23 outcome-producing action names | any 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.py | the A relation serialized to Rust and checked exhaustively on the host, so A’s semantics cannot drift from the generated table | give 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.py | the ownership ledger for the token half: 11 volatile writers, 14 persistent writers, 7 outcome producers, each with a derived-and-checked disposition | own anything outside the token: the retry budget, the soft lock, the reset window and the walk owner have no ledger anywhere |
formal/RSKeySecurityState.tla | tier 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 restated | close 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.jsonl | runtime 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 refuse | reach 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.py | 69 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 matrix | the 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 gap | decide 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.py | the 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 untraced | say 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 incrates/rsk-device/src/presence_kani.rs, two of them carrying its name. It appears here only where a mutant is shared;getNextAssertionownership. The stateful assertion walk appears in noformal/*.tlamodule, and the walk-owner harness’s own “what this does not prove” list says thegnawalk is not modelled. It is a stage-4 obligation this slice does not take;EF_DEVICE_PINandEF_MINPINLEN. The model carries one PIN record and says so in as many words aboveLocalPinEnabled— “the device PIN is no CTAP credential, and EF_DEVICE_PIN is not modelled” — whileEF_MINPINLENappears 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
firmwareand 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.
NoAuthorizationBypassat 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; rpBoundis 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;
persistentGrantis that record, not a platform holding it. Since 0x09CB the device writesEF_PAUTHTOKENitself at a boot, a finished reset or a backup load (ProvisionGrant), soUseCm’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 asgate.ppuatandPpuatGuardreads 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) andRESET_WINDOW_MS(10000) are outside it by construction.
The B map
B is formal/RSKeySecurityState.tla. The invariant is three conjuncts:
- the ghost —
"NoAuthorizationBypass" \notin viol; - the §6.5.5.7 triad, read out of state —
(upSpent /\ tok.live) => tok.perms = {}; - the soft lock reflecting its policy —
(lock.policyMism >= MismatchLimit) => lock.soft, withPIN_MISMATCH_LIMIT(3) andMAX_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 gate | Production callers | Reached by the harness? |
|---|---|---|
CredMgmtState::may_walk_rps | one — enumerate_rps, crates/rsk-fido/src/credmgmt.rs, the else if !… arm | no — reproduced |
CredMgmtState::may_walk_creds | one — enumerate_creds, same file, same shape | no — reproduced |
spend_and_verify_pin_hash | three — changePIN’s old-PIN check, the getPinToken door, and the on-pad PIN door, all in crates/rsk-fido/src/clientpin.rs | no 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_lock | crates/rsk-device/src/ctap.rs on both sides of a warm reset, with the board half in firmware/src/pin_lock.rs | no harness exists |
enforce_pin | two distinct private functions, one in makecredential.rs and one in getassertion.rs, one call site each — not one gate with two callers | no |
verify_cm_token | three, all in credmgmt.rs | no |
authorized_by_ppuat | one — authorize_cm, credmgmt.rs | no |
authenticator_config | one — the CBOR dispatch in crates/rsk-fido/src/lib.rs | no |
vendor::pin_gate | six sites in crates/rsk-fido/src/vendor.rs | no |
consume_after_user_presence | one — 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 returns | no |
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:
begin_rpswritesrp_totalin one shot. The realenumerate_rpssetsrp_total = 0first and returnsErr(NoCredentials)on an empty scan before advancingrp_counteror stampinglast_leg_ms— an intermediate state the harness has no shape for;- 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; begin_credsnever writescm.rp_id_hash, which the realenumerate_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.
| id | Assumption | Class | Who could discharge it | Expressible in assumption_gate today |
|---|---|---|---|---|
AS-AUTH-1 | tools/emu implements the same authorization gates as the firmware, so a recorded session is evidence about the firmware | tool fidelity | a board recording of the same session, compared boundary by boundary | no — not a model constant |
AS-AUTH-2 | The build does not ship always-uv, so gate.alwaysUv is a free state variable rather than pinned true | build configuration | the matrix’s firmware-always-uv column, whose settling question already names SEC-FIDO-001 | yes, 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-3 | A CTAPHID channel id is a routing label the sender writes, so channel ownership is a scoping rule and never an authentication one | threat model | a clause of the threat model; state.rs states it in prose today | no |
AS-AUTH-4 | PowerOnClearsScratch2 — a real power-on clears the watchdog word the soft lock rides in | platform | the board measurement assurance/assumptions.toml already describes | registered, 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-5 | PermSets, five of the sixteen subsets, is the set a host can actually obtain | model fidelity | reading the two production sites that mint permissions; it is argued in the module, not measured | no |
AS-AUTH-6 | One credential per relying party | model abstraction | the store slice; MAX_RESIDENT_CREDENTIALS (256) is the shipped cardinality | no |
AS-AUTH-7 | Kani/CBMC is sound for the harness’s arithmetic and the pinned solver is the one that ran | tool TCB | the pinned toolchain and a recorded tool hash | no |
AS-AUTH-8 | ea-conformance-rpid’s enterprise-attestation allowlist is not an authorization gate | build configuration | the matrix’s own settling question for that column, which asks exactly this | no |
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”.
| Level | Mutant | Must redden | Expected reason |
|---|---|---|---|
| A | an edge added to AllowedRelation that is Authorized with ~pinSet and no live token | the new A-level configuration | NoAuthorizationBypassA violated on that edge, naming the op |
| A | RequiredGate weakened to TRUE for one op | E4a’s disagreement configuration, not the invariant | it stops being RED for that op’s tuples. A disagreement configuration that goes GREEN is a refusal, not a pass |
| B | the 11 existing switches | 11 Solo_*.cfg and the Mut_* family — already registered RED in formal/floors.txt | the invariant named by each Solo_* |
| B | deleting one action’s viol write | the new ghost-completeness row | the row names the action whose write is gone |
| B→A | MutateTokenGamma, BugDeadTokenAuthorized | TokenRefinementBadMap.cfg, TokenRefinementDeadToken.cfg — already RED | the refinement or the outcome clause |
| C | BugCmWalkIgnoresChannel re-driven against the harness rather than the unit suite | cargo kani -p rsk-fido --harness no_authorization_bypass_walk_owner | assertion NoAuthorizationBypass/B1 or /B2 |
| C | a new authorize_cm-weakening patch at the call site | the new at-call-site harness | the authorization assertion, not the cursor assertion |
| trace | MutateUvNotRqd, MutateAlwaysUvArm, MutateResetWindow, MutatePinSet | four TraceSecurityBad*.cfg — already RED, each with its reason recorded | R4cGateAnswers, 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 print | What would make it fail |
|---|---|---|
| E1 | not 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 one | the 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 |
| E2 | the 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 0 | naming 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 |
| E3 | for 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 it | deleting 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 |
| E4a | at tier A: a configuration whose invariant is RequiredGate(op, s) = GateFromRelation(op, s) goes RED, and its counterexample set is written into the bundle | the 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 |
| E4b | at 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 tree | there 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 |
| E5 | cargo kani -p rsk-fido --harness no_authorization_bypass_walk_owner goes red under the BugCmWalkIgnoresChannel patch, and names NoAuthorizationBypass/B1 or /B2 | it 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 |
| E6 | a 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 range | ten 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 |
| E7 | after 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 gap | using 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 |
| E8 | SEC-FIDO-001’s status is still BOUNDED | nothing — 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 |
| E9 | nix 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 second | reading 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.
- 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. - 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. - 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,
cfgand feature set, and the relation between each bound and the shipped constant.KAT/differentialis published vectors, or a reference implementation, run against this one; it is discharged by the#[test]or thetests/*.pythat RAN them, never by the table they sit in — and the gate holds the second half as literally as the first, a.pyoutsidetests/needing to name adefof its own that a test runner collects, which in Python is the name and not an attribute. It is notmeasurement, which in this contract means a result taken off a board and owes the silicon revision it was taken on. - 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 withcargo install --locked kani-verifier, so its version is pinned by a workflow variable and not byflake.lock. A bundle that records the number without that provenance records a version nothing in the tree holds. - 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. - Raw artifact or log — the path to the unedited output of every run, kept whole. A summarized log is not an artifact.
- Assumptions and TCB / trust dependencies — the eight
AS-AUTH-*rows above, each with its class, its discharger and whether it is expressible inassurance/assumptions.tomltoday; plus every solver, compiler and platform dependency on the path. - Mutation verdicts — per mutant: the level, the patch anchor, the
invocation, the verdict, the assertion that fell and its direction, and
the
readingthat argues whether it describes the modelled defect or its inverse. A row whose direction isinverseis a finding about the mutant and not a result about the property, so it also carries adisposition: eithersuperseded, naming insuperseded_byanother row of the group that corrects it — a chain that must end at a row which is not itselfinverse, because a cycle corrects nothing — orkept-as-a-finding. Both arms owe thereading, and the success line counts the disposed rows apart from the verdicts so one cannot be read as a kill. - 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.
- 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
NoLiveTokenWithoutPinRecordmaps to A almost directly aslive => pinSet; - groups 7, 8 and 10 are more expensive, and that is the direction the
intuition gets wrong. On
SEC-FIDO-001those fields are transcription — the assumptions are argued in the module, the mutation verdicts exist, the caller set is short. OnSEC-FIDO-007every one of them has to be produced from nothing: thekeydev_decRAM copy’s reachability argument spanscrates/rsk-fido/src/seed.rs, the field’s home instate.rsand the load preference incrates/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-007needed either a dedicatedBug*switch per invariant or a change to howcomutate.pyattributes a bug to an invariant. Naming that blocker was this counterpart’s real deliverable, and the second option is the one taken —comutate.solo_indexreads 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-labelledAllowedEventRel.Nextis its existential closure, not a second relation. - B is
formal/RSKeySecurityState.tla. TLC checks nativeINSTANCErefinement inTokenRefinement.cfg, and checks labelled outcomes separately inTokenRefinementOutcome.cfg. - C is
(FidoState, TokenPersistentView). The persistent view contains exactlyEF_PINandEF_PAUTHTOKEN.EF_ALWAYS_UVis 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 class | Required BootState | Evidence status |
|---|---|---|
| Cold power cycle | warm=false, lock clear | Decoder and model agree; physical scratch2 clearing is M7-Q1 |
Host sys_reset | warm=true, whole lock restored | Encoded/decoded in firmware/src/pin_lock.rs; emulator boot tests cover the consumer |
| Return from BOOTSEL | Cold semantics required | M7-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:
| ID | Clause | Surviving fact | Gate that must still exist |
|---|---|---|---|
SEC-FIDO-006A | ResetKeepsThePinGate | owner credential + owner seed | EF_PIN |
SEC-FIDO-006B | ResetKeepsTheAlwaysUvGate | owner credential + owner seed | EF_ALWAYS_UV |
SEC-FIDO-006C | ResetKeepsTheBackupSeal | owner’s pre-reset seed | EF_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
| Layer | Owner | What it establishes |
|---|---|---|
| Requirement | assurance/properties.toml | Stable IDs, statements, and the bounded evidence ceiling |
| TLA+ B | formal/RSKeySecurityState.tla | Arbitrary ordering within the secret and gate phases; abort, real power cut, boot-time seed provisioning, and all three clauses |
| Rust refinement | crates/rsk-fido/src/reset_assurance.rs | The concrete phase machine and abstraction of the persistent/volatile facts observed by the clauses |
| Kani | crates/rsk-fido/src/reset_refinement_kani.rs | Initialization and one-step induction across begin, every relevant delete, phase advances, abort, finish, reboot, and an unrelated FID |
| Power-cut fuzz | fuzz/fuzz_targets/power_cut.rs | The 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 board | tests/29_reset_power_cut.py | The 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:
- retire volatile state;
- delete
FIDO_SEED_FIDS; - sweep non-gate FIDO secrets until enumeration completes;
- sweep gates until enumeration completes;
- 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 expandedzeroizeloops 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
FidoStateare 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 action | Concrete step | The clause |
|---|---|---|
Put(f, v) | mark_present | f is decided live; no other FID moves |
Delete(f) | mark_absent | f is decided absent; a live neighbour stays live |
Confirm(f), fault = FALSE | record_unless_faulted | the backend’s answer is cached as decided |
Confirm(f), fault = TRUE | record_unless_faulted | nothing is cached — audit run-36 |
Init / Reboot | Fs::new | nothing cached, nothing decided |
| — | known_absent | a 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 >> 3puts0xE010at byte 7170 of 8192, and the compile-time assert above owns that; - that EF_META is disjoint from every FID an applet writes. At
0xE010it is outside every applet range; at0x0017it is inside the file space. That is an over-approximation the shrink INVENTS rather than one it hides — ameta_addwhose subject is EF_META itself is a state the shipped store cannot reach — sostore_meta_kani.rsassumes the collision away and says so; - that
scanregisters every file it is handed. Itsfid == EF_METAskip (fs.rs:287) is compiled undercfg(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 reachesscan; it is what theScanbullet 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,NoFalseMetaAbsentandNoSilentOrphanhave a bridge now —store_steps_tests.rs, below — but it is a host sweep, so the four stayMODELLED-ONLY:assurance_gatereadsBOUNDEDoff a Kani harness name.A harness that does nothing but
meta_addfailed, 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 sFrom 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 isEF_META’s VALUE (0xE010, index 7170), not the map’s WIDTH, and the value takes the same one-line aliasFID_PRESENT_BYTESalready has: with#[cfg(kani)] EF_META = 0x0017and nothing else changed, the same harness is0 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 theFaultBackendthis page’s cache harnesses already use:meta_addrefusing a FAILED EF_META read rather than rebuilding from an empty blob (0.317 s), andmeta_deletenever caching that same read as a decided absence (0.156 s), both measured by theprtier that runs them. Each asserts BOTH directions as separate clauses, because a refusal alone is satisfied by ameta_addthat refuses everything — and because Kani 0.67 reports everyassert!message in this crate as “a placeholder message”, so the failing LINE is the only thing that tells a kill from its inverse. Driven:BugMetaAddDropsOnFaultfails the first on the faulted arm,BugMetaDeleteDropsOnFaultfails the second on the faulted arm.What did not move is the two statuses.
SEC-STORE-003andSEC-STORE-004stayMODELLED-ONLY, and the two harnesses are named so that they stay there:assurance_gateFORCESBOUNDEDfrom a harness function name containing the property’s, without looking at domain, bound orcfg, so a name is all it would have taken. AFaultBackendholds no blob, someta[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.BOUNDEDthere would be a scalar going up while the domain went quietly down. The thing that would earn it is a theorem carrying thepresent/decidedarithmetic to the whole shippedu16domain, 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_MAXshrunk 1024 → 32, both blob obligations time out at 420 s — re-measured,CBMC timed out, at 419.9 s of solving for the record ameta_addmay 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.rscarries it; Kani does not. -
Not a whole-behaviour result. The Kani harnesses are one-step obligations at every FID, which is why
SEC-STORE-002isBOUNDEDand 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*_landedtwin — 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 (ameta_adddropping 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”.
| Sweep | What it covers | Size |
|---|---|---|
| every three-step sequence | the clauses over a fresh store | 12³ = 1728 orderings, 5184 steps |
the same, then a reboot with no scan | EF_META UNKNOWN rather than confirmed — the 0x077C door | 1728 × 12 more steps |
| every two-step sequence over a failing medium | the FAULT path three of the recorders are about | 144 orderings |
| each of the three helper predicates against the state its invariant forbids | that a recorder can answer TRUE at all, and one state over that it does not | 3 × 2 assertions |
| the fifth recorder | pairs 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 recorder | that the sweeps are not a loop over nothing | 5 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.
| Candidate | Where | Size | Portable to a verified C subset? |
|---|---|---|---|
| gate / transition functions | the ten concrete gates docs/authorization-slice.md lists, over crates/rsk-fido/src/state.rs | 856 lines in state.rs alone | No. Half are generic over two traits (<S: Storage, R: Rng>); the other half take a Rust struct by reference, whose layout Rust owns |
| zeroization routines | 16 scrub / wipe_* sites across crates/ and firmware/, and rsk_secret’s drops | 16 sites, 49 files using zeroize | No. Each is a method on a Rust type, and the drop glue that makes it sound is the compiler’s |
| RSA exponentiation and CRT | Rust with shared host and device Montgomery arithmetic | 349 lines in montgomery.rs | Moving the kernels to C would require a source rewrite and a new FFI contract |
| ML-DSA reductions | crates/rsk-mldsa/src/reduce.rs, ntt.rs, round.rs | 256 lines | Yes, in principle. Branch-free integer arithmetic, no generic function in any of the three |
| linker-generated boundaries | 15 of the 32 [[boundary]] rows in assurance/toolchain.toml | 15 symbol imports | Not 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.
| Step | Subject | What a second language does to it |
|---|---|---|
| build the firmware | none | the derivation must carry a second toolchain |
| reproducibility gate | bit-for-bit | the second compiler must be deterministic, and reproducible by whoever holds its licence |
| CycloneDX SBOM | inventory | cargo 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
| Resource | Secure owner | Non-secure access |
|---|---|---|
| Memory | S 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 controls | RSA engine, DRBG, mailbox, stack, launch and flash-pause handshakes | No access to the RSA engine or its reserved SIO resources |
| USB hardware | USBCTRL, DPRAM, physical endpoints, interrupt and bus lifecycle | Bounded endpoint operations and copies of packets and events |
| USB classes | S supplies the boot identity and interface mask, and checks endpoint allocation. | USB descriptors, CTAPHID and CCID framing, keepalives, OTP HID and keyboard reports |
| Timers | TIMER0, tick generation, clocks and reset controls | TIMER1 for the NS executor |
| Flash and keys | KV store, QMI and XIP controls, OTP and TRNG | Applet operations through the worker |
| Board I/O | Presence button, panel and touch, LED and their GPIO, PWM, PIO, SPI and I²C | Status and cancellation through the gateways |
| Access policy | SAU, MPU setup, ACCESSCTRL, DMA channel security, interrupt routing and watchdog | Only 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
- 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.
- 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.
- A Secure storage task binds the root-key source and mounts the KV
backend. The boot task scans file records and reads
EF_PHYto choose the USB identity and interface mask. If storage is unavailable, it selects CCID only for recovery. - 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.
- 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.
- 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.
| Crate | Role |
|---|---|
firmware | Secure board startup, USB controller, worker, OTP, storage, presence and RSA core1 |
firmware-ns | USB descriptors and classes, CTAPHID and CCID framing, OTP HID, keyboard and TIMER1 |
rsk-wipe | SRAM-resident flash erase utility that reboots to BOOTSEL |
rsk-device | Applet composition, dispatch and capability gates, transport sessions, presence arbitration and reboot requests |
rsk-sdk | APDU and BER-TLV codecs, applet dispatch, status words, RNG and presence traits |
rsk-usb | CTAPHID and CCID transport state, USB identity and the shared worker ABI |
rsk-fido | CTAP2 and U2F, credential and PIN/UV policy, extensions, attestation and seed management |
rsk-openpgp | OpenPGP card data, PIN state, key lifecycle, crypto and attestation |
rsk-piv | PIV slot policies, PIN and management authentication, key and certificate lifecycle and private operations |
rsk-oath | YKOATH TOTP and HOTP credentials, access codes and touch policy |
rsk-otp | Four Yubico OTP slots, CCID commands, OTP HID reports and keyboard tickets |
rsk-mgmt | YubiKey management commands, including reading and writing the device configuration |
rsk-rescue | Recovery and provisioning commands for board config, flash, attestation, reboot and OTP sealing |
rsk-vendor | Vendor AID commands for LED settings, reboot and diagnostics |
rsk-fs | File IDs, metadata, applet storage APIs and record lifecycle over the Storage trait |
rsk-store | NOR flash backend, authenticated directory and counter banks, legacy import, fault recovery and compaction |
rsk-devconf | EF_DEV_CONF codec, application capability masks, config lock and updates |
rsk-phy | EF_PHY codec and boot policy for USB identity, interface mask and board settings |
rsk-led | EF_LED_CONF codec for status LED behavior |
rsk-crypto | Hashes, MACs, KDFs, symmetric crypto, DRBG and post-quantum primitives |
rsk-ec | EC and Edwards key formats, public-key derivation, signing and key agreement |
rsk-rsa | RSA key generation and sealed CRT key layout, blinded and fault-checked private operations, with Rust Montgomery arithmetic shared by the host and device |
rsk-mldsa | Stack-bounded ML-DSA for the three parameter sets |
rsk-sha256 | SHA-256 compression and digest implementation |
rsk-sha512 | Compact SHA-512 and SHA-384 implementations for XIP |
rsk-secret | Secret and WipeGuard for wiping key material |
rsk-x509 | DER and certificate construction shared by the card applets |
rsk-bench | Cold sample, median and median absolute deviation for on-device benchmarks |
rsk-bip39 | BIP-39 mnemonic encoding for the display’s recovery screen |
rsk-slip39 | SLIP-39 share encoding for the display’s recovery screen |
rsk-ui | Display layout, prompt text and sanitization, retained scenes and rasterization |
rsk-display | Trusted-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.
| Region | Start | End | Contents |
|---|---|---|---|
| Secure image region | 0x10000000 | 0x1026F000 | Secure firmware and boot blocks |
| NSC | 0x1026F000 | 0x10270000 | CMSE gateway veneers |
| NS image | 0x10270000 | 0x10280000 | Embedded NS firmware |
| KVMAIN | 0x10280000 | 0x103E0000 | 1408 KiB main payload store |
| KVCNT | 0x103E0000 | 0x10400000 | 128 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 bybcdDeviceand 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:
| Transport | Carries | Host API |
|---|---|---|
| Keyboard HID | Yubico OTP feature reports and typed OTP output | OS HID stack / Yubico OTP libraries |
CTAPHID (FIDO HID, usage page 0xF1D0) | CTAP1/U2F, CTAP2, and native HID DeviceInfo commands | hidapi |
| CCID (PC/SC smart-card) | ISO-7816 applets selected by AID, including CTAP over CCID | pyscard / 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 atx = Fso a larger configured retry total cannot wrap into63 C0= blocked), OpenPGP’s69 82as 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.
| SW | Name | Meaning |
|---|---|---|
9000 | OK | success |
63C0 | — | WRITE CONFIG (§6) with a configuration lock code that is not the one set, as a YubiKey 5.8.0 answers it |
6400 | EXEC_ERROR | execution error (internal) |
6285 | TERMINATED | OpenPGP after TERMINATE DF: every command, SELECT included, until ACTIVATE FILE (§5.1) |
6581 | MEMORY_FAILURE | a 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 |
6700 | WRONG_LENGTH | bad Lc/Le for this command |
6883 | LAST_CHAIN_EXPECTED | an APDU arrived that neither continues nor closes the open command chain |
6982 | SECURITY_STATUS_NOT_SATISFIED | auth/precondition missing |
6983 | PIN_BLOCKED | PIN verification is blocked |
6984 | DATA_INVALID | malformed payload (e.g. bad guard magic) |
6985 | CONDITIONS_NOT_SATISFIED | state 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 |
6986 | COMMAND_NOT_ALLOWED | WRITE 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 |
6A80 | WRONG_DATA | bad 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 |
6A82 | FILE_NOT_FOUND | the requested AID or file is unavailable |
6A84 | FILE_FULL | the applet’s storage limit is exhausted |
6A86 | INCORRECT_P1P2 | unsupported P1/P2 |
6A88 | REFERENCE_NOT_FOUND | the object, key or PIN the request names is absent (PIV GET METADATA, MOVE KEY, the PIN commands’ key reference) |
6B00 | WRONG_P1P2 | P1/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 |
6D00 | INS_NOT_SUPPORTED | unknown INS for this applet; OpenPGP and PIV answer it to any SELECT but the one by AID, as a YubiKey 5.8.0 does |
6E00 | CLA_NOT_SUPPORTED | wrong 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:
| Byte | Name | Meaning here |
|---|---|---|
0x00 | OK | success |
0x02 | INVALID_PARAMETER | invalid field or public key, unknown vendor subcommand, or invalid encrypted key for UNLOCK/ATT_IMPORT |
0x03 | INVALID_LENGTH | a request exceeds a command’s input limit (for example, the DeviceInfo config blob) |
0x12 | INVALID_CBOR | the body is not exactly one CBOR item (trailing bytes) |
0x14 | MISSING_PARAMETER | required field absent (e.g. blob/pinUvAuthParam) |
0x27 | OPERATION_DENIED | presence declined or timed out, wrong config lock code on a DeviceInfo write, or CBOR disabled by USB_ENABLED |
0x2D | KEEPALIVE_CANCEL | the host cancelled the active CTAPHID CBOR request |
0x2F | USER_ACTION_TIMEOUT | on-device PIN entry timed out, or a CCID FIDO poll/cancel found no pending operation |
0x30 | NOT_ALLOWED | precondition 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 / 0x32 | PIN_INVALID / PIN_BLOCKED | wrong PIN or exhausted retries |
0x33 | PIN_AUTH_INVALID | pinUvAuthParam MAC or acfg permission wrong |
0x36 | PUAT_REQUIRED | the request requires a PIN token or on-device PIN entry (§9.2) |
0x39 | REQUEST_TOO_LARGE | subCommandParams over the limit |
0x3D | INTEGRITY_FAILURE | blob failed authenticated decryption |
0x3E | INVALID_SUBCOMMAND | unknown vendorCommandId under authenticatorConfig’s 0xFF. A 0x41 subcommand this build does not implement is 0x02, matching a YubiKey |
0x7F | OTHER | internal 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):
| Preset | VID:PID | Manufacturer / Product strings | Notes |
|---|---|---|---|
RSKey (default) | 1209:F1D2 | RS-Key / RS-Key Security Key | pid.codes allocation |
Yubikey5 (opt-in interop) | 1050:0407 | Yubico / YubiKey RSK OTP+FIDO+CCID | so ykman/Yubico Authenticator derive PID from the PC/SC reader name |
| others | NitroHSM, 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
| Field | Value | Where |
|---|---|---|
| firmwareVersion | 5.8.0 → 0x00050800 | CTAP getInfo 0x0E; Management/OTP DeviceInfo TAG_VERSION; Management SELECT ("Virtual mgr - FW version 5.8.0" ASCII, a YubiKey 5.8.0’s words) |
bcdDevice | Firmware build counter | USB device descriptor (firmware/src/main.rs device_release) |
| AAGUID | 2479c7bf-6b30-5683-9ec8-0e8171a918b7 | CTAP 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.
| Applet | AID | Transport | Spec status | Config-relevant? |
|---|---|---|---|---|
| FIDO2 / U2F | A0 00 00 06 47 2F 00 01 | CCID (§5.3) + CTAPHID (no SELECT) | Standard (CTAP2 + CTAP1) | identity only |
| FIDO2 (backup id) | B0 00 00 06 47 2F 00 01 | none — unregistered | RS-Key | — |
| U2F (standalone id) | A0 00 00 05 27 10 02 | none — unregistered; U2F rides the FIDO2 AID | Standard (CTAP1/U2F) | — |
| Management | A0 00 00 05 27 47 11 17 | CCID | Yubico-compatible | yes — §6 |
| OATH | A0 00 00 05 27 21 01 01 | CCID | Yubico OATH | data only |
| OTP | A0 00 00 05 27 20 01 01 | CCID | Yubico OTP | data only |
| PIV | A0 00 00 03 08 00 00 10 00 01 00 | CCID | NIST SP 800-73 | data only |
| OpenPGP | D2 76 00 01 24 01 | CCID | OpenPGP card 3.x | data only |
| Rescue | A0 58 3F C1 9B 7E 4F 21 | CCID | RS-Key-specific | yes — §7 |
| Vendor / LED | F0 00 00 00 01 | CCID + CTAPHID_MSG | RS-Key-specific | yes — §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 (
versionsadvertisesFIDO_2_0,FIDO_2_1andFIDO_2_3): getInfo, makeCredential, getAssertion, getNextAssertion, clientPIN, reset, selection, credentialManagement, authenticatorConfig, largeBlobs (writable without apinUvAuthParamuntil a PIN is set oralwaysUvis on, per §6.10.2 — a--features largeblob-extbuild serves the CTAP 2.3 §12.4largeBlobextension in its place and answers0x0CwithCTAP1_ERR_INVALID_COMMAND, because §12.4 forbids supporting both; detect it from getInfo, which dropslargeBlobs,maxSerializedLargeBlobArrayand thelargeBlobKeyextension in that build).options.perCredMgmtROis true, so a tool may request thepcmrpermission (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 behindgetNextRP/getNextCredentialretires 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 alargeBlobsset; there an abandoned transfer answersCTAP2_ERR_INVALID_SEQand the previously stored array is left intact.maxMsgSize=7609. BothtransportsForReset(0x1A) andtransports(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-pinandfips-profileenable it by default; other builds start withfalse. An authenticatedsetMinPINLengthrequest can enable it with subCommandParams key4: true. A false or absent key leaves it unchanged; onlyauthenticatorResetrestores 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. UnderforcePINChange, an unread current verifier returnsCTAP2_ERR_OTHER(0x7F) and leaves the change pending; it cannot establish a different PIN. The optionalpinComplexityPolicyURL(0x1C) is never emitted.longTouchForReset(0x18) isfalse: 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,authenticatorResetand a seedBACKUP_LOADmint the persistent pinUvAuthToken it is keyed by; setting or changing the PIN, or forcing a change, revokes that grant until the next boot orpcmrrequest, and a soft-locked key omits it — and carriesiv ‖ AES-128-CBC(k, id)— 32 bytes — whereidis a 128-bit device identifier andk = 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, soauthenticatorResetchanges it.encCredStoreState(0x1E) is that same construction under the labelencCredStoreState, over a 128-bit tag that takes a new random value whenever the set of discoverable credentials changes — a create, adeleteCredential, anupdateUserInformation, 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 andauthenticatorResetderive it from the new seed, aBACKUP_LOADdraws one — so a reset changes it even over a store nothing had changed (CTAP 2.3 §6.6). makeCredential acceptsattestationFormatsPreference(request0x0B): a list of exactly["none"]is answered withfmt:"none"and an empty — but present —attStmt, and nothing is signed. Any other list, an empty one, or an absent field leaves the usualpackedstatement, because choosing by lowest supported index needs more than one supported format andattestationFormats(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-Key0x0A6A+): the device’s own certificate attests, withoutep, and the preference holds. Vendor-facilitated (type 1) enterprise attestation reads a stored RP list.enterpriseAttestation: 1returnsepand the org certificate only for an RP on that list; any other RP gets the ordinarypackedstatement with the device’s own certificate and noep. The list holds up to 8sha256(rpId)entries and is empty until written, so a device upgraded from firmware without it behaves exactly as before;authenticatorResetclears it. Write it withauthenticatorConfig(0x0D) subCommandvendorPrototype(0xFF) and subCommandParams{1: 0x0e6841934e719be7, 4: [rpId…]}— the ids as text, hashed on the device — gated by anacfgpinUvAuthToken and no touch, the same authorizationenableEnterpriseAttestationitself takes. An empty array clears the list; more than 8 entries is refused withCTAP2_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 viapubKeyCredParams; advertised in getInfo only under theadvertise-pqcbuild, 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-bytemaxMsgSize. The curve-explicit ids ESP256-9, Ed25519-19, ESP384-51and ESP512-52are 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 DATAanswers6A82to a tag list it cannot read and to a P1-P2 other than3FFF, 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 answers6581. 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 answers6581. An existing F9 key that the current root cannot open, or that names another curve, also makes SELECT answer6581, 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 DATAanswers6982without the management key, then6A80to a P1-P2 other than3FFFand to a body that is not5C 03 <id>followed directly by53with its length in the shortest form; bytes after the object are ignored. It stores any5Fxxxxbut5FFF01(the attestation certificate, which no host may write), as a YubiKey does:5FC100–5FC1EFand5FFF00each in its own file, every other id in a pool of 256 objects and 32 KiB of bodies, whose next write answers6A84once either is spent, as a full YubiKey does; an empty53deletes the object, answering9000for one not held. An object is up to 3063 bytes,6700past it, as on a YubiKey 5.8.0: the 3072 bytes a command chain reassembles less the5C 03 id 53 82 LL LLheader. With an extendedLe, a single APDU has room for 3044 object bytes. WithoutLeit has room for 3046.GET DATAfor 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 number0x10) instead of6A82, a hostPUT DATAoverrides it, and an emptyPUT DATAfalls 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
6581and 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: DO0xFAlists01 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 touchD9sets; 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 its7F21occurrence, signed by a P-384 attestation key (reference81) whose self-signed certificate is DOFC. The key reads through GENERATEP1 = 81underB6 { 84 01 81 }and is listed inDE,DA(inside73and inFA),C5/C6/CDandD9, where a YubiKey lists its own; no host can import it, generate it or writeFC. So is Yubico’s SET PIN RETRIES (00 F2 00 00 03 <PW1> <RC> <PW3>, whatykman openpgp access set-retriessends), as a YubiKey 5.8.0 answers it:6982without PW3, then6A80for 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 (C4shows00for it), and PUT DATAD3starts 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 1FP1=0), its rescue twin, and the auto-reboot after a phyCONFIG_WRITEare 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.
| P1 | Name | Behaviour |
|---|---|---|
03 | enforce-user-presence-and-sign | touch required; TUP flag set in the response |
07 | check-only | valid handle → 6985, unknown handle → 6A80; never touches |
08 | don’t-enforce-user-presence-and-sign | signs 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.
| Step | APDU | Answer |
|---|---|---|
| Select | 00 A4 04 00 08 A0000006472F0001 00 | 9000 with body U2F_V2, or FIDO_2_0 while alwaysUv has U2F off (below) |
| CTAP2 | 80 10 00 00 Lc <cmd ‖ CBOR> 00 | 9000 (or 61xx, below) with <status ‖ CBOR> |
| U2F | 00 01/02/03 … | the CTAP1 answer; 6E00 under class 80; 6986 while alwaysUv has U2F off |
| Poll, cancel | 80 11 00 00, 80 11 11 00 | 9000 with body 2F, whatever the P1-P2. Use CCID ABORT to cancel in-flight work |
| Control | 80 12 01 00 | 9000, 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.
| INS | Name | Request | Response |
|---|---|---|---|
1D | READ CONFIG | — | DeviceInfo TLV (see below) |
1C | WRITE CONFIG | data[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 | — | anything | 9000 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:
| Tag | Name | Len | Value |
|---|---|---|---|
01 | USB_SUPPORTED | 2 | capability bitmask (BE16) of applications the firmware implements |
02 | SERIAL | 4 | 8-digit serial (chip-id[0..4], MSB masked & 0x03) |
04 | FORM_FACTOR | 1 | 01 = USB-A keychain |
05 | VERSION | 3 | major, minor, patch (default 05 08 00) |
03 | USB_ENABLED | 2 | currently-enabled capability bitmask (BE16) |
08 | DEVICE_FLAGS | 1 | 80 = touch-eject, 40 = remote wakeup; 00 unless a host set them |
0A | CONFIG_LOCK | 1 | 00 = 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:
0Awith a 16-byte code, on an unlocked device or with the current code in0B. Clear:0Aof 16 zero bytes, with the current code (ykman’s--clear). A code of any other width, in either tag, is refused as malformed (6A80;0x02overCONFIG_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,0x27overCONFIG_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) holds01 ‖ 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, likeEF_DEV_CONF. The display build’s factory reset or anrsk-wipeerase 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 (rescue1C/01, vendor SET LED10,CONFIG_WRITEtargets1and2over either transport, theauthenticatorConfigphy ids) is refused as a DeviceInfo write without its code is (6986;0x30over 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):
| Bit | Application |
|---|---|
0x0001 | OTP |
0x0002 | U2F |
0x0008 | OpenPGP |
0x0010 | PIV |
0x0020 | OATH |
0x0200 | FIDO2 |
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 (
6A80otherwise): it must be well-formed TLV, carry only tags a host may write (03,06,07,08,0A,0B,0C,0E,17— ykman’sDeviceConfigset), and fit the smallest transport’s response buffer. The device-owned identity tags (01supported,02serial,04form factor,05version) 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 survivesauthenticatorReset. 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-configrestores 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’sdevice_reset(sent only when DeviceInfo reports a blocked reset or a Bio with PIV), is6D00, as on a YubiKey 5.8.0;1Eis acknowledged and does nothing. Both were a presence-gated factory reset before 0x0A01, and the rescue and vendor applets’ own1E/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 Management1Eresets FIDO, gets9000here with nothing erased: reset FIDO with CTAPauthenticatorResetinstead.
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.
| INS | P1 | P2 | Request data | Response | Purpose |
|---|---|---|---|---|---|
10 | 01 | 00 | 32-byte SHA-256 digest | 64-byte secp256k1 signature | KEYDEV: sign a digest with the device attestation key |
10 | 02 | 00 | — | 65-byte uncompressed pubkey (04 ‖ X ‖ Y) | KEYDEV: read the device attestation pubkey |
10 | 03 | 00 | X.509 DER cert | — | KEYDEV: store the device end-entity cert |
1C | 01 | 00 | phy 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 |
1C | 02 | 01 | YYYY(BE2) Mon Day Wday Hour Min Sec (8 B) | — | SET RTC (civil). January is month 0. Wday is ignored |
1C | 02 | 02 | epoch seconds (BE4) | — | SET RTC (Unix) |
1E | 01 | 00 | — | 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) |
1E | 02 | 00 | — | free ‖ used ‖ kv_total ‖ nfiles ‖ flash_size (5×BE4 = 20 B) | READ flash usage |
1E | 03 | 00 | — | 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 |
1E | 04 | 01 | — | YYYY(BE2) Mon Day Wday Hour Min Sec (8 B) | READ RTC (civil). January is month 0, Sunday is weekday 0. 6985 if unset |
1E | 04 | 02 | — | epoch seconds (BE4) | READ RTC (Unix); 6985 if unset |
1E | 06 | 00 | — | required(1) ‖ version(1) ‖ capacity(1) | READ anti-rollback state |
1E | 07 | 00 | — | left(2) BE16 | This 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 |
1E | 09 | 00 | — | version(1) ‖ status(1) ‖ left(2) BE16 | Read-only automatic page-58 seal result; version 01, status values below |
1B | 58 | 00 | "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 |
1B | 48 | 00 | "ROLLBK" | — | ⚠️ IRREVERSIBLE — set ROLLBACK_REQUIRED fuse (user-presence-gated) |
1F | 00 | 00 | — | — | REBOOT (warm; device drops off bus) |
1F | 01 | 00 | — | — | REBOOT to BOOTSEL bootloader |
1E | 08 | 00 | — | format(1) ‖ ready(1) | Storage state: 02 01 means active v2 authority; 02 00 means recovery required |
20 | 00 | 00 | "INITV2" | — | Initialize wholly erased storage; physical confirmation required, occupied/active media refused; success queues a warm restart |
20 | 01 | 00 | "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; for1B/58also a boot that left nothing under the pre-burn key, as1E/07reports), 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 0x0871the image carries an RP2350 partition table: the bootloader is denied read and write over the KV store, sopicotool save,loadanderaseacross that range answerpermission 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 gates10/01(attestation sign),10/03(store cert),1C/01(WRITE phy record), the irreversible OTP fuse burns1B/58and1B/48, and1F/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, INS1C) is gated the same way only understrict-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.
| Tag | Name | Len | Value |
|---|---|---|---|
00 | VIDPID | 4 | VID(BE2) ‖ PID(BE2) |
04 | LED_GPIO | 1 | data-pin GPIO 0..=29 |
05 | LED_BRIGHTNESS | 1 | global channel max 0..=255 |
06 | OPTS | 2 | flags (BE16): WCID 0x1, DIMM 0x2, DISABLE_POWER_RESET 0x4, LED_STEADY 0x8 |
08 | PRESENCE_TIMEOUT | 1 | touch-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. |
09 | USB_PRODUCT | 1..33 | up 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 |
0A | ENABLED_CURVES | 4 | FIDO curve bitmask (BE32) |
0B | ENABLED_USB_ITF | 1 | interface mask: CCID 0x1, WCID 0x2, HID 0x4, KB 0x8, LWIP 0x10 |
0C | LED_DRIVER | 1 | 1 = gpio, 2 = pimoroni, 3 = ws2812 (follows PicoForge LedDriverType) |
0D | LED_ORDER | 1 | WS2812 wire order: 0 = rgb, 1 = grb |
0E | LED_NUM | 1 | RS-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. |
0F | USB_MANUFACTURER | 1..33 | iManufacturer 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 hwdoes (tools/rsk/hw.py). Preserving tags you don’t recognize costs you nothing, but note the device does not:merge_saveoverlays 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_NUMandUSB_MANUFACTURERin its RS-Key config path. PRESENCE_TIMEOUThas 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_ITFdefaults 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.
| INS | P1 | P2 | Request | Response | Purpose |
|---|---|---|---|---|---|
01 | — | — | — | counter (BE4) | INCREMENT test counter, return new value. User-presence-gated (6985 if declined) |
02 | — | — | — | counter (BE4) | GET test counter |
10 | brightness 0..255 | color | steady | status<<4 | [effect[, speed]] opt. | — | SET LED for one status; 6986, before any touch, while a configuration lock is set (§6.2) |
11 | 00 | 00 | — | 17-byte config block | GET LED config |
1F | 00/01 | 00 | — | — | 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
brightnessis raised to8. - a non-zero
speedis raised to2(speed 1makes 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 boardbounceandflowboth 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.
| Color | Code | Status | Code | |
|---|---|---|---|---|
| off | 0 | idle | 0 | |
| red | 1 | processing | 1 | |
| green | 2 | touch | 2 | |
| blue | 3 | boot | 3 | |
| yellow | 4 | |||
| magenta | 5 | |||
| cyan | 6 | |||
| white | 7 |
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:
| Effect | Code | Effect | Code | |
|---|---|---|---|---|
| legacy (classic blink) | 0 | flow | 3 | |
| vapor (breathing) | 1 | sparkle | 4 | |
| bounce | 2 |
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).
| Sub | Name | Params (key 2) | Response | Gate |
|---|---|---|---|---|
01 | MSE | {1: COSE_Key, 2: mlkem_ek?} | {1: COSE_Key, 2: ct?} | none (establishes channel) |
02 | BACKUP_EXPORT | — | {1: blob(60)} | MSE + presence + PIN gate. Refused if sealed or on a fips-profile build |
03 | BACKUP_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 |
04 | BACKUP_FINALIZE | — | — | Presence + PIN gate. No MSE |
05 | BACKUP_STATE | — | {1: sealed, 2: has_seed, 3: locked, 4: unlocked, 5: rescrub_refused} | ungated |
06 | UNLOCK | {1: blob(60)} | — | MSE (the lock key is the auth) |
07 | AUDIT_READ | — | Journal window (§9.3) | PIN gate. Also requires presence if no host PIN is set |
08 | AUDIT_CHECKPOINT | {1: nonce(bstr, 0–32 bytes)} | Signed checkpoint (§9.3) | PIN gate + presence. Requires a provisioned DEVK |
09 | ATT_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?” |
0A | ATT_CLEAR | — | — | MSE + presence + PIN gate. Without a host PIN, also asks “Erase this identity?” |
0B | ATT_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 |
0C | CONFIG_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 |
0D | CONFIG_READ | {1: target(uint)} — target 1=PHY, 2=LED | PHY {1: blob(bstr), 2: {phy_tag: uint}}, LED {1: blob(bstr)} | Ungated. An absent record gives an empty blob. A read failure returns 7F |
0E | AUDIT_CONFIG | {1: op(uint)} — 0=disable, 1=enable, 2=status | {1: enabled(bool)} | Setting requires PIN gate + presence. Status (2) is ungated |
0F | CONFIG_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_STATEkey 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 —
authenticatorResetand 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 answer0x00whatever the flash said. Key 5 istruewhen 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/§8phy/LED records): a host that cannot reach the CCID interface writes the same config over CTAPHID.targetselects the record:0x00= the management enabled-apps TLV (EF_DEV_CONF, the §6 blob,≤ 128bytes → the sameCTAP1_ERR_INVALID_LENGTH 0x03cap, 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 samemerge_savethe CCID path uses), effective on the next boot);0x02= the LED config block (EF_LED_CONF, §8,CONF_LENbytes), 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_READtarget2returns 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-configadds 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
0x00and writes nothing — no flash write, no journal entry, and forPHYno auto-reboot latch. AnLEDreplay is still applied live, as SET LED’s is. The comparison is against the merged record forPHY, so a partial blob that changes nothing is also a no-op; an absent or unreadableEF_PHYis never “unchanged”, so a host writing the default values to repair one is not answered0x00with nothing stored.A write that does change something is journalled, and a run of them costs a single ring entry.
CONFIG_WRITEis one of three journalled events an ungated host can drive on demand — the others are agetAssertioncarryingup:falseand a U2FAUTHENTICATEwithP1=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. ForCONFIG_WRITE, when the newest entry is already a config write the device folds into it. The entry keeps itsseq, its timestamp (the first write of the run) and itsaux(the target that opened it), and itsdetailbecomesrepeats(2 LE) ‖ targets(1)— the number of further writes absorbed (saturating) and a1 << targetmask of every record the run touched. A run never folds across a power cycle, so theBOOTentry between two runs is never swallowed.The two silent FIDO events use a different encoding: the entry keeps the
detailof the first occurrence (the rpIdHash shown is the run’s first site) and the count of further folded occurrences is a saturating LEu16in 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 advancingseq_next, so the sameseq_nextwith a different head is legitimate and is not a tamper signal (start,seq_nextand the epoch are untouched, so the window still folds to the head exactly as before).
CONFIG_READ 0x0DPHY key 2 (RS-Key0x0852+): the PHY read returns a2: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. Tag8reports 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 key1blob remains the raw override record for read-modify-write. When the firmware has no effective LED configuration, key2is 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 anauthenticatorReset) and requires presence and the PIN gate (§9.2). Ask for explicit confirmation before exporting the seed.BACKUP_FINALIZEcloses the export window. Thefips-profilebuild 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}.XandYare each exactly 32 bytes — a coordinate whose leading zero your bignum dropped is0x02 INVALID_PARAMETER, not left-padded (RS-Key0x089C+; the same rule the clientPIN and hmac-secret COSE parses apply, and what a YubiKey 5.7.4 does). Optional key2= 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 key2= 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_pubis the 65-byte uncompressed device key04 ‖ dx ‖ dy.
- classical:
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
makeCredentialand 1..=2 ofgetAssertionare 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:falseonmakeCredential, anduv:truewith nopinUvAuthParamon a build without built-in user verification, are0x2C INVALID_OPTIONwhateverpinUvAuthProtocolsays.options.rkis 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 command | ID | Value |
|---|---|---|
| PhysicalVidPid | 0x6fcb19b0cbe3acfa | (vid << 16) | pid |
| PhysicalLedGpio | 0x7b392a394de9f948 | GPIO number |
| PhysicalLedBrightness | 0x76a85945985d02fd | Global brightness |
| PhysicalOptions | 0x269f3b09eceb805f | PHY 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.
| Harness | What executes | Example failure it finds |
|---|---|---|
| Cargo tests | Rust crates and test backends on the host | A PIN retry counter changes after a rejected request |
| Applet emulator | Shared applet and store crates, with host transport and device hooks | A malformed CCID exchange leaves a selected applet in the wrong state |
| picoem library tests | RP2350 CPU and peripheral models on the host | A write clears a programmed OTP bit in the model |
| Image emulator | Secure and Non-secure firmware ELF running on picoem through rsk-emu --image | A reply from an old USB epoch reaches a new session |
| USB/IP | An emulator backend and a Linux USB host stack | A client rejects a descriptor or fails to open a HID interface |
| Board | Firmware on RP2350 silicon, driven over USB or through board inputs | A real reset, panel gesture, OTP access or cache behavior differs from the model |
| Independent client or oracle | A protocol client, test vector, reference implementation or second device | A 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.
| Selector | Assertion |
|---|---|
ceremonies | Deny and cancel produce their host statuses. A short hold cannot approve sign-in. Approval returns a usable credential or assertion. |
stale | A queued touch from an earlier prompt cannot approve a new one. |
physical | A slide, lift or cancel from another channel does not authorize the pending request. |
timeout | The image clock expires the prompt and the host receives the terminal response. |
pin | Device PIN setup, mismatch, cancellation, retries and recovery across reboot follow policy. |
fido-pin | ClientPIN obtains a token via the display and uses it in an authenticated command. |
ccid-pin | CCID 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.
| Failure | What the test looks for |
|---|---|
| Read, program or erase error | The operation reports the right error. An unreadable record does not silently become an empty slot or a default authorization state. |
| Silent lost or torn write | Recovery recognizes what actually reached flash, including an incomplete record or a write that returned success without persisting. |
| Corrupt, truncated or substituted record | Length checks and record authentication reject the data. A record for another key or role cannot stand in for the requested one. |
| Reset during mutation | On reopen, committed data is coherent and any accepted pre- or post-operation result satisfies the operation’s recovery contract. |
| Second failure during recovery | The next mount can recover again. Interrupted cleanup cannot make a deleted credential or an old authorization usable. |
| Full store, wrap or reclamation | Capacity 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.
| Applet | Examples exercised through commands |
|---|---|
| FIDO2 and U2F | Registration, assertions, PIN/UV token scope, retries, resident credentials, extensions, reset and attestation |
| PIV and OpenPGP | PIN and management authentication, private operations, key and certificate lifecycle, command chaining and reset |
| OATH and OTP | TOTP/HOTP calculations, counters, authorization, HID and keyboard reports, touch waiting and cancellation |
| Management and recovery | Settings, 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 group | Input and oracle |
|---|---|
apdu_frame, ccid_frame, ctaphid_roundtrip | Frames and reassembly. Check bounds, length handling and valid round trips. |
fido_cbor, fido_session, fido_session_token | Request bytes and command sequences. Check dispatch, authorization and state after refusals. |
cross_applet and OATH variants | Switch applets between commands. Check that one applet’s authentication and capabilities do not authorize another. |
fs_ops, power_cut, authenticated_store_v2 | Mutations and damaged or partially written media. Check recovered state and authenticated record handling. |
otp_hid, ccid_secure_pin, display_label | Host reports and display input. Exercise length, copy and presentation boundaries. |
| Crypto targets | Valid 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.
| Suite | Metric | Measured | Scope and evidence |
|---|---|---|---|
| Host unit tests | Lines | 42,688 / 43,370 (98.43%) | Default host profile. Host-profile audit |
| Host unit tests | Function groups | 3,607 / 3,609 (99.94%) | Same default profile and run. Host-profile audit |
| Host unit tests | Branch outcomes | 6,509 / 7,646 (85.13%) | Default host profile in a separate, earlier LLVM branch run. Branch measurement |
| Host unit tests | Condition outcomes | 8,207 / 8,723 (94.08%) | Default host profile with LLVM condition instrumentation. Host-profile audit |
Fuzz corpus replay, default | Source lines | 23,062 / 36,301 (63.53%) | Union across 53 targets. Crates alone reached 21,490 / 32,983 (65.15%). Fuzzing report |
Fuzz corpus replay, flavours | Source lines | 22,699 / 36,182 (62.74%) | Separate union across 53 targets. Crates alone reached 21,127 / 32,864 (64.29%). Fuzzing report |
| Host MC/DC campaign | Conditions with witness pairs | 4,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 recipe | Conditions with witness pairs | 201 / 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.
| Component | Measured result | Evidence |
|---|---|---|
| Secure worker, button and Non-secure ABI image | 29 / 31 compiled conditions with pairs | ARM worker measurements |
| Secure USB and display PIN worker | 62 / 71 Secure USB conditions and 8 / 9 in a separate display worker image | Secure USB campaign, display and bench decisions |
| Display panel and WS2812 driver | 39 / 40 panel conditions and 32 / 44 LED conditions in separate component images | Firmware component report |
| Runtime PIN codec and diagnostics | 5 / 5 PIN codec conditions, 4 / 4 stack sweep and 3 / 3 vendor benchmark conditions in separate images | PIN codec, display and bench decisions |
| Native C | 8 / 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 Rust | C and assembly correspondence |
| Native assembly | Both outcomes observed for 19 / 19 compiled predicates | C and assembly correspondence |
Host tools
The host-tool campaign measured these separately from the firmware crates.
| Tool | Lines or statements | Decision outcomes |
|---|---|---|
| Rust TUI | 1,637 / 3,424 lines (47.81%) | 192 / 302 condition outcomes (63.58%) |
| Rust emulator | 3,882 / 6,878 lines (56.44%) | 690 / 1,216 condition outcomes (56.74%) |
Python rsk CLI | 3,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
| Measurement | Scope and schedule | What CI enforces | Where to read it |
|---|---|---|---|
| Line coverage | Default host workspace in deep-checks / coverage, daily and on full runs | At least 80% aggregate line coverage. firmware, firmware-ns and rsk-wipe are excluded | cargo llvm-cov summary in the job log |
| Condition outcomes | Default host profile daily, every declared host profile on full runs | Tests and coverage export must succeed and produce evidence. No percentage floor | unit-coverage-* artifacts with JSON, LCOV and resolved features |
| MC/DC | Selected security decisions in the default host profile in deep-checks / mcdc, on full runs | Tests must pass and the report must contain valid, current witness evidence. No percentage floor | Job summary and mcdc-* artifact with the raw evidence and logs |
| Fuzz corpus coverage | Per-target corpus replay in deep-checks / fuzz-coverage, daily, on dispatch and on matching pushes | Advisory measurement | Job 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
| When | What runs |
|---|---|
| Per commit locally | check.sh, including builds, host tests, static checks and picoem library tests |
| Pull request | The gate and assurance jobs, bounded proofs, and emulator jobs that include firmware image tests on picoem |
| Scheduled | Line and condition coverage, MC/DC, longer proof and TLC tiers, fuzzing and corpus reports, Miri, mutation and reproducibility checks |
| Release | Clean 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.shthe image is built by an earlier row, so thegatephase 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
proofsphases 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 theemuphase 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_hcdand 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.
| Surface | Advertised version | Spec implemented |
|---|---|---|
| FIDO / CTAPHID | getInfo versions = U2F_V2, FIDO_2_0, FIDO_2_1, FIDO_2_3; device version 5.8.0 | CTAP2 (FIDO2) + CTAP1 (U2F) |
| OpenPGP card | 3.4 | OpenPGP Smart Card Application 3.4 |
| PIV | 5.8.0 | NIST SP 800-73-4 (command subset) |
| OATH | SELECT version 5.8.0 | YKOATH (Yubico OATH over CCID), AID A0 00 00 05 27 21 01 01 |
| Management | DeviceInfo version 5.8.0 | YubiKey Management over the FIDO / CCID transports |
USB bcdDevice | a 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 list | ES256K (−47) removed from the menu |
| Post-quantum | all three ML-DSA sets negotiable from pubKeyCredParams (capability always on); not advertised | advertised in getInfo | same as default |
| Minimum PIN length | 4 | 4 | 6 |
| Vendor seed export | allowed | allowed | refused |
| PIV | 3DES management keys + RSA-1024 import allowed | same | new 3DES management keys + RSA-1024 refused |
- PQC capability is on in every build.
advertise-pqconly controls whether the three ML-DSA sets appear in the getInfoalgorithmslist, 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’spubKeyCredParamsregardless — the RP lists the one it wants first, since the first supported entry is selected (CTAP 2.1 §6.1.2). fips-profileis 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
unsafeis 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.



