.. include:: ../vars.rst

.. _chapter-persistence-service:

***********************************
Support for RTI Persistence Service
***********************************

|RTI_PERSISTENCESERVICE| is compatible with the |RTI_SP|. 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 |GovernanceFile| 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 File`).

.. hint::

  To run |PERSISTENCESERVICE| with the |SP|, 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 |SP|' key derivation function and encryption algorithms, see :ref:`p2_core/cryptography:Interactions with Persistence Service`.

In |SP|, 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 (e.g., 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,647 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`