.. include:: ../vars.rst

***************************************
Support for RTI Real-Time WAN Transport
***************************************

|RWT| is compatible with the |RTI_SP_PRODUCT|. The integrity of
the Binding Ping messages can be protected using :ref:`p3_advanced/lightweight_security:The |LIGHT_SP_BUILTIN_HEADING|` as
described in :ref:`p4_integrations/real-time_wan_transport:Binding Ping Messages
Security`. When using |CDS|, the communication with this service can also be
protected by |PSKProtection| as described in
:ref:`p4_integrations/real-time_wan_transport:Security Considerations when Using
Cloud Discovery Service`.

Binding Ping Messages Security
==============================

|RWT| uses special RTPS messages called Binding Ping messages to open NAT
bindings and to resolve UUID locators into public IP transport addresses. These
PING messages are exchanged between |DPs| before they authenticate with each
other (see :ref:`p2_core/authentication:Authentication`), and they contain the
UUID and the RTPS port of the locator with which they are associated (see
:link_connext_dds_pro_um:`Binding Ping Messages in the Core Libraries User's Manual
<#users_manual/BindingPing_Security_WAN.htm>`).

An outside attacker can try to modify Binding Ping messages in transit, in
order to cause a failure in the protocol that establishes WAN connectivity
between |DPs|. For details on this protocol, see :link_connext_dds_pro_um:`Advanced Concepts in
the Core Libraries User's Manual <#users_manual/AdvancedConcepts_WAN.htm>`.

To protect against this attack, the integrity of the Binding Ping messages
can be protected by using |PSKProtection| that must be set in all |DPs| using
the :property:`dds.sec.crypto.rtps_psk_secret_passphrase` property and,
optionally, :property:`dds.sec.crypto.rtps_psk_symmetric_cipher_algorithm`
(see :ref:`p3_advanced/pre-shared_key:Configuring |PSKProtection|`).
If the pre-shared_key is set, |RWT| protects by default the integrity and
confidentiality of the Binding Ping Message. The decision of whether to protect
only integrity, or to protect confidentiality as well, depends on the value of
the :xmltag:`rtps_psk_protection_kind` XML tag in the Governance Document. In
the case of |LIGHT_SP_BUILTIN| (which does not support the Governance Document), it is
configured through the new :property:`dds.sec.access.rtps_psk_protection_kind`
property. The default value is :xmlval:`ENCRYPT` (protect both integrity and
confidentiality). For details,
see :numref:`DDS Security Properties for Configuring Access Control`.

The following example enables security to protect the integrity of the
Binding Ping messages in the `ExternalParticipant` QoS Profile, as described
in :link_connext_dds_pro_um:`Peer-to-Peer Communication with a Participant that has a Public
Address in the Core Libraries User's Manual <#users_manual/P2P_Public_Address.htm>`.

.. literalinclude:: ../snippets/rwt_example.xml
  :language: xml
  :start-after: <!-- ExternalParticipant BINDING_PINGS -->
  :end-before: EOF
  :emphasize-lines: 48-49
  :caption: External Participant Configuration to Protect Binding Pings

.. attention::

  Binding Ping's traffic protection uses the same |PSKProtection| mechanism used to
  protect |DP| communication. If you enable |PSKProtection|, it protects all
  communication not protected by other means. Moreover, the passphrase is the same
  for the entire Domain and there is no way to set one passphrase for Binding Ping's
  traffic protection and a different one for direct communication between |DPs|.


Security Considerations when Using Cloud Discovery Service
==========================================================

|CDS| (CDS), in combination with |RWT| (RWT), plays a key
role in facilitating the NAT traversal process. The service does this by
resolving the public IP transport addresses associated with the UUID locators
received from a |DP| (|P1|) as part of its participant announcements (PA). For
further details, see :link_connext_dds_pro_um:`Transport Locators in the Core Libraries User's
Manual <#users_manual/TransportLocators_WAN.htm>`.

Once |CDS| resolves the public IP transport addresses, it modifies the
participant announcement sent by |P1| to include these public addresses as part
of the locators and sends the updated participant announcement to the other
|DPs| so that they can establish communication with |P1|.
:link_addon_products_cloud_discovery_service:`NAT
Traversal in the Cloud Discovery Service User's Manual <nat.html>` provides
additional details on the protocol for NAT traversal with |CDS|.

An outside attacker can try to modify or replay the participant announcement
messages sent by |CDS| to the |DPs|, in order to cause a failure in the protocol
that establishes WAN connectivity between |DPs|. To protect against these
attacks, you can protect the exchange of participant announcements between |CDS|
and the |DPs| through |PSKProtection| that must be set in all |DPs| and |CDS|:

* |DPs| can set the pre-shared key using the
  :property:`dds.sec.crypto.rtps_psk_secret_passphrase` property (see
  :ref:`p3_advanced/pre-shared_key:Configuring |PSKProtection|`).
* |DPs| can, optionally, change the |PSKProtection| algorithm by setting up the
  :property:`dds.sec.crypto.rtps_psk_symmetric_cipher_algorithm` property.
* |CDS| can set |PSKProtection| by updating the :xmltag:`property` tag
  inside :xmltag:`security` tag (see
  :link_addon_products_cloud_discovery_service:`Security Configuration in
  the Cloud Discovery Service User's Manual <configuration.html#security>`).

Configuring the |PSKProtection| is mandatory to use |CDS| with |DPs| that enable
the |RTI_SP_PRODUCT| and |RWT|.

.. attention::

  |PSKProtection| for both |CDS|-based bootstrapping and direct communication between
  |DPs| share the same :property:`dds.sec.crypto.rtps_psk_secret_passphrase` property.
  If you enable |PSKProtection|, it protects all communication not protected by other
  means. Moreover, the passphrase is the same for the entire system and there is no way
  to set one passphrase for communication with |CDS| and a different one for direct communication
  between |DPs|.

The following examples enable security to protect the integrity of the
participant announcements in the `InternalParticipant` QoS Profile, as described
in :link_connext_dds_pro_um:`Peer-to-Peer Communication with Participants behind Cone NATs Using
RWT and CDS in the Core Libraries User's Manual <#users_manual/P2P_Behind_Cone.htm>`, and
configure |CDS| accordingly.

.. literalinclude:: ../snippets/rwt_example.xml
  :language: xml
  :start-after: <!-- InternalParticipant BINDING_PINGS -->
  :end-before: EOF
  :emphasize-lines: 44-45
  :caption: Internal Participant Configuration to Protect Participant Announcements and Binding Pings


.. _li-cds-config-protect:
.. literalinclude:: ../snippets/rwt_example.xml
  :language: xml
  :start-after: <!-- CDS rtps_psk_secret_passphrase -->
  :end-before: EOF
  :emphasize-lines: 17-18
  :caption: |CDS| Configuration to Protect Participant Announcements and Binding Pings

.. note::

  |CDS| uses |LIGHT_SP_BUILTIN| to protect the discovery announcements it relays. This
  does not limit freedom of choice for |DP| configuration. Either |LIGHT_SP_BUILTIN|
  or |SP_BUILTIN| can be used to protect |DPs|, provided that the |PSKProtection|
  configuration on the |DP| matches the |CDS|'s |PSKProtection| configuration. That is,
  the passphrase, the algorithm, and the protection kind are the same.

Protection Against a Cloud Discovery Service Participant Announcement Replay Attack
-----------------------------------------------------------------------------------

To protect against participant announcement replay attacks, |CDS| uses |PSKProtection|
which ensures that a message was not manipulated by an external attacker. Participant
announcements may, optionally, contain a monotonic epoch number, which increases with
every new participant announcement sent. A |DP| will not accept a message that was
tampered with or contains an epoch number lower or equal to the one previously received
by this |DP|. The protection mechanism can be modelled with the following formula:

.. math::

  m = \mathrm{PSK}_k\left(\mathtt{PA} \parallel \mathtt{nonce\_prefix} \parallel \mathtt{epoch}\right)

Where:

  * ``k`` is a shared secret derived from the Participant Discovery Protection Key.
  * ``nonce_prefix`` is a number bounded to the |CDS| or |DP| sending the
    participant announcement.
  * ``epoch`` is a number that is increased with every new participant announcement.

The concatenation of the ``nonce_prefix`` and the ``epoch`` is a nonce that
should be unique during the system's life. In the case of regular |DPs|, the
``nonce_prefix`` is randomly generated on the |DP| creation, with low chance of
collision. In the case of |CDS|, the ``nonce_prefix`` is derived from the |CDS|
service name (see :link_addon_products_cloud_discovery_service:`XML Tags for
Configuring RTI Cloud Discovery Service
<configuration.html#xml-tags-for-configuring-project>`). Both the
``nonce_prefix`` and ``epoch`` are fields of RTI-specific ``PID_SAMPLE_SIGNATURE``.

.. attention::

  Different instances of |CDS| must have different service names. Otherwise, the
  ``nonce_prefix`` would collide and your system may experience issues with
  discovery and connectivity loss.

The ``epoch`` is initialized with a timestamp obtained from the monotonic clock
of the host where |CDS| is running. After validating the |PSK|, a |DP| will not
accept participant announcements from |CDS| with an ``epoch`` smaller than or
equal to the last ``epoch`` received. This is how the replay attack is avoided.

With this epoch initialization schema, restarting the |CDS| instance will be okay
because the ``epoch`` will be initialized to a value greater than the last
one used before the |CDS| instance was restarted. However, a restart of the host
where |CDS| runs will be problematic because the new instantiation of |CDS| will
use an ``epoch`` smaller than the last one published since the monotonic clock
counter is reset after the host restart. The result is that the participant
announcements sent by the |CDS| instance will be ignored by the |DPs| already
present in the system, and new |DPs| will be vulnerable against replayed |CDS|
messages.

To prevent this situation, you can set the
:property:`dds.participant.discovery_config.signature_validation_persistent_state_file`
property in |CDS| to store the value of the ``epoch`` in a file every time it is
increased. A |CDS| instance will initialize its epoch to the value contained in
the file, if the file exists. For further details on |CDS| security
configuration, see :link_addon_products_cloud_discovery_service:`Security
Configuration in the Cloud Discovery Service User's Manual
<configuration.html#security>`).

Protection against participant announcement replay attacks can be enabled in |CDS|
with the following example:

.. literalinclude:: ../snippets/rwt_example.xml
  :language: xml
  :start-after: <!-- CDS signature_validation_persistent_state_file -->
  :end-before: EOF
  :emphasize-lines: 14,15,18,19,22,23
  :caption: |CDS| Configuration to Protect Against Participant Announcement Replay Attacks