Skip to content

Commit

Permalink
Authentication Handshake Properties documentation (#681) (#703)
Browse files Browse the repository at this point in the history 
* 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>
(cherry picked from commit 557efa3)

Co-authored-by: Mario Domínguez López <116071334+Mario-DL@users.noreply.github.com>
  • Loading branch information
@mergify @Mario-DL
mergify[bot] and Mario-DL authored Mar 13, 2024
1 parent 3280dd1 commit 229b1a7
Show file tree
Hide file tree
Showing 4 changed files with 173 additions and 2 deletions.
15 changes: 15 additions & 0 deletions code/DDSCodeTester.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -594,6 +594,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;
Expand Down
23 changes: 23 additions & 0 deletions code/XMLTester.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2546,6 +2546,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>
Expand Down
133 changes: 131 additions & 2 deletions docs/fastdds/property_policies/security.rst
View file
Original file line number Diff line number Diff line change
@@ -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`.
4 changes: 4 additions & 0 deletions docs/fastdds/security/security.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>`.

0 comments on commit 229b1a7

Please sign in to comment.