Add documentation for preferred_key_agreement property (#963) (#967) (#970)

* Add documentation for `preferred_key_agreement` property (#963)

* Refs #19921. Add new `preferred_key_agreement` property to auth plugin section.



* Refs #19921. Add new `preferred_key_agreement` property to property policies section.



* Refs #19921. Add new `preferred_key_agreement` property to snippets.



* Refs #19921. Fix doc8.



* Refs #22280. Apply suggestion.



* Refs #19921. Add `AUTO` value to new option.



---------


(cherry picked from commit 2f51e7c)

* Change default value to `DH`.



---------



(cherry picked from commit 949a673)

Signed-off-by: Miguel Company <miguelcompany@eprosima.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
Co-authored-by: Miguel Company <miguelcompany@eprosima.com>

Author: mergify[bot]

code/DDSCodeTester.cpp

@@ -588,6 +588,9 @@ void dds_domain_examples()
         pqos.properties().properties().emplace_back(
             "dds.sec.auth.builtin.PKI-DH.password",
             "domainParticipantPassword");
+        pqos.properties().properties().emplace_back(
+            "dds.sec.auth.builtin.PKI-DH.preferred_key_agreement",
+            "ECDH");
         //!--
     }
     {

code/XMLTester.xml

@@ -2641,6 +2641,10 @@
                     <name>dds.sec.auth.builtin.PKI-DH.password</name>
                     <value>domainParticipantPassword</value>
                 </property>
+                <property>
+                    <name>dds.sec.auth.builtin.PKI-DH.preferred_key_agreement</name>
+                    <value>ECDH</value>
+                </property>
             </properties>
         </propertiesPolicy>
     </rtps>

docs/fastdds/library_overview/includes/functionalities.rst

@@ -40,7 +40,8 @@ Security
 * Authentication of remote DomainParticipants.
   The **DDS:Auth:PKI-DH** plugin provides authentication using a trusted Certificate
   Authority (CA) and ECDSA Digital Signature Algorithms to perform the mutual authentication.
-  It also establishes a shared secret using Elliptic Curve Diffie-Hellman (ECDH) Key Agreement protocol.
+  It also establishes a shared secret using either Elliptic Curve Diffie-Hellman (ECDH) or MODP-2048 Diffie-Hellman (DH)
+  as Key Agreement protocol.
 * Access control of entities.
   The **DDS:Access:Permissions** plugin provides access control to DomainParticipants at the DDS Domain and Topic level.
 * Encryption of data.

docs/fastdds/property_policies/security.rst

@@ -42,6 +42,13 @@ The following table outlines the properties used for the :ref:`DDS\:Auth\:PKI-DH
        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.
+   * - ``preferred_key_agreement`` *(optional)*
+     - The preferred algorithm to use for generating the session's shared secret |br|
+       at the end of the authentication phase. Supported values are: |br|
+       a) ``DH``, ``DH+MODP-2048-256`` for  Diffie-Hellman Ephemeral with 2048-bit MODP Group parameters. |br|
+       b) ``ECDH``, ``ECDH+prime256v1-CEUM`` for Elliptic Curve Diffie-Hellman Ephemeral with the NIST P-256 curve. |br|
+       c) ``AUTO`` for selecting the key agreement based on the signature algorithm in the Identity CA's certificate. |br|
+       Will default to ``DH`` if the property is not present.
 
 .. note::
   All properties listed above have the ``dds.sec.auth.builtin.PKI-DH."`` prefix.

docs/fastdds/security/auth_plugin/auth_plugin.rst

@@ -24,7 +24,8 @@ The authentication plugin implemented in Fast DDS is referred to as "DDS:\Auth\:
 `DDS Security <https://www.omg.org/spec/DDS-SECURITY/1.1/>`_ specification.
 The DDS:\Auth\:PKI-DH plugin uses a trusted *Certificate Authority* (CA) and the ECDSA
 Digital Signature Algorithms to perform the mutual authentication.
-It also establishes a shared secret using Elliptic Curve Diffie-Hellman (ECDH) Key Agreement Methods.
+It also establishes a shared secret using either Elliptic Curve Diffie-Hellman (ECDH) or MODP-2048 Diffie-Hellman (DH)
+as Key Agreement protocol.
 This shared secret can be used by other security plugins as :ref:`crypto-aes-gcm-gmac`.
 
 The DDS:\Auth\:PKI-DH authentication plugin, can be activated setting the |DomainParticipantQos|
@@ -56,6 +57,13 @@ The following table outlines the properties used for the DDS:\Auth\:PKI-DH plugi
        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.
+   * - preferred_key_agreement *(optional)*
+     - The preferred algorithm to use for generating the session's shared secret |br|
+       at the end of the authentication phase. Supported values are: |br|
+       a) ``DH``, ``DH+MODP-2048-256`` for  Diffie-Hellman Ephemeral with 2048-bit MODP Group parameters. |br|
+       b) ``ECDH``, ``ECDH+prime256v1-CEUM`` for Elliptic Curve Diffie-Hellman Ephemeral with the NIST P-256 curve. |br|
+       c) ``AUTO`` for selecting the key agreement based on the signature algorithm in the Identity CA's certificate. |br|
+       Will default to ``DH`` if the property is not present.
 
 .. note::
   All listed properties have "dds.sec.auth.builtin.PKI-DH." prefix.