From 557efa306b54797328115343824ed6f2be70fb98 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mario=20Dom=C3=ADnguez=20L=C3=B3pez?=
<116071334+Mario-DL@users.noreply.github.com>
Date: Fri, 1 Mar 2024 07:52:49 +0100
Subject: [PATCH] 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>
---
code/DDSCodeTester.cpp | 15 +++
code/XMLTester.xml | 23 ++++
docs/fastdds/property_policies/security.rst | 133 +++++++++++++++++++-
docs/fastdds/security/security.rst | 4 +
4 files changed, 173 insertions(+), 2 deletions(-)
diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp
index de82abce5..f8411efee 100644
--- 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
index 6c03e363d..296b8e670 100644
--- 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
index e353527f1..7c593a978 100644
--- 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
index 4abd09286..259a382a7 100644
--- 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>`.