From c74012a2c5ad659d62fcb12e5852becd71945e46 Mon Sep 17 00:00:00 2001
From: Tomas Mraz <tomas@openssl.org>
Date: Tue, 9 Jul 2024 17:58:47 +0200
Subject: [PATCH] EVP_PKEY-DH.pod: Clarify the manpage in regards to DH and DHX
 types

Reviewed-by: Paul Dale <ppzgs1@gmail.com>
Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Kurt Roeckx <kurt@roeckx.be>
(Merged from https://github.com/openssl/openssl/pull/24819)

(cherry picked from commit cf3d65b8664f11904ad34f21fe78a6694f23ae62)
---
 doc/man7/EVP_PKEY-DH.pod | 60 +++++++++++++++++++++-------------------
 1 file changed, 31 insertions(+), 29 deletions(-)

diff --git a/doc/man7/EVP_PKEY-DH.pod b/doc/man7/EVP_PKEY-DH.pod
index 1dfc9c7345442..cf4d9c09b9506 100644
--- a/doc/man7/EVP_PKEY-DH.pod
+++ b/doc/man7/EVP_PKEY-DH.pod
@@ -7,11 +7,12 @@ EVP_PKEY-DH, EVP_PKEY-DHX, EVP_KEYMGMT-DH, EVP_KEYMGMT-DHX
 
 =head1 DESCRIPTION
 
-For B<DH> FFC key agreement, two classes of domain parameters can be used:
-"safe" domain parameters that are associated with approved named safe-prime
-groups, and a class of "FIPS186-type" domain parameters. FIPS186-type domain
-parameters should only be used for backward compatibility with existing
-applications that cannot be upgraded to use the approved safe-prime groups.
+For finite field Diffie-Hellman key agreement, two classes of domain
+parameters can be used: "safe" domain parameters that are associated with
+approved named safe-prime groups, and a class of "FIPS186-type" domain
+parameters. FIPS186-type domain parameters should only be used for backward
+compatibility with existing applications that cannot be upgraded to use the
+approved safe-prime groups.
 
 See L<EVP_PKEY-FFC(7)> for more information about FFC keys.
 
@@ -20,11 +21,11 @@ I<q> value.
 The B<DHX> key type uses X9.42 format which saves the value of I<q> and this
 must be used for FIPS186-4. If key validation is required, users should be aware
 of the nuances associated with FIPS186-4 style parameters as discussed in
-L</DH key validation>.
+L</DH and DHX key validation>.
 
 =head2 DH and DHX domain parameters
 
-In addition to the common FCC parameters that all FFC keytypes should support
+In addition to the common FFC parameters that all FFC keytypes should support
 (see L<EVP_PKEY-FFC(7)/FFC parameters>) the B<DHX> and B<DH> keytype
 implementations support the following:
 
@@ -129,43 +130,44 @@ Where s is the security strength of the key which has values of
 
 =back
 
-=head2 DH key validation
+=head2 DH and DHX key validation
 
-For B<DHX> that is not a named group the FIPS186-4 standard specifies that the
+For keys that are not a named group the FIPS186-4 standard specifies that the
 values used for FFC parameter generation are also required for parameter
 validation. This means that optional FFC domain parameter values for
 I<seed>, I<pcounter> and I<gindex> or I<hindex> may need to be stored for
 validation purposes.
 For B<DHX> the I<seed> and I<pcounter> can be stored in ASN1 data
 (but the I<gindex> or I<hindex> cannot be stored). It is recommended to use a
-named safe prime group instead.
+B<DH> parameters with named safe prime group instead.
 
-For DH keys, L<EVP_PKEY_param_check(3)> behaves in the following way:
-The OpenSSL FIPS provider tests if the parameters are either an approved safe
-prime group OR that the FFC parameters conform to FIPS186-4 as defined in
-SP800-56Ar3 I<Assurances of Domain-Parameter Validity>.
-The OpenSSL default provider uses simpler checks that allows there to be no I<q>
-value for backwards compatibility.
+With the OpenSSL FIPS provider, L<EVP_PKEY_param_check(3)> and
+L<EVP_PKEY_param_check_quick(3)> behave in the following way: the parameters
+are tested if they are either an approved safe prime group OR that the FFC
+parameters conform to FIPS186-4 as defined in SP800-56Ar3 I<Assurances of
+Domain-Parameter Validity>.
 
-For DH keys, L<EVP_PKEY_param_check_quick(3)> is equivalent to
-L<EVP_PKEY_param_check(3)>.
+The OpenSSL default provider uses simpler checks that allows there to be no I<q>
+value for backwards compatibility, however the L<EVP_PKEY_param_check(3)> will
+test the I<p> value for being a prime (and a safe prime if I<q> is missing)
+which can take significant time. The L<EVP_PKEY_param_check_quick(3)> avoids
+the prime tests.
 
-For DH keys, L<EVP_PKEY_public_check(3)> conforms to
-SP800-56Ar3 I<FFC Full Public-Key Validation>.
+L<EVP_PKEY_public_check(3)> conforms to SP800-56Ar3
+I<FFC Full Public-Key Validation>.
 
-For DH keys, L<EVP_PKEY_public_check_quick(3)> conforms to
-SP800-56Ar3 I<FFC Partial Public-Key Validation> when the
-DH key is an approved named safe prime group, otherwise it is the same as
-L<EVP_PKEY_public_check(3)>.
+L<EVP_PKEY_public_check_quick(3)> conforms to SP800-56Ar3
+I<FFC Partial Public-Key Validation> when the key is an approved named safe
+prime group, otherwise it is the same as L<EVP_PKEY_public_check(3)>.
 
-For DH Keys, L<EVP_PKEY_private_check(3)> tests that the private key is in the
-correct range according to SP800-56Ar3. The OpenSSL FIPS provider requires the
-value of I<q> to be set (note that this is set for named safe prime groups).
+L<EVP_PKEY_private_check(3)> tests that the private key is in the correct range
+according to SP800-56Ar3. The OpenSSL FIPS provider requires the value of I<q>
+to be set (note that this is implicitly set for named safe prime groups).
 For backwards compatibility the OpenSSL default provider only requires I<p> to
 be set.
 
-For DH keys, L<EVP_PKEY_pairwise_check(3)> conforms to
-SP800-56Ar3 I<Owner Assurance of Pair-wise Consistency>.
+L<EVP_PKEY_pairwise_check(3)> conforms to SP800-56Ar3
+I<Owner Assurance of Pair-wise Consistency>.
 
 =head1 EXAMPLES