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 establishedsession (PD by sending a NAK, CP by starting a new SC handshake). This documentexplains the secure channel workflow to help application developers understandfailure logs emitted by LibOSDP.

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

Secure Channel Session ​

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

The CP starts by sending CMD_CHLNG, to which the PD replies withREPLY_CCRYPT. With this response the CP authenticates the PD and computesits session keys. Next, the CP sends CMD_SCRYPT, which the PD uses toauthenticate the CP and compute its session keys. If all goes well, both CP andPD will have a working set of session keys (s-enc, s-mac1, and s-mac2). Thefinal 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 encryptingits next command (MAC chaining).

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

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

SCBK (Secure Channel Base Key) ​

This is the primary key used to derive the secure channel session keys. Whensetting 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, thePD is set up with secure channel disabled.

Master Key (MK) ​

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

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

Install Mode ​

Install mode is a provisioning-time, insecure mode that instructs the PD touse SCBK-Default (a hardcoded key defined by OSDP) and allows the CP to set anew 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 inosdp_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 PDinto 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 duringreboot, 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 anRFID reader soon after boot to trigger install mode (as some HID devicesimplement).

The ENFORCE_SECURE Flag ​

Enforce Secure is a LibOSDP flag introduced due to the insecure nature ofinstall mode. A CP/PD instructed to use this flag operates with strictersecurity, 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, theCP/PD attempted an action that LibOSDP deemed a protected operation requiringsupervision.

Persistence of Keys ​

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

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