.. include:: ../vars.rst .. _chapter-lightweight-security: ********************** The |LIGHT_SP_HEADING| ********************** The |LIGHT_SP| is a separate library that includes an alternate set of |SP|. 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, :property:`cryptography.rtps_protection_preshared_key` [#fPrefix]_ (see :ref:`p3_advanced/pre-shared_key:|PSKProtection|`). This key is used to protect the integrity and/or confidentiality of RTPS messages. The intent of |LIGHT_SP| 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 |LIGHT_SP|, then you must assume the following: #. If and only if a |DP| has the pre-shared key seed, then it is trusted. #. None of the data at rest (e.g., in |RTI_PERSISTENCESERVICE|) needs to be protected by the |SP|. |LIGHT_SP| is *not* intended to provide an easily-configurable analogue of the |SP|. Protection offered by the |LIGHT_SP| is significantly narrower and focuses only on basic communication protection against outsiders. We recommended using the |SP| whenever possible. You are responsible for managing this pre-shared key seed, including changing it when you decide that a |DP| needs to be ignored or revoked. For more information about mutability of the pre-shared key, please see :ref:`p2_core/cryptography:Properties for Configuring Cryptography` section on the :property:`cryptography.rtps_protection_preshared_key` property. Configuring the |LIGHT_SP_HEADING| ================================== * You must set the :property:`cryptography.rtps_protection_preshared_key` [#fPrefix]_ to the value of a pre-shared key seed. It must follow the format ``str::``. 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 |DPs| 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 |DPs|. The key has to be manually updated for all |DPs| in the system. Until the key is updated across the system, decryption errors will occur. See :ref:`p2_core/cryptography: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 :property:`cryptography.rtps_protection_preshared_key_algorithm` [#fPrefix]_ property. If not set, the default value of :value:`AES256+GCM` is used. The value of this property must be the same for all the |DPs| in your system. * If your application links the |LIGHT_SP| dynamically, you must change the value of the :property:`library` [#fPrefix]_ property to ``nddslightweightsecurity``, and the value of the :property:`create_function` [#fPrefix]_ property to ``RTI_SecurityLightweight_PluginSuite_create``. See :ref:`p2_core/building_apps:Building and Running Security Plugins-Based Applications` for more information about the properties for enabling the |SP|. * If your application links the |LIGHT_SP| statically, you must change the value of the :property:`create_function_ptr` [#fPrefix]_ property to the ``RTI_SecurityLightweight_PluginSuite_create`` function pointer. See :ref:`p2_core/building_apps:Building and Running Security Plugins-Based Applications` for more information about the properties for enabling the |SP|. * The |LIGHT_SP| do not read the |GovernanceDoc|, the |PermissionsDoc|, Private Key, |IdentityCert|, or the certificates of the Identity and Permissions CA. You should not configure the related properties. The |LIGHT_SP_HEADING| and |RTI_ADMINCONSOLE| --------------------------------------------- Configuring |LIGHT_SP| via |RTI_ADMINCONSOLE| in a production environment is not viable because of conflicting assumptions for the host platform. |LIGHT_SP| is meant for resource-constrained devices, while *Admin Console* expects a more performant system where all |CONNEXT| features can be easily run. Note that |SP| can communicate with |LIGHT_SP| if properly configured; see :ref:`p3_advanced/pre-shared_key:|LIGHT_SP_HEADING| and |SP_HEADING| Interoperability` for detailed information. If you do want to configure |LIGHT_SP| via *Admin Console*, modify *Admin Console's* underlying configuration files. For details, see :ref:`p4_integrations/admin_console:|RTI_ADMINCONSOLE| and the |LIGHT_SP|` The |LIGHT_SP_HEADING| vs HMAC-Only Mode ======================================== The |LIGHT_SP| offer a functionality similar to the <> HMAC-Only mode (see :ref:`p3_advanced/rtps_hmac_only_mode: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 |LIGHT_SP| library is smaller because it only contains the pre-shared key functionality. * The HMAC-Only mode does not interoperate with |SP| not running under HMAC-Only mode. |LIGHT_SP| can interoperate with |SP| under certain configurations, see :ref:`p3_advanced/pre-shared_key:|LIGHT_SP_HEADING| and |SP_HEADING| Interoperability`. As a consequence, the HMAC-Only mode is deprecated by the |LIGHT_SP|. .. note:: .. [#fPrefix] Prefix the property name with :property:`com.rti.serv.secure.`. This assumes you used :value:`com.rti.serv.secure` as the alias to load the plugin. If not, change the prefix to match the string used with :property:`com.rti.serv.load_plugins`, followed by the :value:`.` character.