Authentication Handshake Properties documentation (#681)

* Refs #20439: AuthenticationHandshakeProperties documentation Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com> * Refs #20439: Review suggestions Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com> --------- Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>
eProsima · Mar 1, 2024 · 557efa3 · 557efa3
1 parent 0e4aadb
commit 557efa3
Show file tree

Hide file tree

Showing 4 changed files with 173 additions and 2 deletions.
diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp
@@ -592,6 +592,21 @@ void dds_domain_examples()
             "domainParticipantPassword");
         //!--
     }
+    {
+        // DDS_SECURITY_AUTH_HANDSHAKE_PROPS
+        DomainParticipantQos pqos;
+
+        pqos.properties().properties().emplace_back(
+            "dds.sec.auth.builtin.PKI-DH.max_handshake_requests",
+            "5");
+        pqos.properties().properties().emplace_back(
+            "dds.sec.auth.builtin.PKI-DH.initial_handshake_resend_period",
+            "250");
+        pqos.properties().properties().emplace_back(
+            "dds.sec.auth.builtin.PKI-DH.handshake_resend_period_gain",
+            "1.5");
+        //!--
+    }
     {
         // DDS_SECURITY_ACCESS_CONTROL_PLUGIN
         DomainParticipantQos pqos;

diff --git a/code/XMLTester.xml b/code/XMLTester.xml
@@ -2949,6 +2949,29 @@
 </participant>
 <!--><-->
 
+<!-->DDS_SECURITY_AUTH_HANDSHAKE_PROPS<-->
+<participant profile_name="secure_domainparticipant_conf_auth_handshake_props_xml_profile">
+    <rtps>
+        <propertiesPolicy>
+            <properties>
+                <property>
+                    <name>dds.sec.auth.builtin.PKI-DH.max_handshake_requests</name>
+                    <value>5</value>
+                </property>
+                <property>
+                    <name>dds.sec.auth.builtin.PKI-DH.initial_handshake_resend_period</name>
+                    <value>250</value>
+                </property>
+                <property>
+                    <name>dds.sec.auth.builtin.PKI-DH.handshake_resend_period_gain</name>
+                    <value>1.5</value>
+                </property>
+            </properties>
+        </propertiesPolicy>
+    </rtps>
+</participant>
+<!--><-->
+
 <!-->DDS_SECURITY_ACCESS_CONTROL_PLUGIN<-->
 <participant profile_name="secure_domainparticipant_conf_access_control_plugin_xml_profile">
     <rtps>

diff --git a/docs/fastdds/property_policies/security.rst b/docs/fastdds/property_policies/security.rst
@@ -1,10 +1,139 @@
 .. include:: ../../03-exports/aliases.include
 .. include:: ../../03-exports/aliases-api.include
+.. include:: ../../03-exports/roles.include
 
 .. _property_policies_security:
 
 Security Plugins Settings
 -------------------------
 
-.. warning::
-    This section is still under work.
+As described in the :ref:`security` section, the security
+plugins admit a set of settings that can be configured.
+
+Authentication plugin settings
+******************************
+
+The :ref:`DDS\:Auth\:PKI-DH <auth-pki-dh>` authentication plugin, can be activated setting the |DomainParticipantQos|
+|DomainParticipantQos::properties-api|
+``dds.sec.auth.plugin`` with the value ``builtin.PKI-DH``.
+The following table outlines the properties used for the :ref:`DDS\:Auth\:PKI-DH <auth-pki-dh>` plugin configuration.
+
+.. list-table::
+   :header-rows: 1
+   :align: left
+
+   * - PropertyPolicyQos name
+     - PropertyPolicyQos value
+   * - ``identity_ca``
+     - URI to the X.509 v3 certificate of the Identity CA in PEM format. |br|
+       Supported URI schemes: file. |br|
+   * - ``identity_certificate``
+     - URI to an X.509 v3 certificate signed by the Identity CA in PEM format |br|
+       containing the signed public key for the Participant. |br|
+       Supported URI schemes: file.
+   * - ``identity_crl`` *(optional)*
+     - URI to a X.509 Certificate Revocation List (CRL). |br|
+       Supported URI schemes: file.
+   * - ``private_key``
+     - URI to access the private Private Key for the Participant. |br|
+       Supported URI schemes: file, :ref:`PKCS#11 <pkcs11-support>`.
+   * - ``password`` *(optional)*
+     - A password used to decrypt the *private_key*.  |br|
+       If the *password* property is not present, then the value supplied in the |br|
+       *private_key* property must contain the decrypted private key. |br|
+       The *password* property is ignored if the *private_key* is given in PKCS#11 scheme.
+
+.. note::
+  All properties listed above have the ``dds.sec.auth.builtin.PKI-DH."`` prefix.
+  For example: ``dds.sec.auth.builtin.PKI-DH.identity_ca``. For examples
+  and further information, please refer to the :ref:`auth-pki-dh` section.
+
+Authentication handshake settings
+*********************************
+
+The authentication phase starts when discovery information is received
+from the remote |DomainParticipants|. At this moment, the participant sends
+a handshake request until a handshake response is received from the remote participant.
+Some parameters are involved in the behavior of this exchange:
+
+* ``max_handshake_requests`` controls the maximum number of handshake requests to be sent.
+
+* ``initial_handshake_resend_period`` represents the initial waiting time (in milliseconds)
+  for the first handshake request that has to be resent.
+
+* ``handshake_resend_period_gain`` is the gain against which the period is multiplied
+  between two handshake requests.
+
+Hence, the period of time to wait for sending a new handshake request is computed at each
+iteration as the period between the last two handshake requests multiplied by the gain
+(so that the period increases).
+
+The following table lists the
+settings to configure the authentication handshake behavior within
+the ``dds.sec.auth.builtin.PKI-DH`` plugin:
+
+.. list-table::
+   :header-rows: 1
+   :align: left
+
+   * - PropertyPolicyQos name
+     - PropertyPolicyQos value
+     - PropertyPolicyQos bounds
+     - Default value
+   * - ``max_handshake_requests``
+     - ``<int>``
+     - ``[1, max)``
+     - ``10``
+   * - ``initial_handshake_resend_period``
+     - ``<int>``
+     - ``[1, max)``
+     - ``125``
+   * - ``handshake_resend_period_gain``
+     - ``<double>``
+     - ``(1.0, max)``
+     - ``1.5``
+
+.. note::
+
+    All listed properties have the ``dds.sec.auth.builtin.PKI-DH.`` prefix.
+    For example: ``dds.sec.auth.builtin.PKI-DH.max_handshake_requests``.
+
+The following is an example of how to set the properties of DomainParticipantQoS for the
+authentication handshake configuration.
+
++----------------------------------------------------------------------------------------------------------------------+
+| **C++**                                                                                                              |
++----------------------------------------------------------------------------------------------------------------------+
+| .. literalinclude:: /../code/DDSCodeTester.cpp                                                                       |
+|    :language: c++                                                                                                    |
+|    :start-after: // DDS_SECURITY_AUTH_HANDSHAKE_PROPS                                                                |
+|    :end-before: //!--                                                                                                |
+|    :dedent: 8                                                                                                        |
++----------------------------------------------------------------------------------------------------------------------+
+| **XML**                                                                                                              |
++----------------------------------------------------------------------------------------------------------------------+
+| .. literalinclude:: /../code/XMLTester.xml                                                                           |
+|    :language: xml                                                                                                    |
+|    :start-after: <!-->DDS_SECURITY_AUTH_HANDSHAKE_PROPS<-->                                                          |
+|    :end-before: <!--><-->                                                                                            |
++----------------------------------------------------------------------------------------------------------------------+
+
+Cryptographic plugin settings
+*****************************
+
+The :ref:`DDS\:Crypto\:AES-GCM-GMAC <crypto-aes-gcm-gmac>` authentication plugin,
+can be activated setting the |DomainParticipantQos| |DomainParticipantQos::properties-api|
+``dds.sec.crypto.plugin`` with the value ``builtin.AES-GCM-GMAC``.
+Moreover, this plugin needs the activation of the :ref:`auth-pki-dh`.
+The :ref:`DDS\:Crypto\:AES-GCM-GMAC <crypto-aes-gcm-gmac>` plugin is configured using the
+:ref:`access-permissions`, i.e the cryptography plugin is configured through the properties
+and configuration files of the access control plugin.
+For further information and examples in this regard please refer to :ref:`crypto-aes-gcm-gmac`.
+
+Logging plugin settings
+***********************
+The :ref:`DDS\:Logging\:DDS_LogTopic <logging-logtopic>` authentication plugin,
+can be activated setting the |DomainParticipantQos| |DomainParticipantQos::properties-api|
+``dds.sec.log.plugin`` with the value ``builtin.DDS_LogTopic``.
+The following table outlines the properties used for the DDS\:Logging\:DDS_LogTopic plugin configuration.
+For further information and examples follow the dedicated documentation: :ref:`logging-logtopic`.
diff --git a/docs/fastdds/security/security.rst b/docs/fastdds/security/security.rst
@@ -17,3 +17,7 @@ Security
    crypto_plugin/crypto_plugin
    logging_plugin/logging_plugin
    pkcs11_support/pkcs11_support
+
+Also, the following section contains the list of :ref:`propertypolicyqos`
+that can be set within *Fast DDS Security*:
+:ref:`Security Property QoS Settings <property_policies_security>`.