.. 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 `. .. [#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 in the Security Plugins User's Manual `. .. [#PermissionsCA] In systems where multiple Permissions Certificate Authorities may exist, you can use the :property:`access_control.alternative_permissions_authority_files` property to specify alternative Permissions CA certificates. For further details, see :link_connext_dds_secure_um:`Governance and Permissions in the Security Plugins User's Manual `. .. [#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 in the Security Plugins User's Manual `. .. _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, in the RTI Security Plugins User's Manual `). 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 |SP|, along with all the security artifacts needed for communication. .. [#] 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. .. [#] |PARTITIONs| are outside the scope of this document. For more information, see :link_connext_dds_secure_um:`Partitions in the Security Plugins User's Manual ` and the :link_connext_dds_pro_um:`PARTITION QosPolicy in the Connext DDS Core Libraries User's Manual<#users_manual/PARTITION_QosPolicy.htm>`.