.. include:: ../vars.rst

.. _chapter-lightweight-security:

******************************
The |LIGHT_SP_BUILTIN_HEADING|
******************************

The |LIGHT_SP_BUILTIN| 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,
:property:`dds.sec.crypto.rtps_psk_secret_passphrase`
(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_BUILTIN| 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_BUILTIN|, 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 |RTI_SP_PRODUCT|.


|LIGHT_SP_BUILTIN| is *not* intended to provide an easily-configurable analogue of the |SP_BUILTIN|.
Protection offered by the |LIGHT_SP_BUILTIN| is significantly narrower and focuses only on
basic communication protection against outsiders. We recommended using the |SP_BUILTIN|
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:`dds.sec.crypto.rtps_psk_secret_passphrase` property.

Configuring the |LIGHT_SP_BUILTIN_HEADING|
==========================================

* You must set the :property:`dds.sec.crypto.rtps_psk_secret_passphrase`
  [#fPrefix]_ to the value of a pre-shared key seed. See
  :numref:`|RTI_SP_PRODUCT_HEADING| Properties for Configuring Cryptography`
  for the acceptable formats for this property.

  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:`dds.sec.crypto.rtps_psk_symmetric_cipher_algorithm`
  property. If not set, the default value of :value:`AUTO` (equivalent to
  :value:`AES256+GCM`) is used. You can also set the algorithm explicitly with
  one of the values: :value:`AES256+GCM`, :value:`AES128+GCM` and
  :value:`SM4+GCM` (exclusively in |LIGHT_SP_BUILTIN|). The value of this
  property must be the same for all the |DPs| in your system.

* You can optionally configure the
  :property:`dds.sec.access.rtps_psk_protection_kind`
  property. It specifies if the |LIGHT_SP_BUILTIN| will protect the confidentiality and
  integrity of RTPS messages (:value:`ENCRYPT`), only their integrity
  (:value:`SIGN`), or neither (:value:`NONE`). If not set, the default value of
  :value:`ENCRYPT` 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_BUILTIN| 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 |RTI_SP_PRODUCT_HEADING|-Based Applications`
  for more information about the properties for enabling the |RTI_SP_PRODUCT|.

* If your application links the |LIGHT_SP_BUILTIN| 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 |RTI_SP_PRODUCT_HEADING|-Based Applications`
  for more information about the properties for enabling the |RTI_SP_PRODUCT|.

* The |LIGHT_SP_BUILTIN| 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_BUILTIN_HEADING| and |RTI_ADMINCONSOLE|
-----------------------------------------------------

Configuring |LIGHT_SP_BUILTIN| via |RTI_ADMINCONSOLE| in a production environment
is not viable because of conflicting assumptions for
the host platform. |LIGHT_SP_BUILTIN| 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_BUILTIN| can communicate with |LIGHT_SP_BUILTIN| if properly
configured; see :ref:`p3_advanced/pre-shared_key:|LIGHT_SP_BUILTIN_HEADING| and |SP_BUILTIN_HEADING| Interoperability`
for detailed information.

If you do want to configure |LIGHT_SP_BUILTIN| via *Admin Console*,
modify *Admin Console's* underlying configuration files. For details, see
:ref:`p4_integrations/admin_console:|RTI_ADMINCONSOLE| and the |LIGHT_SP_BUILTIN|`

.. 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.