.. include:: ../vars.rst

.. _chapter-using-dds-secure:

************************
Using Connext DDS Secure
************************


.. _section-securing-distributed-systems:

Securing Distributed Systems
============================


In a DDS Secure system, a |GovernanceDoc| defines the security requirements for
communication. This file contains a mapping between domain IDs and the security
policies that all |DPs| must follow to interact in that domain. In other words,
the |GovernanceDoc| defines what types of protection will be applied to your
|SecDomains| and how specific |TOPICs| will be protected.

All the |DPs| in your secure system need to load the same (or compatible)
|GovernanceDoc|, either by having a copy of it, or by accessing a single
|GovernanceDoc| from a common location. In addition to meeting the security
requirements specified in the |GovernanceDoc|, every |DP| joining a |SecDomain|
must be associated with a |PermissionsDoc|. This |PermissionsDoc| contains a
set of grants, which determine what the local participant is allowed to do in
the secure domain. For example, a publisher application, Alice, should only have
permission to publish specific |TOPICs|; a subscriber application, Bob, should
only have permission to subscribe to specific |TOPICs|, but not have permission
to publish any |TOPICs|.

This step of creating |PermissionsDocs| goes beyond many traditional methods of
security, where an application that is allowed to communicate within a secure
system is generally assumed to be safe, and may be able to access data that it
should not. The use of |PermissionsDocs| locks down the specific access that
trusted applications have, so if one application becomes compromised, the damage
to the system is limited.


.. admonition:: Key Terms

    A **Governance Document** defines how your system is protected, while
    **Permissions Documents** define who can access what.

Both the Governance and Permissions Documents have to be signed by the Permissions
Certificate Authority (CA). The Permissions CA must be shared by all
|DPs|, therefore any |DP| trusting that Permissions CA can verify whether
another |DP| has the permissions it claims (see
:ref:`p2_core/elements_dds_secure_system:Governance and Permissions`).

Governance and Permissions Documents allow you to define the security requirements
of your system in a data-centric way.

All the |DPs| joining your secure domain have to meet the requirements specified
in the |GovernanceDoc| in order to communicate. System-wide security
requirements are completely defined by the following files:

* **Permissions CA Certificate:** |br|
  Shared by all the |DPs| in your secure system. The Permissions CA Certificate
  is used to verify that Permissions and Governance Documents are legitimate.

* **Identity CA Certificate:** |br|
  Shared by all the |DPs| in your secure system [#]_. The Identity CA
  Certificate is used to authenticate the remote |DPs|, by verifying that the
  Identity Certificates are legitimate.

* **Governance Document:** |br|
  Shared by all the |DPs| in your secure system. The |GovernanceDoc| specifies
  which domains should be secured and how. It is signed by the Permissions CA.

For further details on these files, refer to
:ref:`p2_core/elements_dds_secure_system:Elements of a Connext DDS Secure System`.
Note that the Identity CA and Permissions CA may be the same, depending on your use case.


.. _securing-a-domainparticipant:

Securing a DomainParticipant
============================

|DPs| in a |SecDomain| need to be mutually authenticated. To achieve this, every
|SecDP| has an Identity Certificate and a Private Key [#]_. These documents are
needed to perform mutual authentication and to establish shared secrets in a
secure way, by using the Diffie-Hellman public-key protocol.

To prevent attackers from forging identities, all the Identity Certificates in
your system have to be signed by an Identity CA. As part of the authentication
process, secure |DPs| will use the Identity CA certificate to
validate the identity of discovered peers.

Authenticated participants claim permissions by exchanging their
|PermissionsDocs|. To verify that the |PermissionsDoc| provided by a remote
participant is legitimate, |PermissionsDocs| have to be signed by the
Permissions CA. In addition, the grants in a |PermissionsDoc| are bound to an
Identity Certificate, therefore only the |DP| proving that identity in the
Authentication can claim these permissions.

The identity and permissions of a |DP| are completely defined by the following
additional files:

* **Identity Certificate** signed by the Identity CA. Other participants
  will request this certificate to verify the identity of the local
  participant.

* **Private key**, only known to the local participant. It is needed
  to complete the authentication process, which provides a way of
  verifying the identity and setting a shared secret.

* **Permissions Document** signed by the Permissions CA. This document
  specifies what |DOMAINs| and |PARTITIONs| the local participant
  can join and what |TOPICs| it can read/write.

.. figure:: /../shared_content/static/artifacts.png
  :scale: 50%
  :name: figure-artifacts
  :align: center

  Minimal security artifacts needed for communication

:numref:`figure-artifacts` depicts two |DPs| with the minimal security artifacts
they need for communication. In
:ref:`p2_core/elements_dds_secure_system:Elements of a Connext DDS Secure System`
we will explore all of these elements in detail.


.. [#] Depending on your use case, different |DPs| may trust a different
        Identity CA, for example, when several intermediate CAs exist in your PKI.

.. [#] Private keys need to be securely stored and securely accessed by the
        local application. The |SP| do not provide a secure storage mechanism.
        You are responsible for storing your private keys in a secure place.