16. The Lightweight Security Plugins

The Lightweight Security Plugins is a separate library that includes an alternate set of Security Plugins. These plugins allow RTPS messages to be protected with a per-participant key derived from some publicly available data and a pre-shared key seed, cryptography.rtps_protection_preshared_key 1 (see Pre-Shared Key Protection). This key is used to protect the integrity and/or confidentiality of RTPS messages.

The intent of Lightweight Security Plugins is to provide a minimal security solution to devices with limited resources or fast startup requirements. This is done by avoiding the discovery-time overhead of mutual authentication and key exchange. If you use the Lightweight Security Plugins, then you must assume the following:

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

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

Lightweight Security Plugins is not intended to provide an easily-configurable analogue of the Security Plugins. Protection offered by the Lightweight Security Plugins is significantly narrower and focuses only on basic communication protection against outsiders. We recommended using the Security Plugins whenever possible.

You are responsible for managing this pre-shared key seed, including changing it when you decide that a DomainParticipant needs to be ignored or revoked. For more information about mutability of the pre-shared key, please see Properties for Configuring Cryptography section on the cryptography.rtps_protection_preshared_key property.

16.1. Configuring the Lightweight Security Plugins

  • You must set the cryptography.rtps_protection_preshared_key 1 to the value of a pre-shared key seed. It must follow the format str:<ID>:<SEED>. Start with the “str:” prefix, continue with a unique key identifier (number between 0 and 254) followed by a colon (“:”), and finish with the secret key. Both the key seed and the unique key identifier must be consistent across all DomainParticipants in the system. The key seed, combined with public information, is used to produce the key which is used to encrypt and decrypt RTPS messages. This property can be changed by the user at runtime, and the unique key identifier is used to determine if the correct key revision is used for different DomainParticipants. The key has to be manually updated for all DomainParticipants in the system. Until the key is updated across the system, decryption errors will occur. See Properties for Configuring Cryptography for more details about this property.

  • You can optionally configure the algorithm used to protect RTPS messages by changing the value of the cryptography.rtps_protection_preshared_key_algorithm 1 property. If not set, the default value of AES256+GCM is used. The value of this property must be the same for all the DomainParticipants in your system.

  • If your application links the Lightweight Security Plugins dynamically, you must change the value of the library 1 property to nddslightweightsecurity, and the value of the create_function 1 property to RTI_SecurityLightweight_PluginSuite_create. See Building and Running Security Plugins-Based Applications for more information about the properties for enabling the Security Plugins.

  • If your application links the Lightweight Security Plugins statically, you must change the value of the create_function_ptr 1 property to the RTI_SecurityLightweight_PluginSuite_create function pointer. See Building and Running Security Plugins-Based Applications for more information about the properties for enabling the Security Plugins.

  • The Lightweight Security Plugins do not read the Governance Document, the Permissions Document, Private Key, Identity Certificate, or the certificates of the Identity and Permissions CA. You should not configure the related properties.

16.1.1. The Lightweight Security Plugins and RTI Administration Console

Configuring Lightweight Security Plugins via RTI Administration Console in a production environment is not viable because of conflicting assumptions for the host platform. Lightweight Security Plugins is meant for resource-constrained devices, while Admin Console expects a more performant system where all Connext features can be easily run. Note that Security Plugins can communicate with Lightweight Security Plugins if properly configured; see Lightweight Security Plugins and Security Plugins Interoperability for detailed information.

If you do want to configure Lightweight Security Plugins via Admin Console, modify Admin Console’s underlying configuration files. For details, see RTI Administration Console and the Lightweight Security Plugins

16.2. The Lightweight Security Plugins vs HMAC-Only Mode

The Lightweight Security Plugins offer a functionality similar to the <<deprecated>> HMAC-Only mode (see RTPS-HMAC-Only Mode). However, there are some limitations of the HMAC-Only mode:

  • HMAC-Only is not effective at protecting participant discovery metadata.

  • The HMAC-Only mode does not protect confidentiality of the RTPS messages.

  • The HMAC-Only mode is part of the full nddssecurity library. On the other hand, the size of the Lightweight Security Plugins library is smaller because it only contains the pre-shared key functionality.

  • The HMAC-Only mode does not interoperate with Security Plugins not running under HMAC-Only mode. Lightweight Security Plugins can interoperate with Security Plugins under certain configurations, see Lightweight Security Plugins and Security Plugins Interoperability.

As a consequence, the HMAC-Only mode is deprecated by the Lightweight Security Plugins.

Note

1(1,2,3,4,5,6)

Prefix the property name with com.rti.serv.secure.. This assumes 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.