.. include:: ../vars.rst

.. _chapter-infrastructure-services:

***************************************
Support for RTI Infrastructure Services
***************************************

.. _section-persistence-service:

RTI Persistence Service
=======================

|RTI_PERSISTENCESERVICE| is compatible with the |RTI_SP_PRODUCT|. To store persisted data protected, |PERSISTENCESERVICE| must use a configuration whose :xmltag:`domain_participant_qos` includes security properties for:

#. Dynamically loading the security libraries (see :ref:`p2_core/building_apps:Dynamic Linking`), and
#. Using a |GovernanceDoc| that sets :xmltag:`data_protection_kind` to a value other than :xmlval:`NONE` for the desired topics (see :ref:`p2_core/elements_dds_secure_system:Governance Document`).

.. hint::

  To run |PERSISTENCESERVICE| with the |RTI_SP_PRODUCT|, the ``%PATH%`` or
  ``$LD_LIBRARY_PATH`` environment variable must include RTI and OpenSSL DLLs or
  libraries.


When |PERSISTENCESERVICE| discovers a |TOPIC|, it creates a :entity:`PRSTDataReader` and a :entity:`PRSTDataWriter`. When security is enabled, these |EPs| will use |DataProtection|, at the level specified by the :xmltag:`data_protection_kind` |GovRule| (see :ref:`p2_core/cryptography:data_protection_kind (topic_rule)`).

The :entity:`PRSTDataReader` receives data from the |CONNEXTDATABUS| and verifies (and potentially decrypts) it. The :entity:`PRSTDataWriter` then applies |DataProtection| to the data with its own |SenderKey| before inserting it into the database. The stored encoded data includes the payload and the metadata necessary to verify (and potentially decrypt) it, such as the |CryptoHeader| and |CryptoFooter|.

When |PERSISTENCESERVICE| reads the database's data, the :entity:`PRSTDataWriter` does NOT verify the MAC stored with the data before sending it on the wire. It is up to the user |DRs| to verify the MAC. Consequently, if an attacker alters the database's data, the :entity:`PRSTDataWriter` will resend the tampered data many times over the wire until the reliability protocol causes the data to be lost.

|PERSISTENCESERVICE| encrypts and stores the :entity:`PRSTDataWriter`'s
|SenderKey| in the database row containing information about the writer. The
encryption key is the output of a derivation function whose input is the
:property:`dds.data_writer.history.key_material_key` property (see
:numref:`Properties for Configuring Secure Persistence Service`), and the
cryptography plugin implementation determines both the key derivation function
and the encryption algorithm. For details on the |RTI_SP_PRODUCT|' key
derivation function and encryption algorithms, see
:ref:`p2_core/cryptography:Interactions with Persistence Service`.

In the |RTI_SP_PRODUCT|, the Key Derivation Function involves PBKDF2
(Password-Based Key Derivation Function) with SHA-512 (Secure Hash Algorithm
with a 512-bit hash value) and a random salt, and the encryption algorithm
involves AES-256-GCM. The Key Derivation Function derives both the key and the
IV (Initialization Vector) used in the encryption. |PERSISTENCESERVICE| stores
the random salt along with the :entity:`PRSTDataWriter`'s encrypted key.

When |PERSISTENCESERVICE| restarts, the new :entity:`PRSTDataWriter` uses the |SenderKey| from the previous :entity:`PRSTDataWriter`, which it securely exchanges with user |DRs| to allow them to decrypt the data correctly. For this reason, to read the data from the database, |PERSISTENCESERVICE| needs to load the same configuration it previously used to write data into the database. If |PERSISTENCESERVICE| restarts with a different configuration (for example, wrong value for :property:`dds.data_writer.history.key_material_key`), |PERSISTENCESERVICE| creation will fail.


.. list-table:: Properties for Configuring Secure |PERSISTENCESERVICE|
  :name: Properties for Configuring Secure Persistence Service
  :widths: 40 60
  :header-rows: 1
  :class: longtable

  * - Property Name
    - Property Value Description

  * - :property:`dds.data_writer.history.key_material_key`
    - :required:`Required`

      The basis of the cryptographic material used to derive the key to encrypt
      the :entity:`PRSTDataWriter`'s |KeyMaterial|. This property may be
      specified in either the DomainParticipantQos or the DataWriterQos.

      Attempting to restore encrypted data using a nonexistent or incorrect
      :property:`key_material_key` will result in an informative log message and
      failure to create |PERSISTENCESERVICE|.

      You may specify either the file name or the document contents:

      * If specifying the file name, the property value may optionally have the prefix :value:`file:` (no space after the colon), followed by the fully qualified path and name of the file.

      * If specifying the contents of the document, the property value must have the prefix :value:`data:,` (no space after the comma), followed by the contents inside the document. For example: :value:`data:,myPassword`.

      The length of the :property:`key_material_key` contents may not exceed
      2,147,483,646 bytes.

      :type:`String`. When 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. Similarly, when this key is provided as a
      path to a file, it is recommended that you take the appropriate measures
      to protect the file containing the pre-shared key.

      Default: :value:`NULL`


RTI Routing Service
===================

|RTI_ROUTINGSERVICE| is compatible with the |RTI_SP_PRODUCT|. When secure data
reaches a |ROUTINGSERVICE| |DR| the |RTI_SP_PRODUCT| will decrypt the data into
cleartext (non-secure), and the service will move it through the corresponding
*Route* into the output, where it can be secured again if necessary. For further
reference, 
see :link_services_routing_service:`Routing Service User's Manual - Support for Security Plugins <configuration.html#support-for-rti-sp-product-heading>`.

RTI Recording Service
=====================

|RTI_RECS| is compatible with the |RTI_SP_PRODUCT|. When secure data reaches a
|RECS| |DR| the |RTI_SP_PRODUCT| will decrypt the data into cleartext
(non-secure) and store it into the configured storage. The sample is passed to
the storage layer without any security or encryption. Custom storage
implementations may encrypt the data again before storing it. For further
reference, see :link_services_recording_service:`Recording Service User's Manual - Support for Security Plugins in Recording Service <recorder/record_configuration.html#support-for-rti-sp-product-heading>`.

|RTI_REPS| is compatible with the |RTI_SP_PRODUCT|. When Replay is configured
with security, the data will be read in cleartext format from storage and
secured by the |RTI_SP_PRODUCT| once the output endpoint is reached. For further
reference, see :link_services_recording_service:`Recording Service User's Manual - Support for Security Plugins in Replay Service <replay/replay_configuration.html#support-for-rti-sp-product-heading>`.

RTI Web Integration Service
===========================

*RTI Web Integration Service* is compatible with the |RTI_SP_PRODUCT|.
When secure data reaches a *Web Integration Service* |DR| the |RTI_SP_PRODUCT| will
decrypt the data into cleartext (non-secure), and the service will transform it
into the web-enabled representation to be sent over the web protocol. 
For further reference, see :link_services_web_integration_service:`Web Integration Service User's Manual - Support for Security Plugins <configuration.html#support-for-rti-sp-product>`.

