15. Pre-Shared Key Protection

This chapter describes Pre-Shared Key Protection, which expands and unifies RTI Security Plugins entry-level protection. This mechanism is scheduled to eventually replace similar mechanisms (see the note below for details) under a common, more capable interface.

Note

The following mechanisms are planned to be replaced: legacy pre-shared key used in HMAC-Only mode (RTPS-HMAC-Only Mode), RTI Real-Time WAN Transport protection (cryptography.rtps_protection_key), RTI Cloud Discovery Service protection (authentication.participant_discovery_protection_key, Support for RTI Real-Time WAN Transport).

Pre-Shared Key Protection is a Cryptography Plugin mechanism that supports basic communication protection. It is based on a Pre-Shared Key, distributed out-of-band to DomainParticipants. The Pre-Shared Key Protection does not require authentication and does not support more sophisticated security features such as granular security and topic permissions enforcement. A Pre-Shared Key offers metadata and data protection on the wire and restricts communication only to DomainParticipants holding the pre-shared, user-configurable key seed.

Pre-Shared Key Protection can be leveraged in two different ways:

  • As part of the RTI Security Plugins: RTPS Pre-Shared Key Protection works alongside existing Security Plugins features and secures the communication happening before two DomainParticipants authenticate each other.

  • As part of RTI Lightweight Security Plugins: In this case, all traditional DDS Security mechanisms are disabled and the entire communication is protected with RTPS Pre-Shared Key Protection. Lightweight Security Plugins is described in detail in The Lightweight Security Plugins.

Attention

Pre-Shared Key Protection is being standardized and in this process the final configuration and functionality may change.

15.1. Pre-Shared Key Protection Motivation and Benefits

Pre-Shared Key Protection expands the Connext security offering and enables basic-level protection wherever traditional DDS Security mechanisms were unavailable, or infeasible due to limited resources or paramount performance requirements. The Pre-Shared Key secures all the traffic from the start-up of a DDS Entity and restricts the communication only to Entities holding the correct pre-shared key seed.

15.1.1. Pre-Shared Key Protection in Lightweight Security Plugins vs. Pre-Shared Key Protection in Security Plugins

Pre-Shared Key Protection uses the same mechanism in both Lightweight Security Plugins and the Security Plugins, and offers the same level of protection. The difference is in the Pre-Shared Key area of responsibility.

Pre-Shared Key Protection within the Security Plugins secures all communication that occurs before two DomainParticipants authenticate each other. Once authentication completes successfully, more sophisticated Security Plugins features (such as enforcement of permissions at the topic-level) can be used. In this setting, Pre-Shared Key Protection complements more advanced mechanisms and secures potentially sensitive information exchanged to bootstrap the DDS system (such as topic names in the Permission Document, locators in SPDP messages, or Participant User QoS propagated information), which would otherwise be vulnerable to tampering and visible to unauthorized parties. Pre-Shared Key Protection also provides an additional mitigation for potential vulnerabilities impacting the participant discovery process.

Lightweight Security Plugins are provided as a separate library. It supports Pre-Shared Key Protection only and the entire communication is protected with it. More sophisticated security mechanisms are unavailable. Lightweight Security Plugins are recommended in systems that do not require granular security, sophisticated authentication and permission management, but are resource-limited or demand high performance and low latency.

Attention

Pre-Shared Key Protection in Lightweight Security Plugins and Pre-Shared Key Protection in Security Plugins are not interoperable because Lightweight Security Plugins lacks features required by Security Plugins.

15.2. Configuring Pre-Shared Key Protection

The following properties are important for successfully configuring the Pre-Shared Key Protection:

  • The required property cryptography.rtps_protection_preshared_key sets the value of the pre-shared key seed and enables Pre-Shared Key Protection. It must be identical for all the DomainParticipants in your system.

  • An optional property determines the algorithm used to protect RTPS messages. For Security Plugins, use cryptography.encryption_algorithm. For Lightweight Security Plugins, use cryptography.rtps_protection_preshared_key_algorithm.

For more information about these properties, see Table 6.8.

15.3. How Pre-Shared Key Protection Works

15.3.1. Pre-Shared Key Material

Pre-Shared Key Protection relies on deriving unique symmetric keys for every DomainParticipant. The keys are based on a user-configurable, pre-shared secret key seed (common for all DomainParticipants) and publicly available data that uniquely identifies a DomainParticipant in the network. Thanks to this architecture, every DomainParticipant with the right pre-shared key seed can recreate the unique key material (Master Sender Salt and Master Sender Key) of any other DomainParticipant in the network without the need for costly key material exchange. The key material is used as an input parameter for a cryptographic algorithm to encrypt or MAC RTPS messages.

The 256-bit long Master Sender Salt is derived according to this algorithm:

HMAC-SHA256(
  HMAC-SHA256(
    concatenate("PSK-SALT", sender's domain ID, target's RTPS header),
    pre-shared key seed),
  concatenate("master salt derivation", 0x01))

The 256-bit long Master Sender Key is derived according to this algorithm:

HMAC-SHA256(
  HMAC-SHA256(
    concatenate("PSK-SKEY", sender's domain ID, target's RTPS header),
    pre-shared key seed),
  concatenate("master sender key derivation", 0x01))

Note

The uniqueness of every DomainParticipant’s key material is important to ensure a high level of security. No two DomainParticipants can have the same key. The algorithm’s goal is to ensure reliable and fast protection against external threats, and that no external party can forge the key material without knowledge of the pre-shared key seed. It is not the intent of this mechanism to protect against insider spoofing. If insiders are not fully trustworthy, use a different mechanism from the Security Plugins portfolio.

15.3.2. Key Management

A PSK-enabled DomainParticipant, upon its creation, derives its own key material which is stored and readily available for later use. Whenever it wants to communicate with another DomainParticipant, it applies the chosen protection (encryption or MAC) to the outgoing message, using its pre-calculated key material. The recipient of the PSK-protected message can quickly determine that the message is PSK-protected by checking the submessage flags in the RTPS Crypto Header. If the message is determined to be PSK-protected, the receiving DomainParticipant checks if its internal storage has the key corresponding to the RTPS Header received in the message. If so, it uses that key to decode or verify the message. If the key is not found in the list, the receiving DomainParticipant derives the key using the algorithm and puts it in the list.

Note

The remote DomainParticipants’ keys are stored in a list of a fixed size (10 slots) during their initial discovery. Whenever all available key slots are used and a “new” remote DomainParticipant is encountered, the oldest entry in the list is replaced with the newly derived one. This mechanism may have a considerable performance impact whenever we discover a number of nodes exceeding the number of slots in the list within a short time - the recipient would end up recalculating the keys frequently. After remote DomainParticipants discovery is complete, this limitation no longer exists since the keys are no longer stored in the list.