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.