OSDP Secure Channel

OSDP uses AES with a key size of 128 bits (16 bytes). The Secure Channel (SC) session is initiated by the CP, and either side can invalidate an established session (PD by sending a NAK, CP by starting a new SC handshake). This document explains the secure channel workflow to help application developers understand failure logs emitted by LibOSDP.

LibOSDP has a working implementation of the secure channel. Any CP/PD using this library will advertise this as an implicit capability. To disable secure communication (e.g. for debugging), call osdp_pd_set_capabilities() after osdp_setup() and set the compliance level of OSDP_PD_CAP_COMMUNICATION_SECURITY to 0.

Secure Channel Session ​

A SC session is initiated with a handshake involving 2 command-reply transactions between the CP and PD. Once established, a session can be kept active indefinitely until either party discards it or a timeout (400 ms) occurs.

The CP starts by sending CMD_CHLNG, to which the PD replies with REPLY_CCRYPT. With this response the CP authenticates the PD and computes its session keys. Next, the CP sends CMD_SCRYPT, which the PD uses to authenticate the CP and compute its session keys. If all goes well, both CP and PD will have a working set of session keys (s-enc, s-mac1, and s-mac2). The final message of the handshake is the REPLY_RMAC_I response from the PD, which carries the initial reply MAC the CP will use as the IV for encrypting its next command (MAC chaining).

This process works if both the CP and PD have the same SCBK. If there is a mismatch, the CP will fail to verify the PD's authenticity when it receives REPLY_CCRYPT. At that point, LibOSDP will try a new SC handshake with SCBK-default to check if the PD is in install-mode. If that also fails, the CP goes online without a secure session and retries every 10 minutes.

Note: This is the default behavior. With ENFORCE_SECURE enabled, the behavior changes (see below).

SCBK (Secure Channel Base Key) ​

This is the primary key used to derive the secure channel session keys. When setting up a CP or PD, pass the SCBK in osdp_pd_info_t::scbk.

If osdp_pd_info_t::scbk is NULL:

• In PD mode: the PD is forced into install mode.
• In CP mode: LibOSDP looks for a master key. If that also doesn't exist, the PD is set up with secure channel disabled.

Master Key (MK) ​

A CP-specific key used to derive individual PD SCBKs. This can be passed to osdp_cp_setup(). The MK is common for all PDs connected to this CP, while the SCBK must be unique to each PD.

Note: The latest OSDP specification discourages the use of the master key and recommends that the CP maintain the SCBKs directly. LibOSDP will print a warning if a master key is used for any PD.

Install Mode ​

Install mode is a provisioning-time, insecure mode that instructs the PD to use SCBK-Default (a hardcoded key defined by OSDP) and allows the CP to set a new SCBK. Once the PD receives a new SCBK, it automatically exits install mode, preventing another SCBK key set.

Enable install mode by passing OSDP_FLAG_INSTALL_MODE in osdp_pd_info_t::flags. Do not pass this flag during normal operation.

Entering Install Mode ​

If you are building a PD as a product, you'll need a method to force the PD into install mode during provisioning to allow the CP to set a new SCBK.

A simple approach is a pin-hole tactile switch that, when pressed during reboot, causes your application to pass the OSDP_FLAG_INSTALL_MODE flag.

This is not very secure since an attacker with physical access can do the same. More secure alternatives include special configuration cards presented to an RFID reader soon after boot to trigger install mode (as some HID devices implement).

On the CP side, keying the SCBK while a PD is in install mode is what Osprio Provisioner automates — it sets the new SCBK over a controlled point-to-point link and verifies it with a fresh secure-channel handshake before the PD is handed to the production bus.

The ENFORCE_SECURE Flag ​

Enforce Secure is a LibOSDP flag introduced due to the insecure nature of install mode. A CP/PD instructed to use this flag operates with stricter security, disallowing certain OSDP features such as install mode.

When ENFORCE_SECURE is enabled:

• Secure Channel cannot be disabled
• The CP/PD will not operate without a secure channel if setup fails
• SCBK-Default (install mode) is not allowed
• Master key–based SCBK derivation is disallowed

When you see a "... due to ENFORCE_SECURE" failure message in the logs, the CP/PD attempted an action that LibOSDP deemed a protected operation requiring supervision.

Persistence of Keys ​

LibOSDP does not retain the SCBK across power cycles. The application is responsible for storing and providing the correct SCBK/MK on each call to osdp_cp/pd_setup().

In CP mode, the CP owns the SCBK/MK, so the CP app already has the key. In PD mode, when the PD receives a new SCBK from the CP, the PD app gets a copy in the OSDP_CMD_KEYSET callback.