Skip to content

Commit 557efa3

Browse files
Mario-DLMario-DL
authored
Authentication Handshake Properties documentation (#681)
* Refs #20439: AuthenticationHandshakeProperties documentation Signed-off-by: Mario Dominguez <[email protected]> * Refs #20439: Review suggestions Signed-off-by: Mario Dominguez <[email protected]> --------- Signed-off-by: Mario Dominguez <[email protected]>
1 parent 0e4aadb commit 557efa3

File tree

4 files changed

+173
-2
lines changed

4 files changed

+173
-2
lines changed

‎code/DDSCodeTester.cpp

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -592,6 +592,21 @@ void dds_domain_examples()
592592
"domainParticipantPassword");
593593
//!--
594594
}
595+
{
596+
// DDS_SECURITY_AUTH_HANDSHAKE_PROPS
597+
DomainParticipantQos pqos;
598+
599+
pqos.properties().properties().emplace_back(
600+
"dds.sec.auth.builtin.PKI-DH.max_handshake_requests",
601+
"5");
602+
pqos.properties().properties().emplace_back(
603+
"dds.sec.auth.builtin.PKI-DH.initial_handshake_resend_period",
604+
"250");
605+
pqos.properties().properties().emplace_back(
606+
"dds.sec.auth.builtin.PKI-DH.handshake_resend_period_gain",
607+
"1.5");
608+
//!--
609+
}
595610
{
596611
// DDS_SECURITY_ACCESS_CONTROL_PLUGIN
597612
DomainParticipantQos pqos;

‎code/XMLTester.xml

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2949,6 +2949,29 @@
29492949
</participant>
29502950
<!--><-->
29512951

2952+
<!-->DDS_SECURITY_AUTH_HANDSHAKE_PROPS<-->
2953+
<participant profile_name="secure_domainparticipant_conf_auth_handshake_props_xml_profile">
2954+
<rtps>
2955+
<propertiesPolicy>
2956+
<properties>
2957+
<property>
2958+
<name>dds.sec.auth.builtin.PKI-DH.max_handshake_requests</name>
2959+
<value>5</value>
2960+
</property>
2961+
<property>
2962+
<name>dds.sec.auth.builtin.PKI-DH.initial_handshake_resend_period</name>
2963+
<value>250</value>
2964+
</property>
2965+
<property>
2966+
<name>dds.sec.auth.builtin.PKI-DH.handshake_resend_period_gain</name>
2967+
<value>1.5</value>
2968+
</property>
2969+
</properties>
2970+
</propertiesPolicy>
2971+
</rtps>
2972+
</participant>
2973+
<!--><-->
2974+
29522975
<!-->DDS_SECURITY_ACCESS_CONTROL_PLUGIN<-->
29532976
<participant profile_name="secure_domainparticipant_conf_access_control_plugin_xml_profile">
29542977
<rtps>

‎docs/fastdds/property_policies/security.rst

Lines changed: 131 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,139 @@
11
.. include:: ../../03-exports/aliases.include
22
.. include:: ../../03-exports/aliases-api.include
3+
.. include:: ../../03-exports/roles.include
34

45
.. _property_policies_security:
56

67
Security Plugins Settings
78
-------------------------
89

9-
.. warning::
10-
This section is still under work.
10+
As described in the :ref:`security` section, the security
11+
plugins admit a set of settings that can be configured.
12+
13+
Authentication plugin settings
14+
******************************
15+
16+
The :ref:`DDS\:Auth\:PKI-DH <auth-pki-dh>` authentication plugin, can be activated setting the |DomainParticipantQos|
17+
|DomainParticipantQos::properties-api|
18+
``dds.sec.auth.plugin`` with the value ``builtin.PKI-DH``.
19+
The following table outlines the properties used for the :ref:`DDS\:Auth\:PKI-DH <auth-pki-dh>` plugin configuration.
20+
21+
.. list-table::
22+
:header-rows: 1
23+
:align: left
24+
25+
* - PropertyPolicyQos name
26+
- PropertyPolicyQos value
27+
* - ``identity_ca``
28+
- URI to the X.509 v3 certificate of the Identity CA in PEM format. |br|
29+
Supported URI schemes: file. |br|
30+
* - ``identity_certificate``
31+
- URI to an X.509 v3 certificate signed by the Identity CA in PEM format |br|
32+
containing the signed public key for the Participant. |br|
33+
Supported URI schemes: file.
34+
* - ``identity_crl`` *(optional)*
35+
- URI to a X.509 Certificate Revocation List (CRL). |br|
36+
Supported URI schemes: file.
37+
* - ``private_key``
38+
- URI to access the private Private Key for the Participant. |br|
39+
Supported URI schemes: file, :ref:`PKCS#11 <pkcs11-support>`.
40+
* - ``password`` *(optional)*
41+
- A password used to decrypt the *private_key*. |br|
42+
If the *password* property is not present, then the value supplied in the |br|
43+
*private_key* property must contain the decrypted private key. |br|
44+
The *password* property is ignored if the *private_key* is given in PKCS#11 scheme.
45+
46+
.. note::
47+
All properties listed above have the ``dds.sec.auth.builtin.PKI-DH."`` prefix.
48+
For example: ``dds.sec.auth.builtin.PKI-DH.identity_ca``. For examples
49+
and further information, please refer to the :ref:`auth-pki-dh` section.
50+
51+
Authentication handshake settings
52+
*********************************
53+
54+
The authentication phase starts when discovery information is received
55+
from the remote |DomainParticipants|. At this moment, the participant sends
56+
a handshake request until a handshake response is received from the remote participant.
57+
Some parameters are involved in the behavior of this exchange:
58+
59+
* ``max_handshake_requests`` controls the maximum number of handshake requests to be sent.
60+
61+
* ``initial_handshake_resend_period`` represents the initial waiting time (in milliseconds)
62+
for the first handshake request that has to be resent.
63+
64+
* ``handshake_resend_period_gain`` is the gain against which the period is multiplied
65+
between two handshake requests.
66+
67+
Hence, the period of time to wait for sending a new handshake request is computed at each
68+
iteration as the period between the last two handshake requests multiplied by the gain
69+
(so that the period increases).
70+
71+
The following table lists the
72+
settings to configure the authentication handshake behavior within
73+
the ``dds.sec.auth.builtin.PKI-DH`` plugin:
74+
75+
.. list-table::
76+
:header-rows: 1
77+
:align: left
78+
79+
* - PropertyPolicyQos name
80+
- PropertyPolicyQos value
81+
- PropertyPolicyQos bounds
82+
- Default value
83+
* - ``max_handshake_requests``
84+
- ``<int>``
85+
- ``[1, max)``
86+
- ``10``
87+
* - ``initial_handshake_resend_period``
88+
- ``<int>``
89+
- ``[1, max)``
90+
- ``125``
91+
* - ``handshake_resend_period_gain``
92+
- ``<double>``
93+
- ``(1.0, max)``
94+
- ``1.5``
95+
96+
.. note::
97+
98+
All listed properties have the ``dds.sec.auth.builtin.PKI-DH.`` prefix.
99+
For example: ``dds.sec.auth.builtin.PKI-DH.max_handshake_requests``.
100+
101+
The following is an example of how to set the properties of DomainParticipantQoS for the
102+
authentication handshake configuration.
103+
104+
+----------------------------------------------------------------------------------------------------------------------+
105+
| **C++** |
106+
+----------------------------------------------------------------------------------------------------------------------+
107+
| .. literalinclude:: /../code/DDSCodeTester.cpp |
108+
| :language: c++ |
109+
| :start-after: // DDS_SECURITY_AUTH_HANDSHAKE_PROPS |
110+
| :end-before: //!-- |
111+
| :dedent: 8 |
112+
+----------------------------------------------------------------------------------------------------------------------+
113+
| **XML** |
114+
+----------------------------------------------------------------------------------------------------------------------+
115+
| .. literalinclude:: /../code/XMLTester.xml |
116+
| :language: xml |
117+
| :start-after: <!-->DDS_SECURITY_AUTH_HANDSHAKE_PROPS<--> |
118+
| :end-before: <!--><--> |
119+
+----------------------------------------------------------------------------------------------------------------------+
120+
121+
Cryptographic plugin settings
122+
*****************************
123+
124+
The :ref:`DDS\:Crypto\:AES-GCM-GMAC <crypto-aes-gcm-gmac>` authentication plugin,
125+
can be activated setting the |DomainParticipantQos| |DomainParticipantQos::properties-api|
126+
``dds.sec.crypto.plugin`` with the value ``builtin.AES-GCM-GMAC``.
127+
Moreover, this plugin needs the activation of the :ref:`auth-pki-dh`.
128+
The :ref:`DDS\:Crypto\:AES-GCM-GMAC <crypto-aes-gcm-gmac>` plugin is configured using the
129+
:ref:`access-permissions`, i.e the cryptography plugin is configured through the properties
130+
and configuration files of the access control plugin.
131+
For further information and examples in this regard please refer to :ref:`crypto-aes-gcm-gmac`.
132+
133+
Logging plugin settings
134+
***********************
135+
The :ref:`DDS\:Logging\:DDS_LogTopic <logging-logtopic>` authentication plugin,
136+
can be activated setting the |DomainParticipantQos| |DomainParticipantQos::properties-api|
137+
``dds.sec.log.plugin`` with the value ``builtin.DDS_LogTopic``.
138+
The following table outlines the properties used for the DDS\:Logging\:DDS_LogTopic plugin configuration.
139+
For further information and examples follow the dedicated documentation: :ref:`logging-logtopic`.

‎docs/fastdds/security/security.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,7 @@ Security
1717
crypto_plugin/crypto_plugin
1818
logging_plugin/logging_plugin
1919
pkcs11_support/pkcs11_support
20+
21+
Also, the following section contains the list of :ref:`propertypolicyqos`
22+
that can be set within *Fast DDS Security*:
23+
:ref:`Security Property QoS Settings <property_policies_security>`.

0 commit comments

Comments
 (0)