.. include:: vars.rst

.. _section-sec-securing-domain:

Securing a DDS Domain
=====================

In a DDS Secure system, a **Governance Document** defines the security
requirements for communication. This file contains a mapping between |DOMAIN|
IDs and the security policies that |DPs| must follow to interact in that
|DOMAIN|. Some examples of those rules are:
 
 .. list-table::
    :name: ExampleRules
    :widths: 30 40 30
    :header-rows: 1
    :class: longtable

    * - Governance rule
      - Description
      - Possible values
    * - :xmltag:`discovery_protection_kind`
      - The level of protection |DPs| must use for discovery
      - :xmlval:`NONE`, :xmlval:`SIGN`,
        :xmlval:`SIGN_WITH_ORIGIN_AUTHENTICATION`, :xmlval:`ENCRYPT` or
        :xmlval:`ENCRYPT_WITH_ORIGIN_AUTHENTICATION`
    * - :xmltag:`allow_unauthenticated_participants`
      - Whether unauthenticated |DPs| may communicate within the |DOMAIN|
      - :xmlval:`TRUE` or :xmlval:`FALSE`
    * - :xmltag:`data_protection_kind`
      - The level of protection that should be used for data of individual
        |TOPICs| within that |DOMAIN|
      - :xmlval:`NONE`, :xmlval:`SIGN`,
        :xmlval:`SIGN_WITH_ORIGIN_AUTHENTICATION`, :xmlval:`ENCRYPT` or
        :xmlval:`ENCRYPT_WITH_ORIGIN_AUTHENTICATION`

Going back to our example, the hospital can now protect the confidentiality
of |TOPIC| *T* by setting its :xmltag:`data_protection_kind` to
:xmlval:`ENCRYPT` in the |DOMAINS|
where it is published. With this, Eve will not be able to guess the vital
signs of the patients, even if she has access to the messages being exchanged
in the |SecDomain|.

As you can see, the rules that compose the |GovernanceDoc| specify how
your system is protected. All the |DPs| in your secure system need to load the
same [#GovernanceFile]_ |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 **Permissions Document**. This |PermissionsDoc| contains
a set of grants, which determine what the local participant is allowed to
do in the |DOMAIN|.

For example, Alice should only have permission to publish |TOPIC| *T*, since her
only mission is to monitor patient vitals. On the other hand, Bob's role is to
display everything related to patients' health conditions. Therefore, he
should have permission to subscribe to any |TOPIC| related to patients'
health, but he should not be allowed 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 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.

To prevent Mallory from pretending to have permission to both publish
and subscribe to |TOPIC| *T*, both Governance and Permissions Documents are signed
by the **Permissions Certificate Authority (CA)**. The Permissions CA must
be shared by all |DPs| [#PermissionsCA]_, therefore any |DP|
trusting that Permissions CA can verify whether another |DP|
has the permissions it claims.

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

In :ref:`section-sec-HO2`, you will define the security requirements of your
secure |DDS_DOMAIN|. All the |DPs| joining your |SecDomain|
will have to meet these requirements 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. [#PermissionsCA]_
  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. [#IdentityCA]_
  The Identity CA certificate is used to authenticate  the remote
  |DPs|, by verifying that the Identity Certificates are
  legitimate (see :ref:`section-sec-securing-domainparticipant`).
* **Governance Document:** |br|
  Shared by all the |DPs| in your secure system. [#GovernanceFile]_
  The |GovernanceDoc| specifies which |DOMAINs| should be secured and how.
  It is signed by the Permissions CA.

.. note::

   The Identity CA and Permissions CA may be the same, depending on
   your use case.

.. [#] This approach is based on the Principle of Least Privilege. For further
  information, see :link_connext_dds_secure_um:`Applying DDS Protection in the Security
  Plugins User's Manual <p1_welcome/overview.html#applying-dds-protection>`.

.. [#GovernanceFile] If not the same, at least |GovernanceDocs| loaded by
  different |DPs| need to be compatible. For further information, see
  :link_connext_dds_secure_um:`Governance Document
  <p2_core/elements_dds_secure_system.html#governance-document>`
  in the |SP_UM|.

.. [#PermissionsCA] In systems where multiple Permissions Certificate
  Authorities may exist, you can use the
  :property:`access_control.alternative_permissions_cas` property to specify
  alternative Permissions CA certificates. For further details, see
  :link_connext_dds_secure_um:`Governance and Permissions
  <p2_core/elements_dds_secure_system.html#governance-and-permissions>`
  in the |SP_UM|.

.. [#IdentityCA] Depending on your use case, different |DPs| may trust a
  different Identity CA, for example, when several intermediate CAs exist in
  your PKI. For further details, see :link_connext_dds_secure_um:`Alternative CAs
  <p2_core/elements_dds_secure_system.html#alternative-cas>`
  in the |SP_UM|.

.. _section-sec-securing-domainparticipant:

Securing a DomainParticipant
----------------------------

As introduced in the previous section, the |PermissionsDoc| defines
what a specific |DP| is allowed to do in a secure |DDS_DOMAIN|.
However, |PermissionsDocs| need to be exchanged to claim and
verify permissions. This means that Mallory, who will not give up that
easily, may intercept some |PermissionsDocs| and pretend to be the
legitimate holder of those permissions. To avoid this situation,
|DPs| in a |SecDomain| need to be mutually authenticated.
To achieve this, every secure |DP| 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 Mallory from forging her own identity, all the |IdentityCerts|
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.

If a |DP| cannot be authenticated, it won't be allowed
to publish or subscribe to protected |TOPICs|. Depending on the policies
defined in the |GovernanceDoc|, it will be restricted to unprotected
|TOPICs| or it won't be allowed to communicate at all (see
:xmltag:`allow_unauthenticated_participants` in the
:link_connext_dds_secure_um:`Related Governance Attributes for Authentication
<p2_core/authentication.html#related-governance-rules>`)
in the |SP_UM|.

Because Mallory cannot forge her own identity, she will fail to
authenticate, thus she will not be able to claim any permissions.
That guarantees that Mallory will not be able to publish or subscribe
to |TOPIC| *T*.

In :ref:`section-sec-HO3`, you will provide an identity to your
|DPs| and set the permissions for each of them.
The steps in this hands-on exercise guarantee that if an attacker is able to
compromise a trusted application in the system, the damage they can 
do is limited. The following files define the identity and permissions of a |DP|
entirely:

* **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 |SharedSecret|.
* **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
    :name: FigureArtifacts
    :align: center

    Two |DPs| (|P1| and |P2|) using the |RTI_SP_PRODUCT|, along
    with all the security artifacts needed for communication.

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

.. [#] Partitions are outside the scope of this document. For more
       information, see
       :link_connext_dds_secure_um:`Partitions
       <p2_core/access_control.html#partitions>` in the |SP_UM|
       and the
       :link_connext_dds_pro_um:`PARTITION QosPolicy in the Connext DDS Core Libraries
       User's Manual<#users_manual/PARTITION_QosPolicy.htm>`.
