14. RTPS-HMAC-Only Mode

The Security Plugins library includes an alternative set of “RTPS-HMAC-Only” plugins. These plugins allow RTPS messages to be protected with a user-provided HMAC Key while disabling all other security features (authentication, access control and encryption). This key is used to both protect the integrity of outgoing messages and authenticate incoming messages. To set up the behavior of the RTPS-HMAC-Only mode, refer to Table 14.1.

You may use this capability to avoid the discovery-time overhead of mutual authentication and key exchange, which scales quadratically with the number of DomainParticipants that discover each other. If you use this capability, then you must assume the following:

1. If and only if a DomainParticipant has the shared key, then it is trusted.

2. None of the data needs to be encrypted by the Security Plugins.

3. None of the data at rest (e.g., in RTI Persistence Service) needs to be protected by the Security Plugins.

You are responsible for managing this shared key, including changing the key when you decide that a DomainParticipant needs to be ignored or revoked.

Table 14.1 Properties for Configuring HMAC-Only Mode

Property Name (prefix with com.rti.serv.secure.) 1	Property Value Description
hmac_only.enabled	Optional Enables or disables the HMAC-only mode. Note: When the HMAC-only mode is enabled, the properties configuring the non-HMAC-only plugins will be silently ignored. Similarly, if the HMAC-only mode is disabled, all of the other properties listed in this table will be ignored. Boolean. Default: FALSE
hmac_only.cryptography.key	Required if hmac_only.enabled = TRUE Pre-shared key from which Security Plugins derive the HMAC Key used to compute message authentication codes. The pre-shared key can be either a plain text string or an arbitrary binary string. Empty keys (either string or binary) are not allowed. Plain text pre-shared keys are case sensitive, and must start with the prefix str: (e.g.: str:Some secret key string). Binary pre-shared keys must be provided as a sequence of upper- or lower-case hexadecimal digits prefixed by hex: (e.g.: hex:1489a95de3873df5). The maximum pre-shared key size is bounded by the maximum property size, controlled by the DomainParticipant resource limit participant_property_string_max_length. To compute the actual key that the RTPS-HMAC-Only plugins use, the plugins compute a SHA256 hash over the contents of a buffer containing the user-provided HMAC Key, plus a random session-id, plus some non-disclosed strings. Consequently, passing a user-provided HMAC Key longer than 32 bytes does not provide any benefit with respect to the security of the key. As such, we recommend using a full entropy 32-byte HMAC Key for maximum security. This pre-shared key is also used to derive the HMAC Key used to compute message authentication codes over UDP WAN binding pings. DomainParticipants must set this property to the same value in order to communicate with each other. If cryptography.rtps_protection_key (see Table 6.8) and hmac_only.cryptography.key are both set, then the key that is used depends on the value of hmac_only.enabled. If it is TRUE, then the value of hmac_only.cryptography.key is used. Otherwise, the value of cryptography.rtps_protection_key is used to protect UDP WAN binding pings. String. Since this key is provided as a String, it is recommended that you take the appropriate measures to protect any configuration XML file containing this key, or alternatively to securely retrieve and set up this property programmatically. Default: not set
hmac_only.cryptography.max_blocks_per_session	Optional For protecting the integrity of RTPS messages, HMAC-only mode uses a Session Key that derives from the HMAC Key and a Session ID. This Session ID is serialized as part of the protected RTPS message. This property sets the number of message blocks to protect before changing the Session ID. Note that the current message block size is fixed at 32 bytes. Therefore, this property controls the number of 32-byte blocks protected with the same Session Key. Unsigned integer: [1 - MAX_UINT64] Default: MAX_UINT64

1

Assuming you used com.rti.serv.secure as the alias to load the plugin. If not, change the prefix to match the string used with com.rti.serv.load_plugins, followed by the . character.