Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

FIDO2 / WebAuthn / U2F

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Touch is always required

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

Set a PIN first

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

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

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

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

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

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

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

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

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

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

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

Passkeys (resident / discoverable credentials)

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

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

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

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

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

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

Second-factor registrations (non-resident)

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

Legacy U2F (CTAP1, U2F_V2) works the same way for older 2FA setups: the register/authenticate pair is non-resident, with a monotonic signature counter, attested by the device’s end-entity certificate. With alwaysUv on, U2F is switched off, since a touch verifies nobody: the device stops announcing it, as a YubiKey does, and refuses its commands. The display build with a PIN set is the exception, where each U2F operation asks for the PIN on the panel.

Signature counters

Every assertion carries a signature counter, the tripwire a relying party watches for a cloned key. RS-Key keeps one per resident credential: a passkey starts at 0 and only its own logins advance it, so colluding sites can’t read a shared global counter to gauge how much you use the key elsewhere (WebAuthn §6.1.1). A non-resident second-factor credential stores nothing on the device, so it reports 0. Legacy U2F keeps the single monotonic counter that protocol expects, and a U2F registration asserted over CTAP2 (a site’s appid login) reports and advances that same counter, as a YubiKey 5.8.0 does, so the site sees one rising sequence on both paths.

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

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

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

Advertised algorithms

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

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

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

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

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

Post-quantum credentials

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

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

Extensions supported

getInfo advertises nine extensions:

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

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

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

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

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

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

previewSign (experimental, off by default)

A build option, not part of the default image:

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

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

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

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

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

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

Deliberate deviations from the draft:

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

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

Factory reset

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

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

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

Two details that catch people out:

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

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

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

Troubleshooting

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