Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

RS-Key host protocol reference

This document specifies the host-facing protocol of the RS-Key firmware: how a configuration/management tool talks to the device, what commands exist, the exact byte layout of each request and response, and what authenticates each one.

It exists so that third-party tooling (e.g. PicoForge) can configure and manage RS-Key devices. The rsk Python CLI is a runnable reference for the management operations it exposes. Firmware source paths accompany the wire formats.

Audience & scope. This is a wire spec, not a tutorial. It documents the commands a host sends and the bytes it gets back. It does not cover the on-device storage format, the crypto internals, or the build system. Those live in architecture.md and the crate sources.

Licensing. RS-Key firmware is AGPL-3.0-only. This protocol description is published as part of the same repository; you are free to implement a client against it under any license. Interop implementations do not inherit AGPL by talking to the device.

Stability. The transports and the standard applets (FIDO2, U2F, PIV, OATH, OTP, OpenPGP, Yubico Management) are stable. They follow public specs. The RS-Key-specific surface (Rescue applet, Vendor/LED applet, CTAP authenticatorVendor 0x41) is versioned by bcdDevice and may grow; new tags/subcommands are added, existing ones are not silently repurposed. Probe the version handshakes (§3, §6.1) and treat unknown tags as skippable.


1. Transports

RS-Key is a USB composite device. Its default interface set is:

TransportCarriesHost API
Keyboard HIDYubico OTP feature reports and typed OTP outputOS HID stack / Yubico OTP libraries
CTAPHID (FIDO HID, usage page 0xF1D0)CTAP1/U2F, CTAP2, and native HID DeviceInfo commandshidapi
CCID (PC/SC smart-card)ISO-7816 applets selected by AID, including CTAP over CCIDpyscard / PC/SC

On the default build, keyboard HID also carries the ykman OTP-HID admin writes (SET_DEVICE_INFO 0x15, DEVICE_CONFIG 0x11, SCAN_MAP 0x12, NDEF 0x08/0x09). SET_DEVICE_INFO shares the DeviceInfo store with CCID WRITE CONFIG (§6). SCAN_MAP remaps typed OTP output. DEVICE_CONFIG and NDEF have no effect on USB operation. An accepted admin write advances the status frame’s program-sequence byte. Under strict-config these slots leave it unchanged, which ykman/yubikit treat as a rejected command.

The interfaces are presented in the stock YubiKey order — keyboard/OTP, FIDO HID, CCID — because some hosts address the OTP interface by index instead of by descriptor: the libusb backend ykpers/ykcore ships (KeePassXC, ykchalresp, pam_yubico) claims interface 0 and sends the OTP frame reports there whatever the descriptors say. An interface switched off in ENABLED_USB_ITF (§7) is omitted and the rest keep that relative order, so a host that assumes a fixed index only holds where the same interface set is enabled.

The OTP frame protocol answers HID feature GET/SET_REPORT on the keyboard interface only. On macOS, access to the keyboard interface can require Input Monitoring. The FIDO interrupt endpoints carry CTAPHID, and their report descriptor declares no feature report.

A slot programmed to require a touch answers its challenge only after a button press, and reports the wait in the status byte (0x20) meanwhile. Two things end that wait early, both matching a YubiKey: the host’s dummy write — a report whose sequence byte is out of range, 0x8f, which also resets the read mode after a response — and any new frame, which supersedes the pending challenge. A host that does neither waits out the touch timeout (§7 PRESENCE_TIMEOUT), during which the transport reports only that it is waiting.

Once announced, 0x20 holds for the rest of the command — the press itself does not clear it, only the response frame or the idle status frame does. ykpers reads a byte carrying neither the pending nor the waiting bit as a touch timeout, so a device that dropped the wait between the press and its answer would lose challenges it had in fact completed.

1.1 CCID APDU framing

CCID ABORT has two phases (CCID 1.1 §4.1). Send an EP0 class request with bmRequestType=21, bRequest=01, wValue=bSlot | bSeq<<8 at the CCID interface, followed by PC_to_RDR_Abort (72) with the matching slot/sequence. Slot 0 is the only slot. Until the matching bulk command arrives, commands fail with CMD_ABORTED (FF); the bulk acknowledgement is RDR_to_PC_SlotStatus (81). An unmatched bulk sequence is refused with field offset 06. An aborted transfer returns a failed DataBlock with bError=FF in place of its APDU reply. Cancellation can end a presence wait. Synchronous work reaches its normal safe point, and committed writes remain in effect.

USB reset, deconfiguration or suspend invalidates pending replies and clears transient applet authorization in Secure before new work is accepted. Persisted keys and the FIDO per-boot PIN mismatch budget survive a bus event. The same event discards partial CTAPHID messages and clears the channel lock. Continuation frames from the old session cannot resume an interrupted message.

CCID accepts ISO-7816 short and extended APDUs. Use 00 A4 04 00 Lc <AID> 00 to select by AID. RS-Key also accepts the P2 = 04 form used by PicoForge. The selected applet then receives CLA INS P1 P2 [Lc <data>] [Le]. There is no ISO master file, so the master-file SELECT (00 A4 00 0C …, GnuPG’s 3F00 probe) answers 6D00 like a YubiKey. The power-on ATR is T=1, its historical bytes labelled YubiKey when the effective USB VID is 1050 and RS-Key otherwise (identical card capabilities). The reference transport is tools/rsk/ccid.py:

def select(conn, aid):
    return transmit(conn, [0x00, 0xA4, 0x04, 0x00, len(aid)] + list(aid) + [0x00])

The class byte is judged before the command, for every applet, GET RESPONSE aside (below). Bit 0x10 marks a command-chaining segment and is looked at first, so 10, 1C, 90 and FF are all ordinary segments. Otherwise only 00, 04, 80 and 84 reach an applet. Every other class gets an empty answer: a data block with no body and no status word, which a client library that expects one raises on (pyscard: Card returned no valid response). Under 04 and 84, the secure-messaging classes, SELECT works as under 00 and any other command to a selected applet is 6E00 — no applet here implements secure messaging, and OpenPGP’s Extended Capabilities says so. With no applet selected, as after a card reset, every command but a SELECT is 6D00 whatever its class, a SELECT by file id or with P2 0C included, and a SELECT of an AID the device lacks is 6A82. All of that is a YubiKey 5.8.0’s, read class by class over raw USB. RS-Key’s own: an unanswered command changes nothing, so an open chain still takes its final segment and a held tail its GET RESPONSE. An XfrBlock of one or three bytes, too short for CLA INS P1 P2, is refused by the reader as a YubiKey 5.8.0 refuses one, measured with the slot powered: a failed RDR_to_PC_SlotStatus, bStatus 40, whose bError 01 names dwLength, and no APDU runs. RS-Key’s own: none and two bytes are refused the same way, and a powered-off slot keeps its ICC status (bStatus 41). An empty block is no response continuation here: RS-Key never chains a response across CCID messages (bChainParameter stays 00). Applets that additionally name a class of their own reject anything else themselves: OATH, management and OTP take 00 and 80 alike, both of which a YubiKey 5.8.0 serves there, U2F wants 00 and rescue 80. A chain can carry at most 3072 bytes of command data. A non-final segment must leave room below that limit. The final segment may fill it exactly. On overflow, the device returns 6700 and drops the chain. Segments must match on (CLA & ~0x10, INS, P1, P2). A mismatch returns 6883 and clears the chain. A SELECT-by-AID discards the old chain before looking up the AID.

A single XfrBlock fits a 3062-byte APDU after the 10-byte CCID header. An extended APDU can therefore carry up to 3055 bytes of data without Le, or 3053 with Le. Use ISO-7816 command chaining for larger inputs within the reassembly limit.

The lengths have to describe the command exactly, short or extended (00, then a two-byte Lc or Le): a byte past the Le, or an Lc its data does not fill, is 6700 before any applet sees the command, as a YubiKey 5.8.0 answers it over raw USB. Two shapes outside ISO 7816-4 are read as that YubiKey reads them: a two-byte body 00 xx is the extended Le 00xx, and an extended Le followed by two more bytes is a case 4 with Lc 0000, those two bytes its Le. RS-Key’s own: the selection, an open chain and a held tail stay as they were.

PIV, OpenPGP and CTAP over CCID answer a success body longer than the request’s Le with ISO-7816 response chaining: the first chunk ships with status 61 XX (XX = further bytes available, 00 = 256+), and the host issues GET RESPONSE (00 C0 00 00 <Le>) until 9000. A short command with no Le (Case 1 or Case 3) is capped at 256; an extended one with no Le is not, and gets the whole body in one frame, as a YubiKey 5.8.0 answers it. One frame carries 3060 bytes of body; a longer one chains from there whatever the Le, where a YubiKey’s PIV cuts the frame and loses its status word. GET RESPONSE is cut by its own encoding the same way. A certificate object over 256 bytes chains when it is read with a short GET DATA, so a host that sends a short GET DATA without an Le must still follow 61xx. A 00 C0 with nothing left to serve is 6A80 on PIV and 6D00 on OpenPGP, OATH, management, OTP and FIDO. While a tail is owed, a GET RESPONSE without the chaining bit serves it whatever its class, since that answer already began in the clear: a YubiKey 5.8.0 does so under 00, 80, 04, 84 and 0C, a class it answers nothing otherwise, and RS-Key under every class. With the chaining bit (10, 90, 1C), owed tail or not, it is a 9000 that opens no chain and leaves any tail for the next one; inside an open chain it is 6883, like any command outside that chain, both as on a YubiKey 5.8.0. With nothing owed, a GET RESPONSE under 04 or 84 is 6E00 to a selected applet and 6D00 with none, like any command but SELECT there, and under a class no applet is reached by it gets the empty answer.

OATH LIST (0xA1) and CALCULATE ALL (0xA4) responses that outgrow the command’s Le chain the YubiKey-OATH way instead: 61 XX followed by SEND REMAINING (00 A5 00 00) rather than GET RESPONSE, matching what ykman / Yubico Authenticator send. A short command with no Le gets 256 bytes a frame and an extended one as much as a CCID frame holds. Frames are cut at the byte, so an entry can straddle two of them: join the frames before parsing. SEND REMAINING never judges its P1-P2, and with no page owed it answers 6D00, as a YubiKey 5.8.0 does.

OATH PUT. PUT (0x01) is strict about the credential body — KEY TLV 16..=66 bytes (a secret shorter than 14 bytes is refused, not padded: zero-pad it first, as ykman does, and the codes do not change), digits 6/7/8, type 0x10/0x20, algorithm 1/2/3, name 1..=64 bytes, the initial moving factor on HOTP only and exactly 4 bytes, the PROPERTY byte as the bare 78 vv pair, the four YKOATH tags in that order, no duplicate, no unknown tag and no trailing byte. Anything else is 6A80 with nothing stored, so a rejected PUT leaves an existing credential of that name working. RS-Key also stores the password-safe fields 0x83/0x84/0x85, up to 255 bytes each, anywhere in the body.

OATH access code. SET CODE (0x03) holds its key to the same measured rule: the 73 TLV is one algorithm byte plus 14..=64 bytes of key material, or empty to remove the access code — anything else is 6A80 and whatever code was installed is left exactly as it was. Its proof travels over an exactly 8-byte 74 challenge (os.urandom(8), as ykman sends it); any other width is 6A80, and removing a code needs no challenge at all. VALIDATE (0xA3) then refuses a proof that does not match with 6A80 as well; 6984 from it means something else entirely — no access code is installed to match against.

OATH only-increasing property. A TOTP credential with PROPERTIES bit 0 computes only for a challenge strictly greater than the highest one it has served, comparing the raw challenge bytes zero-extended on the right — plain numeric > for the usual 8-byte counter. A challenge at or below that mark is 6A80, and in CALCULATE ALL one such credential fails the whole command with an empty body. The one exception is a credential a build before this rule stored: its body can leave no room for the mark, and CALCULATE ALL then reports it with 77 (no response) and computes the rest of the store rather than failing — its own CALCULATE still answers 6A80.

The bulk preflight refuses a flash read fault with 6581 and no response body, before a code can be emitted without its mark. Marks committed before the failing slot remain advanced; the operation is not atomic across credentials.

OATH challenge length. CALCULATE (0xA2) and CALCULATE ALL (0xA4) take an opaque byte string of 0..=64 bytes in the 74 TLV and HMAC all of it; 65 or more is 6A80, judged before the credential is looked up and whatever the credential’s type, so a HOTP account that ignores the challenge refuses an over-wide one too. Both read paths therefore answer the same code for the same challenge at every accepted width — including across a SEND REMAINING page — and the usual 8-byte TOTP counter is simply the common case.

OATH TLV order. CALCULATE, VALIDATE and SET CODE are parsed by position: exactly the documented TLVs, in the documented order, with nothing before, between or after them — 71 then 74 for CALCULATE, 75 then 74 for VALIDATE (the response comes first, as ykman sends it), 73 then 74 then 75 for SET CODE, or a lone 73 00 to remove the code — that spelling and no other, so a SET CODE carrying no body at all is 6A80 and the standing code goes on opening the applet, as on a YubiKey. A reordering, a repeated tag, an unknown tag or a trailing byte is 6A80, with nothing stored. CALCULATE ALL is the one exception the card makes: its 74 must be the first TLV, and whatever follows it is ignored.

OATH truncation. With P2 = 0x01 the 76 TLV is [digits][code(4)], and the four bytes are the RFC 4226 dynamic truncation already reduced to that credential’s digit count — big-endian, so a 6-digit account never exceeds 000F 423F. A host must not reduce a second time expecting a different answer, and VERIFY CODE (0xB1) compares exactly the value CALCULATE sent. The untruncated form (P2 = 0x00, tag 75) is unaffected: it carries the whole HMAC.

OATH parameter bytes. Default to P1 = 00, P2 = 00. The 01 that selects the truncated form belongs to CALCULATE and CALCULATE ALL and to nothing else — on PUT, DELETE, SET CODE, RENAME and LIST it is refused like any other stray byte. RESET alone takes DE AD, and VALIDATE is the card’s own exception: it refuses only when both bytes are non-zero. Anything else is 6B00, judged before the command’s body and before the access-code gate so nothing is written; an instruction the applet does not implement still answers 6D00 first.

1.2 CTAPHID framing

64-byte HID reports. Init frame: CID(4) | CMD(1) | BCNT_HI | BCNT_LO | data[:57]; continuation frames: CID(4) | SEQ(1) | data[:59]. CTAPHID_INIT = 0x86, CTAPHID_CBOR = 0x90, CTAPHID_KEEPALIVE = 0xBB. A CTAP2 message is command_byte | CBOR_payload. A CTAP2 response starts with a one-byte status. Native HID DeviceInfo commands use their own HID command byte (§6.1). Reference implementation in tools/rsk/ctaphid.py.

While a CBOR command runs, the device sends CTAPHID_KEEPALIVE every 100 ms with status 01 (processing) or 02 (waiting for user presence). A zero-length CTAPHID_CANCEL (wire command 0x91) on the active CID gets no separate reply. The original CBOR request returns 2D (CTAP2_ERR_KEEPALIVE_CANCEL) at a safe point. A committed write stays committed.

Take the channel id from the CTAPHID_INIT response and use that one: every INIT on the broadcast CID allocates a fresh id, so an id hardcoded or cached across sessions will not be yours. CTAPHID_LOCK is honoured for the 1–10 seconds it asks for, though no INIT capability bit says so: CTAP defines none for it, and 0x02 — a pre-standard U2FHID header’s LOCK bit — stays clear, as on a YubiKey 5.8.0. Meanwhile every other channel gets ERR_CHANNEL_BUSY — including one sending CTAPHID_INIT to resynchronise itself. The exception is an INIT on the broadcast CID, which still gets through: a client arriving mid-lock is given an id, then turned away on it.

1.3 CCID secure PIN entry (pinpad) — display builds only

A trusted-display build advertises bPINSupport = 0x01 (VERIFY) in its CCID class descriptor (body byte 50 / full descriptor byte 52), so a host driver treats it as a pinpad reader and sends PC_to_RDR_Secure (0x69) instead of a plaintext VERIFY; the PIN is then typed on the device’s own screen. A standard (no-screen) build leaves bPINSupport = 0x00 and rejects 0x69. No control transfer is involved. The host CCID driver reads bPINSupport straight from the descriptor; the device only has to handle 0x69. The validated trigger is GnuPG’s internal CCID driver (keys solely off bPINSupport); PC/SC + libccid and macOS CryptoTokenKit also expose pinpad from the descriptor, but their FEATURE_VERIFY_PIN_DIRECT coverage varies, so treat the GnuPG-internal path as the reliable one.

The host must use pinpad mode to keep the PIN off the wire. A normal XfrBlock VERIFY (00 20 P1 P2 Lc <PIN>) still carries a plaintext PIN.

Whatever the host driver, the bytes on the wire follow the CCID structure below, not the PC/SC v2 Part 10 IOCTL structure (the driver drops that structure’s bTimeOut2 and ulDataLength when it builds the 0x69), so the VERIFY template is always at abData offset 15. The 0x69 payload is the CCID abPINDataStructure for VERIFY:

bPINOperation(1)=0x00 verify | bTimeOut(1) | bmFormatString(1) | bmPINBlockString(1) |
bmPINLengthFormat(1) | wPINMaxExtraDigit(2 LE) | bEntryValidationCondition(1) |
bNumberMessage(1) | wLangId(2 LE) | bMsgIndex(1) | bTeoPrologue(3) |
abPINApdu = CLA INS=0x20 P1 P2 …   (the VERIFY template, at offset 15)

Select an enabled OpenPGP or PIV applet first. The display asks “Allow host PIN entry?” before opening the PIN pad. The device reads the template’s P2 (OpenPGP 0x81/0x82/0x83 = PW1-sign / PW1-other / PW3-admin; PIV 0x80 = application PIN), collects the PIN on the pad, builds the real VERIFY APDU (00 20 P1 P2 Lc <ASCII PIN>; PIV pads with 0xFF to 8 bytes), runs it through the selected applet, and replies with a normal RDR_to_PC_DataBlock (0x80) carrying only the status word:

  • success → 90 00, bStatus = 0, bError = 0.
  • wrong PIN → the card’s real answer: PIV’s 63 Cx (tries left, reported saturated at x = F so a larger configured retry total cannot wrap into 63 C0 = blocked), OpenPGP’s 69 82 as a YubiKey 5.8.0 answers (its tries are on an empty VERIFY) / 69 83 (blocked), bStatus = 0, bError = 0 (the command succeeded; the card said wrong).
  • user cancel → bStatus = 0x40 (failed), bError = 0xEF → SCARD_W_CANCELLED_BY_USER.
  • initial approval declined or timed out → bStatus = 0x40, bError = 0xEF.
  • pad timeout → bStatus = 0x40, bError = 0xF0 → SCARD_E_TIMEOUT.
  • unsupported pinpad request or no eligible applet selected → bStatus = 0x40, bError = 0x00.

The transport sends CCID time extensions while the device waits on the screen. The device ignores the host’s PIN format and offset bits when assembling VERIFY. With GnuPG’s internal CCID driver, run gpg-connect-agent "scd checkpin OPENPGP.1" /bye. The parser and VERIFY assembly are in crates/rsk-usb/src/secure_pin.rs.


2. Status words & error codes

2.1 CCID status words (ISO-7816 SW1 SW2)

Source: crates/rsk-sdk/src/sw.rs.

SWNameMeaning
9000OKsuccess
63C0—WRITE CONFIG (§6) with a configuration lock code that is not the one set, as a YubiKey 5.8.0 answers it
6400EXEC_ERRORexecution error (internal)
6285TERMINATEDOpenPGP after TERMINATE DF: every command, SELECT included, until ACTIVATE FILE (§5.1)
6581MEMORY_FAILUREa storage failure, including Rescue READ phy or a DeviceInfo merge. Storage recovery also uses this status for unavailable Rescue operations (§7). OpenPGP uses it for undecipherable RSA ciphertext, an unusable ECDH peer point, oversized RSA signing input, reading an empty key slot, or importing correctly sized RSA primes that fail key construction
6700WRONG_LENGTHbad Lc/Le for this command
6883LAST_CHAIN_EXPECTEDan APDU arrived that neither continues nor closes the open command chain
6982SECURITY_STATUS_NOT_SATISFIEDauth/precondition missing
6983PIN_BLOCKEDPIN verification is blocked
6984DATA_INVALIDmalformed payload (e.g. bad guard magic)
6985CONDITIONS_NOT_SATISFIEDstate precondition unmet (e.g. RTC unset); a WRITE CONFIG setting a configuration lock where none is set without its touch (§6.2); OpenPGP PSO:CDS, the RSA and ECDH arms of PSO:DECIPHER and INTERNAL AUTHENTICATE with no key in the slot, and ATTEST of an empty slot or an imported key, as a YubiKey 5.8.0 answers them
6986COMMAND_NOT_ALLOWEDWRITE CONFIG (§6) with no lock code while a configuration lock is set, as a YubiKey 5.8.0 answers it; a phy (§7) or LED (§8) write while one is set
6A80WRONG_DATAbad data field; PIV MOVE KEY onto a slot that holds a key or takes none, or onto itself; PIV PUT DATA with a P1-P2 other than 3FFF; OpenPGP GENERATE and IMPORT with a control-reference template they cannot read or whose key reference 84 01 xx names another slot, and GENERATE P1 = 80 and IMPORT under Yubico’s attestation-key template B6 { 84 01 81 }; OpenPGP ATTEST with a P1-P2 or a body it does not take; OpenPGP SELECT DATA with any body but 60 04 5C 02 7F 21
6A82FILE_NOT_FOUNDthe requested AID or file is unavailable
6A84FILE_FULLthe applet’s storage limit is exhausted
6A86INCORRECT_P1P2unsupported P1/P2
6A88REFERENCE_NOT_FOUNDthe object, key or PIN the request names is absent (PIV GET METADATA, MOVE KEY, the PIN commands’ key reference)
6B00WRONG_P1P2P1/P2 outside what this command takes — including a DO that P1P2 addresses and the command does not serve (OpenPGP GET DATA, PUT DATA), and an OpenPGP SELECT DATA occurrence past the third or P2 other than 04, judged before its body
6D00INS_NOT_SUPPORTEDunknown INS for this applet; OpenPGP and PIV answer it to any SELECT but the one by AID, as a YubiKey 5.8.0 does
6E00CLA_NOT_SUPPORTEDwrong CLA for this applet (OpenPGP ATTEST takes class 80 only)

2.2 CTAP2 errors

Standard CTAP2 status bytes (0x00 = success), returned by CTAP2 and by the 0x41 vendor command. Source: crates/rsk-fido/src/error.rs. The ones the vendor surface returns:

ByteNameMeaning here
0x00OKsuccess
0x02INVALID_PARAMETERinvalid field or public key, unknown vendor subcommand, or invalid encrypted key for UNLOCK/ATT_IMPORT
0x03INVALID_LENGTHa request exceeds a command’s input limit (for example, the DeviceInfo config blob)
0x12INVALID_CBORthe body is not exactly one CBOR item (trailing bytes)
0x14MISSING_PARAMETERrequired field absent (e.g. blob/pinUvAuthParam)
0x27OPERATION_DENIEDpresence declined or timed out, wrong config lock code on a DeviceInfo write, or CBOR disabled by USB_ENABLED
0x2DKEEPALIVE_CANCELthe host cancelled the active CTAPHID CBOR request
0x2FUSER_ACTION_TIMEOUTon-device PIN entry timed out, or a CCID FIDO poll/cancel found no pending operation
0x30NOT_ALLOWEDprecondition unmet (a CONFIG_WRITE of EF_DEV_CONF with no lock code, or of the phy or LED record, while a lock is set (§6.2), no MSE channel, one already spent or owned by another CTAPHID channel, an MSE while one is live (§9.1), sealed, soft-locked, or an authenticatorReset outside the §5.1 power-up window)
0x31 / 0x32PIN_INVALID / PIN_BLOCKEDwrong PIN or exhausted retries
0x33PIN_AUTH_INVALIDpinUvAuthParam MAC or acfg permission wrong
0x36PUAT_REQUIREDthe request requires a PIN token or on-device PIN entry (§9.2)
0x39REQUEST_TOO_LARGEsubCommandParams over the limit
0x3DINTEGRITY_FAILUREblob failed authenticated decryption
0x3EINVALID_SUBCOMMANDunknown vendorCommandId under authenticatorConfig’s 0xFF. A 0x41 subcommand this build does not implement is 0x02, matching a YubiKey
0x7FOTHERinternal failure, for example an unreadable CONFIG_READ record

3. Device identity & discovery

3.1 USB identity

The build picks a VID/PID preset (firmware/build.rs):

PresetVID:PIDManufacturer / Product stringsNotes
RSKey (default)1209:F1D2RS-Key / RS-Key Security Keypid.codes allocation
Yubikey5 (opt-in interop)1050:0407Yubico / YubiKey RSK OTP+FIDO+CCIDso ykman/Yubico Authenticator derive PID from the PC/SC reader name
othersNitroHSM, NitroFIDO2, GnuPG, Pico, Dev—local interop only

The VID/PID, the product string and the manufacturer string can all be overridden at runtime via the phy record (§7), taking effect at the next boot: VID/PID (tag 0x00), product (tag 0x09) and manufacturer (tag 0x0F). If a runtime product looks like a YubiKey (yubikey, any case) but omits the smartcard CCID token, the firmware appends OTP+FIDO+CCID before enumerating — a token-less Yubico YubiKey reader name otherwise crashes ykman / Yubico Authenticator on Windows (_pid_from_name → PID.of → KeyError('YK4_'), which aborts the whole PC/SC scan). Source: normalize_usb_product in crates/rsk-phy/src/lib.rs.

Each string is resolved in precedence order: an explicit phy tag (0x0F / 0x09) wins; otherwise the effective VID picks a default — a Yubico VID (0x1050) yields Yubico / YubiKey RSK OTP+FIDO+CCID plus the Yubico OpenPGP AID vendor, so setting only the Yubico VID/PID makes the whole identity “just work” for ykman / Yubico Authenticator; otherwise the build const. The OpenPGP AID vendor id stays keyed on the effective VID (a registered number, not a free string). ⚠️ so a phy-repointed default key can present a full Yubico identity at runtime; the USB/smartcard identity is cosmetic and host-configurable, never a security or anti-counterfeiting control (see docs/threat-model.md).

For PC/SC discovery, rsk looks for RS-Key, RSK or the appended USB serial (rs-key-0001) in reader names. Linux pcscd may use the driver’s friendly name in place of the USB product string. Probe the applet you need on a candidate reader. See RSK_READER_TOKENS in tools/rsk/ccid.py.

3.2 Firmware version & bcdDevice

FieldValueWhere
firmwareVersion5.8.0 → 0x00050800CTAP getInfo 0x0E; Management/OTP DeviceInfo TAG_VERSION; Management SELECT ("Virtual mgr - FW version 5.8.0" ASCII, a YubiKey 5.8.0’s words)
bcdDeviceFirmware build counterUSB device descriptor (firmware/src/main.rs device_release)
AAGUID2479c7bf-6b30-5683-9ec8-0e8171a918b7CTAP getInfo 0x03; one value across every VID/PID flavor of a build, overridable at build time with AAGUID=<uuid>

The build accepts FW_VERSION=X, X.Y or X.Y.Z. The default is 5.8.0 for compatibility with Yubico tooling. Read bcdDevice from the USB descriptor when checking for an RS-Key protocol change.


4. AID registry

SELECT an applet with 00 A4 04 00 Lc <AID> 00.

How an AID is matched (RS-Key 0x088C+): ISO 7816-4 truncated select — the AID you send must be a prefix of a registered one, and the first applet it matches wins. So a shortened AID selects (PIV answers to A0 00 00 03 08), an AID with anything appended does not (earlier builds selected on registered AID ‖ junk, which let PIV answer to A0 00 00 03 08 00 00 00 00 — the AID SP 800-85A-4 C.1.1.2 names as invalid), and an empty AID is refused rather than treated as “select the default application”. Two consequences worth planning for: OpenPGP is selected by the 6-byte AID below, not by the 16-byte value it reports in DO 4F (that one carries the device serial and is longer, so it is not a prefix — a real YubiKey refuses it too); and a prefix short enough to match several applets resolves in dispatch order among selectable applets (Vendor, OpenPGP, Management, OATH, OTP, PIV, Rescue, FIDO). Use the full AID when probing for an applet. OATH and OTP are registered by their full 8-byte instance AIDs, as a YubiKey registers them: Yubico’s Android SDK selects by all 8 bytes, while ykman sends the 7-byte prefix, and both select (0x09D4+; from 0x088C to 0x09D3 only the 7-byte form did).

Where that SELECT works. The recipe above is CCID’s (§1.1), and two of the ten rows below are not CCID applets: the FIDO2 backup id and the standalone U2F AID answer 6A82 (FILE_NOT_FOUND) — registered identifiers rather than anything this build dispatches to. The FIDO2 AID is selectable over CCID and carries CTAP2 and U2F there (§5.3). Over HID, send CTAP2 directly in CTAPHID_CBOR and U2F in CTAPHID_MSG. Only the Vendor AID can be selected in CTAPHID_MSG. Use a fresh CTAPHID_INIT before switching that channel back to U2F. An INIT or a change of CID clears the MSG applet selection.

AppletAIDTransportSpec statusConfig-relevant?
FIDO2 / U2FA0 00 00 06 47 2F 00 01CCID (§5.3) + CTAPHID (no SELECT)Standard (CTAP2 + CTAP1)identity only
FIDO2 (backup id)B0 00 00 06 47 2F 00 01none — unregisteredRS-Key—
U2F (standalone id)A0 00 00 05 27 10 02none — unregistered; U2F rides the FIDO2 AIDStandard (CTAP1/U2F)—
ManagementA0 00 00 05 27 47 11 17CCIDYubico-compatibleyes — §6
OATHA0 00 00 05 27 21 01 01CCIDYubico OATHdata only
OTPA0 00 00 05 27 20 01 01CCIDYubico OTPdata only
PIVA0 00 00 03 08 00 00 10 00 01 00CCIDNIST SP 800-73data only
OpenPGPD2 76 00 01 24 01CCIDOpenPGP card 3.xdata only
RescueA0 58 3F C1 9B 7E 4F 21CCIDRS-Key-specificyes — §7
Vendor / LEDF0 00 00 00 01CCID + CTAPHID_MSGRS-Key-specificyes — §8

Sources: crates/rsk-fido/src/consts.rs, crates/rsk-mgmt (+ crates/rsk-devconf for the DeviceInfo record), crates/rsk-oath, crates/rsk-otp, crates/rsk-piv, crates/rsk-openpgp/src/consts.rs, crates/rsk-rescue, firmware/src/vendor.rs. Which AID each transport actually offers is not in any of those: it is the applet list crates/rsk-device/src/ccid.rs builds for CCID and the one-entry list in crates/rsk-device/src/ctap.rs for CTAPHID_MSG.


5. Standard interfaces (pointers, not re-specified)

For the base command formats, see the CTAP specification, Yubico OATH protocol and PIV card command specification.

Resident FIDO discovery returns at most 16 distinct credentials per getAssertion/getNextAssertion walk, newest first. Equal creation times use descending storage-slot order. With more than 16 visible matches, the queue retains the newest 16; the first reply is the first entry in that same queue.

RS-Key implements:

  • FIDO2 / CTAP2 (versions advertises FIDO_2_0, FIDO_2_1 and FIDO_2_3): getInfo, makeCredential, getAssertion, getNextAssertion, clientPIN, reset, selection, credentialManagement, authenticatorConfig, largeBlobs (writable without a pinUvAuthParam until a PIN is set or alwaysUv is on, per §6.10.2 — a --features largeblob-ext build serves the CTAP 2.3 §12.4 largeBlob extension in its place and answers 0x0C with CTAP1_ERR_INVALID_COMMAND, because §12.4 forbids supporting both; detect it from getInfo, which drops largeBlobs, maxSerializedLargeBlobArray and the largeBlobKey extension in that build). options.perCredMgmtRO is true, so a tool may request the pcmr permission (0x40, alone) and get the persistent pinUvAuthToken: it drives getCredsMetadata / enumerateRPs / enumerateCredentials, never the two writers, and survives replugs until a PIN change or a reset — a credential list can be refreshed without re-prompting for the PIN. The enumerate walk it opens is not that durable: the cursor behind getNextRP / getNextCredential retires after 30 s idle, and after any command that is not one of those two continuations (CTAP 2.3 §6), so draw a list in one uninterrupted pass and restart from the Begin if it stalls. The same 30 s applies between the fragments of a largeBlobs set; there an abandoned transfer answers CTAP2_ERR_INVALID_SEQ and the previously stored array is left intact. maxMsgSize = 7609. Both transportsForReset (0x1A) and transports (0x09) are ["usb", "smart-card"]. These lists describe the supported protocol transports (§5.3). Interface configuration and host driver binding determine whether the smart-card interface is reachable. pinComplexityPolicy (0x1B) reports the effective PIN complexity policy. strong-pin and fips-profile enable it by default; other builds start with false. An authenticated setMinPINLength request can enable it with subCommandParams key 4: true. A false or absent key leaves it unchanged; only authenticatorReset restores the build default. The policy rejects periodic PINs, ascending/descending runs, at most two distinct code points, and the keypad-pattern denylist, on both host and trusted-display PIN changes. Under forcePINChange, an unread current verifier returns CTAP2_ERR_OTHER (0x7F) and leaves the change pending; it cannot establish a different PIN. The optional pinComplexityPolicyURL (0x1C) is never emitted. longTouchForReset (0x18) is false: a reset takes the same touch as any other presence check — CTAP 2.3 cut the long-touch hold from 2.2’s 10 s to 5 s, and RS-Key implements neither gesture. encIdentifier (0x19) is present from provisioning — boot, authenticatorReset and a seed BACKUP_LOAD mint the persistent pinUvAuthToken it is keyed by; setting or changing the PIN, or forcing a change, revokes that grant until the next boot or pcmr request, and a soft-locked key omits it — and carries iv ‖ AES-128-CBC(k, id) — 32 bytes — where id is a 128-bit device identifier and k = HKDF-SHA-256(salt = 32 zero bytes, IKM = that token, info = "encIdentifier", L = 16). The IV is regenerated on every getInfo, so the bytes differ each time while the identifier under them does not: a tool holding the token recognises the device across sessions, and one without it learns nothing. The identifier is derived from the device seed, so authenticatorReset changes it. encCredStoreState (0x1E) is that same construction under the label encCredStoreState, over a 128-bit tag that takes a new random value whenever the set of discoverable credentials changes — a create, a deleteCredential, an updateUserInformation, or a delete driven from the trusted display. Reads never move it. A platform holding the token caches the plaintext and re-enumerates only when it differs; one without the token sees bytes that change every call and learns nothing. The tag is stored, not counted in RAM, so a power cycle does not reset it — and it is written ahead of the change it describes, so what a torn write leaves is a tag that over-reports (one wasted re-enumeration) rather than one that under-reports (a stale cache). A tag the flash cannot serve omits the member rather than publishing the zero one: zero is what a device an older build provisioned carries until its first change, so a platform can be holding it, while an absent member matches no cached tag at all and costs only the walk. A new store starts with a new tag, as unpredictable as its seed — provisioning and authenticatorReset derive it from the new seed, a BACKUP_LOAD draws one — so a reset changes it even over a store nothing had changed (CTAP 2.3 §6.6). makeCredential accepts attestationFormatsPreference (request 0x0B): a list of exactly ["none"] is answered with fmt:"none" and an empty — but present — attStmt, and nothing is signed. Any other list, an empty one, or an absent field leaves the usual packed statement, because choosing by lowest supported index needs more than one supported format and attestationFormats (0x16) stays ["packed"]. An enterprise attestation that was actually performed outranks the preference and is still returned in full. None is performed over an org key whose stored chain is missing or does not read back whole (RS-Key 0x0A6A+): the device’s own certificate attests, without ep, and the preference holds. Vendor-facilitated (type 1) enterprise attestation reads a stored RP list. enterpriseAttestation: 1 returns ep and the org certificate only for an RP on that list; any other RP gets the ordinary packed statement with the device’s own certificate and no ep. The list holds up to 8 sha256(rpId) entries and is empty until written, so a device upgraded from firmware without it behaves exactly as before; authenticatorReset clears it. Write it with authenticatorConfig (0x0D) subCommand vendorPrototype (0xFF) and subCommandParams {1: 0x0e6841934e719be7, 4: [rpId…]} — the ids as text, hashed on the device — gated by an acfg pinUvAuthToken and no touch, the same authorization enableEnterpriseAttestation itself takes. An empty array clears the list; more than 8 entries is refused with CTAP2_ERR_KEY_STORE_FULL, never truncated. Type 2 (platform-managed) is unaffected — it applies to any RP once enterprise attestation is enabled. Supported COSE algorithms: ES256 -7, ES384 -35, ES512 -36, ES256K -47, EdDSA -8, ML-DSA-44 -48, ML-DSA-65 -49, ML-DSA-87 -50 (all three negotiable via pubKeyCredParams; advertised in getInfo only under the advertise-pqc build, in descending security order). ML-DSA-87’s 2592-byte public key and 4627-byte signature are the widest the device mints, and the org attestation chain cap (ATT_CHAIN_MAX) is derived so the worst-case makeCredential still fits the 7609-byte maxMsgSize. The curve-explicit ids ESP256 -9, Ed25519 -19, ESP384 -51 and ESP512 -52 are negotiable and unadvertised on the same terms, and the attested key carries the id the request selected rather than the classic spelling of the same curve. (crates/rsk-fido/src/consts.rs.)
  • CTAP1 / U2F 1.1/1.2.
  • PIV: NIST SP 800-73 (Yubico PIV extensions for metadata). GET DATA answers 6A82 to a tag list it cannot read and to a P1-P2 other than 3FFF, the answer for an object the card does not hold, as a YubiKey 5.8.0 does. Key replacement and MOVE retire the prior per-slot public-point cache before committing a key; failed cache retirement answers 6581. Missing or refused cache refreshes fall back to the current metadata point or that key’s scalar. SELECT compares F9’s stored certificate point and public cache with its sealed P-384 key. It repairs absent, empty, truncated or preceding-key certificates under that key and retires stale caches from older builds. Recreating an absent F9 key removes its preceding certificate before committing the replacement; a failed read, retirement or repair answers 6581. An existing F9 key that the current root cannot open, or that names another curve, also makes SELECT answer 6581, preserving the key. A later boot retries unfinished root migration. Selection remains current after refusal, so subsequent raw APDUs still reach PIV’s command handlers and their gates. PUT DATA answers 6982 without the management key, then 6A80 to a P1-P2 other than 3FFF and to a body that is not 5C 03 <id> followed directly by 53 with its length in the shortest form; bytes after the object are ignored. It stores any 5Fxxxx but 5FFF01 (the attestation certificate, which no host may write), as a YubiKey does: 5FC100–5FC1EF and 5FFF00 each in its own file, every other id in a pool of 256 objects and 32 KiB of bodies, whose next write answers 6A84 once either is spent, as a full YubiKey does; an empty 53 deletes the object, answering 9000 for one not held. An object is up to 3063 bytes, 6700 past it, as on a YubiKey 5.8.0: the 3072 bytes a command chain reassembles less the 5C 03 id 53 82 LL LL header. With an extended Le, a single APDU has room for 3044 object bytes. Without Le it has room for 3046. GET DATA for the CHUID (5FC102) returns a synthesized default (non-federal FASC-N + a device-stable GUID = sha256(serial)[..16]) when the host has not written one, so the Windows minidriver can enumerate the card; a host-written CHUID overrides it. The Card Capability Container (5FC107, mandatory per SP 800-73-4 pt1 §3.1.1) is served on the same terms: with no host-written object the card answers a 9-byte synthesized default (F0 00 F1 00 F2 00 F5 01 10 — zero-length mandatory elements plus the PIV data model number 0x10) instead of 6A82, a host PUT DATA overrides it, and an empty PUT DATA falls back to the default again.
  • OATH: Yubico OATH (TOTP/HOTP).
  • OTP: Yubico OTP / HOTP keyboard + CCID.
  • OpenPGP card 3.x. An unreadable variable GET DATA child or password-status record makes the complete response fail with 6581 and no body. PUT DATA C1/C2/C3 changes a slot’s algorithm attribute; when the value changes, RS-Key invalidates that slot’s existing private/public key pair before the new attribute becomes visible. An idempotent same-value write preserves the pair. RSA attributes carry a 17-bit exponent length, as a YubiKey’s do: DO 0xFA lists 01 nnnn 0011 00, PUT DATA takes any length from 17 bits and stores 17, and two attributes that differ only there are the same value. Yubico’s attestation is there too: ATTEST (80 FB <key ref> 00, PW1 in mode 81, the touch D9 sets; past the touch it spends a one-shot PW1 as PSO:CDS does) writes an X.509 statement for a key the card generated into its 7F21 occurrence, signed by a P-384 attestation key (reference 81) whose self-signed certificate is DO FC. The key reads through GENERATE P1 = 81 under B6 { 84 01 81 } and is listed in DE, DA (inside 73 and in FA), C5/C6/CD and D9, where a YubiKey lists its own; no host can import it, generate it or write FC. So is Yubico’s SET PIN RETRIES (00 F2 00 00 03 <PW1> <RC> <PW3>, what ykman openpgp access set-retries sends), as a YubiKey 5.8.0 answers it: 6982 without PW3, then 6A80 for a body that is not three bytes, P1 and P2 not judged. A byte from 1 to 255 becomes that PIN’s maximum and its tries left, unblocking it with its value kept; 0 leaves the PIN as it is. The resetting code’s maximum is kept while none is set (C4 shows 00 for it), and PUT DATA D3 starts a new one there. The PINs and PW3’s status stay, the maxima survive a power cycle, and TERMINATE DF + ACTIVATE FILE put back 3, 3, 3.

The management extensions are in §6 (DeviceInfo), §7 (Rescue), §8 (Vendor/LED) and §9 (CTAP 0x41).

5.1 Where a standard command answers differently

Places where a host that works against other authenticators sees a status byte it may not expect. All are spec-permitted strictness, not extensions, and each says where it matches the YubiKey this project is measured against.

authenticatorReset has a power-up window. CTAP 2.1 §6.6 lets an authenticator with no display refuse a reset that does not follow a fresh power-up. RS-Key does: more than 10 s after the device attached, command 0x07 answers 0x30 CTAP2_ERR_NOT_ALLOWED before the touch prompt, so a host waiting on a press gets an immediate refusal instead. Four properties a host implementation has to plan for:

  • The origin is the USB attach, not power-on. Boot spends seconds before the bus pull-up goes up (TRNG seeding, seal migrations, the one-shot at-rest hardening lap), and none of it is time a host could have used.
  • A warm reset closes the window, it does not reopen one. The vendor REBOOT (§8 INS 1F P1=0), its rescue twin, and the auto-reboot after a phy CONFIG_WRITE are all host-requestable without a credential, so a window a host can restart at will would be no window at all. Only a real power cycle opens one.
  • Trusted-display builds are exempt. Their prompt names the operation on screen, which is what the window substitutes for; a reset is accepted at any time there and still needs the on-screen confirmation.
  • The touch is unchanged. Inside the window the reset still requires user presence, and a decline or timeout answers 0x27 OPERATION_DENIED.

Practically: prompt the user to replug, then send the reset. rsk offboard does exactly that — it sends the reset, and only on 0x30 prints the unplug/replug prompt and retries in the new window (tools/rsk/offboard.py), so it stays correct against a display build and against pre-0x0854 firmware, which both accept the first attempt.

PIV refuses a one-byte command body, whatever the instruction. A PIV APDU carrying Lc = 1 answers 6A80 before anything else — before the PIN or the management key, before P1/P2, and before the instruction is looked up, so even an unimplemented INS answers 6A80 rather than 6D00. No PIV command takes a one-byte body, and a YubiKey 5.7.4 does the same on every instruction. The rule is PIV-only: OATH’s LIST takes a legitimate Lc = 1, and SELECT-by-AID with a one-byte AID prefix is served by the transport before any applet sees it.

U2F AUTHENTICATE rejects a reserved P1. U2F Raw Message Formats §7.2 assigns three control bytes; RS-Key accepts exactly those and answers 6A86 (INCORRECT_P1P2) to anything else, before parsing the request body.

P1NameBehaviour
03enforce-user-presence-and-signtouch required; TUP flag set in the response
07check-onlyvalid handle → 6985, unknown handle → 6A80; never touches
08don’t-enforce-user-presence-and-signsigns with no touch, TUP flag clear; rejected with 6A86 under --features strict-up, which promises a touch on every assertion

U2F over CTAPHID_MSG takes the extended encoding alone. U2F HID v1.2 §2 frames every raw message in extended-length encoding, and a U2F request over CTAPHID is read as a YubiKey 5.8.0 reads it: the class first (6E00 past 00), then either the bare four-byte header or 00 Lc Lc and at least that many data bytes, with anything after them, an Le included, ignored. A short Lc or Le is 6700 whatever the instruction. Over CCID (§5.3) both encodings stay open, as there. On either transport a VERSION that carries data is 6700, since U2F Raw Message Formats §6.1 has it take none; its P1 and P2 are not judged, as on a YubiKey.

OpenPGP GET DATA reads a nested DO only through its template. OpenPGP 3.4 §4.4.1 lists 5B, 5F2D and 5F35 only inside 65, 93 only inside 7A, and 73 — with the C0–C3, C5, C6 and CD it carries — only inside 6E; the fixed-width C7–D0 are readable only as the slices of C5/C6/CD. Each of those 21 answers 6B00 to a GET DATA of its own, and PUT DATA still takes the writable ones. A YubiKey 5.8.0 answers the same, with keys and a name set. The Gnuk-derived suite in third_party/openpgp-card-tests reads them one by one; a host written that way has to read the template instead.

GET DATA answers 6581 with no response body if its construction buffer cannot hold the complete object. A constructed template keeps BER’s shortest length form; fixed-width fingerprint and timestamp fields still truncate older long records and pad short records with zeroes. The 7A security-support template requires its three-byte DS-Counter (93); an absent, unreadable or wrong-width counter answers 6581 with no body.

OpenPGP TERMINATE DF leaves the applet terminated until ACTIVATE FILE. As on a YubiKey 5.8.0, TERMINATE DF (00 E6 00 00, PW3 verified or blocked, 6982 otherwise) wipes the applet and then every command answers 6285, SELECT included, until ACTIVATE FILE (00 44 00 00) answers 9000 and leaves the factory state: C4 = 01 7F 7F 7F 03 00 03, PW1 123456, PW3 12345678. The state survives a reset and a power cycle; a PW1 or PW3 verified before TERMINATE is still verified after ACTIVATE, now against the factory password. ACTIVATE FILE on an applet that is not terminated answers 9000 and changes nothing. RS-Key 0x0A83+; an older build answered TERMINATE with the factory state at once, and a host that sends ACTIVATE right after it, as ykman and gpg-card do, works with both.


5.2 FIDO extension outputs and PIN policy

The uvm extension accepts a boolean on makeCredential and getAssertion. When requested with true, signed authData reports the ceremony factors as [method, keyProtection, matcherProtection] entries: presence (0x0001), external PIN (0x0800), device-local PIN (0x0004), or no interaction (0x0200). Key and matcher protection are 0x0002 (hardware) and 0x0004 (on-chip). getNextAssertion carries the originating ceremony’s methods. A false input produces no output.

The pinComplexityPolicy extension takes a boolean on makeCredential and returns the effective policy only to an RP on the minPinLengthRPIDs list; unlisted RPs receive no output. It has no getAssertion output. Both extensions reject an input of the wrong type. An omitted or empty minPinLengthRPIDs config parameter preserves the existing list; a non-empty list replaces it.

The persisted EF_MINPINLEN layout remains [minimum: u8, flags: u8, rpIdHash…]. Flag bit 0 means forceChangePin; bit 1 enables complexity. Older records with flags 0 or 1 load unchanged, and clearing forceChangePin preserves bit 1 and all RP hashes. Older firmware interprets any nonzero flags byte as a pending PIN change, so downgrading a key with complexity enabled keeps authentication blocked until reset. The upgrade itself requires no migration or reset.

5.3 CTAP over CCID

The FIDO applet answers on the CCID interface as well as on CTAPHID, as ISO 7816 APDUs — the encoding CTAP 2.1 §11.2.1 defines for ISO7816 readers, which python-fido2’s CtapPcscDevice (and therefore ykman over PC/SC) speaks unchanged. PC/SC does not distinguish an NFC reader from the device’s own CCID interface, so this is reachable over plain USB.

StepAPDUAnswer
Select00 A4 04 00 08 A0000006472F0001 009000 with body U2F_V2, or FIDO_2_0 while alwaysUv has U2F off (below)
CTAP280 10 00 00 Lc <cmd ‖ CBOR> 009000 (or 61xx, below) with <status ‖ CBOR>
U2F00 01/02/03 …the CTAP1 answer; 6E00 under class 80; 6986 while alwaysUv has U2F off
Poll, cancel80 11 00 00, 80 11 11 009000 with body 2F, whatever the P1-P2. Use CCID ABORT to cancel in-flight work
Control80 12 01 009000, then 6986 to every command until the next Select; any other P1-P2 6A86

The three CTAP2 instructions (10, 11, 12) are taken under class 00 as under 80, as on a YubiKey 5.8.0. Anything else under 80 is 6D00, under 00 it is U2F’s, under 04 and 84 it is refused 6E00, and no other class reaches it (above).

alwaysUv switches U2F off on both transports (CTAP 2.1 §7.2.4) unless a built-in UV method is configured, the display build’s pad with a PIN: REGISTER, AUTHENTICATE and VERSION answer 6986 over CCID and CTAPHID alike, getInfo drops U2F_V2, and the Select above answers FIDO_2_0, the version string CTAP 2.3 §11.3.3 gives an authenticator with CTAP2 alone. A YubiKey 5.8.0 answers each of these the same.

Control’s END ends the FIDO session on this interface (CTAP 2.3 §11.3.4). CTAP2 and U2F alike answer 6986 until the next Select, by the AID or a prefix of it. A chain’s segments are still acknowledged, and CTAPHID is not affected. A YubiKey 5.8.0 answers each of these the same.

Chaining runs in both directions. Send a CTAP2 command longer than 255 bytes in an extended APDU or in CLA|0x10 segments. A response longer than the short Le ships its first chunk with 61xx and the rest through GET RESPONSE (00 C0 00 00 <Le>). A bare getInfo is already ~520 bytes, so a client that does not follow 61xx sees nothing useful. An extended-length APDU with no Le, or Le 0000, gets up to 3060 bytes in one exchange, and a longer response chains from there.

No 91 00 keep-alive is ever returned. A touch wait blocks inside the exchange while the CCID transport streams T=1 time extensions, exactly as an OATH touch-flagged CALCULATE and an OpenPGP UIF signature already do, so the NFCCTAP_GETRESPONSE poll loop never runs. The poll and cancel APDUs both return 2F 90 00. To abort the in-flight CCID exchange, use the two-phase CCID ABORT (§1.1).

The transport is smaller than CTAPHID. A command chain reassembles 3072 bytes and a response is built in as many, so that is the ceiling on a command and on a response here, against the 7609 that getInfo’s maxMsgSize reports for CTAPHID. Commands stay well inside it; a response that does not fit comes back as a CTAP error rather than truncated. An ML-DSA credential’s attestation does not fit and is CTAPHID-only in practice.

CCID and HID share FIDO state, but CCID uses reserved CID 00000000. Keep CID-bound operations such as MSE and its consumer on the same transport.

Both applications are gated separately. One AID serves CTAP2 and U2F, and ykman config usb --disable fido2 / --disable u2f name them apart, so the commands are gated rather than the SELECT: disabling one leaves the AID selectable for the other and answers the disabled half 6986 — for CTAP2 its MSG, since a poll or a control carries nothing to gate. With neither enabled the AID is gone (6A82).

Some CCID drivers bind only to recognized VID/PID pairs. If such a driver omits the default 1209:F1D2, use the repository’s ccid-rs-key overlay or a VIDPID=Yubikey5 build.

6. Management applet (Yubico-compatible) — applet enable/disable

AID A0 00 00 05 27 47 11 17. CLA 00 or 80. This is what ykman / Yubico Authenticator SELECT first to identify the key and to read/write which applications are enabled. Source: crates/rsk-mgmt/src/lib.rs for the command surface, crates/rsk-devconf/src/lib.rs for the EF_DEV_CONF record it reads and writes.

SELECT returns the firmware version in a YubiKey 5.8.0’s ASCII words, "Virtual mgr - FW version 5.8.0"; take the version from its last word.

INSNameRequestResponse
1DREAD CONFIG—DeviceInfo TLV (see below)
1CWRITE CONFIGdata[0] = inner length n, then n bytes of enabled-apps TLV (n ≤ 128)— (gated by the configuration lock once a code is set, §6.2; presence-gated as well under strict-config)
1E—anything9000 with no body, and nothing is done — as a YubiKey 5.8.0 answers it

6.1 DeviceInfo TLV (READ CONFIG 0x1D)

Response = one leading overall-length byte, then concatenated TAG LEN VALUE:

TagNameLenValue
01USB_SUPPORTED2capability bitmask (BE16) of applications the firmware implements
02SERIAL48-digit serial (chip-id[0..4], MSB masked & 0x03)
04FORM_FACTOR101 = USB-A keychain
05VERSION3major, minor, patch (default 05 08 00)
03USB_ENABLED2currently-enabled capability bitmask (BE16)
08DEVICE_FLAGS180 = touch-eject, 40 = remote wakeup; 00 unless a host set them
0ACONFIG_LOCK100 = unlocked, 01 = a lock code is set (§6.2)

Native FIDO HID READ CONFIG uses command 0x42 (wire byte 0xC2) with an empty request. Its reply is the same length-prefixed DeviceInfo blob, without a CTAP status byte. Native WRITE CONFIG uses 0x43 (wire byte 0xC3) with the same length-prefixed body as the write APDU. Success is an empty reply. A refused or unsupported write returns CTAPHID_ERROR with ERR_INVALID_CMD. The native write is unavailable under strict-config. Neither native command uses the CTAP CBOR vendor envelope (§9). The corresponding OTP feature-report slots are READ CONFIG 0x13 and SET_DEVICE_INFO 0x15.

When no host config has been written, the device returns the defaults: USB_ENABLED = all-supported, DEVICE_FLAGS = 00, CONFIG_LOCK = 00. Once WRITE CONFIG has stored a blob, READ CONFIG echoes that blob after the fixed USB_SUPPORTED/SERIAL/FORM_FACTOR/VERSION prefix, adds DEVICE_FLAGS = 00 after it when the blob carries none (a YubiKey 5.8.0 reports the tag in every DeviceInfo; the stored blob itself is not changed), then always appends CONFIG_LOCK.

A stored blob is echoed only if it still satisfies the WRITE CONFIG rules — each tag at most once, USB_ENABLED exactly two bytes. One that does not (a record an older, laxer build accepted) is not echoed verbatim; the response instead carries a synthesised USB_ENABLED equal to the mask the device actually enforces. So READ CONFIG is always parseable and never contradicts enforcement, whatever is in flash (audit run-34 #25). The config-lock tags (0A set-code, 0B unlock) are write-only: a code is never stored in EF_DEV_CONF or echoed (audit run-30), and 0A on read is the 1-byte lock state (§6.2). A code a build before 0.4.5 stored in the record is dropped at boot and never honoured as a lock.

6.2 Configuration lock

ykman config set-lock-code locks the configuration as it does a YubiKey 5.8.0. While a code is set, every write of EF_DEV_CONF — CCID WRITE CONFIG, OTP-HID SET_DEVICE_INFO 0x15, CTAPHID 0x43 and the FIDO vendor CONFIG_WRITE target 0 (§9) — lands only if it carries that code in 0B (UNLOCK). Without one it is refused (6986; 0x30 over CONFIG_WRITE), with another code likewise (63C0; 0x27), and nothing is stored either way, even for a write that would change nothing. OTP-HID refuses by leaving the program-sequence byte where it was, and CTAPHID 0x43 answers CTAPHID_ERROR. There is no retry counter, as there is none on a YubiKey.

  • Set: 0A with a 16-byte code, on an unlocked device or with the current code in 0B. Clear: 0A of 16 zero bytes, with the current code (ykman’s --clear). A code of any other width, in either tag, is refused as malformed (6A80; 0x02 over CONFIG_WRITE).
  • Who can set one: a host that can reach one of the four writers, on a device with no code yet, and only with a touch of the key, which a YubiKey does not ask for: a code its owner does not hold would keep every config change behind a factory wipe (threat-model.md §1). Declined or timed out, the write is refused whole (6985, 0x27 over CONFIG_WRITE, or the native HID refusal described above). Changing or clearing a code still requires the current code. It needs no extra confirmation beyond the write’s usual gate.
  • At rest: EF_DEV_LOCK (0x1124) holds 01 ‖ SHA-256("RS-Key/CONFIG-LOCK" ‖ serial ‖ code), the serial being DeviceInfo’s four bytes; absent is unlocked. A record in any other form reads locked and opens for no code.
  • Scope: it survives authenticatorReset, like EF_DEV_CONF. The display build’s factory reset or an rsk-wipe erase clears it, which is how a lost code is recovered. It gates the RS-Key phy and LED records (§7, §8) as well, which have no YubiKey counterpart, and no code opens them: while a code is set, every host write of either (rescue 1C/01, vendor SET LED 10, CONFIG_WRITE targets 1 and 2 over either transport, the authenticatorConfig phy ids) is refused as a DeviceInfo write without its code is (6986; 0x30 over CTAP), a replay included, and changes nothing. Clear the lock to change them. The trusted display’s own settings (the touch timeout, for one) are not a host write and stay open.

Capability bits (USB_SUPPORTED / USB_ENABLED):

BitApplication
0x0001OTP
0x0002U2F
0x0008OpenPGP
0x0010PIV
0x0020OATH
0x0200FIDO2

USB_SUPPORTED is fixed at 0x023B (all six). To enable/disable applications, WRITE CONFIG a TAG_USB_ENABLED(03) TLV with the desired mask, e.g. enable only FIDO2+U2F → inner blob 03 02 02 02, full APDU 00 1C 00 00 05 04 03 02 02 02.

USB_ENABLED is enforced, not merely reported: a cleared bit makes that application’s applet stop answering. PIV/OpenPGP/OATH/OTP return 6A82 on CCID SELECT. Disabling FIDO2 makes CTAPHID_CBOR return 27, including authenticatorVendor. Disabling U2F makes CTAPHID_MSG return 6985, including attempts to select the Vendor AID. The OTP keyboard stops typing OTPs. The change takes effect on the next command. Bits outside USB_SUPPORTED are ignored.

To re-enable an application, use CCID Management. On a default build, you can also use a native DeviceInfo write on an available HID interface. The configuration lock still applies. On a strict-config build with CCID omitted, keep the FIDO2 capability enabled so the CTAP config path stays reachable. Restoring an omitted USB interface requires a PHY update and reboot (§7.1).

WRITE CONFIG validates the inner blob (6A80 otherwise): it must be well-formed TLV, carry only tags a host may write (03, 06, 07, 08, 0A, 0B, 0C, 0E, 17 — ykman’s DeviceConfig set), and fit the smallest transport’s response buffer. The device-owned identity tags (01 supported, 02 serial, 04 form factor, 05 version) are emitted by the card and refused on write: READ CONFIG echoes the stored blob after them, and host parsers take the last occurrence, so a stored duplicate would override the real identity and a malformed one would make the whole DeviceInfo unparseable — permanently, since this record survives authenticatorReset. On the default build the write is ungated until a lock code is set (§6.2) — full ykman parity: any USB host can rewrite the reported config, matching a stock YubiKey with no config-lock code. Building --features strict-config restores an on-device user-presence confirmation (Approve on the trusted-display build, a BOOTSEL press otherwise), so a hostile host cannot rewrite it unattended (declined/timed-out → 6985). Either way the identity is cosmetic, never an authenticity signal (see docs/threat-model.md §1/§3).

There is no device-wide reset here. 1F, ykman’s device_reset (sent only when DeviceInfo reports a blocked reset or a Bio with PIV), is 6D00, as on a YubiKey 5.8.0; 1E is acknowledged and does nothing. Both were a presence-gated factory reset before 0x0A01, and the rescue and vendor applets’ own 1E/1F, sent while Management was selected, reached it. The trusted display’s menu keeps a factory reset, and each applet its own. A host written for pico-fido, whose Management 1E resets FIDO, gets 9000 here with nothing erased: reset FIDO with CTAP authenticatorReset instead.


7. Rescue applet (RS-Key configuration conduit)

AID A0 58 3F C1 9B 7E 4F 21. CLA 80 for every INS below (SELECT itself is the standard 00 A4 …). This applet carries the phy device-config record (USB identity + LED hardware), RTC, flash/secure-boot status, the device attestation key, and the one-way OTP fuses. Source: crates/rsk-rescue/src/lib.rs.

SELECT response (identity): MCU(1) | PRODUCT(1) | SDK_MAJOR(1) | SDK_MINOR(1) | serial(8) = 01 02 08 06 <8-byte chip serial>. (MCU 1 = RP2350, PRODUCT 2 = FIDO, SDK 8.6 is the applet SDK version, distinct from the 5.8.0 firmware version.) Use this to identify a Rescue applet. A successful SELECT does not imply that every selector is supported. Probe read-only selectors individually.

INSP1P2Request dataResponsePurpose
10010032-byte SHA-256 digest64-byte secp256k1 signatureKEYDEV: sign a digest with the device attestation key
100200—65-byte uncompressed pubkey (04 ‖ X ‖ Y)KEYDEV: read the device attestation pubkey
100300X.509 DER cert—KEYDEV: store the device end-entity cert
1C0100phy TLV blob (§7.1)—WRITE phy record. 6986 while a configuration lock is set (§6.2), before asking for presence. 6400 if the merge or write fails
1C0201YYYY(BE2) Mon Day Wday Hour Min Sec (8 B)—SET RTC (civil). January is month 0. Wday is ignored
1C0202epoch seconds (BE4)—SET RTC (Unix)
1E0100—phy TLV blob (§7.1)READ phy record; 6581 if the record cannot be read (never the never-written default — the host RMWs on this answer)
1E0200—free ‖ used ‖ kv_total ‖ nfiles ‖ flash_size (5×BE4 = 20 B)READ flash usage
1E0300—enabled(1) ‖ locked(1) ‖ bootkey_slot(1) (FF = none)READ secure-boot status; locked requires one trusted key, all other slots revoked, both debug disables, complete hardening and page-1/2 BL/NS lock copies
1E0401—YYYY(BE2) Mon Day Wday Hour Min Sec (8 B)READ RTC (civil). January is month 0, Sunday is weekday 0. 6985 if unset
1E0402—epoch seconds (BE4)READ RTC (Unix); 6985 if unset
1E0600—required(1) ‖ version(1) ‖ capacity(1)READ anti-rollback state
1E0700—left(2) BE16This boot’s outstanding seal work. Bits 0001 FIDO seed/attestation key/grant, 0002 device key, 0004 PIV, 0008 OATH (including legacy OTP PIN), 0010 OTP, 0020 storage authority. FFFF means no fused key was provisioned. FFFE means the fused key was unreadable and the seal pass did not run
1E0900—version(1) ‖ status(1) ‖ left(2) BE16Read-only automatic page-58 seal result; version 01, status values below
1B5800"LOCK58"—⚠️ IRREVERSIBLE legacy service command — attempt 3D3D3D into page-58 lock row 0xFF5, over a blank row or a subset of the latch. ROM refuses completion once the Secure read-only majority is set (6400). 9000 with nothing burnt when the full latch is there; 6985 over foreign bits, unfinished migration (1E/07 != 0000), or declined presence. From the next boot on no device-sealed record opens under the pre-burn key or in the clear
1B4800"ROLLBK"—⚠️ IRREVERSIBLE — set ROLLBACK_REQUIRED fuse (user-presence-gated)
1F0000——REBOOT (warm; device drops off bus)
1F0100——REBOOT to BOOTSEL bootloader
1E0800—format(1) ‖ ready(1)Storage state: 02 01 means active v2 authority; 02 00 means recovery required
200000"INITV2"—Initialize wholly erased storage; physical confirmation required, occupied/active media refused; success queues a warm restart
200100"IMPORTV2"—Explicitly trust and import readable legacy records; physical confirmation required; success queues a warm restart

For 1E/06, version is the fused minimum epoch. capacity counts the 48 OTP rollback bits. The highest epoch accepted by the signing workflow is 47. The ROM can set ROLLBACK_REQUIRED when installing a versioned signed image. Rescue 1B/48 only sets that flag and checks that Secure Boot is enabled. It does not inspect the running image’s rollback metadata. An already-set flag returns 9000 without another burn or touch. Follow the production sequence for image signing and provisioning.

Storage recovery mode exposes CCID with the Rescue AID only. It permits READ selectors 03, 04, 06, 07, 08, 09, reboot and storage setup. Normal boot automatically initializes wholly blank media or migrates readable legacy storage; neither setup command nor physical confirmation is required for a firmware upgrade. Other rescue operations answer 6581; other applets cannot be selected. Normal FIDO/U2F, OTP and management dispatch stay closed. Setup returns 6985 for declined confirmation or incompatible state, 6581 for a storage failure, 6A86 for invalid selectors and 6A80 for a wrong magic payload. READ 1E/07 includes bit 0020 while storage authority remains under the pre-OTP root. Storage setup performs no OTP operation.

The firmware automatically completes page-58 sealing at boot, including devices previously fused without locking. Secure code validates keys/chaff, waits for left=0000 and performs a fresh successful flash scrub. It first completes and reads back every 0x3C3C3C access-lock bit, preserving any existing latch bits, then burns 0x3D3D3D. This ordering keeps the first step resumable and prevents a torn latch from stranding an unfinished BOOTSEL/Non-secure access lock. A newly closed latch causes a scrubbed restart before command dispatch; TrustZone has not started Non-secure code yet. No APDU or physical touch is required for this boot step. Explicit 1B/58 keeps its existing presence and migration guards for compatibility; READ 1E/09 performs no writes and needs no presence.

1E/09 status: 00 unchecked, 01 unprovisioned, 02 sealed, 03 migration pending, 04 scrub incomplete, 05 incomplete/invalid provisioning, 06 OTP read failure, 07 foreign lock bits, 08 lock write/readback failure, 09 fake-key firmware (real sealing disabled), 0A majority already seals access but the raw latch has incomplete redundancy. For 0A, ROM refuses further writes because Secure is already read-only; boot keeps the migration arms closed and does not retry the burn. 0B means Secure writes closed before the access lock was complete: ROM cannot repair it, root reads and migration are blocked, and storage stays in recovery. left has the 1E/07 meaning. Status is this boot’s result: after a required PIN use, restart to retry migration and sealing. Only 02 confirms a complete latch; unknown versions/statuses must not be interpreted as sealed.

Build 0x0BA8 extends v2 with private, owner-bound PIN/HOTP counter records; APDUs and the 02 01 state response are unchanged. Migration occurs on the first counter update. Earlier builds report recovery and refuse normal applets on this store. Reinstalling a compatible build resumes it; storage initialization is not an upgrade or downgrade procedure.

Every P1 this applet implements is in that table. A P1 outside it answers 6A86 (RS-Key 0x088E+; earlier builds answered 9000 to an unimplemented 1C selector without writing anything, so a newer client could not tell a too-old firmware from a completed write). Use that, and the SELECT handshake above, to detect a firmware that predates a selector you send.

⚠️ Irreversible operations — handle with explicit confirmation

1B/58 ("LOCK58") permanently locks OTP page-58; 1B/48 ("ROLLBK") permanently sets the anti-rollback-required fuse. Both are one-way fuse burns that cannot be undone and can brick a device if misapplied. The firmware triple-guards each (exact P1, exact magic payload, and a provisioning precondition; for 1B/58 also a boot that left nothing under the pre-burn key, as 1E/07 reports), both are idempotent, and the firmware now also requires an on-device user-presence confirmation before the burn (the magic payload is a source-visible constant, not authentication). A config tool must still put these behind an explicit, clearly-worded user confirmation: never a default action, never a bulk “apply”. Most management tools should not expose them at all. 1F/01 (BOOTSEL) drops the device into the bootloader for reflashing; also confirm.

In BOOTSEL, the KV store is fenced off

Since bcdDevice 0x0871 the image carries an RP2350 partition table: the bootloader is denied read and write over the KV store, so picotool save, load and erase across that range answer permission failure. A tool that offers “back up / restore the device’s flash” must expect that and must not present the failure as a device fault. Whole-image flashing is unaffected — the firmware partition stays bootloader-writable. Rationale, and why this is not a substitute for secure boot: threat-model.md.

User-presence gate (runtime)

The runtime-reachable privileged commands require an on-device user-presence confirmation (a button touch, or an Approve on the trusted-display build) before the firmware acts, and return 6985 (CONDITIONS_NOT_SATISFIED) if the operator declines or the wait times out. This gates 10/01 (attestation sign), 10/03 (store cert), 1C/01 (WRITE phy record), the irreversible OTP fuse burns 1B/58 and 1B/48, and 1F/01 (reboot to BOOTSEL) against a hostile USB host. Read-only status (1E/*), the pubkey read (10/02), SET RTC (1C/02) and a warm reboot (1F/00) stay ungated.

The Management applet’s WRITE CONFIG (§6, INS 1C) is gated the same way only under strict-config; the default build ungates it (§6). The rescue phy WRITE (1C/01), OTP-fuse burns and BOOTSEL reboot above stay gated in both builds — they are not part of the ykman admin-write flip.

The vendor applet (§8) exposes the same reboot verb, reachable over both the CCID and CTAPHID transports; its 1F/01 (BOOTSEL) is gated identically, so the gate cannot be bypassed via the vendor AID. Its warm reboot (1F/00) is ungated. Its test-counter write (01) is gated in every build — see §8.

7.1 The phy record (EF_PHY) — PicoForge-compatible

The phy record is the device-config TLV blob. It is the same format PicoForge already writes, so an existing PicoForge config path largely works as-is. Source: crates/rsk-phy/src/lib.rs.

Wire format: a flat sequence of TAG(1) LEN(1) VALUE(LEN) records, any order, all optional. An unknown tag is skipped; a record whose length runs past the buffer ends the parse. The firmware applies the record at boot (USB identity + LED hardware).

A write (Rescue 1C/01, or CTAP vendor CONFIG_WRITE 0x0C target 1, §9) is a read-modify-write merge: only the tags the blob carries are updated; every untouched tag keeps its stored value. So a host may send just the fields it changed without wiping the rest. The meaning of zero depends on the tag. To clear either USB string, send a length of 01 with one NUL byte as the value. A zero-length string TLV is ignored.

TagNameLenValue
00VIDPID4VID(BE2) ‖ PID(BE2)
04LED_GPIO1data-pin GPIO 0..=29
05LED_BRIGHTNESS1global channel max 0..=255
06OPTS2flags (BE16): WCID 0x1, DIMM 0x2, DISABLE_POWER_RESET 0x4, LED_STEADY 0x8
08PRESENCE_TIMEOUT1touch-wait timeout in seconds, bounding the whole ceremony on a button build — the press wait and the release debounce that follows a confirm share it; a trusted-display ceremony may add up to 3 s absorbing a resting finger (0/absent ⇒ firmware default 30 s; a non-zero value below 10 is raised to 10). Matches PicoForge PresenceTimeout.
09USB_PRODUCT1..33up to 32 string bytes. A NUL ends the string and counts toward the TLV length. A 33-byte value with no NUL leaves the stored string unchanged. 09 01 00 clears the override
0AENABLED_CURVES4FIDO curve bitmask (BE32)
0BENABLED_USB_ITF1interface mask: CCID 0x1, WCID 0x2, HID 0x4, KB 0x8, LWIP 0x10
0CLED_DRIVER11 = gpio, 2 = pimoroni, 3 = ws2812 (follows PicoForge LedDriverType)
0DLED_ORDER1WS2812 wire order: 0 = rgb, 1 = grb
0ELED_NUM1RS-Key extension — addressable LEDs actually connected (1..=255; 0/absent = the build’s MAX_LEDS). Firmware saturates a value above its compiled MAX_LEDS ceiling.
0FUSB_MANUFACTURER1..33iManufacturer string with the same encoding as USB_PRODUCT. 0F 01 00 clears the override and restores the default described in §3.1

Notes for a host implementation:

  • Read-modify-write. READ the record, change only your tags, WRITE it back. This is exactly what rsk hw does (tools/rsk/hw.py). Preserving tags you don’t recognize costs you nothing, but note the device does not: merge_save overlays your blob onto the parsed record and re-serializes only the tags this firmware knows, so a tag it does not recognize is dropped at the first write whatever the host sends.
  • PicoForge recognizes ENABLED_USB_ITF, LED_ORDER, LED_NUM and USB_MANUFACTURER in its RS-Key config path.
  • PRESENCE_TIMEOUT has a floor. The record is host-writable and the touch wait reads it live, so a one-second window could expire in the middle of a press and let the next queued request inherit that same hold. The firmware raises any non-zero value below 10 seconds. The floor is applied at boot, on the way to the wait. The stored record keeps the value as written, so a read-modify-write round-trip is lossless; CONFIG_READ’s effective map (§9) reports the floored value, because that is the window the device actually waits.
  • ENABLED_USB_ITF defaults to all interfaces. The firmware instantiates CCID, FIDO HID and keyboard HID. WCID and LWIP have reserved mask bits. A mask without either CCID or FIDO HID falls back to the default at boot, including a keyboard-only mask. An unreadable PHY record gives CCID and FIDO HID only, unless storage recovery restricts the device to CCID.
  • A never-written record reads back as the single zero-OPTS TLV 06 02 00 00.

8. Vendor / LED applet — per-status LED color & effects

AID F0 00 00 00 01. CLA 00. Live LED customization (color/brightness/effect per device status), persisted in flash and applied immediately. Source: crates/rsk-vendor/src/lib.rs, firmware/src/led.rs. Reference client: tools/rsk/led.py.

INSP1P2RequestResponsePurpose
01———counter (BE4)INCREMENT test counter, return new value. User-presence-gated (6985 if declined)
02———counter (BE4)GET test counter
10brightness 0..255color | steady | status<<4[effect[, speed]] opt.—SET LED for one status; 6986, before any touch, while a configuration lock is set (§6.2)
110000—17-byte config blockGET LED config
1F00/0100——REBOOT (warm / BOOTSEL). 01 is user-presence-gated (6985 if declined; see §7)

INS 12 (CORE1_STATS), INS 13 (KEYGEN_BENCH), INS 14 (BENCH) and INS 15 (STACK_RESIDUE, the dead-stack probe tests/55_stack_residue.py drives) exist only in the measurement builds that ask for them (--features core1-stats / keygen-bench / bench, which carries the last two); a shipped image answers 6D00, and none is part of the stable surface.

SET LED 0x10 requires presence under strict-config. A decline or timeout returns 6982. The configuration lock applies in all builds.

SET LED 0x10 is idempotent. A request whose resulting 17-byte block already matches the stored EF_LED_CONF answers 9000 without a flash write. The LED config is still applied live. The next write upgrades a stored 13-, 9-, 3- or 2-byte block to the current layout.

INCREMENT 0x01 always goes through the presence gate. The diagnostic no-touch build confirms automatically. A CTAPHID caller sees KEEPALIVE(UPNEEDED) while the device waits for confirmation. GET 0x02 requires no presence.

Touch-status normalization. The awaiting-touch indicator is the only consent signal on a build without the trusted display, so the EF_LED_CONF codec — not any one command handler — normalizes it on every decode: the vendor SET LED, the FIDO CONFIG_WRITE LED target (§9), and the boot reload of the stored record alike. Four rules, in that order:

  • color 0 (off) on the touch status becomes the default touch colour (yellow).
  • its brightness is raised to 8.
  • a non-zero speed is raised to 2 (speed 1 makes the breathing effect render an all-black frame every tick while the brightness byte still reads compliant).
  • the touch colour is the touch status’s alone. Any other status configured in that colour is reset to its own factory look — whatever its effect, brightness or speed. Uniqueness deliberately keys on colour rather than on the whole (effect, color, brightness, speed) quad: brightness and speed are continuous bytes, so a one-unit nudge is byte-unequal and eye-identical; steady mode renders a solid frame for every effect; and on a one-LED board bounce and flow both collapse to the same solid frame, so the effect byte carries no signal there.

The give-way case. If the status wearing the touch colour has that colour as its factory colour, resetting it would not resolve the clash, so the touch status reverts to its factory look (bounce / yellow) instead. Only boot (red) and idle/processing (green) can trigger this. A red touch status therefore sticks only while boot is not red, and a green one only while neither idle nor processing is green. Yellow is nobody else’s factory colour, which is what makes the fallback converge: enforcing twice is enforcing once.

What this does not guarantee. Two statuses in different colours can still be hard to tell apart. The gpio backend has no hue at all — the indicator is lit or unlit; red, green and yellow are mutually confusable under red-green colour blindness; and on a one-LED board the effect adds nothing. What separates the states there is the per-status blink timing (touch 1000/100 ms vs idle 500/500 ms), which is compile-time fixed and cannot be reconfigured — but the global steady toggle suppresses blinking altogether, and on a single-colour backend that leaves nothing at all to tell the states apart. A build with the trusted display remains the strong answer for consent signalling.

SET LED 0x10 persists the normalized block. GET LED 0x11 returns the live configuration for all statuses. The FIDO CONFIG_WRITE LED target (§9) stores the supplied 17-byte block before normalization. Use CONFIG_READ to retrieve the stored bytes.

SET LED 0x10 P2 layout: bits [2:0] = color, bit 3 (0x08) = steady (solid, no blink, a global toggle), bits [5:4] = status. P1 = per-channel brightness. The command data field is optional: data[0] sets the status’s effect, data[1] its speed (0 = the effect’s built-in default). They are independent: send no data to leave both unchanged, one byte to set only the effect (the current speed is kept), two bytes to set both.

GET LED 0x11 response (config_block, 17 bytes): steady(1) | (effect, color, brightness, speed) × 4 for statuses idle, processing, touch, boot in that order. (block[0] = steady; status s → effect block[1+4s], color block[2+4s], brightness block[3+4s], speed block[4+4s].) Read the response length: older firmware returns a 13-byte (effect, color, brightness) or 9-byte (color, brightness) block. The stride is (len − 1) / 4.

ColorCodeStatusCode
off0idle0
red1processing1
green2touch2
blue3boot3
yellow4
magenta5
cyan6
white7

Effects (the effect byte, ws2812 backend only; gpio/pimoroni always use the classic on/off blink). legacy reproduces the original blink; the rest animate across the connected LEDs and reduce gracefully on a single LED:

EffectCodeEffectCode
legacy (classic blink)0flow3
vapor (breathing)1sparkle4
bounce2

Example. Set the idle status to solid blue at brightness 0x20: P2 = color 3 | steady 0x08 | status 0<<4 = 0x0B, APDU 00 10 20 0B. Example. Set touch to yellow bounce at brightness 0x10, speed 0x0F: P2 = color 4 | status 2<<4 = 0x24, data = effect 2 ‖ speed 0x0F, APDU 00 10 10 24 02 02 0F.


9. CTAP authenticatorVendor (0x41) — seed backup, attestation, audit

A CTAP2 vendor command with command byte 0x41 followed by a CBOR map. Send it inside CTAPHID_CBOR or over CTAP on CCID (§5.3). It can export the device master seed. Source: crates/rsk-fido/src/vendor.rs, constants in crates/rsk-fido/src/consts.rs.

Request map: {1: subcommand(uint), 2: subCommandParams(map), 3: pinUvAuthProtocol(uint), 4: pinUvAuthParam(bstr)}. Encode key 1 before key 2 so the parser knows how to read the parameters. Omit key 2 for a command without parameters. Keys 3 and 4 carry the host PIN token authentication when the gate requires it (§9.2).

SubNameParams (key 2)ResponseGate
01MSE{1: COSE_Key, 2: mlkem_ek?}{1: COSE_Key, 2: ct?}none (establishes channel)
02BACKUP_EXPORT—{1: blob(60)}MSE + presence + PIN gate. Refused if sealed or on a fips-profile build
03BACKUP_LOAD{1: blob(60)}—MSE + presence + PIN gate. Refused while soft-locked. Without a host PIN, also asks “Replace device seed?”. A new seed makes credentials sealed to the old seed unreadable
04BACKUP_FINALIZE——Presence + PIN gate. No MSE
05BACKUP_STATE—{1: sealed, 2: has_seed, 3: locked, 4: unlocked, 5: rescrub_refused}ungated
06UNLOCK{1: blob(60)}—MSE (the lock key is the auth)
07AUDIT_READ—Journal window (§9.3)PIN gate. Also requires presence if no host PIN is set
08AUDIT_CHECKPOINT{1: nonce(bstr, 0–32 bytes)}Signed checkpoint (§9.3)PIN gate + presence. Requires a provisioned DEVK
09ATT_IMPORT{1: blob(60), 2: chain(bstr)}—MSE + presence + PIN gate. The DER certificates are concatenated, leaf first. Without a host PIN, also asks “Replace this identity?”
0AATT_CLEAR——MSE + presence + PIN gate. Without a host PIN, also asks “Erase this identity?”
0BATT_STATE—{1: present, 2: sha256(packed_chain)?}Ungated. Key 2 hashes the device’s packed record. It can be absent even when 1 is true if the chain is missing, unreadable or oversized
0CCONFIG_WRITE{1: target(uint), 2: blob(bstr)} — target 0=DEV_CONF, 1=PHY, 2=LED—The configuration lock applies to all targets (§6.2). strict-config also requires presence and the PIN gate. No MSE
0DCONFIG_READ{1: target(uint)} — target 1=PHY, 2=LEDPHY {1: blob(bstr), 2: {phy_tag: uint}}, LED {1: blob(bstr)}Ungated. An absent record gives an empty blob. A read failure returns 7F
0EAUDIT_CONFIG{1: op(uint)} — 0=disable, 1=enable, 2=status{1: enabled(bool)}Setting requires PIN gate + presence. Status (2) is ungated
0FCONFIG_COMMANDS—{1: [vendorCommandId(uint), …]}Ungated. Lists the authenticatorConfig vendorPrototype (0xFF) IDs this build serves (§11). Older builds before bcdDevice 0x0A80 answer 0x02

After MSE, an invalid BACKUP_LOAD blob length returns 14, and an invalid authentication tag returns 3D. UNLOCK and ATT_IMPORT return 02 for an invalid encrypted key blob.

ATT_IMPORT accepts up to four concatenated DER certificates. To compare the ATT_STATE digest with a known chain, hash the packed form count(1) ‖ (length(2 LE) ‖ certificate DER)*.

rescrub_refused (BACKUP_STATE key 5, bcdDevice ≥ 0x09C5)

Flash health for this power cycle, and nothing more. After the one-shot at-rest hardening lap has run, any command that supersedes a record still sealed to the pre-OTP root must re-arm that lap by clearing its marker. The wipe paths — authenticatorReset and the applet factory resets — take that re-arm best-effort and go on regardless, because refusing there would mean leaving the secrets live, and they answer 0x00 whatever the flash said. Key 5 is true when a re-arm this power cycle could not be shown to have landed, so a stuck medium is reported somewhere other than in the answer to a reset that did succeed.

It does not say the hardening marker is wrong, or that hardening failed. Away from the wipe paths the re-arm gates the write that follows it, so a refusal stops that write: nothing is superseded, and the command either errors or skips a lazy migration and leaves the older record in force. Read key 5 as “this device’s flash refused a write it was asked for”, and nothing stronger.

Coverage is lost in one arm only, a wipe whose refusal was persistent. A wipe tries more than once — ahead of its sweep and again after it — and a refusal the retry recovers still sets key 5 even though the marker is then gone and the next boot laps as it should. When no attempt lands, the marker stays latched over the records the wipe superseded, no later boot ever laps, and those copies stay recoverable from a physical flash dump while the reset answered 0x00. Key 5 does not say which arm it is, and repeating the reset does not recover what that one already exposed, so a device that keeps reporting it has a failing medium and should be retired rather than trusted at rest. It is RAM state, so it clears on the next power cycle whether or not the flash recovered, and an older build simply omits the key.

Device configuration over FIDO (CONFIG_WRITE 0x0C)

The pcscd-free twin of the CCID device-config writes (§6 WRITE CONFIG and the §7/§8 phy/LED records): a host that cannot reach the CCID interface writes the same config over CTAPHID. target selects the record: 0x00 = the management enabled-apps TLV (EF_DEV_CONF, the §6 blob, ≤ 128 bytes → the same CTAP1_ERR_INVALID_LENGTH 0x03 cap, under the §6.2 lock); 0x01 = the phy record (EF_PHY, §7.1: VID/PID, USB interfaces, LED wiring, presence-timeout; a read-modify-write merge — only the TLV tags in the blob are updated, the rest preserved (the same merge_save the CCID path uses), effective on the next boot); 0x02 = the LED config block (EF_LED_CONF, §8, CONF_LEN bytes), persisted and then applied live by the firmware. Send at least 17 bytes for the LED target. The device stores the first 17 bytes and ignores any suffix. CONFIG_READ target 2 returns the stored block verbatim, so it can differ from the live configuration after §8’s normalization. With the configuration unlocked, the default build permits these writes without presence or PIN authentication. strict-config adds both the presence gate and the PIN gate (§9.2). The CCID and CTAP management paths use the same DeviceInfo record, so a later CCID READ CONFIG reports the change.

Replays and the audit journal. A write whose result equals what is already stored returns 0x00 and writes nothing — no flash write, no journal entry, and for PHY no auto-reboot latch. An LED replay is still applied live, as SET LED’s is. The comparison is against the merged record for PHY, so a partial blob that changes nothing is also a no-op; an absent or unreadable EF_PHY is never “unchanged”, so a host writing the default values to repair one is not answered 0x00 with nothing stored.

A write that does change something is journalled, and a run of them costs a single ring entry. CONFIG_WRITE is one of three journalled events an ungated host can drive on demand — the others are a getAssertion carrying up:false and a U2F AUTHENTICATE with P1=0x08, both of which take the spec-mandated silent path — so appending one per call would let any of them evict the 128-entry window. All three coalesce. For CONFIG_WRITE, when the newest entry is already a config write the device folds into it. The entry keeps its seq, its timestamp (the first write of the run) and its aux (the target that opened it), and its detail becomes repeats(2 LE) ‖ targets(1) — the number of further writes absorbed (saturating) and a 1 << target mask of every record the run touched. A run never folds across a power cycle, so the BOOT entry between two runs is never swallowed.

The two silent FIDO events use a different encoding: the entry keeps the detail of the first occurrence (the rpIdHash shown is the run’s first site) and the count of further folded occurrences is a saturating LE u16 in the entry’s trailing two bytes — previously reserved and always zero, so an older build’s entries decode as a single occurrence. That fold scans the whole window, not just the newest entry, so interleaving two silent classes does not defeat it. A gestured assertion never folds. For a host re-checking the chain: a fold changes the head without advancing seq_next, so the same seq_next with a different head is legitimate and is not a tamper signal (start, seq_next and the epoch are untouched, so the window still folds to the head exactly as before).

CONFIG_READ 0x0D PHY key 2 (RS-Key 0x0852+): the PHY read returns a 2: map of boot-effective values keyed by phy tag: 4 = LED GPIO pin, 12 = LED driver, 8 = presence timeout (seconds) — resolved to the build default when the record has no override. Tag 8 reports the window the wait actually uses, i.e. with the 10 s floor of §7.1 already applied. It is for display by the host. The key 1 blob remains the raw override record for read-modify-write. When the firmware has no effective LED configuration, key 2 is an empty map.

⚠️ Seed export hands out a normally non-exportable key

BACKUP_EXPORT (0x02) returns the device’s 32-byte master seed (encrypted over the MSE channel). It is gated by a one-time setup window (re-opened only by an authenticatorReset) and requires presence and the PIN gate (§9.2). Ask for explicit confirmation before exporting the seed. BACKUP_FINALIZE closes the export window. The fips-profile build refuses export entirely.

9.1 The MSE channel (0x41 / 0x01)

Establishes an encrypted channel for the seed-moving subcommands.

  • Request subCommandParams = {1: COSE_Key} where the COSE key is the host’s P-256 public key {1:2, 3:-25, -1:1, -2:X, -3:Y}. X and Y are each exactly 32 bytes — a coordinate whose leading zero your bignum dropped is 0x02 INVALID_PARAMETER, not left-padded (RS-Key 0x089C+; the same rule the clientPIN and hmac-secret COSE parses apply, and what a YubiKey 5.7.4 does). Optional key 2 = the host’s ML-KEM-768 encapsulation key (1184 B) to make the channel hybrid PQC.
  • Response {1: COSE_Key} = the device’s ephemeral P-256 public key (same COSE shape, -2:dx, -3:dy). If the request included an ML-KEM ek, the response adds key 2 = the 1088-byte ML-KEM ciphertext.
  • Channel key (32 bytes):
    • classical: HKDF-SHA256(salt="", ikm = ECDH_x(32), info = dev_pub(65))
    • hybrid: HKDF-SHA256(salt="RSK-MSE-PQ-v1", ikm = ECDH_x(32) ‖ ss_mlkem(32), info = dev_pub(65) ‖ ct(1088))
    • dev_pub is the 65-byte uncompressed device key 04 ‖ dx ‖ dy.

Blob format (the 60-byte blob in EXPORT/LOAD/UNLOCK/ATT_IMPORT): nonce(12) ‖ ciphertext(32) ‖ tag(16), ChaCha20-Poly1305 under the channel key with AAD = dev_pub (65 bytes).

The device has one live MSE slot. Run MSE immediately before the protected command on the same transport and CID. Once a vendor consumer request parses, it takes the slot before checking the remaining gates, including presence and decryption. A CID mismatch empties the slot without giving the caller its key. For authenticatorConfig AUT_ENABLE, the slot is taken after the config authentication check.

A second valid MSE request while the slot is live clears the slot and returns 30. Start a fresh handshake after that response. A CTAPHID CID is a host-supplied routing value. Refusing an in-place rekey prevents a second MSE from replacing a live recipient key for BACKUP_EXPORT.

9.2 PIN gating

With a host clientPIN configured, commands marked PIN gate require pinUvAuthProtocol (key 3) and pinUvAuthParam (key 4). The token must carry the acfg permission (0x20).

HMAC-SHA256(pinUvAuthToken, FF × 32 ‖ 41 ‖ subcommand ‖ rawSubCommandParams)

Use the first 16 MAC bytes with protocol 1 and all 32 with protocol 2. rawSubCommandParams is the verbatim CBOR encoding of the key-2 map, or zero bytes if key 2 is absent. The reference client is tools/rsk/backup.py.

An unsupported protocol (including 0) returns 02. Missing key 4 returns 36. If key 4 is present and key 3 is missing, the device returns 14. A bad MAC or missing acfg permission returns 33.

Without a host PIN, a configured device PIN is collected on the trusted display. If the current build cannot collect it, the request returns 36. Decline, timeout and cancellation during PIN entry return 27, 2F and 2D respectively. A wrong PIN consumes a retry. With neither PIN configured, the PIN gate passes and any separate presence checks still apply.

An unsupported one is judged before the algorithm, the extensions and the remaining options — makeCredential and getAssertion included, where it used to be judged after all of them, so a request that got two things wrong was told about the wrong one (bcdDevice 0x08B6). Two things still outrank it, both because a YubiKey 5.7.4 puts them there:

  • the request map’s own shape — keys 1..=4 of makeCredential and 1..=2 of getAssertion are read in order, and an absent, empty or over-long one is answered before any value is validated;
  • the option values of §6.1.2/§6.2.2 step 4: up:false on makeCredential, and uv:true with no pinUvAuthParam on a build without built-in user verification, are 0x2C INVALID_OPTION whatever pinUvAuthProtocol says. options.rk is not in that class and loses to the protocol, on that card and here.

9.3 Audit journal format

AUDIT_READ returns {1: start, 2: seq_next, 3: epoch, 4: entries}. The sequence numbers are CBOR unsigned 32-bit values. epoch is a 32-byte byte string. entries is a byte string of 20-byte records in sequence order.

seq(4 LE) ‖ uptime_ms(4 LE) ‖ event(1) ‖ aux(1) ‖ detail(8) ‖ repeats(2 LE)

Start with the exported epoch and compute SHA-256(previous_hash ‖ entry) for each record. The final hash is the chain head. Event IDs and detail layouts are defined in crates/rsk-fido/src/journal.rs.

AUDIT_CHECKPOINT returns {1: head, 2: seq_next, 3: signature, 4: public_key}. The head is 32 bytes. The signature is DER-encoded ECDSA-SHA256 and the public key is a 65-byte uncompressed P-256 point (04 ‖ X ‖ Y). Verify the signature over the following bytes, using the DEVK-derived audit public key.

ASCII("RSK-AUDIT-CKPT-v1") ‖ head(32) ‖ seq_next(4 LE) ‖ nonce(0–32)

A journal entry can change in place when events coalesce. Compare the computed head as well as seq_next when checking whether the export and checkpoint cover the same snapshot.


10. Worked examples

All bytes hex; → shows the response (status word omitted when 9000).

Identify the device (Management DeviceInfo):

SELECT  00 A4 04 00 08 A0 00 00 05 27 47 11 17 00
READ    00 1D 00 00 00
→  1C 01 02 023B 02 04 <serial> 04 01 01 05 03 050800 03 02 023B 08 01 00 0A 01 00

Read the phy record (Rescue):

SELECT  00 A4 04 00 08 A0 58 3F C1 9B 7E 4F 21 00
→  01 02 08 06 <8-byte serial>            # identity handshake
READ    80 1E 01 00 00
→  <phy TLV blob>                          # e.g. 06 02 00 00 on a virgin device

Switch USB identity to 1209:F1D2 by sending a patch for tag 00 to the selected Rescue applet. Confirm the write on the device, then reboot after 9000.

WRITE   80 1C 01 00 06 00 04 12 09 F1 D2 00
REBOOT  80 1F 00 00 00

Set processing-status LED to red, brightness 64 (Vendor/LED):

SELECT  00 A4 04 00 05 F0 00 00 00 01 00
SET     00 10 40 11        # P1=0x40 brightness, P2 = color 1 | status 1<<4 = 0x11

Read backup state over CTAPHID. Send CTAP2 message 41 A1 01 05 (0x41 + CBOR {1: 5}) → on a fresh provisioned device 00 A5 01 F4 02 F5 03 F4 04 F4 05 F4. After the 00 status byte, the map sets has_seed to true and sealed, locked, unlocked and rescrub_refused to false.


11. Integration notes for PicoForge

PicoForge can reuse its PHY TLV codec (§7.1) with the RS-Key Rescue AID A0 58 3F C1 9B 7E 4F 21 and CLA 80. Send only the tags to update. Skip unknown tags while reading. An unsupported CTAP vendor subcommand returns 02. Use the read-only probes in §6.1, §7 and §9 to discover capabilities.

For the legacy hardware-config path, send authenticatorConfig (CTAP 0x0D) with subcommand vendorPrototype (0xFF) and parameters {1: vendorCommandId(u64), 3: value(uint)}. The four PHY writes require an acfg token and do not ask for presence. A configuration lock returns 30.

PHY commandIDValue
PhysicalVidPid0x6fcb19b0cbe3acfa(vid << 16) | pid
PhysicalLedGpio0x7b392a394de9f948GPIO number
PhysicalLedBrightness0x76a85945985d02fdGlobal brightness
PhysicalOptions0x269f3b09eceb805fPHY OPTS bitmask (§7.1)

getInfo lists 0xFF in authenticatorConfigCommands (0x1F) and returns an empty vendorPrototypeConfigCommands array (0x15). Use authenticatorVendor CONFIG_COMMANDS (41 / 0F) to retrieve the 64-bit IDs. The list includes soft-lock enable and disable (0x03e43f56b34285e2 and 0x1831a40f04a25ed9) and the enterprise-attestation RP list (0x0e6841934e719be7, RP IDs at key 4). Soft-lock enable also uses MSE.

Use the Rescue PHY commands or authenticatorVendor CONFIG_READ/WRITE for fields beyond the four legacy PHY IDs, such as product name, touch timeout, LED driver and curves. PHY changes take effect at boot. A changed FIDO PHY write normally queues a reboot. Setting DISABLE_POWER_RESET keeps the device attached until the host or operator reboots it.

Use DeviceInfo for applet enable/disable (§6), and require explicit confirmation before fuse burns (§7), rebooting to BOOTSEL (§7/§8) or exporting a seed (§9). Reference client paths under tools/rsk include ccid.py, ctaphid.py, hw.py, led.py, backup.py, status.py and inventory.py.