14. RTPS-HMAC-Only Mode
Attention
Starting with version 7.1.0, RTPS-HMAC-Only mode is deprecated and will be removed in the future. Instead, we recommend using Pre-Shared Key Protection, described in Pre-Shared Key Protection.
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:
If and only if a DomainParticipant has the shared key, then it is trusted.
None of the data needs to be encrypted by the Security Plugins.
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.
Property Name (prefix with |
Property Value Description |
---|---|
|
Optional Enables or disables the HMAC-only mode.
Boolean. Default: |
|
Required if hmac_only.enabled = TRUE Pre-shared key from which the 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.
The maximum pre-shared key size is bounded by the maximum property size,
controlled by the DomainParticipant resource limit 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 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 |
|
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: Default: |
- 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 withcom.rti.serv.load_plugins
, followed by the.
character.
Note
The “RTPS-HMAC-Only” plugins do not check compatibility between secure
DomainParticipants based on their security algorithms - as described in
discovery_protection_kind (domain_rule)
and Discovery of a Remote Secure Entity.
Specifying the set of supported algorithms using
allowed_security_algorithms
in your Governance Document has no effect
in the case of “RTPS-HMAC-Only” plugins. DomainParticipants will match regardless of
their security algorithms, and they will try to authenticate each other.
Authentication will then fail if the algorithms are incompatible.