RS-Key host protocol reference
This document specifies the host-facing protocol of the RS-Key firmware: how a configuration/management tool talks to the device, what commands exist, the exact byte layout of each request and response, and what authenticates each one.
It exists so that third-party tooling (e.g. PicoForge) can configure and
manage RS-Key devices. The rsk Python CLI is a runnable reference for the
management operations it exposes. Firmware source paths accompany the wire
formats.
Audience & scope. This is a wire spec, not a tutorial. It documents the commands a host sends and the bytes it gets back. It does not cover the on-device storage format, the crypto internals, or the build system. Those live in architecture.md and the crate sources.
Licensing. RS-Key firmware is AGPL-3.0-only. This protocol description is published as part of the same repository; you are free to implement a client against it under any license. Interop implementations do not inherit AGPL by talking to the device.
Stability. The transports and the standard applets (FIDO2, U2F, PIV, OATH, OTP, OpenPGP, Yubico Management) are stable. They follow public specs. The RS-Key-specific surface (Rescue applet, Vendor/LED applet, CTAP
authenticatorVendor 0x41) is versioned bybcdDeviceand may grow; new tags/subcommands are added, existing ones are not silently repurposed. Probe the version handshakes (§3, §6.1) and treat unknown tags as skippable.
1. Transports
RS-Key is a USB composite device. Its default interface set is:
| Transport | Carries | Host API |
|---|---|---|
| Keyboard HID | Yubico OTP feature reports and typed OTP output | OS HID stack / Yubico OTP libraries |
CTAPHID (FIDO HID, usage page 0xF1D0) | CTAP1/U2F, CTAP2, and native HID DeviceInfo commands | hidapi |
| CCID (PC/SC smart-card) | ISO-7816 applets selected by AID, including CTAP over CCID | pyscard / PC/SC |
On the default build, keyboard HID also carries the ykman OTP-HID admin writes (SET_DEVICE_INFO 0x15,
DEVICE_CONFIG 0x11, SCAN_MAP 0x12, NDEF 0x08/0x09).
SET_DEVICE_INFO shares the DeviceInfo store with CCID WRITE CONFIG (§6).
SCAN_MAP remaps typed OTP output. DEVICE_CONFIG and NDEF have no effect on USB
operation. An accepted admin write advances the status frame’s program-sequence
byte. Under strict-config these slots leave it unchanged, which ykman/yubikit
treat as a rejected command.
The interfaces are presented in the stock YubiKey order — keyboard/OTP, FIDO
HID, CCID — because some hosts address the OTP interface by index instead of
by descriptor: the libusb backend ykpers/ykcore ships (KeePassXC,
ykchalresp, pam_yubico) claims interface 0 and sends the OTP frame reports
there whatever the descriptors say. An interface switched off in
ENABLED_USB_ITF (§7) is omitted and the rest keep that relative order, so a
host that assumes a fixed index only holds where the same interface set is
enabled.
The OTP frame protocol answers HID feature GET/SET_REPORT on the keyboard interface only. On macOS, access to the keyboard interface can require Input Monitoring. The FIDO interrupt endpoints carry CTAPHID, and their report descriptor declares no feature report.
A slot programmed to require a touch answers its challenge only after a button
press, and reports the wait in the status byte (0x20) meanwhile. Two things end
that wait early, both matching a YubiKey: the host’s dummy write — a report
whose sequence byte is out of range, 0x8f, which also resets the read mode after
a response — and any new frame, which supersedes the pending challenge. A host
that does neither waits out the touch timeout (§7 PRESENCE_TIMEOUT), during
which the transport reports only that it is waiting.
Once announced, 0x20 holds for the rest of the command — the press itself does
not clear it, only the response frame or the idle status frame does. ykpers reads
a byte carrying neither the pending nor the waiting bit as a touch timeout, so a
device that dropped the wait between the press and its answer would lose
challenges it had in fact completed.
1.1 CCID APDU framing
CCID ABORT has two phases (CCID 1.1 §4.1). Send an EP0 class request with
bmRequestType=21, bRequest=01, wValue=bSlot | bSeq<<8
at the CCID interface, followed by PC_to_RDR_Abort (72) with the matching
slot/sequence. Slot 0 is the only slot. Until the matching bulk command arrives,
commands fail with CMD_ABORTED (FF); the bulk acknowledgement is
RDR_to_PC_SlotStatus (81). An unmatched bulk sequence is refused with field
offset 06. An aborted transfer returns a failed DataBlock with bError=FF
in place of its APDU reply. Cancellation can end a presence wait. Synchronous
work reaches its normal safe point, and committed writes remain in effect.
USB reset, deconfiguration or suspend invalidates pending replies and clears transient applet authorization in Secure before new work is accepted. Persisted keys and the FIDO per-boot PIN mismatch budget survive a bus event. The same event discards partial CTAPHID messages and clears the channel lock. Continuation frames from the old session cannot resume an interrupted message.
CCID accepts ISO-7816 short and extended APDUs. Use
00 A4 04 00 Lc <AID> 00 to select by AID. RS-Key also accepts the
P2 = 04 form used by PicoForge. The
selected applet then receives CLA INS P1 P2 [Lc <data>] [Le]. There is no ISO
master file, so the master-file SELECT (00 A4 00 0C …, GnuPG’s 3F00 probe)
answers 6D00 like a YubiKey. The power-on ATR is T=1, its historical bytes labelled
YubiKey when the effective USB VID is 1050 and RS-Key otherwise (identical
card capabilities). The reference transport is tools/rsk/ccid.py:
def select(conn, aid):
return transmit(conn, [0x00, 0xA4, 0x04, 0x00, len(aid)] + list(aid) + [0x00])
The class byte is judged before the command, for every applet, GET RESPONSE
aside (below). Bit 0x10 marks a command-chaining segment and is looked at
first, so 10, 1C, 90 and FF are all ordinary segments. Otherwise only
00, 04, 80 and 84 reach an applet. Every other class gets an empty
answer: a data block with no body and no status word, which a client library
that expects one raises on (pyscard: Card returned no valid response). Under
04 and 84, the secure-messaging classes, SELECT works as under 00 and any
other command to a selected applet is 6E00 — no applet here implements secure
messaging, and OpenPGP’s Extended Capabilities says so. With no applet
selected, as after a card reset, every command but a SELECT is 6D00 whatever
its class, a SELECT by file id or with P2 0C included, and a SELECT of an AID
the device lacks is 6A82. All of that is a YubiKey 5.8.0’s, read class by class
over raw USB. RS-Key’s own: an unanswered command changes nothing,
so an open chain still takes its final segment and a held tail its
GET RESPONSE. An XfrBlock of one or three bytes, too short for CLA INS P1 P2, is refused by the reader as a YubiKey 5.8.0 refuses one, measured with the
slot powered: a failed RDR_to_PC_SlotStatus, bStatus 40, whose bError 01
names dwLength, and no APDU runs. RS-Key’s own: none and two bytes are refused
the same way, and a powered-off slot keeps its ICC status (bStatus 41). An
empty block is no response continuation here: RS-Key never chains a response
across CCID messages (bChainParameter stays 00).
Applets that additionally name a class of their own reject
anything else themselves: OATH, management and OTP take 00 and 80 alike,
both of which a YubiKey 5.8.0 serves there, U2F wants 00 and rescue 80. A
chain can carry at most 3072 bytes of command data. A non-final segment must
leave room below that limit. The final segment may fill it exactly. On overflow,
the device returns 6700 and drops the chain. Segments must match on
(CLA & ~0x10, INS, P1, P2). A mismatch returns 6883 and clears the chain.
A SELECT-by-AID discards the old chain before looking up the AID.
A single XfrBlock fits a 3062-byte APDU after the 10-byte CCID header.
An extended APDU can therefore carry up to 3055 bytes of data without Le,
or 3053 with Le. Use ISO-7816 command chaining for larger inputs within the
reassembly limit.
The lengths have to describe the command exactly, short or extended (00, then
a two-byte Lc or Le): a byte past the Le, or an Lc its data does not
fill, is 6700 before any applet sees the command, as a YubiKey 5.8.0 answers it
over raw USB. Two shapes outside ISO 7816-4 are read as that YubiKey reads them:
a two-byte body 00 xx is the extended Le 00xx, and an extended Le
followed by two more bytes is a case 4 with Lc 0000, those two bytes its
Le. RS-Key’s own: the selection, an open chain and a held tail stay as they
were.
PIV, OpenPGP and CTAP over CCID answer a success body longer than the request’s
Le with ISO-7816 response chaining: the first chunk ships with status
61 XX (XX = further bytes available, 00 = 256+), and the host issues
GET RESPONSE (00 C0 00 00 <Le>) until 9000. A short command with no Le
(Case 1 or Case 3) is capped at 256; an extended one with no Le is not, and gets
the whole body in one frame, as a YubiKey 5.8.0 answers it. One frame carries 3060
bytes of body; a longer one chains from there whatever the Le, where a YubiKey’s
PIV cuts the frame and loses its status word. GET RESPONSE is cut by its own
encoding the same way. A certificate object over 256 bytes chains when
it is read with a short GET DATA, so a host that sends a short GET DATA without
an Le must still follow 61xx. A 00 C0 with nothing left to serve is 6A80
on PIV and 6D00 on OpenPGP, OATH, management, OTP and FIDO. While a tail is
owed, a GET RESPONSE without the chaining bit serves it whatever its class,
since that answer already began in the clear: a YubiKey 5.8.0 does so under 00,
80, 04, 84 and 0C, a class it answers nothing otherwise, and RS-Key
under every class. With the chaining bit (10, 90, 1C), owed tail or not,
it is a 9000 that opens no chain and leaves any tail for the next one; inside
an open chain it is 6883, like any command outside that chain, both as on a
YubiKey 5.8.0.
With nothing owed, a GET RESPONSE under 04 or 84 is 6E00 to a selected
applet and 6D00 with none, like any command but SELECT there, and under a class
no applet is reached by it gets the empty answer.
OATH LIST (0xA1) and CALCULATE ALL (0xA4) responses that outgrow the
command’s Le chain the YubiKey-OATH way instead: 61 XX followed by SEND
REMAINING (00 A5 00 00) rather than GET RESPONSE, matching what ykman /
Yubico Authenticator send. A short command with no Le gets 256 bytes a frame and
an extended one as much as a CCID frame holds. Frames are cut at the byte, so an entry can
straddle two of them: join the frames before parsing. SEND REMAINING never judges
its P1-P2, and with no page owed it answers 6D00, as a YubiKey 5.8.0 does.
OATH PUT. PUT
(0x01) is strict about the credential body — KEY TLV 16..=66 bytes (a secret
shorter than 14 bytes is refused, not padded: zero-pad it first, as ykman does,
and the codes do not change), digits 6/7/8, type 0x10/0x20, algorithm 1/2/3,
name 1..=64 bytes, the initial moving factor on HOTP only and exactly 4 bytes,
the PROPERTY byte as the bare 78 vv pair, the four YKOATH tags in that order,
no duplicate, no unknown tag and no trailing byte. Anything else is 6A80 with
nothing stored, so a rejected PUT leaves an existing credential of that
name working. RS-Key also stores the password-safe fields 0x83/0x84/0x85,
up to 255 bytes each, anywhere in the body.
OATH access code. SET CODE (0x03) holds
its key to the same measured rule: the 73 TLV is one algorithm byte plus
14..=64 bytes of key material, or empty to remove the access code — anything
else is 6A80 and whatever code was installed is left exactly as it was. Its
proof travels over an exactly 8-byte 74 challenge (os.urandom(8), as
ykman sends it); any other width is 6A80, and removing a code needs no
challenge at all. VALIDATE (0xA3) then refuses a proof that does not match
with 6A80 as well; 6984 from it means something else entirely — no access
code is installed to match against.
OATH only-increasing property. A TOTP credential with PROPERTIES bit 0
computes only for a challenge strictly
greater than the highest one it has served, comparing the raw challenge bytes
zero-extended on the right — plain numeric > for the usual 8-byte counter. A
challenge at or below that mark is 6A80, and in CALCULATE ALL one such
credential fails the whole command with an empty body. The one exception is a
credential a build before this rule stored: its body can leave no room for the
mark, and CALCULATE ALL then reports it with 77 (no response) and computes
the rest of the store rather than failing — its own CALCULATE still answers
6A80.
The bulk preflight refuses a flash read fault with 6581 and no response body,
before a code can be emitted without its mark. Marks committed before the
failing slot remain advanced; the operation is not atomic across credentials.
OATH challenge length. CALCULATE (0xA2) and CALCULATE ALL
(0xA4) take an opaque byte string of 0..=64 bytes in the 74 TLV and HMAC
all of it; 65 or more is 6A80, judged before the credential is looked up and
whatever the credential’s type, so a HOTP account that ignores the challenge
refuses an over-wide one too. Both read paths therefore answer the same code for
the same challenge at every accepted width — including across a SEND REMAINING
page — and the usual 8-byte TOTP counter is simply the common case.
OATH TLV order. CALCULATE, VALIDATE and SET CODE
are parsed by position: exactly the documented TLVs, in the documented
order, with nothing before, between or after them — 71 then 74 for
CALCULATE, 75 then 74 for VALIDATE (the response comes first, as
ykman sends it), 73 then 74 then 75 for SET CODE, or a lone 73 00 to
remove the code — that spelling and no other, so a SET CODE carrying no body
at all is 6A80 and the standing code goes on opening the applet, as on a
YubiKey. A reordering, a repeated tag, an unknown tag or a trailing byte is
6A80, with nothing stored. CALCULATE ALL is the one exception the card
makes: its 74 must be the first TLV, and whatever follows it is ignored.
OATH truncation. With P2 = 0x01 the 76 TLV is
[digits][code(4)], and the four bytes are the RFC 4226 dynamic truncation
already reduced to that credential’s digit count — big-endian, so a 6-digit
account never exceeds 000F 423F. A host must not reduce a second time expecting
a different answer, and VERIFY CODE (0xB1) compares exactly the value
CALCULATE sent. The untruncated form (P2 = 0x00, tag 75) is unaffected: it
carries the whole HMAC.
OATH parameter bytes. Default to P1 = 00, P2 = 00. The 01 that
selects the truncated form belongs to
CALCULATE and CALCULATE ALL and to nothing else — on PUT, DELETE, SET CODE, RENAME and LIST it is refused like any other stray byte. RESET alone
takes DE AD, and VALIDATE is the card’s own exception: it refuses only when
both bytes are non-zero. Anything else is 6B00, judged before the
command’s body and before the access-code gate so nothing is written; an
instruction the applet does not implement still answers 6D00 first.
1.2 CTAPHID framing
64-byte HID reports. Init frame: CID(4) | CMD(1) | BCNT_HI | BCNT_LO | data[:57];
continuation frames: CID(4) | SEQ(1) | data[:59]. CTAPHID_INIT = 0x86,
CTAPHID_CBOR = 0x90, CTAPHID_KEEPALIVE = 0xBB. A CTAP2 message is
command_byte | CBOR_payload. A CTAP2 response starts with a one-byte status.
Native HID DeviceInfo commands use their own HID command byte (§6.1).
Reference implementation in tools/rsk/ctaphid.py.
While a CBOR command runs, the device sends CTAPHID_KEEPALIVE every 100 ms
with status 01 (processing) or 02 (waiting for user presence). A
zero-length CTAPHID_CANCEL (wire command 0x91) on the active CID gets no
separate reply. The original CBOR request returns 2D
(CTAP2_ERR_KEEPALIVE_CANCEL) at a safe point. A committed write stays committed.
Take the channel id from the CTAPHID_INIT response and use that one: every INIT on
the broadcast CID allocates a fresh id, so an id hardcoded or cached across sessions
will not be yours. CTAPHID_LOCK is honoured for the 1–10 seconds it asks for,
though no INIT capability bit says so: CTAP defines none for it, and 0x02 — a
pre-standard U2FHID header’s LOCK bit — stays clear, as on a YubiKey 5.8.0. Meanwhile
every other channel gets ERR_CHANNEL_BUSY — including one sending CTAPHID_INIT
to resynchronise itself. The exception is an INIT on the broadcast CID, which
still gets through: a client arriving mid-lock is given an id, then turned away on
it.
1.3 CCID secure PIN entry (pinpad) — display builds only
A trusted-display build advertises bPINSupport = 0x01 (VERIFY) in its CCID class
descriptor (body byte 50 / full descriptor byte 52), so a host driver treats it as
a pinpad reader and sends PC_to_RDR_Secure (0x69) instead of a plaintext
VERIFY; the PIN is then typed on the device’s own screen. A standard (no-screen)
build leaves bPINSupport = 0x00 and rejects 0x69. No control transfer is
involved. The host CCID driver reads bPINSupport straight from the descriptor;
the device only has to handle 0x69. The validated trigger is GnuPG’s internal
CCID driver (keys solely off bPINSupport); PC/SC + libccid and macOS
CryptoTokenKit also expose pinpad from the descriptor, but their FEATURE_VERIFY_PIN_DIRECT
coverage varies, so treat the GnuPG-internal path as the reliable one.
The host must use pinpad mode to keep the PIN off the wire. A normal
XfrBlock VERIFY (00 20 P1 P2 Lc <PIN>) still carries a plaintext PIN.
Whatever the host driver, the bytes on the wire follow the CCID structure
below, not the PC/SC v2 Part 10 IOCTL structure (the driver drops that structure’s
bTimeOut2 and ulDataLength when it builds the 0x69), so the VERIFY template is
always at abData offset 15. The 0x69 payload is the CCID abPINDataStructure for
VERIFY:
bPINOperation(1)=0x00 verify | bTimeOut(1) | bmFormatString(1) | bmPINBlockString(1) |
bmPINLengthFormat(1) | wPINMaxExtraDigit(2 LE) | bEntryValidationCondition(1) |
bNumberMessage(1) | wLangId(2 LE) | bMsgIndex(1) | bTeoPrologue(3) |
abPINApdu = CLA INS=0x20 P1 P2 … (the VERIFY template, at offset 15)
Select an enabled OpenPGP or PIV applet first. The display asks
“Allow host PIN entry?” before opening the PIN pad.
The device reads the template’s P2 (OpenPGP 0x81/0x82/0x83 = PW1-sign /
PW1-other / PW3-admin; PIV 0x80 = application PIN), collects the PIN on the pad,
builds the real VERIFY APDU (00 20 P1 P2 Lc <ASCII PIN>; PIV pads with 0xFF to
8 bytes), runs it through the selected applet, and replies with a normal
RDR_to_PC_DataBlock (0x80) carrying only the status word:
- success →
90 00,bStatus = 0,bError = 0. - wrong PIN → the card’s real answer: PIV’s
63 Cx(tries left, reported saturated atx = Fso a larger configured retry total cannot wrap into63 C0= blocked), OpenPGP’s69 82as a YubiKey 5.8.0 answers (its tries are on an empty VERIFY) /69 83(blocked),bStatus = 0,bError = 0(the command succeeded; the card said wrong). - user cancel →
bStatus = 0x40(failed),bError = 0xEF→SCARD_W_CANCELLED_BY_USER. - initial approval declined or timed out →
bStatus = 0x40,bError = 0xEF. - pad timeout →
bStatus = 0x40,bError = 0xF0→SCARD_E_TIMEOUT. - unsupported pinpad request or no eligible applet selected →
bStatus = 0x40,bError = 0x00.
The transport sends CCID time extensions while the device waits on the screen.
The device ignores the host’s PIN format and offset bits when assembling VERIFY.
With GnuPG’s internal CCID driver, run
gpg-connect-agent "scd checkpin OPENPGP.1" /bye.
The parser and VERIFY assembly are in crates/rsk-usb/src/secure_pin.rs.
2. Status words & error codes
2.1 CCID status words (ISO-7816 SW1 SW2)
Source: crates/rsk-sdk/src/sw.rs.
| SW | Name | Meaning |
|---|---|---|
9000 | OK | success |
63C0 | — | WRITE CONFIG (§6) with a configuration lock code that is not the one set, as a YubiKey 5.8.0 answers it |
6400 | EXEC_ERROR | execution error (internal) |
6285 | TERMINATED | OpenPGP after TERMINATE DF: every command, SELECT included, until ACTIVATE FILE (§5.1) |
6581 | MEMORY_FAILURE | a storage failure, including Rescue READ phy or a DeviceInfo merge. Storage recovery also uses this status for unavailable Rescue operations (§7). OpenPGP uses it for undecipherable RSA ciphertext, an unusable ECDH peer point, oversized RSA signing input, reading an empty key slot, or importing correctly sized RSA primes that fail key construction |
6700 | WRONG_LENGTH | bad Lc/Le for this command |
6883 | LAST_CHAIN_EXPECTED | an APDU arrived that neither continues nor closes the open command chain |
6982 | SECURITY_STATUS_NOT_SATISFIED | auth/precondition missing |
6983 | PIN_BLOCKED | PIN verification is blocked |
6984 | DATA_INVALID | malformed payload (e.g. bad guard magic) |
6985 | CONDITIONS_NOT_SATISFIED | state precondition unmet (e.g. RTC unset); a WRITE CONFIG setting a configuration lock where none is set without its touch (§6.2); OpenPGP PSO:CDS, the RSA and ECDH arms of PSO:DECIPHER and INTERNAL AUTHENTICATE with no key in the slot, and ATTEST of an empty slot or an imported key, as a YubiKey 5.8.0 answers them |
6986 | COMMAND_NOT_ALLOWED | WRITE CONFIG (§6) with no lock code while a configuration lock is set, as a YubiKey 5.8.0 answers it; a phy (§7) or LED (§8) write while one is set |
6A80 | WRONG_DATA | bad data field; PIV MOVE KEY onto a slot that holds a key or takes none, or onto itself; PIV PUT DATA with a P1-P2 other than 3FFF; OpenPGP GENERATE and IMPORT with a control-reference template they cannot read or whose key reference 84 01 xx names another slot, and GENERATE P1 = 80 and IMPORT under Yubico’s attestation-key template B6 { 84 01 81 }; OpenPGP ATTEST with a P1-P2 or a body it does not take; OpenPGP SELECT DATA with any body but 60 04 5C 02 7F 21 |
6A82 | FILE_NOT_FOUND | the requested AID or file is unavailable |
6A84 | FILE_FULL | the applet’s storage limit is exhausted |
6A86 | INCORRECT_P1P2 | unsupported P1/P2 |
6A88 | REFERENCE_NOT_FOUND | the object, key or PIN the request names is absent (PIV GET METADATA, MOVE KEY, the PIN commands’ key reference) |
6B00 | WRONG_P1P2 | P1/P2 outside what this command takes — including a DO that P1P2 addresses and the command does not serve (OpenPGP GET DATA, PUT DATA), and an OpenPGP SELECT DATA occurrence past the third or P2 other than 04, judged before its body |
6D00 | INS_NOT_SUPPORTED | unknown INS for this applet; OpenPGP and PIV answer it to any SELECT but the one by AID, as a YubiKey 5.8.0 does |
6E00 | CLA_NOT_SUPPORTED | wrong CLA for this applet (OpenPGP ATTEST takes class 80 only) |
2.2 CTAP2 errors
Standard CTAP2 status bytes (0x00 = success), returned by CTAP2 and by the
0x41 vendor command. Source: crates/rsk-fido/src/error.rs. The ones the vendor
surface returns:
| Byte | Name | Meaning here |
|---|---|---|
0x00 | OK | success |
0x02 | INVALID_PARAMETER | invalid field or public key, unknown vendor subcommand, or invalid encrypted key for UNLOCK/ATT_IMPORT |
0x03 | INVALID_LENGTH | a request exceeds a command’s input limit (for example, the DeviceInfo config blob) |
0x12 | INVALID_CBOR | the body is not exactly one CBOR item (trailing bytes) |
0x14 | MISSING_PARAMETER | required field absent (e.g. blob/pinUvAuthParam) |
0x27 | OPERATION_DENIED | presence declined or timed out, wrong config lock code on a DeviceInfo write, or CBOR disabled by USB_ENABLED |
0x2D | KEEPALIVE_CANCEL | the host cancelled the active CTAPHID CBOR request |
0x2F | USER_ACTION_TIMEOUT | on-device PIN entry timed out, or a CCID FIDO poll/cancel found no pending operation |
0x30 | NOT_ALLOWED | precondition unmet (a CONFIG_WRITE of EF_DEV_CONF with no lock code, or of the phy or LED record, while a lock is set (§6.2), no MSE channel, one already spent or owned by another CTAPHID channel, an MSE while one is live (§9.1), sealed, soft-locked, or an authenticatorReset outside the §5.1 power-up window) |
0x31 / 0x32 | PIN_INVALID / PIN_BLOCKED | wrong PIN or exhausted retries |
0x33 | PIN_AUTH_INVALID | pinUvAuthParam MAC or acfg permission wrong |
0x36 | PUAT_REQUIRED | the request requires a PIN token or on-device PIN entry (§9.2) |
0x39 | REQUEST_TOO_LARGE | subCommandParams over the limit |
0x3D | INTEGRITY_FAILURE | blob failed authenticated decryption |
0x3E | INVALID_SUBCOMMAND | unknown vendorCommandId under authenticatorConfig’s 0xFF. A 0x41 subcommand this build does not implement is 0x02, matching a YubiKey |
0x7F | OTHER | internal failure, for example an unreadable CONFIG_READ record |
3. Device identity & discovery
3.1 USB identity
The build picks a VID/PID preset (firmware/build.rs):
| Preset | VID:PID | Manufacturer / Product strings | Notes |
|---|---|---|---|
RSKey (default) | 1209:F1D2 | RS-Key / RS-Key Security Key | pid.codes allocation |
Yubikey5 (opt-in interop) | 1050:0407 | Yubico / YubiKey RSK OTP+FIDO+CCID | so ykman/Yubico Authenticator derive PID from the PC/SC reader name |
| others | NitroHSM, NitroFIDO2, GnuPG, Pico, Dev | — | local interop only |
The VID/PID, the product string and the manufacturer string can all be overridden
at runtime via the phy record (§7), taking effect at the next boot: VID/PID
(tag 0x00), product (tag 0x09) and manufacturer (tag 0x0F). If a runtime
product looks like a YubiKey (yubikey, any case) but omits the smartcard CCID
token, the firmware appends OTP+FIDO+CCID before enumerating — a token-less
Yubico YubiKey reader name otherwise crashes ykman / Yubico Authenticator on
Windows (_pid_from_name → PID.of → KeyError('YK4_'), which aborts the whole
PC/SC scan). Source: normalize_usb_product in crates/rsk-phy/src/lib.rs.
Each string is resolved in precedence order: an explicit phy tag (0x0F /
0x09) wins; otherwise the effective VID picks a default — a Yubico VID
(0x1050) yields Yubico / YubiKey RSK OTP+FIDO+CCID plus the Yubico OpenPGP AID
vendor, so setting only the Yubico VID/PID makes the whole identity “just work” for
ykman / Yubico Authenticator; otherwise the build const. The OpenPGP AID
vendor id stays keyed on the effective VID (a registered number, not a free
string). ⚠️ so a phy-repointed default key can present a full Yubico identity at
runtime; the USB/smartcard identity is cosmetic and host-configurable, never a
security or anti-counterfeiting control (see docs/threat-model.md).
For PC/SC discovery, rsk looks for RS-Key, RSK or the appended USB
serial (rs-key-0001) in reader names. Linux pcscd may use the driver’s
friendly name in place of the USB product string. Probe the applet you
need on a candidate reader. See RSK_READER_TOKENS in tools/rsk/ccid.py.
3.2 Firmware version & bcdDevice
| Field | Value | Where |
|---|---|---|
| firmwareVersion | 5.8.0 → 0x00050800 | CTAP getInfo 0x0E; Management/OTP DeviceInfo TAG_VERSION; Management SELECT ("Virtual mgr - FW version 5.8.0" ASCII, a YubiKey 5.8.0’s words) |
bcdDevice | Firmware build counter | USB device descriptor (firmware/src/main.rs device_release) |
| AAGUID | 2479c7bf-6b30-5683-9ec8-0e8171a918b7 | CTAP getInfo 0x03; one value across every VID/PID flavor of a build, overridable at build time with AAGUID=<uuid> |
The build accepts FW_VERSION=X, X.Y or X.Y.Z. The default is 5.8.0
for compatibility with Yubico tooling. Read bcdDevice from the USB descriptor
when checking for an RS-Key protocol change.
4. AID registry
SELECT an applet with 00 A4 04 00 Lc <AID> 00.
How an AID is matched (RS-Key 0x088C+): ISO 7816-4 truncated select — the
AID you send must be a prefix of a registered one, and the first applet it
matches wins. So a shortened AID selects (PIV answers to A0 00 00 03 08), an
AID with anything appended does not (earlier builds selected on
registered AID ‖ junk, which let PIV answer to A0 00 00 03 08 00 00 00 00 —
the AID SP 800-85A-4 C.1.1.2 names as invalid), and an empty AID is refused
rather than treated as “select the default application”. Two consequences worth
planning for: OpenPGP is selected by the 6-byte AID below, not by the 16-byte
value it reports in DO 4F (that one carries the device serial and is longer, so
it is not a prefix — a real YubiKey refuses it too); and a prefix short enough to
match several applets resolves in dispatch order among selectable applets
(Vendor, OpenPGP, Management, OATH, OTP, PIV, Rescue, FIDO). Use the full AID
when probing for an applet. OATH and OTP are
registered by their full 8-byte instance AIDs, as a YubiKey registers them:
Yubico’s Android SDK selects by all 8 bytes, while ykman sends the 7-byte prefix,
and both select (0x09D4+; from 0x088C to 0x09D3 only the 7-byte form did).
Where that SELECT works. The recipe above is CCID’s (§1.1), and two of the ten
rows below are not CCID applets: the FIDO2 backup id and the standalone U2F AID
answer 6A82 (FILE_NOT_FOUND) — registered identifiers rather than anything this
build dispatches to. The FIDO2 AID is selectable over CCID and carries CTAP2
and U2F there (§5.3). Over HID, send CTAP2 directly in CTAPHID_CBOR and U2F
in CTAPHID_MSG. Only the Vendor AID can be selected in CTAPHID_MSG.
Use a fresh CTAPHID_INIT before switching that channel back to U2F.
An INIT or a change of CID clears the MSG applet selection.
| Applet | AID | Transport | Spec status | Config-relevant? |
|---|---|---|---|---|
| FIDO2 / U2F | A0 00 00 06 47 2F 00 01 | CCID (§5.3) + CTAPHID (no SELECT) | Standard (CTAP2 + CTAP1) | identity only |
| FIDO2 (backup id) | B0 00 00 06 47 2F 00 01 | none — unregistered | RS-Key | — |
| U2F (standalone id) | A0 00 00 05 27 10 02 | none — unregistered; U2F rides the FIDO2 AID | Standard (CTAP1/U2F) | — |
| Management | A0 00 00 05 27 47 11 17 | CCID | Yubico-compatible | yes — §6 |
| OATH | A0 00 00 05 27 21 01 01 | CCID | Yubico OATH | data only |
| OTP | A0 00 00 05 27 20 01 01 | CCID | Yubico OTP | data only |
| PIV | A0 00 00 03 08 00 00 10 00 01 00 | CCID | NIST SP 800-73 | data only |
| OpenPGP | D2 76 00 01 24 01 | CCID | OpenPGP card 3.x | data only |
| Rescue | A0 58 3F C1 9B 7E 4F 21 | CCID | RS-Key-specific | yes — §7 |
| Vendor / LED | F0 00 00 00 01 | CCID + CTAPHID_MSG | RS-Key-specific | yes — §8 |
Sources: crates/rsk-fido/src/consts.rs,
crates/rsk-mgmt (+ crates/rsk-devconf for the DeviceInfo record),
crates/rsk-oath,
crates/rsk-otp,
crates/rsk-piv,
crates/rsk-openpgp/src/consts.rs,
crates/rsk-rescue,
firmware/src/vendor.rs. Which AID each transport actually offers is not in any
of those: it is the applet list crates/rsk-device/src/ccid.rs builds for CCID
and the one-entry list in crates/rsk-device/src/ctap.rs for CTAPHID_MSG.
5. Standard interfaces (pointers, not re-specified)
For the base command formats, see the CTAP specification, Yubico OATH protocol and PIV card command specification.
Resident FIDO discovery returns at most 16 distinct credentials per getAssertion/getNextAssertion walk, newest first. Equal creation times use descending storage-slot order. With more than 16 visible matches, the queue retains the newest 16; the first reply is the first entry in that same queue.
RS-Key implements:
- FIDO2 / CTAP2 (
versionsadvertisesFIDO_2_0,FIDO_2_1andFIDO_2_3): getInfo, makeCredential, getAssertion, getNextAssertion, clientPIN, reset, selection, credentialManagement, authenticatorConfig, largeBlobs (writable without apinUvAuthParamuntil a PIN is set oralwaysUvis on, per §6.10.2 — a--features largeblob-extbuild serves the CTAP 2.3 §12.4largeBlobextension in its place and answers0x0CwithCTAP1_ERR_INVALID_COMMAND, because §12.4 forbids supporting both; detect it from getInfo, which dropslargeBlobs,maxSerializedLargeBlobArrayand thelargeBlobKeyextension in that build).options.perCredMgmtROis true, so a tool may request thepcmrpermission (0x40, alone) and get the persistent pinUvAuthToken: it drives getCredsMetadata / enumerateRPs / enumerateCredentials, never the two writers, and survives replugs until a PIN change or a reset — a credential list can be refreshed without re-prompting for the PIN. The enumerate walk it opens is not that durable: the cursor behindgetNextRP/getNextCredentialretires after 30 s idle, and after any command that is not one of those two continuations (CTAP 2.3 §6), so draw a list in one uninterrupted pass and restart from the Begin if it stalls. The same 30 s applies between the fragments of alargeBlobsset; there an abandoned transfer answersCTAP2_ERR_INVALID_SEQand the previously stored array is left intact.maxMsgSize=7609. BothtransportsForReset(0x1A) andtransports(0x09) are["usb", "smart-card"]. These lists describe the supported protocol transports (§5.3). Interface configuration and host driver binding determine whether the smart-card interface is reachable.pinComplexityPolicy(0x1B) reports the effective PIN complexity policy.strong-pinandfips-profileenable it by default; other builds start withfalse. An authenticatedsetMinPINLengthrequest can enable it with subCommandParams key4: true. A false or absent key leaves it unchanged; onlyauthenticatorResetrestores the build default. The policy rejects periodic PINs, ascending/descending runs, at most two distinct code points, and the keypad-pattern denylist, on both host and trusted-display PIN changes. UnderforcePINChange, an unread current verifier returnsCTAP2_ERR_OTHER(0x7F) and leaves the change pending; it cannot establish a different PIN. The optionalpinComplexityPolicyURL(0x1C) is never emitted.longTouchForReset(0x18) isfalse: a reset takes the same touch as any other presence check — CTAP 2.3 cut the long-touch hold from 2.2’s 10 s to 5 s, and RS-Key implements neither gesture.encIdentifier(0x19) is present from provisioning — boot,authenticatorResetand a seedBACKUP_LOADmint the persistent pinUvAuthToken it is keyed by; setting or changing the PIN, or forcing a change, revokes that grant until the next boot orpcmrrequest, and a soft-locked key omits it — and carriesiv ‖ AES-128-CBC(k, id)— 32 bytes — whereidis a 128-bit device identifier andk = HKDF-SHA-256(salt = 32 zero bytes, IKM = that token, info = "encIdentifier", L = 16). The IV is regenerated on every getInfo, so the bytes differ each time while the identifier under them does not: a tool holding the token recognises the device across sessions, and one without it learns nothing. The identifier is derived from the device seed, soauthenticatorResetchanges it.encCredStoreState(0x1E) is that same construction under the labelencCredStoreState, over a 128-bit tag that takes a new random value whenever the set of discoverable credentials changes — a create, adeleteCredential, anupdateUserInformation, or a delete driven from the trusted display. Reads never move it. A platform holding the token caches the plaintext and re-enumerates only when it differs; one without the token sees bytes that change every call and learns nothing. The tag is stored, not counted in RAM, so a power cycle does not reset it — and it is written ahead of the change it describes, so what a torn write leaves is a tag that over-reports (one wasted re-enumeration) rather than one that under-reports (a stale cache). A tag the flash cannot serve omits the member rather than publishing the zero one: zero is what a device an older build provisioned carries until its first change, so a platform can be holding it, while an absent member matches no cached tag at all and costs only the walk. A new store starts with a new tag, as unpredictable as its seed — provisioning andauthenticatorResetderive it from the new seed, aBACKUP_LOADdraws one — so a reset changes it even over a store nothing had changed (CTAP 2.3 §6.6). makeCredential acceptsattestationFormatsPreference(request0x0B): a list of exactly["none"]is answered withfmt:"none"and an empty — but present —attStmt, and nothing is signed. Any other list, an empty one, or an absent field leaves the usualpackedstatement, because choosing by lowest supported index needs more than one supported format andattestationFormats(0x16) stays["packed"]. An enterprise attestation that was actually performed outranks the preference and is still returned in full. None is performed over an org key whose stored chain is missing or does not read back whole (RS-Key0x0A6A+): the device’s own certificate attests, withoutep, and the preference holds. Vendor-facilitated (type 1) enterprise attestation reads a stored RP list.enterpriseAttestation: 1returnsepand the org certificate only for an RP on that list; any other RP gets the ordinarypackedstatement with the device’s own certificate and noep. The list holds up to 8sha256(rpId)entries and is empty until written, so a device upgraded from firmware without it behaves exactly as before;authenticatorResetclears it. Write it withauthenticatorConfig(0x0D) subCommandvendorPrototype(0xFF) and subCommandParams{1: 0x0e6841934e719be7, 4: [rpId…]}— the ids as text, hashed on the device — gated by anacfgpinUvAuthToken and no touch, the same authorizationenableEnterpriseAttestationitself takes. An empty array clears the list; more than 8 entries is refused withCTAP2_ERR_KEY_STORE_FULL, never truncated. Type 2 (platform-managed) is unaffected — it applies to any RP once enterprise attestation is enabled. Supported COSE algorithms: ES256-7, ES384-35, ES512-36, ES256K-47, EdDSA-8, ML-DSA-44-48, ML-DSA-65-49, ML-DSA-87-50(all three negotiable viapubKeyCredParams; advertised in getInfo only under theadvertise-pqcbuild, in descending security order). ML-DSA-87’s 2592-byte public key and 4627-byte signature are the widest the device mints, and the org attestation chain cap (ATT_CHAIN_MAX) is derived so the worst-case makeCredential still fits the 7609-bytemaxMsgSize. The curve-explicit ids ESP256-9, Ed25519-19, ESP384-51and ESP512-52are negotiable and unadvertised on the same terms, and the attested key carries the id the request selected rather than the classic spelling of the same curve. (crates/rsk-fido/src/consts.rs.) - CTAP1 / U2F 1.1/1.2.
- PIV: NIST SP 800-73 (Yubico PIV extensions for metadata).
GET DATAanswers6A82to a tag list it cannot read and to a P1-P2 other than3FFF, the answer for an object the card does not hold, as a YubiKey 5.8.0 does. Key replacement and MOVE retire the prior per-slot public-point cache before committing a key; failed cache retirement answers6581. Missing or refused cache refreshes fall back to the current metadata point or that key’s scalar. SELECT compares F9’s stored certificate point and public cache with its sealed P-384 key. It repairs absent, empty, truncated or preceding-key certificates under that key and retires stale caches from older builds. Recreating an absent F9 key removes its preceding certificate before committing the replacement; a failed read, retirement or repair answers6581. An existing F9 key that the current root cannot open, or that names another curve, also makes SELECT answer6581, preserving the key. A later boot retries unfinished root migration. Selection remains current after refusal, so subsequent raw APDUs still reach PIV’s command handlers and their gates.PUT DATAanswers6982without the management key, then6A80to a P1-P2 other than3FFFand to a body that is not5C 03 <id>followed directly by53with its length in the shortest form; bytes after the object are ignored. It stores any5Fxxxxbut5FFF01(the attestation certificate, which no host may write), as a YubiKey does:5FC100–5FC1EFand5FFF00each in its own file, every other id in a pool of 256 objects and 32 KiB of bodies, whose next write answers6A84once either is spent, as a full YubiKey does; an empty53deletes the object, answering9000for one not held. An object is up to 3063 bytes,6700past it, as on a YubiKey 5.8.0: the 3072 bytes a command chain reassembles less the5C 03 id 53 82 LL LLheader. With an extendedLe, a single APDU has room for 3044 object bytes. WithoutLeit has room for 3046.GET DATAfor the CHUID (5FC102) returns a synthesized default (non-federal FASC-N + a device-stable GUID =sha256(serial)[..16]) when the host has not written one, so the Windows minidriver can enumerate the card; a host-written CHUID overrides it. The Card Capability Container (5FC107, mandatory per SP 800-73-4 pt1 §3.1.1) is served on the same terms: with no host-written object the card answers a 9-byte synthesized default (F0 00 F1 00 F2 00 F5 01 10— zero-length mandatory elements plus the PIV data model number0x10) instead of6A82, a hostPUT DATAoverrides it, and an emptyPUT DATAfalls back to the default again. - OATH: Yubico OATH (TOTP/HOTP).
- OTP: Yubico OTP / HOTP keyboard + CCID.
- OpenPGP card 3.x. An unreadable variable GET DATA child or password-status
record makes the complete response fail with
6581and no body. PUT DATA C1/C2/C3 changes a slot’s algorithm attribute; when the value changes, RS-Key invalidates that slot’s existing private/public key pair before the new attribute becomes visible. An idempotent same-value write preserves the pair. RSA attributes carry a 17-bit exponent length, as a YubiKey’s do: DO0xFAlists01 nnnn 0011 00, PUT DATA takes any length from 17 bits and stores 17, and two attributes that differ only there are the same value. Yubico’s attestation is there too: ATTEST (80 FB <key ref> 00, PW1 in mode 81, the touchD9sets; past the touch it spends a one-shot PW1 as PSO:CDS does) writes an X.509 statement for a key the card generated into its7F21occurrence, signed by a P-384 attestation key (reference81) whose self-signed certificate is DOFC. The key reads through GENERATEP1 = 81underB6 { 84 01 81 }and is listed inDE,DA(inside73and inFA),C5/C6/CDandD9, where a YubiKey lists its own; no host can import it, generate it or writeFC. So is Yubico’s SET PIN RETRIES (00 F2 00 00 03 <PW1> <RC> <PW3>, whatykman openpgp access set-retriessends), as a YubiKey 5.8.0 answers it:6982without PW3, then6A80for a body that is not three bytes, P1 and P2 not judged. A byte from 1 to 255 becomes that PIN’s maximum and its tries left, unblocking it with its value kept; 0 leaves the PIN as it is. The resetting code’s maximum is kept while none is set (C4shows00for it), and PUT DATAD3starts a new one there. The PINs and PW3’s status stay, the maxima survive a power cycle, and TERMINATE DF + ACTIVATE FILE put back 3, 3, 3.
The management extensions are in §6 (DeviceInfo), §7 (Rescue), §8 (Vendor/LED)
and §9 (CTAP 0x41).
5.1 Where a standard command answers differently
Places where a host that works against other authenticators sees a status byte it may not expect. All are spec-permitted strictness, not extensions, and each says where it matches the YubiKey this project is measured against.
authenticatorReset has a power-up window. CTAP 2.1 §6.6 lets an
authenticator with no display refuse a reset that does not follow a fresh
power-up. RS-Key does: more than 10 s after the device attached, command
0x07 answers 0x30 CTAP2_ERR_NOT_ALLOWED before the touch prompt, so a host
waiting on a press gets an immediate refusal instead. Four properties a host
implementation has to plan for:
- The origin is the USB attach, not power-on. Boot spends seconds before the bus pull-up goes up (TRNG seeding, seal migrations, the one-shot at-rest hardening lap), and none of it is time a host could have used.
- A warm reset closes the window, it does not reopen one. The vendor REBOOT
(§8
INS 1FP1=0), its rescue twin, and the auto-reboot after a phyCONFIG_WRITEare all host-requestable without a credential, so a window a host can restart at will would be no window at all. Only a real power cycle opens one. - Trusted-display builds are exempt. Their prompt names the operation on screen, which is what the window substitutes for; a reset is accepted at any time there and still needs the on-screen confirmation.
- The touch is unchanged. Inside the window the reset still requires user
presence, and a decline or timeout answers
0x27 OPERATION_DENIED.
Practically: prompt the user to replug, then send the reset. rsk offboard does
exactly that — it sends the reset, and only on 0x30 prints the unplug/replug
prompt and retries in the new window (tools/rsk/offboard.py), so it stays
correct against a display build and against pre-0x0854 firmware, which both
accept the first attempt.
PIV refuses a one-byte command body, whatever the instruction. A PIV APDU
carrying Lc = 1 answers 6A80 before anything else — before the PIN or the
management key, before P1/P2, and before the instruction is looked up, so
even an unimplemented INS answers 6A80 rather than 6D00. No PIV command
takes a one-byte body, and a YubiKey 5.7.4 does the same on every instruction.
The rule is PIV-only: OATH’s LIST takes a legitimate Lc = 1, and
SELECT-by-AID with a one-byte AID prefix is served by the transport before any
applet sees it.
U2F AUTHENTICATE rejects a reserved P1. U2F Raw Message Formats §7.2 assigns
three control bytes; RS-Key accepts exactly those and answers 6A86
(INCORRECT_P1P2) to anything else, before parsing the request body.
| P1 | Name | Behaviour |
|---|---|---|
03 | enforce-user-presence-and-sign | touch required; TUP flag set in the response |
07 | check-only | valid handle → 6985, unknown handle → 6A80; never touches |
08 | don’t-enforce-user-presence-and-sign | signs with no touch, TUP flag clear; rejected with 6A86 under --features strict-up, which promises a touch on every assertion |
U2F over CTAPHID_MSG takes the extended encoding alone. U2F HID v1.2 §2 frames
every raw message in extended-length encoding, and a U2F request over CTAPHID is
read as a YubiKey 5.8.0 reads it: the class first (6E00 past 00), then either
the bare four-byte header or 00 Lc Lc and at least that many data bytes, with
anything after them, an Le included, ignored. A short Lc or Le is 6700
whatever the instruction. Over CCID (§5.3) both encodings stay open, as there.
On either transport a VERSION that carries data is 6700, since U2F Raw Message
Formats §6.1 has it take none; its P1 and P2 are not judged, as on a YubiKey.
OpenPGP GET DATA reads a nested DO only through its template. OpenPGP 3.4
§4.4.1 lists 5B, 5F2D and 5F35 only inside 65, 93 only inside 7A, and
73 — with the C0–C3, C5, C6 and CD it carries — only inside 6E; the
fixed-width C7–D0 are readable only as the slices of C5/C6/CD. Each of
those 21 answers 6B00 to a GET DATA of its own, and PUT DATA still takes the
writable ones. A YubiKey 5.8.0 answers the same, with keys and a name set. The
Gnuk-derived suite in third_party/openpgp-card-tests reads them one by one; a
host written that way has to read the template instead.
GET DATA answers 6581 with no response body if its construction buffer cannot
hold the complete object. A constructed template keeps BER’s shortest length
form; fixed-width fingerprint and timestamp fields still truncate older long
records and pad short records with zeroes.
The 7A security-support template requires its three-byte DS-Counter (93);
an absent, unreadable or wrong-width counter answers 6581 with no body.
OpenPGP TERMINATE DF leaves the applet terminated until ACTIVATE FILE. As on a
YubiKey 5.8.0, TERMINATE DF (00 E6 00 00, PW3 verified or blocked, 6982
otherwise) wipes the applet and then every command answers 6285, SELECT
included, until ACTIVATE FILE (00 44 00 00) answers 9000 and leaves the factory
state: C4 = 01 7F 7F 7F 03 00 03, PW1 123456, PW3 12345678. The state
survives a reset and a power cycle; a PW1 or PW3 verified before TERMINATE is still
verified after ACTIVATE, now against the factory password. ACTIVATE FILE on an
applet that is not terminated answers 9000 and changes nothing. RS-Key 0x0A83+;
an older build answered TERMINATE with the factory state at once, and a host that
sends ACTIVATE right after it, as ykman and gpg-card do, works with both.
5.2 FIDO extension outputs and PIN policy
The uvm extension accepts a boolean on makeCredential and getAssertion.
When requested with true, signed authData reports the ceremony factors as
[method, keyProtection, matcherProtection] entries: presence (0x0001),
external PIN (0x0800), device-local PIN (0x0004), or no interaction (0x0200).
Key and matcher protection are 0x0002 (hardware) and 0x0004 (on-chip).
getNextAssertion carries the originating ceremony’s methods. A false input
produces no output.
The pinComplexityPolicy extension takes a boolean on makeCredential and returns
the effective policy only to an RP on the minPinLengthRPIDs list; unlisted RPs
receive no output. It has no getAssertion output. Both extensions reject an
input of the wrong type. An omitted or empty minPinLengthRPIDs config parameter
preserves the existing list; a non-empty list replaces it.
The persisted EF_MINPINLEN layout remains [minimum: u8, flags: u8, rpIdHash…].
Flag bit 0 means forceChangePin; bit 1 enables complexity. Older records with
flags 0 or 1 load unchanged, and clearing forceChangePin preserves bit 1 and
all RP hashes. Older firmware interprets any nonzero flags byte as a pending
PIN change, so downgrading a key with complexity enabled keeps authentication
blocked until reset. The upgrade itself requires no migration or reset.
5.3 CTAP over CCID
The FIDO applet answers on the CCID interface as well as on CTAPHID, as ISO 7816
APDUs — the encoding CTAP 2.1 §11.2.1 defines for ISO7816 readers, which
python-fido2’s CtapPcscDevice (and therefore ykman over PC/SC) speaks
unchanged. PC/SC does not distinguish an NFC reader from the device’s own CCID
interface, so this is reachable over plain USB.
| Step | APDU | Answer |
|---|---|---|
| Select | 00 A4 04 00 08 A0000006472F0001 00 | 9000 with body U2F_V2, or FIDO_2_0 while alwaysUv has U2F off (below) |
| CTAP2 | 80 10 00 00 Lc <cmd ‖ CBOR> 00 | 9000 (or 61xx, below) with <status ‖ CBOR> |
| U2F | 00 01/02/03 … | the CTAP1 answer; 6E00 under class 80; 6986 while alwaysUv has U2F off |
| Poll, cancel | 80 11 00 00, 80 11 11 00 | 9000 with body 2F, whatever the P1-P2. Use CCID ABORT to cancel in-flight work |
| Control | 80 12 01 00 | 9000, then 6986 to every command until the next Select; any other P1-P2 6A86 |
The three CTAP2 instructions (10, 11, 12) are taken under class 00 as
under 80, as on a YubiKey 5.8.0. Anything else under 80 is 6D00, under 00
it is U2F’s, under 04 and 84 it is refused 6E00, and no other class reaches
it (above).
alwaysUv switches U2F off on both transports (CTAP 2.1 §7.2.4) unless a built-in
UV method is configured, the display build’s pad with a PIN: REGISTER, AUTHENTICATE and
VERSION answer 6986 over CCID and CTAPHID alike, getInfo drops U2F_V2, and the
Select above answers FIDO_2_0, the version string CTAP 2.3 §11.3.3 gives an
authenticator with CTAP2 alone. A YubiKey 5.8.0 answers each of these the same.
Control’s END ends the FIDO session on this interface (CTAP 2.3 §11.3.4).
CTAP2 and U2F alike answer 6986 until the next Select, by the AID or a prefix of
it. A chain’s segments are still acknowledged, and CTAPHID is not affected. A
YubiKey 5.8.0 answers each of these the same.
Chaining runs in both directions. Send a CTAP2 command longer than 255 bytes
in an extended APDU or in CLA|0x10 segments. A response longer than the short
Le ships its first chunk with 61xx and the rest through GET RESPONSE
(00 C0 00 00 <Le>). A bare getInfo is already ~520 bytes, so a client that does
not follow 61xx sees nothing useful. An extended-length APDU with no Le, or
Le 0000, gets up to 3060 bytes in one exchange, and a longer response chains
from there.
No 91 00 keep-alive is ever returned. A touch wait blocks inside the
exchange while the CCID transport streams T=1 time extensions, exactly as an OATH
touch-flagged CALCULATE and an OpenPGP UIF signature already do, so the
NFCCTAP_GETRESPONSE poll loop never runs. The poll and cancel APDUs both
return 2F 90 00. To abort the in-flight CCID exchange, use the two-phase
CCID ABORT (§1.1).
The transport is smaller than CTAPHID. A command chain reassembles 3072 bytes
and a response is built in as many, so that is the ceiling on a command and on a
response here, against the 7609 that getInfo’s maxMsgSize reports for CTAPHID.
Commands stay well inside it; a response that does not fit comes back as a CTAP
error rather than truncated. An ML-DSA credential’s attestation does not fit and
is CTAPHID-only in practice.
CCID and HID share FIDO state, but CCID uses reserved CID 00000000.
Keep CID-bound operations such as MSE and its consumer on the same transport.
Both applications are gated separately. One AID serves CTAP2 and U2F, and
ykman config usb --disable fido2 / --disable u2f name them apart, so the
commands are gated rather than the SELECT: disabling one leaves the AID
selectable for the other and answers the disabled half 6986 — for CTAP2 its MSG,
since a poll or a control carries nothing to gate. With neither
enabled the AID is gone (6A82).
Some CCID drivers bind only to recognized VID/PID pairs. If such a driver
omits the default 1209:F1D2, use the repository’s ccid-rs-key overlay or a
VIDPID=Yubikey5 build.
6. Management applet (Yubico-compatible) — applet enable/disable
AID A0 00 00 05 27 47 11 17. CLA 00 or 80. This is what ykman / Yubico
Authenticator SELECT first to identify the key and to read/write which
applications are enabled. Source: crates/rsk-mgmt/src/lib.rs for the command
surface, crates/rsk-devconf/src/lib.rs for the EF_DEV_CONF record it reads
and writes.
SELECT returns the firmware version in a YubiKey 5.8.0’s ASCII words,
"Virtual mgr - FW version 5.8.0"; take the version from its last word.
| INS | Name | Request | Response |
|---|---|---|---|
1D | READ CONFIG | — | DeviceInfo TLV (see below) |
1C | WRITE CONFIG | data[0] = inner length n, then n bytes of enabled-apps TLV (n ≤ 128) | — (gated by the configuration lock once a code is set, §6.2; presence-gated as well under strict-config) |
1E | — | anything | 9000 with no body, and nothing is done — as a YubiKey 5.8.0 answers it |
6.1 DeviceInfo TLV (READ CONFIG 0x1D)
Response = one leading overall-length byte, then concatenated TAG LEN VALUE:
| Tag | Name | Len | Value |
|---|---|---|---|
01 | USB_SUPPORTED | 2 | capability bitmask (BE16) of applications the firmware implements |
02 | SERIAL | 4 | 8-digit serial (chip-id[0..4], MSB masked & 0x03) |
04 | FORM_FACTOR | 1 | 01 = USB-A keychain |
05 | VERSION | 3 | major, minor, patch (default 05 08 00) |
03 | USB_ENABLED | 2 | currently-enabled capability bitmask (BE16) |
08 | DEVICE_FLAGS | 1 | 80 = touch-eject, 40 = remote wakeup; 00 unless a host set them |
0A | CONFIG_LOCK | 1 | 00 = unlocked, 01 = a lock code is set (§6.2) |
Native FIDO HID READ CONFIG uses command 0x42 (wire byte 0xC2) with
an empty request. Its reply is the same length-prefixed DeviceInfo blob,
without a CTAP status byte. Native WRITE CONFIG uses 0x43 (wire byte
0xC3) with the same length-prefixed body as the write APDU. Success is an
empty reply. A refused or unsupported write returns CTAPHID_ERROR with
ERR_INVALID_CMD. The native write is unavailable under strict-config.
Neither native command uses the CTAP CBOR vendor envelope (§9).
The corresponding OTP feature-report slots are READ CONFIG 0x13 and
SET_DEVICE_INFO 0x15.
When no host config has been written, the device returns the defaults:
USB_ENABLED = all-supported, DEVICE_FLAGS = 00, CONFIG_LOCK = 00. Once
WRITE CONFIG has stored a blob, READ CONFIG echoes that blob after the fixed
USB_SUPPORTED/SERIAL/FORM_FACTOR/VERSION prefix, adds DEVICE_FLAGS = 00 after
it when the blob carries none (a YubiKey 5.8.0 reports the tag in every
DeviceInfo; the stored blob itself is not changed), then always appends
CONFIG_LOCK.
A stored blob is echoed only if it still satisfies the WRITE CONFIG rules —
each tag at most once, USB_ENABLED exactly two bytes. One that does not (a record
an older, laxer build accepted) is not echoed verbatim; the response instead
carries a synthesised USB_ENABLED equal to the mask the device actually enforces.
So READ CONFIG is always parseable and never contradicts enforcement, whatever is
in flash (audit run-34 #25). The config-lock tags (0A set-code, 0B unlock) are
write-only: a code is never stored in EF_DEV_CONF or echoed (audit run-30),
and 0A on read is the 1-byte lock state (§6.2). A code a build before 0.4.5
stored in the record is dropped at boot and never honoured as a lock.
6.2 Configuration lock
ykman config set-lock-code locks the configuration as it does a YubiKey 5.8.0.
While a code is set, every write of EF_DEV_CONF — CCID WRITE CONFIG, OTP-HID
SET_DEVICE_INFO 0x15, CTAPHID 0x43 and the FIDO vendor CONFIG_WRITE target
0 (§9) — lands only if it carries that code in 0B (UNLOCK). Without one it is
refused (6986; 0x30 over CONFIG_WRITE), with another code likewise (63C0;
0x27), and nothing is stored either way, even for a write that would change
nothing. OTP-HID refuses by leaving the program-sequence byte where it was, and
CTAPHID 0x43 answers CTAPHID_ERROR. There is no retry counter, as there is
none on a YubiKey.
- Set:
0Awith a 16-byte code, on an unlocked device or with the current code in0B. Clear:0Aof 16 zero bytes, with the current code (ykman’s--clear). A code of any other width, in either tag, is refused as malformed (6A80;0x02overCONFIG_WRITE). - Who can set one: a host that can reach one of the four writers, on a device
with no code yet, and only with a touch of the key, which a YubiKey does not ask
for: a code its owner does not hold would keep every config change behind a
factory wipe (threat-model.md §1). Declined or timed out, the
write is refused whole (
6985,0x27overCONFIG_WRITE, or the native HID refusal described above). Changing or clearing a code still requires the current code. It needs no extra confirmation beyond the write’s usual gate. - At rest:
EF_DEV_LOCK(0x1124) holds01 ‖ SHA-256("RS-Key/CONFIG-LOCK" ‖ serial ‖ code), the serial being DeviceInfo’s four bytes; absent is unlocked. A record in any other form reads locked and opens for no code. - Scope: it survives
authenticatorReset, likeEF_DEV_CONF. The display build’s factory reset or anrsk-wipeerase clears it, which is how a lost code is recovered. It gates the RS-Key phy and LED records (§7, §8) as well, which have no YubiKey counterpart, and no code opens them: while a code is set, every host write of either (rescue1C/01, vendor SET LED10,CONFIG_WRITEtargets1and2over either transport, theauthenticatorConfigphy ids) is refused as a DeviceInfo write without its code is (6986;0x30over CTAP), a replay included, and changes nothing. Clear the lock to change them. The trusted display’s own settings (the touch timeout, for one) are not a host write and stay open.
Capability bits (USB_SUPPORTED / USB_ENABLED):
| Bit | Application |
|---|---|
0x0001 | OTP |
0x0002 | U2F |
0x0008 | OpenPGP |
0x0010 | PIV |
0x0020 | OATH |
0x0200 | FIDO2 |
USB_SUPPORTED is fixed at 0x023B (all six). To enable/disable applications,
WRITE CONFIG a TAG_USB_ENABLED(03) TLV with the desired mask, e.g. enable only
FIDO2+U2F → inner blob 03 02 02 02, full APDU
00 1C 00 00 05 04 03 02 02 02.
USB_ENABLED is enforced, not merely reported: a cleared bit makes that
application’s applet stop answering. PIV/OpenPGP/OATH/OTP return 6A82 on
CCID SELECT. Disabling FIDO2 makes CTAPHID_CBOR return 27, including
authenticatorVendor. Disabling U2F makes CTAPHID_MSG return 6985,
including attempts to select the Vendor AID. The OTP keyboard stops typing OTPs.
The change takes effect on the next command. Bits outside USB_SUPPORTED
are ignored.
To re-enable an application, use CCID Management. On a default build, you can
also use a native DeviceInfo write on an available HID interface. The
configuration lock still applies. On a strict-config build with CCID omitted,
keep the FIDO2 capability enabled so the CTAP config path stays reachable.
Restoring an omitted USB interface requires a PHY update and reboot (§7.1).
WRITE CONFIG validates the inner blob (
6A80otherwise): it must be well-formed TLV, carry only tags a host may write (03,06,07,08,0A,0B,0C,0E,17— ykman’sDeviceConfigset), and fit the smallest transport’s response buffer. The device-owned identity tags (01supported,02serial,04form factor,05version) are emitted by the card and refused on write: READ CONFIG echoes the stored blob after them, and host parsers take the last occurrence, so a stored duplicate would override the real identity and a malformed one would make the whole DeviceInfo unparseable — permanently, since this record survivesauthenticatorReset. On the default build the write is ungated until a lock code is set (§6.2) — full ykman parity: any USB host can rewrite the reported config, matching a stock YubiKey with no config-lock code. Building--features strict-configrestores an on-device user-presence confirmation (Approve on the trusted-display build, a BOOTSEL press otherwise), so a hostile host cannot rewrite it unattended (declined/timed-out →6985). Either way the identity is cosmetic, never an authenticity signal (see docs/threat-model.md §1/§3).There is no device-wide reset here.
1F, ykman’sdevice_reset(sent only when DeviceInfo reports a blocked reset or a Bio with PIV), is6D00, as on a YubiKey 5.8.0;1Eis acknowledged and does nothing. Both were a presence-gated factory reset before 0x0A01, and the rescue and vendor applets’ own1E/1F, sent while Management was selected, reached it. The trusted display’s menu keeps a factory reset, and each applet its own. A host written for pico-fido, whose Management1Eresets FIDO, gets9000here with nothing erased: reset FIDO with CTAPauthenticatorResetinstead.
7. Rescue applet (RS-Key configuration conduit)
AID A0 58 3F C1 9B 7E 4F 21. CLA 80 for every INS below (SELECT itself is
the standard 00 A4 …). This applet carries the phy device-config record
(USB identity + LED hardware), RTC, flash/secure-boot status, the device
attestation key, and the one-way OTP fuses. Source:
crates/rsk-rescue/src/lib.rs.
SELECT response (identity): MCU(1) | PRODUCT(1) | SDK_MAJOR(1) | SDK_MINOR(1) | serial(8)
= 01 02 08 06 <8-byte chip serial>. (MCU 1 = RP2350, PRODUCT 2 = FIDO,
SDK 8.6 is the applet SDK version, distinct from the 5.8.0 firmware version.)
Use this to identify a Rescue applet. A successful SELECT does not imply that
every selector is supported. Probe read-only selectors individually.
| INS | P1 | P2 | Request data | Response | Purpose |
|---|---|---|---|---|---|
10 | 01 | 00 | 32-byte SHA-256 digest | 64-byte secp256k1 signature | KEYDEV: sign a digest with the device attestation key |
10 | 02 | 00 | — | 65-byte uncompressed pubkey (04 ‖ X ‖ Y) | KEYDEV: read the device attestation pubkey |
10 | 03 | 00 | X.509 DER cert | — | KEYDEV: store the device end-entity cert |
1C | 01 | 00 | phy TLV blob (§7.1) | — | WRITE phy record. 6986 while a configuration lock is set (§6.2), before asking for presence. 6400 if the merge or write fails |
1C | 02 | 01 | YYYY(BE2) Mon Day Wday Hour Min Sec (8 B) | — | SET RTC (civil). January is month 0. Wday is ignored |
1C | 02 | 02 | epoch seconds (BE4) | — | SET RTC (Unix) |
1E | 01 | 00 | — | phy TLV blob (§7.1) | READ phy record; 6581 if the record cannot be read (never the never-written default — the host RMWs on this answer) |
1E | 02 | 00 | — | free ‖ used ‖ kv_total ‖ nfiles ‖ flash_size (5×BE4 = 20 B) | READ flash usage |
1E | 03 | 00 | — | enabled(1) ‖ locked(1) ‖ bootkey_slot(1) (FF = none) | READ secure-boot status; locked requires one trusted key, all other slots revoked, both debug disables, complete hardening and page-1/2 BL/NS lock copies |
1E | 04 | 01 | — | YYYY(BE2) Mon Day Wday Hour Min Sec (8 B) | READ RTC (civil). January is month 0, Sunday is weekday 0. 6985 if unset |
1E | 04 | 02 | — | epoch seconds (BE4) | READ RTC (Unix); 6985 if unset |
1E | 06 | 00 | — | required(1) ‖ version(1) ‖ capacity(1) | READ anti-rollback state |
1E | 07 | 00 | — | left(2) BE16 | This boot’s outstanding seal work. Bits 0001 FIDO seed/attestation key/grant, 0002 device key, 0004 PIV, 0008 OATH (including legacy OTP PIN), 0010 OTP, 0020 storage authority. FFFF means no fused key was provisioned. FFFE means the fused key was unreadable and the seal pass did not run |
1E | 09 | 00 | — | version(1) ‖ status(1) ‖ left(2) BE16 | Read-only automatic page-58 seal result; version 01, status values below |
1B | 58 | 00 | "LOCK58" | — | ⚠️ IRREVERSIBLE legacy service command — attempt 3D3D3D into page-58 lock row 0xFF5, over a blank row or a subset of the latch. ROM refuses completion once the Secure read-only majority is set (6400). 9000 with nothing burnt when the full latch is there; 6985 over foreign bits, unfinished migration (1E/07 != 0000), or declined presence. From the next boot on no device-sealed record opens under the pre-burn key or in the clear |
1B | 48 | 00 | "ROLLBK" | — | ⚠️ IRREVERSIBLE — set ROLLBACK_REQUIRED fuse (user-presence-gated) |
1F | 00 | 00 | — | — | REBOOT (warm; device drops off bus) |
1F | 01 | 00 | — | — | REBOOT to BOOTSEL bootloader |
1E | 08 | 00 | — | format(1) ‖ ready(1) | Storage state: 02 01 means active v2 authority; 02 00 means recovery required |
20 | 00 | 00 | "INITV2" | — | Initialize wholly erased storage; physical confirmation required, occupied/active media refused; success queues a warm restart |
20 | 01 | 00 | "IMPORTV2" | — | Explicitly trust and import readable legacy records; physical confirmation required; success queues a warm restart |
For 1E/06, version is the fused minimum epoch. capacity counts
the 48 OTP rollback bits. The highest epoch accepted by the signing workflow
is 47. The ROM can set ROLLBACK_REQUIRED when installing a versioned
signed image. Rescue 1B/48 only sets that flag and checks that Secure Boot
is enabled. It does not inspect the running image’s rollback metadata.
An already-set flag returns 9000 without another burn or touch. Follow the
production sequence for image signing and provisioning.
Storage recovery mode exposes CCID with the Rescue AID only. It permits READ
selectors 03, 04, 06, 07, 08, 09, reboot and storage setup.
Normal boot automatically initializes wholly blank
media or migrates readable legacy storage; neither setup command nor physical
confirmation is required for a firmware upgrade. Other rescue
operations answer 6581; other applets cannot be selected. Normal FIDO/U2F,
OTP and management dispatch stay closed. Setup returns 6985 for declined
confirmation or incompatible state, 6581 for a storage failure, 6A86 for
invalid selectors and 6A80 for a wrong magic payload. READ 1E/07 includes
bit 0020 while storage authority remains under the pre-OTP root. Storage
setup performs no OTP operation.
The firmware automatically completes page-58 sealing at boot, including devices
previously fused without locking. Secure code validates keys/chaff, waits for
left=0000 and performs a fresh successful flash scrub. It first completes and
reads back every 0x3C3C3C access-lock bit, preserving any existing latch bits,
then burns 0x3D3D3D. This ordering keeps the first step resumable and prevents
a torn latch from stranding an unfinished BOOTSEL/Non-secure access lock.
A newly closed latch causes a scrubbed restart before command dispatch; TrustZone
has not started Non-secure code yet. No APDU or physical touch is required for
this boot step. Explicit 1B/58 keeps its existing presence and migration guards
for compatibility; READ 1E/09 performs no writes and needs no presence.
1E/09 status: 00 unchecked, 01 unprovisioned, 02 sealed,
03 migration pending, 04 scrub incomplete, 05 incomplete/invalid provisioning,
06 OTP read failure, 07 foreign lock bits, 08 lock write/readback failure,
09 fake-key firmware (real sealing disabled), 0A majority already seals access
but the raw latch has incomplete redundancy. For 0A, ROM refuses further
writes because Secure is already read-only; boot keeps the migration arms closed
and does not retry the burn. 0B means Secure writes closed before the access
lock was complete: ROM cannot repair it, root reads and migration are blocked,
and storage stays in recovery. left has the 1E/07 meaning.
Status is this boot’s result: after a required PIN use, restart to retry migration
and sealing. Only 02 confirms a complete latch; unknown versions/statuses must
not be interpreted as sealed.
Build 0x0BA8 extends v2 with private, owner-bound PIN/HOTP counter records;
APDUs and the 02 01 state response are unchanged. Migration occurs on the
first counter update. Earlier builds report recovery and refuse normal applets
on this store. Reinstalling a compatible build resumes it; storage initialization
is not an upgrade or downgrade procedure.
Every P1 this applet implements is in that table. A P1 outside it answers
6A86 (RS-Key 0x088E+; earlier builds answered 9000 to an unimplemented
1C selector without writing anything, so a newer client could not tell a
too-old firmware from a completed write). Use that, and the SELECT handshake
above, to detect a firmware that predates a selector you send.
⚠️ Irreversible operations — handle with explicit confirmation
1B/58("LOCK58") permanently locks OTP page-58;1B/48("ROLLBK") permanently sets the anti-rollback-required fuse. Both are one-way fuse burns that cannot be undone and can brick a device if misapplied. The firmware triple-guards each (exact P1, exact magic payload, and a provisioning precondition; for1B/58also a boot that left nothing under the pre-burn key, as1E/07reports), both are idempotent, and the firmware now also requires an on-device user-presence confirmation before the burn (the magic payload is a source-visible constant, not authentication). A config tool must still put these behind an explicit, clearly-worded user confirmation: never a default action, never a bulk “apply”. Most management tools should not expose them at all.1F/01(BOOTSEL) drops the device into the bootloader for reflashing; also confirm.
In BOOTSEL, the KV store is fenced off
Since
bcdDevice 0x0871the image carries an RP2350 partition table: the bootloader is denied read and write over the KV store, sopicotool save,loadanderaseacross that range answerpermission failure. A tool that offers “back up / restore the device’s flash” must expect that and must not present the failure as a device fault. Whole-image flashing is unaffected — the firmware partition stays bootloader-writable. Rationale, and why this is not a substitute for secure boot: threat-model.md.
User-presence gate (runtime)
The runtime-reachable privileged commands require an on-device user-presence confirmation (a button touch, or an Approve on the trusted-display build) before the firmware acts, and return
6985(CONDITIONS_NOT_SATISFIED) if the operator declines or the wait times out. This gates10/01(attestation sign),10/03(store cert),1C/01(WRITE phy record), the irreversible OTP fuse burns1B/58and1B/48, and1F/01(reboot to BOOTSEL) against a hostile USB host. Read-only status (1E/*), the pubkey read (10/02), SET RTC (1C/02) and a warm reboot (1F/00) stay ungated.The Management applet’s WRITE CONFIG (
§6, INS1C) is gated the same way only understrict-config; the default build ungates it (§6). The rescue phy WRITE (1C/01), OTP-fuse burns and BOOTSEL reboot above stay gated in both builds — they are not part of the ykman admin-write flip.The vendor applet (§8) exposes the same reboot verb, reachable over both the CCID and CTAPHID transports; its
1F/01(BOOTSEL) is gated identically, so the gate cannot be bypassed via the vendor AID. Its warm reboot (1F/00) is ungated. Its test-counter write (01) is gated in every build — see §8.
7.1 The phy record (EF_PHY) — PicoForge-compatible
The phy record is the device-config TLV blob. It is the same format PicoForge
already writes, so an existing PicoForge config path largely works
as-is. Source: crates/rsk-phy/src/lib.rs.
Wire format: a flat sequence of TAG(1) LEN(1) VALUE(LEN) records, any order, all
optional. An unknown tag is skipped; a record whose length runs past the buffer
ends the parse. The firmware applies the record at boot (USB identity + LED
hardware).
A write (Rescue 1C/01, or CTAP vendor CONFIG_WRITE 0x0C target 1, §9) is a
read-modify-write merge: only the tags the blob carries are updated; every
untouched tag keeps its stored value. So a host may send just the fields it
changed without wiping the rest. The meaning of zero depends on the tag. To
clear either USB string, send a length of 01 with one NUL byte as the value.
A zero-length string TLV is ignored.
| Tag | Name | Len | Value |
|---|---|---|---|
00 | VIDPID | 4 | VID(BE2) ‖ PID(BE2) |
04 | LED_GPIO | 1 | data-pin GPIO 0..=29 |
05 | LED_BRIGHTNESS | 1 | global channel max 0..=255 |
06 | OPTS | 2 | flags (BE16): WCID 0x1, DIMM 0x2, DISABLE_POWER_RESET 0x4, LED_STEADY 0x8 |
08 | PRESENCE_TIMEOUT | 1 | touch-wait timeout in seconds, bounding the whole ceremony on a button build — the press wait and the release debounce that follows a confirm share it; a trusted-display ceremony may add up to 3 s absorbing a resting finger (0/absent ⇒ firmware default 30 s; a non-zero value below 10 is raised to 10). Matches PicoForge PresenceTimeout. |
09 | USB_PRODUCT | 1..33 | up to 32 string bytes. A NUL ends the string and counts toward the TLV length. A 33-byte value with no NUL leaves the stored string unchanged. 09 01 00 clears the override |
0A | ENABLED_CURVES | 4 | FIDO curve bitmask (BE32) |
0B | ENABLED_USB_ITF | 1 | interface mask: CCID 0x1, WCID 0x2, HID 0x4, KB 0x8, LWIP 0x10 |
0C | LED_DRIVER | 1 | 1 = gpio, 2 = pimoroni, 3 = ws2812 (follows PicoForge LedDriverType) |
0D | LED_ORDER | 1 | WS2812 wire order: 0 = rgb, 1 = grb |
0E | LED_NUM | 1 | RS-Key extension — addressable LEDs actually connected (1..=255; 0/absent = the build’s MAX_LEDS). Firmware saturates a value above its compiled MAX_LEDS ceiling. |
0F | USB_MANUFACTURER | 1..33 | iManufacturer string with the same encoding as USB_PRODUCT. 0F 01 00 clears the override and restores the default described in §3.1 |
Notes for a host implementation:
- Read-modify-write. READ the record, change only your tags, WRITE it back.
This is exactly what
rsk hwdoes (tools/rsk/hw.py). Preserving tags you don’t recognize costs you nothing, but note the device does not:merge_saveoverlays your blob onto the parsed record and re-serializes only the tags this firmware knows, so a tag it does not recognize is dropped at the first write whatever the host sends. - PicoForge recognizes
ENABLED_USB_ITF,LED_ORDER,LED_NUMandUSB_MANUFACTURERin its RS-Key config path. PRESENCE_TIMEOUThas a floor. The record is host-writable and the touch wait reads it live, so a one-second window could expire in the middle of a press and let the next queued request inherit that same hold. The firmware raises any non-zero value below 10 seconds. The floor is applied at boot, on the way to the wait. The stored record keeps the value as written, so a read-modify-write round-trip is lossless;CONFIG_READ’s effective map (§9) reports the floored value, because that is the window the device actually waits.ENABLED_USB_ITFdefaults to all interfaces. The firmware instantiates CCID, FIDO HID and keyboard HID. WCID and LWIP have reserved mask bits. A mask without either CCID or FIDO HID falls back to the default at boot, including a keyboard-only mask. An unreadable PHY record gives CCID and FIDO HID only, unless storage recovery restricts the device to CCID.- A never-written record reads back as the single zero-OPTS TLV
06 02 00 00.
8. Vendor / LED applet — per-status LED color & effects
AID F0 00 00 00 01. CLA 00. Live LED customization (color/brightness/effect
per device status), persisted in flash and applied immediately. Source:
crates/rsk-vendor/src/lib.rs,
firmware/src/led.rs. Reference client:
tools/rsk/led.py.
| INS | P1 | P2 | Request | Response | Purpose |
|---|---|---|---|---|---|
01 | — | — | — | counter (BE4) | INCREMENT test counter, return new value. User-presence-gated (6985 if declined) |
02 | — | — | — | counter (BE4) | GET test counter |
10 | brightness 0..255 | color | steady | status<<4 | [effect[, speed]] opt. | — | SET LED for one status; 6986, before any touch, while a configuration lock is set (§6.2) |
11 | 00 | 00 | — | 17-byte config block | GET LED config |
1F | 00/01 | 00 | — | — | REBOOT (warm / BOOTSEL). 01 is user-presence-gated (6985 if declined; see §7) |
INS 12 (CORE1_STATS), INS 13 (KEYGEN_BENCH), INS 14 (BENCH) and INS 15
(STACK_RESIDUE, the dead-stack probe tests/55_stack_residue.py drives) exist only
in the measurement builds that ask for them (--features core1-stats /
keygen-bench / bench, which carries the last two); a shipped image answers
6D00, and none is part of the stable surface.
SET LED 0x10 requires presence under strict-config. A decline or timeout
returns 6982. The configuration lock applies in all builds.
SET LED 0x10 is idempotent. A request whose resulting 17-byte block already
matches the stored EF_LED_CONF answers 9000 without a flash write.
The LED config is still applied live. The next write upgrades a stored
13-, 9-, 3- or 2-byte block to the current layout.
INCREMENT 0x01 always goes through the presence gate. The diagnostic
no-touch build confirms automatically. A CTAPHID caller sees
KEEPALIVE(UPNEEDED) while the device waits for confirmation. GET 0x02
requires no presence.
Touch-status normalization. The awaiting-touch indicator is the only consent
signal on a build without the trusted display, so the EF_LED_CONF codec — not any
one command handler — normalizes it on every decode: the vendor SET LED, the
FIDO CONFIG_WRITE LED target (§9), and the boot reload of the stored record
alike. Four rules, in that order:
color 0(off) on the touch status becomes the default touch colour (yellow).- its
brightnessis raised to8. - a non-zero
speedis raised to2(speed 1makes the breathing effect render an all-black frame every tick while the brightness byte still reads compliant). - the touch colour is the touch status’s alone. Any other status configured in
that colour is reset to its own factory look — whatever its effect, brightness or
speed. Uniqueness deliberately keys on colour rather than on the whole
(effect, color, brightness, speed)quad: brightness and speed are continuous bytes, so a one-unit nudge is byte-unequal and eye-identical; steady mode renders a solid frame for every effect; and on a one-LED boardbounceandflowboth collapse to the same solid frame, so the effect byte carries no signal there.
The give-way case. If the status wearing the touch colour has that colour as
its factory colour, resetting it would not resolve the clash, so the touch
status reverts to its factory look (bounce / yellow) instead. Only boot (red) and
idle/processing (green) can trigger this. A red touch status therefore sticks
only while boot is not red, and a green one only while neither idle nor
processing is green. Yellow is nobody else’s factory colour, which is what makes
the fallback converge: enforcing twice is enforcing once.
What this does not guarantee. Two statuses in different colours can still be
hard to tell apart. The gpio backend has no hue at all — the indicator is lit or
unlit; red, green and yellow are mutually confusable under red-green colour
blindness; and on a one-LED board the effect adds nothing. What separates the
states there is the per-status blink timing (touch 1000/100 ms vs idle
500/500 ms), which is compile-time fixed and cannot be reconfigured — but the
global steady toggle suppresses blinking altogether, and on a single-colour backend
that leaves nothing at all to tell the states apart. A build with the trusted
display remains the strong answer for consent signalling.
SET LED 0x10 persists the normalized block. GET LED 0x11 returns the live
configuration for all statuses. The FIDO CONFIG_WRITE LED target (§9)
stores the supplied 17-byte block before normalization. Use CONFIG_READ to
retrieve the stored bytes.
SET LED 0x10 P2 layout: bits [2:0] = color, bit 3 (0x08) = steady
(solid, no blink, a global toggle), bits [5:4] = status. P1 = per-channel
brightness. The command data field is optional: data[0] sets the status’s
effect, data[1] its speed (0 = the effect’s built-in default). They
are independent: send no data to leave both unchanged, one byte to set only the
effect (the current speed is kept), two bytes to set both.
GET LED 0x11 response (config_block, 17 bytes):
steady(1) | (effect, color, brightness, speed) × 4 for statuses idle,
processing, touch, boot in that order. (block[0] = steady; status s →
effect block[1+4s], color block[2+4s], brightness block[3+4s], speed
block[4+4s].) Read the response length: older firmware returns a 13-byte
(effect, color, brightness) or 9-byte (color, brightness) block. The stride
is (len − 1) / 4.
| Color | Code | Status | Code | |
|---|---|---|---|---|
| off | 0 | idle | 0 | |
| red | 1 | processing | 1 | |
| green | 2 | touch | 2 | |
| blue | 3 | boot | 3 | |
| yellow | 4 | |||
| magenta | 5 | |||
| cyan | 6 | |||
| white | 7 |
Effects (the effect byte, ws2812 backend only; gpio/pimoroni always
use the classic on/off blink). legacy reproduces the original blink; the rest
animate across the connected LEDs and reduce gracefully on a single LED:
| Effect | Code | Effect | Code | |
|---|---|---|---|---|
| legacy (classic blink) | 0 | flow | 3 | |
| vapor (breathing) | 1 | sparkle | 4 | |
| bounce | 2 |
Example. Set the idle status to solid blue at brightness 0x20:
P2 = color 3 | steady 0x08 | status 0<<4 = 0x0B, APDU 00 10 20 0B.
Example. Set touch to yellow bounce at brightness 0x10, speed 0x0F:
P2 = color 4 | status 2<<4 = 0x24, data = effect 2 ‖ speed 0x0F,
APDU 00 10 10 24 02 02 0F.
9. CTAP authenticatorVendor (0x41) — seed backup, attestation, audit
A CTAP2 vendor command with command byte 0x41 followed by a CBOR map.
Send it inside CTAPHID_CBOR or over CTAP on CCID (§5.3).
It can export the device master seed. Source:
crates/rsk-fido/src/vendor.rs, constants in
crates/rsk-fido/src/consts.rs.
Request map: {1: subcommand(uint), 2: subCommandParams(map), 3: pinUvAuthProtocol(uint), 4: pinUvAuthParam(bstr)}.
Encode key 1 before key 2 so the parser knows how to read the parameters.
Omit key 2 for a command without parameters. Keys 3 and 4 carry the host PIN
token authentication when the gate requires it (§9.2).
| Sub | Name | Params (key 2) | Response | Gate |
|---|---|---|---|---|
01 | MSE | {1: COSE_Key, 2: mlkem_ek?} | {1: COSE_Key, 2: ct?} | none (establishes channel) |
02 | BACKUP_EXPORT | — | {1: blob(60)} | MSE + presence + PIN gate. Refused if sealed or on a fips-profile build |
03 | BACKUP_LOAD | {1: blob(60)} | — | MSE + presence + PIN gate. Refused while soft-locked. Without a host PIN, also asks “Replace device seed?”. A new seed makes credentials sealed to the old seed unreadable |
04 | BACKUP_FINALIZE | — | — | Presence + PIN gate. No MSE |
05 | BACKUP_STATE | — | {1: sealed, 2: has_seed, 3: locked, 4: unlocked, 5: rescrub_refused} | ungated |
06 | UNLOCK | {1: blob(60)} | — | MSE (the lock key is the auth) |
07 | AUDIT_READ | — | Journal window (§9.3) | PIN gate. Also requires presence if no host PIN is set |
08 | AUDIT_CHECKPOINT | {1: nonce(bstr, 0–32 bytes)} | Signed checkpoint (§9.3) | PIN gate + presence. Requires a provisioned DEVK |
09 | ATT_IMPORT | {1: blob(60), 2: chain(bstr)} | — | MSE + presence + PIN gate. The DER certificates are concatenated, leaf first. Without a host PIN, also asks “Replace this identity?” |
0A | ATT_CLEAR | — | — | MSE + presence + PIN gate. Without a host PIN, also asks “Erase this identity?” |
0B | ATT_STATE | — | {1: present, 2: sha256(packed_chain)?} | Ungated. Key 2 hashes the device’s packed record. It can be absent even when 1 is true if the chain is missing, unreadable or oversized |
0C | CONFIG_WRITE | {1: target(uint), 2: blob(bstr)} — target 0=DEV_CONF, 1=PHY, 2=LED | — | The configuration lock applies to all targets (§6.2). strict-config also requires presence and the PIN gate. No MSE |
0D | CONFIG_READ | {1: target(uint)} — target 1=PHY, 2=LED | PHY {1: blob(bstr), 2: {phy_tag: uint}}, LED {1: blob(bstr)} | Ungated. An absent record gives an empty blob. A read failure returns 7F |
0E | AUDIT_CONFIG | {1: op(uint)} — 0=disable, 1=enable, 2=status | {1: enabled(bool)} | Setting requires PIN gate + presence. Status (2) is ungated |
0F | CONFIG_COMMANDS | — | {1: [vendorCommandId(uint), …]} | Ungated. Lists the authenticatorConfig vendorPrototype (0xFF) IDs this build serves (§11). Older builds before bcdDevice 0x0A80 answer 0x02 |
After MSE, an invalid BACKUP_LOAD blob length returns 14, and an invalid
authentication tag returns 3D. UNLOCK and ATT_IMPORT return 02 for an
invalid encrypted key blob.
ATT_IMPORT accepts up to four concatenated DER certificates. To compare the
ATT_STATE digest with a known chain, hash the packed form
count(1) ‖ (length(2 LE) ‖ certificate DER)*.
rescrub_refused(BACKUP_STATEkey 5, bcdDevice ≥0x09C5)Flash health for this power cycle, and nothing more. After the one-shot at-rest hardening lap has run, any command that supersedes a record still sealed to the pre-OTP root must re-arm that lap by clearing its marker. The wipe paths —
authenticatorResetand the applet factory resets — take that re-arm best-effort and go on regardless, because refusing there would mean leaving the secrets live, and they answer0x00whatever the flash said. Key 5 istruewhen a re-arm this power cycle could not be shown to have landed, so a stuck medium is reported somewhere other than in the answer to a reset that did succeed.It does not say the hardening marker is wrong, or that hardening failed. Away from the wipe paths the re-arm gates the write that follows it, so a refusal stops that write: nothing is superseded, and the command either errors or skips a lazy migration and leaves the older record in force. Read key 5 as “this device’s flash refused a write it was asked for”, and nothing stronger.
Coverage is lost in one arm only, a wipe whose refusal was persistent. A wipe tries more than once — ahead of its sweep and again after it — and a refusal the retry recovers still sets key 5 even though the marker is then gone and the next boot laps as it should. When no attempt lands, the marker stays latched over the records the wipe superseded, no later boot ever laps, and those copies stay recoverable from a physical flash dump while the reset answered
0x00. Key 5 does not say which arm it is, and repeating the reset does not recover what that one already exposed, so a device that keeps reporting it has a failing medium and should be retired rather than trusted at rest. It is RAM state, so it clears on the next power cycle whether or not the flash recovered, and an older build simply omits the key.
Device configuration over FIDO (
CONFIG_WRITE 0x0C)The pcscd-free twin of the CCID device-config writes (§6 WRITE CONFIG and the
§7/§8phy/LED records): a host that cannot reach the CCID interface writes the same config over CTAPHID.targetselects the record:0x00= the management enabled-apps TLV (EF_DEV_CONF, the §6 blob,≤ 128bytes → the sameCTAP1_ERR_INVALID_LENGTH 0x03cap, under the §6.2 lock);0x01= the phy record (EF_PHY, §7.1: VID/PID, USB interfaces, LED wiring, presence-timeout; a read-modify-write merge — only the TLV tags in the blob are updated, the rest preserved (the samemerge_savethe CCID path uses), effective on the next boot);0x02= the LED config block (EF_LED_CONF, §8,CONF_LENbytes), persisted and then applied live by the firmware. Send at least 17 bytes for the LED target. The device stores the first 17 bytes and ignores any suffix.CONFIG_READtarget2returns the stored block verbatim, so it can differ from the live configuration after §8’s normalization. With the configuration unlocked, the default build permits these writes without presence or PIN authentication.strict-configadds both the presence gate and the PIN gate (§9.2). The CCID and CTAP management paths use the same DeviceInfo record, so a later CCID READ CONFIG reports the change.Replays and the audit journal. A write whose result equals what is already stored returns
0x00and writes nothing — no flash write, no journal entry, and forPHYno auto-reboot latch. AnLEDreplay is still applied live, as SET LED’s is. The comparison is against the merged record forPHY, so a partial blob that changes nothing is also a no-op; an absent or unreadableEF_PHYis never “unchanged”, so a host writing the default values to repair one is not answered0x00with nothing stored.A write that does change something is journalled, and a run of them costs a single ring entry.
CONFIG_WRITEis one of three journalled events an ungated host can drive on demand — the others are agetAssertioncarryingup:falseand a U2FAUTHENTICATEwithP1=0x08, both of which take the spec-mandated silent path — so appending one per call would let any of them evict the 128-entry window. All three coalesce. ForCONFIG_WRITE, when the newest entry is already a config write the device folds into it. The entry keeps itsseq, its timestamp (the first write of the run) and itsaux(the target that opened it), and itsdetailbecomesrepeats(2 LE) ‖ targets(1)— the number of further writes absorbed (saturating) and a1 << targetmask of every record the run touched. A run never folds across a power cycle, so theBOOTentry between two runs is never swallowed.The two silent FIDO events use a different encoding: the entry keeps the
detailof the first occurrence (the rpIdHash shown is the run’s first site) and the count of further folded occurrences is a saturating LEu16in the entry’s trailing two bytes — previously reserved and always zero, so an older build’s entries decode as a single occurrence. That fold scans the whole window, not just the newest entry, so interleaving two silent classes does not defeat it. A gestured assertion never folds. For a host re-checking the chain: a fold changes the head without advancingseq_next, so the sameseq_nextwith a different head is legitimate and is not a tamper signal (start,seq_nextand the epoch are untouched, so the window still folds to the head exactly as before).
CONFIG_READ 0x0DPHY key 2 (RS-Key0x0852+): the PHY read returns a2:map of boot-effective values keyed by phy tag:4= LED GPIO pin,12= LED driver,8= presence timeout (seconds) — resolved to the build default when the record has no override. Tag8reports the window the wait actually uses, i.e. with the 10 s floor of §7.1 already applied. It is for display by the host. The key1blob remains the raw override record for read-modify-write. When the firmware has no effective LED configuration, key2is an empty map.
⚠️ Seed export hands out a normally non-exportable key
BACKUP_EXPORT (0x02)returns the device’s 32-byte master seed (encrypted over the MSE channel). It is gated by a one-time setup window (re-opened only by anauthenticatorReset) and requires presence and the PIN gate (§9.2). Ask for explicit confirmation before exporting the seed.BACKUP_FINALIZEcloses the export window. Thefips-profilebuild refuses export entirely.
9.1 The MSE channel (0x41 / 0x01)
Establishes an encrypted channel for the seed-moving subcommands.
- Request
subCommandParams = {1: COSE_Key}where the COSE key is the host’s P-256 public key{1:2, 3:-25, -1:1, -2:X, -3:Y}.XandYare each exactly 32 bytes — a coordinate whose leading zero your bignum dropped is0x02 INVALID_PARAMETER, not left-padded (RS-Key0x089C+; the same rule the clientPIN and hmac-secret COSE parses apply, and what a YubiKey 5.7.4 does). Optional key2= the host’s ML-KEM-768 encapsulation key (1184 B) to make the channel hybrid PQC. - Response
{1: COSE_Key}= the device’s ephemeral P-256 public key (same COSE shape,-2:dx, -3:dy). If the request included an ML-KEM ek, the response adds key2= the 1088-byte ML-KEM ciphertext. - Channel key (32 bytes):
- classical:
HKDF-SHA256(salt="", ikm = ECDH_x(32), info = dev_pub(65)) - hybrid:
HKDF-SHA256(salt="RSK-MSE-PQ-v1", ikm = ECDH_x(32) ‖ ss_mlkem(32), info = dev_pub(65) ‖ ct(1088)) dev_pubis the 65-byte uncompressed device key04 ‖ dx ‖ dy.
- classical:
Blob format (the 60-byte blob in EXPORT/LOAD/UNLOCK/ATT_IMPORT):
nonce(12) ‖ ciphertext(32) ‖ tag(16), ChaCha20-Poly1305 under the channel key
with AAD = dev_pub (65 bytes).
The device has one live MSE slot. Run MSE immediately before the protected
command on the same transport and CID. Once a vendor consumer request parses,
it takes the slot before checking the remaining gates, including presence and
decryption. A CID mismatch empties the slot without giving the caller its key.
For authenticatorConfig AUT_ENABLE, the slot is taken after the config
authentication check.
A second valid MSE request while the slot is live clears the slot and returns
30. Start a fresh handshake after that response. A CTAPHID CID is a
host-supplied routing value. Refusing an in-place rekey prevents a second MSE
from replacing a live recipient key for BACKUP_EXPORT.
9.2 PIN gating
With a host clientPIN configured, commands marked PIN gate require
pinUvAuthProtocol (key 3) and pinUvAuthParam (key 4). The token must
carry the acfg permission (0x20).
HMAC-SHA256(pinUvAuthToken, FF × 32 ‖ 41 ‖ subcommand ‖ rawSubCommandParams)
Use the first 16 MAC bytes with protocol 1 and all 32 with protocol 2.
rawSubCommandParams is the verbatim CBOR encoding of the key-2 map, or
zero bytes if key 2 is absent. The reference client is tools/rsk/backup.py.
An unsupported protocol (including 0) returns 02. Missing key 4 returns
36. If key 4 is present and key 3 is missing, the device returns 14.
A bad MAC or missing acfg permission returns 33.
Without a host PIN, a configured device PIN is collected on the trusted
display. If the current build cannot collect it, the request returns 36.
Decline, timeout and cancellation during PIN entry return 27, 2F and
2D respectively. A wrong PIN consumes a retry. With neither PIN configured,
the PIN gate passes and any separate presence checks still apply.
An unsupported one is judged before the algorithm, the extensions and the
remaining options — makeCredential and getAssertion included, where it used
to be judged after all of them, so a request that got two things wrong was told
about the wrong one (bcdDevice 0x08B6). Two things still outrank it, both
because a YubiKey 5.7.4 puts them there:
- the request map’s own shape — keys 1..=4 of
makeCredentialand 1..=2 ofgetAssertionare read in order, and an absent, empty or over-long one is answered before any value is validated; - the option values of §6.1.2/§6.2.2 step 4:
up:falseonmakeCredential, anduv:truewith nopinUvAuthParamon a build without built-in user verification, are0x2C INVALID_OPTIONwhateverpinUvAuthProtocolsays.options.rkis not in that class and loses to the protocol, on that card and here.
9.3 Audit journal format
AUDIT_READ returns {1: start, 2: seq_next, 3: epoch, 4: entries}.
The sequence numbers are CBOR unsigned 32-bit values. epoch is a 32-byte
byte string. entries is a byte string of 20-byte records in sequence order.
seq(4 LE) ‖ uptime_ms(4 LE) ‖ event(1) ‖ aux(1) ‖ detail(8) ‖ repeats(2 LE)
Start with the exported epoch and compute SHA-256(previous_hash ‖ entry)
for each record. The final hash is the chain head. Event IDs and detail
layouts are defined in crates/rsk-fido/src/journal.rs.
AUDIT_CHECKPOINT returns {1: head, 2: seq_next, 3: signature, 4: public_key}.
The head is 32 bytes. The signature is DER-encoded ECDSA-SHA256 and the public
key is a 65-byte uncompressed P-256 point (04 ‖ X ‖ Y). Verify the
signature over the following bytes, using the DEVK-derived audit public key.
ASCII("RSK-AUDIT-CKPT-v1") ‖ head(32) ‖ seq_next(4 LE) ‖ nonce(0–32)
A journal entry can change in place when events coalesce. Compare the computed
head as well as seq_next when checking whether the export and checkpoint
cover the same snapshot.
10. Worked examples
All bytes hex; → shows the response (status word omitted when 9000).
Identify the device (Management DeviceInfo):
SELECT 00 A4 04 00 08 A0 00 00 05 27 47 11 17 00
READ 00 1D 00 00 00
→ 1C 01 02 023B 02 04 <serial> 04 01 01 05 03 050800 03 02 023B 08 01 00 0A 01 00
Read the phy record (Rescue):
SELECT 00 A4 04 00 08 A0 58 3F C1 9B 7E 4F 21 00
→ 01 02 08 06 <8-byte serial> # identity handshake
READ 80 1E 01 00 00
→ <phy TLV blob> # e.g. 06 02 00 00 on a virgin device
Switch USB identity to 1209:F1D2 by sending a patch for tag 00 to the
selected Rescue applet. Confirm the write on the device, then reboot after
9000.
WRITE 80 1C 01 00 06 00 04 12 09 F1 D2 00
REBOOT 80 1F 00 00 00
Set processing-status LED to red, brightness 64 (Vendor/LED):
SELECT 00 A4 04 00 05 F0 00 00 00 01 00
SET 00 10 40 11 # P1=0x40 brightness, P2 = color 1 | status 1<<4 = 0x11
Read backup state over CTAPHID. Send CTAP2 message 41 A1 01 05
(0x41 + CBOR {1: 5}) → on a fresh provisioned device
00 A5 01 F4 02 F5 03 F4 04 F4 05 F4. After the 00 status byte,
the map sets has_seed to true and sealed, locked, unlocked
and rescrub_refused to false.
11. Integration notes for PicoForge
PicoForge can reuse its PHY TLV codec (§7.1) with the RS-Key Rescue AID
A0 58 3F C1 9B 7E 4F 21 and CLA 80. Send only the tags to update.
Skip unknown tags while reading. An unsupported CTAP vendor subcommand
returns 02. Use the read-only probes in §6.1, §7 and §9 to discover capabilities.
For the legacy hardware-config path, send authenticatorConfig (CTAP 0x0D)
with subcommand vendorPrototype (0xFF) and parameters
{1: vendorCommandId(u64), 3: value(uint)}. The four PHY writes require an
acfg token and do not ask for presence. A configuration lock returns 30.
| PHY command | ID | Value |
|---|---|---|
| PhysicalVidPid | 0x6fcb19b0cbe3acfa | (vid << 16) | pid |
| PhysicalLedGpio | 0x7b392a394de9f948 | GPIO number |
| PhysicalLedBrightness | 0x76a85945985d02fd | Global brightness |
| PhysicalOptions | 0x269f3b09eceb805f | PHY OPTS bitmask (§7.1) |
getInfo lists 0xFF in authenticatorConfigCommands (0x1F) and returns
an empty vendorPrototypeConfigCommands array (0x15). Use
authenticatorVendor CONFIG_COMMANDS (41 / 0F) to retrieve the 64-bit IDs.
The list includes soft-lock enable and disable (0x03e43f56b34285e2 and
0x1831a40f04a25ed9) and the enterprise-attestation RP list
(0x0e6841934e719be7, RP IDs at key 4). Soft-lock enable also uses MSE.
Use the Rescue PHY commands or authenticatorVendor CONFIG_READ/WRITE for
fields beyond the four legacy PHY IDs, such as product name, touch timeout,
LED driver and curves. PHY changes take effect at boot. A changed FIDO PHY
write normally queues a reboot. Setting DISABLE_POWER_RESET keeps the
device attached until the host or operator reboots it.
Use DeviceInfo for applet enable/disable (§6), and require explicit confirmation
before fuse burns (§7), rebooting to BOOTSEL (§7/§8) or exporting a seed (§9).
Reference client paths under tools/rsk include ccid.py, ctaphid.py,
hw.py, led.py, backup.py, status.py and inventory.py.