From 25b91a4936217abb4c53bc51fe0b0a9ffa91a902 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Fri, 29 Nov 2024 07:40:25 +0100 Subject: [PATCH] Add documentation for `preferred_key_agreement` property (#963) (#967) * Add documentation for `preferred_key_agreement` property (#963) * Refs #19921. Add new `preferred_key_agreement` property to auth plugin section. Signed-off-by: Miguel Company * Refs #19921. Add new `preferred_key_agreement` property to property policies section. Signed-off-by: Miguel Company * Refs #19921. Add new `preferred_key_agreement` property to snippets. Signed-off-by: Miguel Company * Refs #19921. Fix doc8. Signed-off-by: Miguel Company * Refs #22280. Apply suggestion. Signed-off-by: Miguel Company * Refs #19921. Add `AUTO` value to new option. Signed-off-by: Miguel Company --------- Signed-off-by: Miguel Company (cherry picked from commit 2f51e7c6e96880ecd87eeaac609ea7c6a65a5871) * Change default value to `DH`. Signed-off-by: Miguel Company --------- Signed-off-by: Miguel Company Co-authored-by: Miguel Company (cherry picked from commit 949a67335adcd9e660e3e63bb5d99ab9c99936c6) --- code/DDSCodeTester.cpp | 3 +++ code/XMLTester.xml | 4 ++++ .../library_overview/includes/functionalities.rst | 3 ++- docs/fastdds/property_policies/security.rst | 7 +++++++ docs/fastdds/security/auth_plugin/auth_plugin.rst | 10 +++++++++- 5 files changed, 25 insertions(+), 2 deletions(-) diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp index 2b31d7fee..8fbe263c4 100644 --- a/code/DDSCodeTester.cpp +++ b/code/DDSCodeTester.cpp @@ -593,6 +593,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"); //!-- } { diff --git a/code/XMLTester.xml b/code/XMLTester.xml index 05d1dd0eb..65d7ae298 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -3108,6 +3108,10 @@ dds.sec.auth.builtin.PKI-DH.password domainParticipantPassword + + dds.sec.auth.builtin.PKI-DH.preferred_key_agreement + ECDH + diff --git a/docs/fastdds/library_overview/includes/functionalities.rst b/docs/fastdds/library_overview/includes/functionalities.rst index b12f5897f..af7f07b34 100644 --- a/docs/fastdds/library_overview/includes/functionalities.rst +++ b/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. diff --git a/docs/fastdds/property_policies/security.rst b/docs/fastdds/property_policies/security.rst index 7c593a978..833e1c59f 100644 --- a/docs/fastdds/property_policies/security.rst +++ b/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. diff --git a/docs/fastdds/security/auth_plugin/auth_plugin.rst b/docs/fastdds/security/auth_plugin/auth_plugin.rst index 3bbb6045d..a8db449ae 100644 --- a/docs/fastdds/security/auth_plugin/auth_plugin.rst +++ b/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 `_ 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.