Documentation

Command and Reply Codes

The following commands and replies are reserved by the protocol for various actions. The tables below show their descriptions and support status in this implementation.

The secure-channel commands — CMD_KEYSET, CMD_CHLNG, and CMD_SCRYPT — are described in Secure Channel.

Legend ​

The Support column in the tables below uses these glyphs:

GlyphMeaning
✓Supported by LibOSDP
✕Not supported
–Not applicable — reserved by the protocol, not implemented
🚧Work in progress — implementation under development
†Deprecated — retained for compatibility, not used
⧉Multi-part message — shown as a second icon next to the support status

Messages tagged with the multi-part icon carry payloads that may exceed a single OSDP packet: they are fragmented on the wire with a total/offset/length header and reassembled by the receiver (spec section 5.10; file transfer uses its own wider variant of the same header). CMD_PIVDATA itself fits one packet, but its reply REPLY_PIVDATAR is multi-part. REPLY_BIOREADR is multi-part only opt-in (see the note below). See Multi-part Messages for how LibOSDP generalizes this into a single engine, and Smartcard Commands for the smart-card flows that use it.

Commands ​

CommandValueDescriptionSupport
CMD_POLL0x60Poll✓
CMD_ID0x61ID Report Request✓
CMD_CAP0x62Peripheral Device Capabilities Request✓
CMD_DIAG0x63Diagnostic Function–
CMD_LSTAT0x64Local Status Report Request✓
CMD_ISTAT0x65Input Status Report Request✓
CMD_OSTAT0x66Output Status Report Request✓
CMD_RSTAT0x67Reader Status Tamper Report Request✓
CMD_OUT0x68Output Control Command✓
CMD_LED0x69Reader LED Control Command✓
CMD_BUZ0x6AReader Buzzer Control Command✓
CMD_TEXT0x6BReader Text Output Command✓
CMD_RMODE0x6CReader Mode Set†
CMD_TDSET0x6DTime and Date Set✓
CMD_COMSET0x6ECommunication Configuration Command✓
CMD_BIOREAD0x73Scan and send biometric data✓
CMD_BIOMATCH0x74Scan and match biometric data✓
CMD_KEYSET0x75Encryption Key Set✓
CMD_CHLNG0x76Challenge and Secure Session Initialization Request✓
CMD_SCRYPT0x77Server's Random Number and Server Cryptogram✓
CMD_ACURXSIZE0x7BMaximum Acceptable Reply Size✓
CMD_FILETRANSFER0x7CFile transfer command✓⧉
CMD_MFG0x80Manufacturer Specific Command✓
CMD_XWR0xA1Extended write data (Transparent Reader Support)✓
CMD_ABORT0xA2Abort PD operation✓
CMD_PIVDATA0xA3Get PIV Data✓
CMD_GENAUTH0xA4Request Authenticate✓⧉
CMD_CRAUTH0xA5Request Crypto Response✓⧉
CMD_KEEPACTIVE0xA7Keep secure channel active✓

Responses ​

ResponseValueDescriptionSupport
REPLY_ACK0x40General Acknowledge, Nothing to Report✓
REPLY_NAK0x41Negative Acknowledge – SIO Comm Handler Error Response✓
REPLY_PDID0x45Device Identification Report✓
REPLY_PDCAP0x46Device Capabilities Report✓
REPLY_LSTATR0x48Local Status Report✓
REPLY_ISTATR0x49Input Status Report✓
REPLY_OSTATR0x4AOutput Status Report✓
REPLY_RSTATR0x4BReader Status Tamper Report✓
REPLY_RAW0x50Card Data Report, Raw Bit Array✓
REPLY_FMT0x51Card Data Report, Character Array†
REPLY_KEYPAD0x53Keypad Data Report✓
REPLY_COM0x54Communication Configuration Report✓
REPLY_BIOREADR0x57Biometric Data✓⧉
REPLY_BIOMATCHR0x58Biometric Match Result✓
REPLY_CCRYPT0x76Client's ID and Client's Random Number✓
REPLY_RMAC_I0x78Client Cryptogram Packet and the Initial R-MAC✓
REPLY_BUSY0x79PD Is Busy Reply✓
REPLY_FTSTAT0x7AFile transfer status✓
REPLY_PIVDATAR0x80PIV data reply✓⧉
REPLY_GENAUTHR0x81Authentication response✓⧉
REPLY_CRAUTHR0x82Response to challenge✓⧉
REPLY_MFGSTATR0x83Manufacturer specific status✓
REPLY_MFGERRR0x84Manufacturer specific error✓
REPLY_MFGREP0x90Manufacturer specific reply✓
REPLY_XRD0xB1Extended read response (Transparent Reader Support)✓

LibOSDP Behavior Notes ​

For CMD_MFG, immediate command response follows normal callback ACK/NAK rules: callback return < 0 yields REPLY_NAK, callback return >= 0 yields REPLY_ACK. If the application wants to send REPLY_MFGREP, it must do so asynchronously by submitting an OSDP_EVENT_MFGREP event, which is then delivered on a subsequent CMD_POLL cycle.

Transparent Reader Support (CMD_XWR / REPLY_XRD). These code points back the transparent-reader feature, in which the CP drives a smartcard directly by tunnelling ISO 7816 APDUs to the reader (IEC 60839-11-5). LibOSDP implements it on both roles: the CP opens a card session, exchanges APDUs, can run secure PIN entry, and closes the session. See Smartcard Commands for the API. TRS is built when LibOSDP is compiled with OPT_BUILD_OSDP_TRS.

Multi-part REPLY_BIOREADR. By default a biometric read reply must fit in a single packet. When both roles set OSDP_FLAG_BIOREADR_MULTIPART, LibOSDP can split a larger template across fragments — a non-conforming extension the two sides opt into. This is why REPLY_BIOREADR carries the multi-part glyph only as opt-in; see Multi-part Messages.

Deprecated REPLY_FMT.REPLY_FMT (Card Data Report, Character Array) was underspecified by SIA and marked for deprecation. LibOSDP ignores it on receipt and never emits it; use REPLY_RAW for card data instead.

Deprecated CMD_RMODE. Reader Mode Set (0x6C) has been removed from the OSDP specification. LibOSDP never implemented it and neither issues nor handles it; the code point is retained only so packet traces can still name it.

CMD_TDSET. Time and Date Set (0x6D) was withdrawn from earlier drafts of the specification and is being re-introduced by SIA. LibOSDP implements it on both roles (gated on the OSDP_PD_CAP_TIME_KEEPING capability): the CP encodes the date/time and the PD validates and applies it. It is kept for legacy interop even where a given spec revision omits it.