mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-03-07 19:38:33 +08:00
Code Issues Packages Projects Releases Wiki Activity

EVP_PKEY-DH.pod: Clarify the manpage in regards to DH and DHX types

Browse Source 
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)
This commit is contained in:
Tomas Mraz 2024-07-09 17:58:47 +02:00
parent 45611a8a89
commit cf3d65b866
1 changed files with 31 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
doc/man7/EVP_PKEY-DH.pod
View File

@ -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.
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(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.
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_param_check_quick(3)> is equivalent to
L<EVP_PKEY_param_check(3)>.
L<EVP_PKEY_public_check(3)> conforms to SP800-56Ar3
I<FFC Full Public-Key Validation>.
For DH keys, L<EVP_PKEY_public_check(3)> conforms to
SP800-56Ar3 I<FFC Full Public-Key Validation>.
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_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)>.
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