17. The Lightweight Builtin Security Plugins

The Lightweight Builtin Security Plugins is a separate library that includes an alternate set of 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, dds.sec.crypto.rtps_psk_secret_passphrase (see Pre-Shared Key Protection). This key is used to protect the integrity and/or confidentiality of RTPS messages.

The intent of Lightweight Builtin 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 Builtin 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 Builtin Security Plugins is not intended to provide an easily-configurable analogue of the Builtin Security Plugins. Protection offered by the Lightweight Builtin Security Plugins is significantly narrower and focuses only on basic communication protection against outsiders. We recommended using the Builtin 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 dds.sec.crypto.rtps_psk_secret_passphrase property.

17.1. Configuring the Lightweight Builtin Security Plugins

  • You must set the dds.sec.crypto.rtps_psk_secret_passphrase [1] to the value of a pre-shared key seed. See Table 6.8 for the acceptable formats for this property.

    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 dds.sec.crypto.rtps_psk_symmetric_cipher_algorithm property. If not set, the default value of AUTO (equivalent to AES256+GCM) is used. The value of this property must be the same for all the DomainParticipants in your system.

  • You can optionally configure the dds.sec.access.rtps_psk_protection_kind property. It specifies if the Lightweight Builtin Security Plugins will protect the confidentiality and integrity of RTPS messages (ENCRYPT), only their integrity (SIGN), or neither (NONE). If not set, the default value of ENCRYPT is used. The value of this property must be the same for all the DomainParticipants in your system.

  • If your application links the Lightweight Builtin 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 Builtin 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 Builtin 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.

17.1.1. The Lightweight Builtin Security Plugins and RTI Admin Console

Configuring Lightweight Builtin Security Plugins via RTI Admin Console in a production environment is not viable because of conflicting assumptions for the host platform. Lightweight Builtin 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 Builtin Security Plugins can communicate with Lightweight Builtin Security Plugins if properly configured; see Lightweight Builtin Security Plugins and Builtin Security Plugins Interoperability for detailed information.

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

17.2. The Lightweight Builtin Security Plugins vs Builtin Security Plugins in HMAC-Only mode

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

  • HMAC-Only mode 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 Builtin Security Plugins nddssecurity library. On the other hand, the size of the Lightweight Builtin Security Plugins library is smaller because it only contains the pre-shared key functionality.

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

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

Note