.. include:: ../vars.rst

.. _chapter-overview:

********
Overview
********

One of the key values of |RTI_CONNEXT| and the |SEC_SPEC| 
is data-centricity. |CONNEXT| is not just a pipe for exchanging data, it is a 
databus you can rely on to share your data among your applications in a 
controlled, effective, and efficient way.

The |RTI_CONNEXTDATABUS| gives you real control over what information your
application is going to access. For instance, you can structure your data in
different topics, so applications can select what data they are interested in,
or even set up a content filter to make sure your applications only receive data
that meets certain criteria. As an example, you could define a topic for patient
monitoring, then configure |CONNEXT| to only deliver updates when a patient
heart rate falls below a certain threshold.

Given its data-centricity, traditional security solutions, which mostly focus on
securing a pipeline for exchanging data, do not fit
:abbr:`OMG (Object Management Group)` DDS well. Moreover, using a secure
pipeline requires one-to-one sessions between peers, which doesn't allow
multicast, so scalability is limited.

To address these issues, multiple vendors worked together to create the
|SEC_SPEC| . This specification addresses
the security aspect of the communication in a one-to-many friendly, data-centric
way: instead of securing pipelines, it enables applications to define different
security policies based on the nature of the shared data. The OMG DDS Security
specification defines a set of builtin plugins for providing interoperable
authentication, access control, cryptography, and a logging topic.

In this document we present the |RTI_SP_PRODUCT|, which are the |CONNEXT|
implementation of the OMG DDS Security builtin plugins. As you will see, the
|RTI_SP_PRODUCT| offer a DDS Security solution that is interoperable with
DDS Security implementations from other vendors.

This document is targeted at |CONNEXT| users who want to secure their DDS
systems with |RTI_SP_PRODUCT|. Therefore, we assume that you have at least
intermediate DDS knowledge, and at least a baseline understanding of security
concepts. For an introduction to |CONNEXT|, please refer to the
:link_connext_dds_pro_gsg:`RTI Connext Getting Started Guide <index.html>`.
For an introduction to the |RTI_SP_PRODUCT|, please refer
to the |SP_GSG_LINK|.

RTI provides two implementations of |RTI_SP_PRODUCT|:

* |SP_BUILTIN|: the RTI implementation of the OMG DDS Security
  builtin plugins.

* |LIGHT_SP_BUILTIN|: the RTI implementation of the OMG DDS Security
  builtin PSK plugins.

.. admonition:: Disclaimer

    Securing a distributed system is an exercise in user risk management. RTI
    expressly disclaims all security guarantees and/or warranties based on the
    names of its products, including |RTI_SP_PRODUCT| and |RTI_SP_SDK_PRODUCT|.
    Visit https://www.rti.com/terms/ for complete product terms and an exclusive
    list of product warranties.


.. _section-description-of-dds-system-threats:

Description of DDS System Threats
=================================

In a DDS system, we have a set of publishers and subscribers within a
data-centric publish-subscribe model. For example, let's analyze the system
depicted in :numref:`figure-threats`, where we have the following participants:

* **Alice**: a legitimate application publishing to |TOPIC| *T*, allowed to
  publish these samples.

* **Bob**: a legitimate application subscribing to |TOPIC| *T*, allowed to
  access that information.

* **Eve**: an eavesdropper trying to subscribe to |TOPIC| *T* without
  authorization - to perform unauthorized subscription (1).

* **Trudy**: an intruder trying to publish into the databus without
  authorization - to perform unauthorized publication (2).

* **Mallory**: a malicious insider (for instance, authorized to subscribe to
  data but not to publish) trying to perform tampering and replay (3).

* **Trent**: an Infrastructure Service that legitimately subscribes to and
  publishes data.

.. figure:: /../shared_content/static/threats.png
    :scale: 50%
    :alt: Participants communicating through the DDS Databus
    :name: figure-threats
    :align: center

    Understanding Threats to DDS Systems

Since Alice and Bob are legitimate applications, they should be able to
communicate as they were designed to. In this case, nothing should prevent them
from communicating. The same applies to Trent. However, Trudy, Eve and Mallory
should not be able to perform the malicious actions they want to perform. Note
that the attackers may be applications outside your DDS system (outsiders), or
legitimate applications in your DDS system trying to perform actions they are
not authorized to perform (insiders). Let's analyze each threat independently.


.. _section-unauthorized-subscription:

Unauthorized Subscription
-------------------------

Unauthorized subscription (aka, Eavesdropping) implies being able to read
sensitive data without authorization.

For example, suppose that we have Eve, a DDS application with a |DR| that is not
supposed to subscribe to a |TOPIC| *T*. In a non-secure scenario, Eve and Alice
will discover each other, then Alice will start sending data samples to Eve.
Since the baseline DDS and RTPS standards do not specifically address security,
they do not define any mechanism to verify whether Eve is authorized to
subscribe to |TOPIC| *T*.

Although eavesdropping is not always a problem on every |TOPIC| or every system,
the |TOPIC| *T* may carry very sensitive data (for example, medical data) and
should be protected against eavesdropping. The |RTI_SP_PRODUCT| provide mechanisms to
protect the confidentiality of data, guaranteeing that only authorized |DRs| are
able to subscribe to |TOPIC| *T* and to make sense of data published to it.


.. _section-unauthorized-publication:

Unauthorized Publication
------------------------

Unauthorized publication means publishing data onto the DDS Databus without
authorization.

For example, suppose that we have Trudy, a DDS application with a |DW| that is
not  supposed to publish |TOPIC| *T*. In an unsecure scenario, Trudy and Bob
will discover each other, then Trudy will start sending data samples to Bob.
This could be a major problem since Bob may be receiving legitimate samples from
Alice as well as forged samples from Trudy.

The |RTI_SP_PRODUCT| provide mechanisms for authenticating both publisher and subscriber
applications, preventing unauthorized publication from outsiders. Also, the
|RTI_SP_PRODUCT| put in place access control mechanisms to prevent insiders from publishing
without authorization.


.. _section-tampering-and-replay:

Tampering And Replay
--------------------

Tampering involves intercepting and modifying data before sending it to the
legitimate subscriber.

This attack can have severe consequences since the attacker could modify the
parts of the message they are interested in. For example, in a bank system a
legitimate subscriber Mallory could be receiving data samples for a |TOPIC| *T*.
This |TOPIC| could have transaction information with sender, receiver and
amount. Mallory could modify the receiver of the transaction and publish the
modified samples without anyone noticing it.

Mallory could also perform replay attacks by resending the data without
modification. In any case, Mallory could create serious problems without
security being enabled.

The |RTI_SP_PRODUCT| put in place mechanisms to protect the integrity of data, hence
preventing tampering and replay attacks.


.. _section-crossing-domains:

Crossing Domains
----------------

All the threats described above could cross DDS domains if an infrastructure
service, such as |RTI_ROUTINGSERVICE|, joins a domain being attacked by
malicious |DPs|.


.. _section-applying-dds-protection:

Applying DDS Protection
=======================

There are two major types of protection that you can achieve with the |RTI_SP_PRODUCT|.
:ref:`section-domain-level-protection` allows you to protect your entire DDS
domain against outsiders, preventing any unauthorized actions by any
unauthorized adversaries that are not supposed to participate in the domain.
There is also :ref:`section-granular-protection-inside-domains` which enables
more advanced kinds of protection to prevent unauthorized actions by legitimate
participants within the domain. This second approach is based on the Principle
of Least Privilege, so |DPs| do not get to know more than what they need to, for
the tasks they are required to do.

For a detailed review on how to use STRIDE threat modeling to analyze security
risks in DDS systems and how to mitigate different threats using the different
types of protection supported by the |RTI_SP_PRODUCT|, see
:ref:`p3_advanced/threat_modeling:Using STRIDE Threat Modeling to Analyze Security Risks in DDS Systems`.


.. _section-domain-level-protection:

Domain-Level Protection
-----------------------

Domain-level protection assumes that the network is the adversary. In other
words, it assumes that adversaries can do anything in the network. To achieve
domain-level protection, the network protocol is secured, therefore protecting
the system against any types of threats that can live inside the network. The
goal of this secured protocol is to prevent any unauthorized actions by any
adversaries that are not supposed to participate in the domain. Domain-level
protection can provide integrity as well as confidentiality.

.. _paragraph-domain-level-protection-threat-model:

Domain-Level Protection Threat Model
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The domain-level protection threat model assumes that the adversary can do
almost anything in the network, such as:

* the adversary can obtain any message passing through the network

* the adversary itself could be a legitimate user of the network and thus can
  initiate and participate in a conversation with any other user

* the adversary can become the receiver of messages

* the adversary can send messages to anybody through impersonation

* any message sent will go through the adversary

* any message received has gone through the adversary

These assumptions involve serious threats that can come from the network and
that can have undesired consequences at the DDS level, for example:

* unauthorized consumption or production of data

* tampering with data

* unauthorized replay of legitimate data

The |RTI_SP_PRODUCT| protect your DDS systems against all those undesired capabilities,
by implementing the |SEC_SPEC|'s builtin mechanisms. Note that
the |SEC_SPEC| defines a network security model, by securing the
network protocol. This implies that from the DDS Security perspective, the local
machine is assumed to be trusted.

.. admonition:: Important Note

    The |SEC_SPEC| assumes that everything that happens inside
    the machine is trusted. As a user, you have to make sure that you have all
    the protection mechanisms in place that are not related to the network
    protocol. For example, make sure you have all the protection mechanisms
    related to your file system and the physical protection of your local
    machine, such that it becomes a trusted platform.

    The threats that are associated with the platform are outside of the scope
    of DDS Security (and therefore outside of the scope of |RTI_SP_PRODUCT|).


.. _paragraph-domain-level-protection:

Domain-Level Protection From Outsider Adversaries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Domain-level protection is a fairly simple model but it may be good enough for
some situations. With domain-level protection, your protected domains are the
boundaries. You provide the participants with the ability to join the domain,
and once a participant is in the domain, it can do anything. Hence, for
legitimate participant, the domain looks like an unsecure |DDS_DOMAIN|, and the
same protection applies to every topic in the domain (see
:numref:`figure-protection-at-boundaries`). All participants need to do is to
authenticate and prove they have the right to participate, after which they can
do anything as if security were disabled.

.. figure:: ../static/protection-at-boundaries.png
    :scale: 50%
    :alt:
    :name: figure-protection-at-boundaries
    :align: center

    Protecting the DDS Domain at the Boundaries


Using domain-level protection, the |RTI_SP_PRODUCT| can prevent unauthorized RTPS protocol
actions by outsider adversaries which should not join the domain. In particular,
|RTI_SP_PRODUCT| can:

* detect the modification or injection of messages (integrity)
* keep message contents secret (confidentiality)

This is done by including additional information in the RTPS messages sent by
your Secure Participants, as explained in
:ref:`section-protecting-the-rtps-protocol`.

Domain-level protection can be achieved with TLS as a transport since it
forces authentication between participants. This can be useful in some
scenarios, but it presents some drawbacks with respect to using the |RTI_SP_PRODUCT|, as
described in :ref:`section-choosing-the-right-technology-to-protect-your-data`.


.. _section-granular-protection-inside-domains:

Granular Protection Inside Domains
----------------------------------

Protection inside domains provides more advanced kinds of protection by
following the Principle of Least Privilege, which implies that participants do
not get to do (or know) more than they need to do (or know) in order to complete
their tasks. This Principle of Least Privilege is based on read and write access
rules per topic and partition. After you define these access rules, the |RTI_SP_PRODUCT|
detect and prevent violations of these access rules.


.. _paragraph-granular-protection-threat-model:

Granular Protection Threat Model
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Similarly to the domain-level protection thread model, protection inside domains
assumes that the network is the adversary. However, it also considers that there
can be malicious insiders in the system, in addition to outsiders. Insiders are
legitimate participants that are allowed in the domain, but that perform actions
they're not supposed to do. These actions range from unauthorized subscription
and publication to data replay and tampering, as described in
:ref:`section-description-of-dds-system-threats`.


.. _paragraph-applying-granular-protection:

Applying Granular Protection Inside Domains
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In addition to the domain-level protection, where you protect your system from
outsiders that are not supposed to participate in the domain, protection inside
the domain implies that there are different levels of trust within the domain
(between all the participants allowed to participate in the domain). This
follows the Principle of Least Privilege per |DP|, meaning that
each participant will only be allowed to perform the required actions for its
legitimate purpose. You cannot achieve granular protection inside domains with
TLS transport security.

To use this model, you have to identify the required publish/subscribe
authorizations. You have to answer the question, “what does each participant
need to publish or subscribe to, in order to do its job?” This authorization has
to happen with the granularity of per |DOMAIN|, per |TOPIC|, or per partition.

Once you identify these required authorizations, you can define access rules
accordingly. In other words, once you know what each participant needs to do to
accomplish its tasks correctly, you can write access rules on a per-participant
basis. Each rule defines which |TOPICs| or partitions a |DP| is allowed to
publish, and which |TOPICs| or partitions it is allowed to subscribe to. The
|RTI_SP_PRODUCT| will detect and prevent any violations of these rules. For example, they
will keep the data secret for those who do not have a need-to-know; and they
will detect unauthorized injection or replay of data by those who are not
allowed to modify data.

.. figure:: ../static/protection-inside-domains.png
    :scale: 50%
    :alt:
    :name: figure-protection-inside-domains
    :align: center

    Granular Protection Inside Domains


:numref:`figure-protection-inside-domains` depicts a scenario where three
participants (|P1|, |P2|, and |P3|) have permission to both publish and
subscribe to the :topic:`blue` |TOPIC|, while only |P1| has these permissions
for the :topic:`red` |TOPIC| -- |P2| can still subscribe to it (single-headed
arrow), but |P3| does not have access to it. As this scenario suggests, the
protection inside domains applies to specific |TOPICs| and partitions, and not
every |DP| is allowed to publish or subscribe to every |TOPIC| or partition.
You can protect the confidentiality and integrity of each |TOPIC| and
partition independently. So, for each of your |DOMAINs|, you can apply
different protections as needed at the granularity of per |TOPIC| or per
partition.


.. _section-protecting-the-rtps-protocol:

Protecting the RTPS Protocol
----------------------------

To prevent unauthorized actions in your secure domain, the DDS Security
specification adds security enhancements to the RTPS protocol. Since you may
face open networks, where anyone could join and start receiving the data, the
only protection mechanism available is to protect the |RTPSmsgs| themselves.

The |RTI_SP_PRODUCT| will add information and modify the |RTPSmsgs| to
protect them. Authentication and key establishment, which are performed by
|DPs| using the |SP_BUILTIN|, use asymmetric cryptography.
Conversely, all the protections applied at the RTPS level are based on
symmetric cryptography, which is required for highly performant, one-to-many
distribution with one-time encryption. Therefore, both the sender and receiver
need to know the secret symmetric key.

The |SEC_SPEC| uses three different kinds of symmetric keys:

- Pre-Shared Key (|PSK|): A key that is distributed out-of-band to the RTPS Protocol and
  that enables |PSKProtection|.

- SHared secret Key (|SHK|): A key that is established between a pair of
  authenticated |DPs| using a Key Establishment algorithm (e.g., Diffie-Hellman).
  This key is used to protect the Secure Key Exchange Builtin Topic (see
  :ref:`p2_core/elements_dds_secure_system:Secure Key Exchange Builtin Topic (ParticipantVolatileMessageSecure)`).

- Authenticated eXchanged Key (|AXK|): A key that is distributed to authenticated
  |DPs| through the Secure Key Exchange Builtin Topic (see
  :ref:`p2_core/elements_dds_secure_system:Secure Key Exchange Builtin Topic (ParticipantVolatileMessageSecure)`).

.. note::

  Unless the documentation indicates differently, the keys (or |KeyMaterial|)
  associated with the |SecEntities| are considered to be |AXK|.

.. note::

  |RTI_SP_PRODUCT|'s cryptographic algorithms never use the |KeyMaterial|
  directly to protect communications. |RTI_SP_PRODUCT| always derives temporary
  |SessionKeys| from the |KeyMaterial|. For more information, please refer to
  :ref:`p2_core/cryptography:Architecture of Secure Entities`.

.. note::

    We refer to “senders” and “receivers” (as opposed to |DWs| and |DRs|). This
    is because both |DWs| and |DRs| can act as sender and receiver (for example,
    a |DW| can send a HEARTBEAT and its matching |DRs| need to respond with an
    ACKNACK).

The supported cryptographic algorithms that you can use with the
|RTI_SP_PRODUCT| are specified in :ref:`section-supported-cryptographic-algorithms`.


.. _section-protecting-bootstrapping-messages:

Protecting Bootstrapping
^^^^^^^^^^^^^^^^^^^^^^^^
As we covered above, |DPs| exchange |AXK| keys after the authentication process is
complete (using the Secure Key Exchange Builtin Topic). As a consequence of
this, certain |RTPSmsgs| cannot be protected using |AXK| keys.
These include messages used during authentication, messages used to detect
initial presence, and lower-level messages used to detect and maintain
network connectivity. The |SEC_SPEC| groups all of these kinds
of messages as |RTPSbootmsgs|.

An |RTPSmsg| is called a |RTPSbootmsg| if and only if one or
more of the following conditions applies:

* It contains |RTPSsubmsgs| for the SPDP Participants Builtin Topic
  (*DCPSParticipant*/*DCPSParticipants*).

* It contains |RTPSsubmsgs| for the SPDP2 Bootstrap Builtin Topic
  (*DISCParticipantBootstrap*).

* It contains |RTPSsubmsgs| for the Authentication Builtin Topic
  (*DCPSParticipantStatelessMessage*).

* It contains |RTPSsubmsgs| for the Secure Key Exchange Builtin Topic
  (*DCPSParticipantVolatileMessageSecure*).

* It is not intended to be processed by a DomainParticipant (e.g. it is a
  transport-level keep-alive message).

Since |RTPSbootmsgs| cannot be protected using |AXK| keys, |PSKProtection| is the
mechanism the |SEC_SPEC| designates to protect |RTPSbootmsgs|.
To learn more about how |PSKProtection| works, read the
:ref:`p3_advanced/pre-shared_key:|PSKProtection|` section.

.. _section-protecting-integrity:

Protecting Integrity
^^^^^^^^^^^^^^^^^^^^

Protecting the integrity of the messages is achieved by appending a Message
Authentication Code (MAC) to the original message. By default, this code is
16-bytes long. The contents of the MAC depend on the original message's contents
as well as a secret key. You need the secret key to both create and validate a
MAC, as depicted in :numref:`figure-mac-computation-validation`. Therefore both
the sender and receiver need to know the secret key. The same secret key is used
by the sender and all its receivers. If there is a failure to validate the MAC
on the receiver side, that implies a breach of integrity.

.. figure:: ../static/mac.png
    :scale: 50%
    :alt:
    :name: figure-mac-computation-validation
    :align: center

    Creation and validation of a message by means of a Message Authentication
    Code


.. _section-protecting-confidentiality:

Protecting Confidentiality
^^^^^^^^^^^^^^^^^^^^^^^^^^

MACs provide integrity protection, therefore an attacker will not be able to
tamper with data, since modifications to data will be detected as a failure to
verify the MAC. However, the MAC itself does not protect confidentiality. If you
need confidentiality, the data has to be encrypted before it is sent on the
wire. The encrypted bytes are generated from the message and a secret key.
Therefore, both sender and receiver need to know the same key.

Encryption itself does not guarantee data integrity. Therefore, the |RTI_SP_PRODUCT| compute
a MAC over the encrypted data and include it in the resulting message. In
practice, the |SEC_SPEC| defines integrity protection and
confidentiality plus integrity protection.

Following the philosophy of the :link_external_dds_spec:`OMG Data Distribution Service
(DDS) standard <>` the |SEC_SPEC| follows a data-centric model, where
everything is distributed. This implies that all legitimate participants joining
the |DDS_DOMAIN| will execute the required protection. That is how they can
communicate with each other (they execute the same types of protection) while
outsiders are prevented from participating (because of that protection). In
other words, if a participant does not execute the required protection, it will
not be able to communicate with the rest of participants in the |SecDomain|.


.. _section-overview-origin-authentication-protection:

Origin Authentication Protection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can also enforce Data Origin Authentication. For example, if you have a
|DW| that matches with multiple |DRs|, all the readers receive the
data from the same writer. Hence, all the readers need to know the same secret
key that is used to encrypt and decrypt the data and to compute and validate the
MAC. If this secret key is shared between hundreds of readers, then all these
readers have the knowledge to reproduce the encryption and the computation of
the MAC because the key is the same as the one used by the writer. In other
words, a reader could impersonate a writer, producing a breach of the access
control mechanism. If readers don't trust each other, you can put in place the
|OrigAuthProtection|.

This type of protection requires additional keys to be utilized in the system.
More concretely, in addition to the |SenderKey|, we will have one |RecSpecificKey|
per sender-receiver pair. Note that both |DWs| and |DRs| can act as senders and
receivers. Also, RTPS messages and submessages will be appended with
additional MACs (one per receiver).

In the previous example, the |DW| will append a list with the additional
|RecSpecificMACs| to the |CommonMAC|. Then, after regular |CommonMAC|
validation, every |DR| has to find its |RecSpecificMAC| inside that
list and verify that the |RecSpecificMAC| was calculated with the secret
key it specifically created for use between itself and the |DW|. By verifying
the |CommonMAC|, the |DR| can trust that data was not tampered with by anyone
who doesn't have the |SenderKey|, since that key is needed to generate the
common MAC. And by verifying the |RecSpecificMAC| the |DR| can verify the
matching |DW| sent that data since it is the only entity the |RecSpecificKey|
was shared with.


.. _sec-introduction-to-the-rti-sp:

Introduction to the |RTI_SP_PRODUCT_HEADING|
============================================

|RTI_SP_PRODUCT| allow you to address your databus security requirements in a
granular and pluggable way. To support this, |RTI_SP_PRODUCT| defines
a plugin-based architecture, where each plugin covers a different aspect of
security:

* **Authentication**. Provides the means to verify the identity of the
  application and/or user that invokes operations on DDS. Includes facilities to
  perform mutual authentication between |DPs| and establish a shared secret.

* **Access Control**. Provides the means to enforce policy decisions on what
  DDS-related operations an authenticated entity can perform. For example, which
  |DOMAINs| it can join, which |TOPICs| it can publish or subscribe to, etc.

* **Cryptography**. Implements (or interfaces with libraries that implement) all
  cryptographic operations including encryption, decryption, hashing, digital
  signatures, etc. This includes the means to derive keys from a shared secret.

* **Logging**. Supports auditing of all DDS security-relevant events, allowing
  you to increase the system's visibility, which may help track and improve
  system's availability. These security-related events can be propagated
  securely through DDS.

The |SEC_SPEC| defines two sets of builtin plugins for providing
interoperable authentication, access control, cryptography, and a secure logging
topic. Similarly, |RTI_SP_PRODUCT| provide two different sets of plugins:

* |SP_BUILTIN|: the RTI implementation of the OMG DDS Security
  builtin plugins (defined in |SEC_SPEC_12|).

* |LIGHT_SP_BUILTIN|: the RTI implementation of the OMG DDS Security
  builtin PSK plugins  (defined in |SEC_SPEC_12|).
  This implementation is meant to support resource-constrained environments that
  are not capable of running |SP_BUILTIN|.

This way, the |RTI_SP_PRODUCT| offer a DDS Security solution that can
interoperate with DDS implementations from other vendors.

.. figure:: /../shared_content/static/plugins-architecture.png
    :scale: 50%
    :alt:
    :name: figure-arch-security-plugins
    :align: center

    Architecture of an application using |RTI_SP_PRODUCT|. |RTI_SP_PRODUCT|
    provide two different sets of plugins: |SP_BUILTIN| and |LIGHT_SP_BUILTIN|.


.. _section-features-of-rti-sp:

Features of |RTI_SP_PRODUCT_HEADING|
------------------------------------

* Decoupled plugins to address different security aspects, as defined in the
  |SEC_SPEC|.

* The |RTI_SP_PRODUCT| can potentially run over any transport, including the
  builtin UDP transport with multicast and TCP transport.

* Secure multicast support enables efficient and scalable distribution of data
  to many subscribers.

* You can customize the |RTI_SP_PRODUCT| to accommodate proprietary or FIPS 140-2
  compliant cryptography solutions, take advantage of custom security hardware
  or change the behavior of the plugins in any number of ways. The
  |RTI_SP_SDK_PRODUCT| enables you to customize the |RTI_SP_PRODUCT| to meet
  your system's security requirements.

* The |SEC_SPEC| addresses the security aspect of the
  communication in a one-to-many, friendly, data-centric way, enabling
  applications to define different security policies based on the nature of the
  shared data. This aligns with the decentralized nature of DDS and asserts its
  benefits:

    * No single point of failure

    * High performance and scalability


.. _section-supported-cryptographic-algorithms:

Supported Cryptographic Algorithms
----------------------------------

A cryptographic algorithm is a well-defined computational procedure that takes
variable inputs, including a cryptographic key and produces an output.

The |RTI_SP_PRODUCT| implement a variety of cryptographic algorithms to support
different aspects of security. In particular, the |RTI_SP_PRODUCT| implement all
of the cryptographic algorithms specified by the |SEC_SPEC|.
In this section we will list all of the algorithms the |RTI_SP_PRODUCT| use.

Cryptographic Algorithms Used for Data Flow Protection with |PSKProtection|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Data integrity and confidentiality:

    * Algorithms:

        * AES-GMAC

            * **Purpose:** Data integrity

            * **Availability:** |SP_BUILTIN| and |LIGHT_SP_BUILTIN|

            * **Specification:** Included in |SEC_SPEC_12|

            * **Key Sizes:** 128 or 256

        * AES-GCM

            * **Purpose:** Data integrity and confidentiality

            * **Availability:** |SP_BUILTIN| and |LIGHT_SP_BUILTIN|

            * **Specification:** Included in |SEC_SPEC_12|

            * **Key Sizes:** 128 or 256

        * SM4-GMAC

            * **Purpose:** Data integrity

            * **Availability:** |LIGHT_SP_BUILTIN| only

            * **Specification:** Not included in |SEC_SPEC|

            * **Key Sizes:** 128

        * SM4-GCM

            * **Purpose:** Data integrity and confidentiality

            * **Availability:** |LIGHT_SP_BUILTIN| only

            * **Specification:** Not included in |SEC_SPEC|

            * **Key Sizes:** 128

* Data source authentication:

    * None

* Key derivation:

    * AES-GMAC & AES-GCM: HMAC-based Key Derivation Function (HKDF) [#HKDF]_ with SHA-256.
    * SM4-GMAC & SM4-GCM: HMAC-based Key Derivation Function (HKDF) [#HKDF]_ with SM3.

Cryptographic Algorithms Used for Data Flow Protection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Data integrity and confidentiality:

    * AES-GCM:

        * **Purpose:** Data integrity and confidentiality

        * **Availability:** |SP_BUILTIN|

        * **Specification:** Included in |SEC_SPEC|

        * **Key Sizes:** 128, 256

    * AES-GMAC:

        * **Purpose:** Data integrity

        * **Availability:** |SP_BUILTIN|

        * **Specification:** Included in |SEC_SPEC|

        * **Key Sizes:** 128, 256

* Data source authentication:

    AES-GMAC:

        * **Purpose:** Protects RTPS message origin authentication

        * **Availability:** |SP_BUILTIN|

        * **Specification:** Included in |SEC_SPEC|

        * **Key Sizes:** 128, 256

* Key derivation:

    * HMAC-based key derivation with SHA-256 (not configurable).

By default, the |CryptoPlugin| uses AES-256-GCM for protecting the
confidentiality and integrity of the messages and AES-256-GMAC when only
protecting the integrity is required. This implies that the symmetric keys will
be 256-bit long, but you can also use 128-bit keys
(see the :property:`dds.sec.crypto.symmetric_cipher_algorithm` property in
:numref:`Properties for Configuring Cryptography Affecting Any Cryptography Plugin`).

As stated by the |SEC_SPEC|, the use of (Galois) counter mode
allows authenticated decryption of blocks in arbitrary order. This is very
important for DDS because a |DR| may not receive all the samples written by a
matched |DW|. The use of *DDS ContentFilteredTopics* as well as DDS QoS policies
such as *History* (with :xmlval:`KEEP_LAST` kind), *Reliability* (with
:xmlval:`BEST_EFFORT` kind),
*Lifespan*, and *TimeBasedFilter*, among others, can result in a |DR|
receiving a subset of the samples written by a |DW|.

The AES-GCM transformation produces both the ciphertext and a message
authentication code (MAC) using the same secret key. This is sufficient to
protect the plaintext and ensure integrity. However there are situations where
multiple MACs are required. For example when a |DW| shares the same key with
multiple |DR| and, in spite of this, the |DW| needs to ensure message-origin
authentication. In this situation the |DW| should create a separate
“reader-specific key” used only for authentication and append additional
reader-specific MACs, each computed with one of the reader-specific keys.


Cryptographic Algorithms Used for Key Exchange
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Key establishment:

    * Support for Diffie-Hellman in ephemeral mode (DHE), with  2048-bit
      MODP Group parameters as specified in RFC 3526 (not configurable).

      * Included in |SEC_SPEC|

    * Support for EC Diffie-Hellman in ephemeral mode (ECDHE), with secp256r1 as
      specified in FIPS PUB 186-4 [#fips186]_ as its curve.

      * Included in |SEC_SPEC|

    * Support for EC Diffie-Hellman in ephemeral mode (ECDHE), with secp384r1 as
      specified in FIPS PUB 186-4 [#fips186]_ as its curve.

      * Included in |SEC_SPEC_12|

    * **<< EXPERIMENTAL >>** Support for EC Diffie-Hellman in ephemeral mode
      (ECDHE), using X25519 as specified in RFC7748
      (https://datatracker.ietf.org/doc/html/rfc7748). Only supported in
      the |RTI_SP_PRODUCT| for OpenSSL, disabled by default
      (see the :property:`authentication.enable_experimental_algorithms`
      property in :numref:`|RTI_SP_PRODUCT_HEADING| Properties for Configuring Authentication`).

      * The |SEC_SPEC| does not support this algorithm.

    * **<< EXPERIMENTAL >>** Support for EC Diffie-Hellman in ephemeral mode
      (ECDHE), using X448 as specified in RFC7748
      (https://datatracker.ietf.org/doc/html/rfc7748). Only supported in
      the |RTI_SP_PRODUCT| for OpenSSL, disabled by default
      (see the :property:`authentication.enable_experimental_algorithms`
      property in :numref:`|RTI_SP_PRODUCT_HEADING| Properties for Configuring Authentication`).

      * The |SEC_SPEC| does not support this algorithm.

    * Selection of the key establishment algorithm happens via configuration.

* Key derivation:

    * HMAC-based Key Derivation Function Extract (HKDF-Extract) with SHA-256
      (not configurable) [#HKDF]_.

* Key exchange confidentiality, which includes integrity:

    * AES-GCM with 256 bits key (not configurable).


Cryptographic Algorithms Used for Digital Signatures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Builtin support for 2048-bit RSA key pairs with SHA-256

    * Support for RSASSA-PSS as specified in PKCS #1
      (`RFC 3447 <https://datatracker.ietf.org/doc/html/rfc3447>`_), using
      MGF1 with SHA-256 as a mask generation function.

      * Included in |SEC_SPEC|

    * Support for RSASSA-PKCS1-v1_5 as specified in PKCS #1
      (`RFC 3447 <https://datatracker.ietf.org/doc/html/rfc3447>`_).

      * Included in |SEC_SPEC_12|.

    * Selection between RSASSA-PSS and RSASSA-PKCS1-v1_5 happens via
      configuration (see the :property:`authentication.rsa_pss_pad` property in
      :numref:`|RTI_SP_PRODUCT_HEADING| Properties for Configuring Authentication`).

* Builtin support for ECDSA secp256r1 key pairs with SHA-256

    * The curve is as specified in FIPS PUB 186-4 [#fips186]_, and the digest
      algorithm is SHA-256.

    * Included in |SEC_SPEC|

* Builtin support for ECDSA secp384r1 key pairs with SHA-384

    * The curve is as specified in FIPS PUB 186-4 [#fips186]_, and the digest
      algorithm is SHA-384.

    * Included in |SEC_SPEC_12|.

* **<< EXPERIMENTAL >>** Builtin support for EDDSA Ed25519 key pairs.

    * The algorithm used is PureEdDSA and the curve Ed25519 as specified in
      RFC8032 (https://datatracker.ietf.org/doc/html/rfc8032). Only supported in
      the |RTI_SP_PRODUCT| for OpenSSL, disabled by default
      (see the :property:`authentication.enable_experimental_algorithms`
      property in :numref:`|RTI_SP_PRODUCT_HEADING| Properties for Configuring Authentication`).

    * The |SEC_SPEC| does not include this curve.

    * This curve is not supported in the context of signing Governance
      or Permissions documents.

* **<< EXPERIMENTAL >>** Builtin support for EDDSA Ed448 key pairs.

    * The algorithm used is PureEdDSA and the curve Ed448 as specified in
      RFC8032 (https://datatracker.ietf.org/doc/html/rfc8032) with the
      context parameter set to zero. Only supported in
      the |RTI_SP_PRODUCT| for OpenSSL, disabled by default
      (see the :property:`authentication.enable_experimental_algorithms`
      property in :numref:`|RTI_SP_PRODUCT_HEADING| Properties for Configuring Authentication`).

    * The |SEC_SPEC| does not include this curve.

    * This curve is not supported in the context of signing Governance
      or Permissions documents.

* Selection of the key pairs happens via configuration

.. [#HKDF] works as specified in RFC5869: HMAC-based Extract-and-Expand Key Derivation 
  Function (HKDF) - https://datatracker.ietf.org/doc/html/rfc5869.

.. _section-choosing-the-right-technology-to-protect-your-data:

Choosing the Right Technology to Protect Your Data
--------------------------------------------------

If your main goal is domain-level protection, you may want to protect your
transport by using TLS instead of using the |RTI_SP_PRODUCT|. This transport
layer is well known and well documented, and the protection level that you will
have is identical to that of the |RTI_SP_PRODUCT| unless you need fine-grained
control. However, there are some differences between securing the transport and
using the |RTI_SP_PRODUCT|.

DDS Security is a standard from the OMG, while the TLS transport is a component
provided by RTI, but not standardized. Consequently, a |CONNEXT| application
using a TLS transport will not interoperate with other vendor's implementations.

TLS applies at the transport layer, so it secures the pipe. On the other
hand, DDS Security provides finer control, as described in
:ref:`section-granular-protection-inside-domains`. With TLS you can protect the
information that goes on the wire between two DDS applications, but you cannot,
for instance, give different permissions to different applications. All of your
applications must have the same level of access control, only the pipe is
secured. With |SP_BUILTIN|, you have finer control, so you can, for instance,
give an application permission to publish or subscribe to data on a |DDS_DOMAIN|
but only for a subset of the topics. This is possible in the |SP_BUILTIN|, but
not in the |LIGHT_SP_BUILTIN|. For more information about choosing one library
or the other, see
:ref:`p3_advanced/pre-shared_key:|PSKProtection| in |LIGHT_SP_BUILTIN_HEADING| vs. |PSKProtection| in |SP_BUILTIN_HEADING|`.

There are also performance implications. TLS does not support multicast,
therefore your data will be re-encrypted as many times as the number of
destinations, which seriously constrains your system's scalability. One of the
nice features of |RTI_SP_PRODUCT| is that it supports secure multicast
communications, so you can scale your one to multi-end communications. See
:ref:`p3_advanced/design_considerations:Interaction Between the |RTI_SP_PRODUCT_HEADING| and Multicast`.

Finally, there is the aspect of pluggability. You cannot adapt the TLS
transport easily. With the |RTI_SP_PRODUCT|, you can, for instance, plug in
your own encryption, or your own signing algorithms. With TLS, you can only use
what the transport has to offer.

.. [#fips186] Note FIPS PUB 186-4 explicitly refers to P-256 and P-384. P-256 is
  equivalent to secp256r1, and P-384 is equivalent to secp384r1 -
  https://tools.ietf.org/html/rfc4492#appendix-A
