.. include:: ../vars.rst

.. _chapter-rtps-hmac-only-mode:

*******************
RTPS-HMAC-Only Mode
*******************

The |SP| library includes an alternative set of "RTPS-HMAC-Only" plugins. These plugins allow RTPS messages to be protected with a user-provided HMAC Key while disabling all other security features (authentication, access control and encryption). This key is used to both protect the integrity of outgoing messages and authenticate incoming messages. To set up the behavior of the RTPS-HMAC-Only mode, refer to :numref:`Properties for Configuring HMAC-Only Mode`.

You may use this capability to avoid the discovery-time overhead of mutual authentication and key exchange, which scales quadratically with the number of |DPs| that discover each other. If you use this capability, then you must assume the following:

#. If and only if a |DP| has the shared key, then it is trusted.
#. None of the data needs to be encrypted by the |SP|.
#. None of the data at rest (e.g., in |RTI_PERSISTENCESERVICE|) needs to be protected by the |SP|.

You are responsible for managing this shared key, including changing the key when you decide that a |DP| needs to be ignored or revoked.

.. list-table:: Properties for Configuring HMAC-Only Mode
  :name: Properties for Configuring HMAC-Only Mode
  :widths: 40 60
  :header-rows: 1
  :class: longtable

  * - Property Name (prefix with :property:`com.rti.serv.secure.`) [#fPrefix]_
    - Property Value Description
  * - :property:`hmac_only.enabled`
    - :required:`Optional`

      Enables or disables the HMAC-only mode.

      Note:
          When the HMAC-only mode is enabled, the properties configuring the
          non-HMAC-only plugins will be silently ignored. Similarly, if the
          HMAC-only mode is disabled, all of the other properties listed in this
          table will be ignored.

      :type:`Boolean`.

      Default: :value:`FALSE`

  * - :property:`hmac_only.cryptography.key`
    - :required:`Required if hmac_only.enabled = TRUE`

      Pre-shared key from which |SP| derive the HMAC Key used to
      compute message authentication codes. The pre-shared key can be either a
      plain text string or an arbitrary binary string. Empty keys (either string
      or binary) are not allowed.

      * Plain text pre-shared keys are case sensitive, and must start with the prefix :value:`str:` (e.g.: :value:`str:Some secret key string`).
      * Binary pre-shared keys must be provided as a sequence of upper- or lower-case hexadecimal digits prefixed by :value:`hex:` (e.g.: :value:`hex:1489a95de3873df5`).

      The maximum pre-shared key size is bounded by the maximum property size,
      controlled by the |DP| resource limit :property:`participant_property_string_max_length`.

      To compute the actual key that the RTPS-HMAC-Only plugins use, the plugins
      compute a SHA256 hash over the contents of a buffer containing the
      user-provided HMAC Key, plus a random session-id, plus some non-disclosed
      strings. Consequently, passing a user-provided HMAC Key longer than 32
      bytes does not provide any benefit with respect to the security of the
      key. As such, we recommend using a full entropy 32-byte HMAC Key for
      maximum security.

      This pre-shared key is also used to derive the HMAC Key used to compute
      message authentication codes over UDP WAN binding pings. |DPs| must set
      this property to the same value in order to communicate with each other.

      If :property:`cryptography.rtps_protection_key` (see
      :numref:`RTI Security Plugins Properties for Configuring Cryptography`)
      and :property:`hmac_only.cryptography.key` are both set, then the key that
      is used depends on the value of :property:`hmac_only.enabled`. If it is
      :value:`TRUE`, then the value of :property:`hmac_only.cryptography.key`
      is used. Otherwise, the value of :property:`cryptography.rtps_protection_key`
      is used to protect UDP WAN binding pings.

      :type:`String`. Since 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.

      Default: not set


  * - :property:`hmac_only.cryptography.max_blocks_per_session`
    - :required:`Optional`

      For protecting the integrity of RTPS messages, HMAC-only mode uses a Session Key that derives from the HMAC Key and a Session ID. This Session ID is serialized as part of the protected RTPS message. This property sets the number of message blocks to protect before changing the Session ID. Note that the current message block size is fixed at 32 bytes. Therefore, this property controls the number of 32-byte blocks protected with the same Session Key.

      :type:`Unsigned integer`: :value:`[1 - MAX_UINT64]`

      Default: :value:`MAX_UINT64`


.. [#fPrefix] Assuming 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.