diff options
Diffstat (limited to 'doc/man7/EVP_PKEY-DH.pod')
| -rw-r--r-- | doc/man7/EVP_PKEY-DH.pod | 60 |
1 files changed, 41 insertions, 19 deletions
diff --git a/doc/man7/EVP_PKEY-DH.pod b/doc/man7/EVP_PKEY-DH.pod index 72d20f6f1c..60865a7120 100644 --- a/doc/man7/EVP_PKEY-DH.pod +++ b/doc/man7/EVP_PKEY-DH.pod @@ -2,7 +2,8 @@ =head1 NAME -EVP_PKEY-DH, EVP_KEYMGMT-DH - EVP_PKEY DH keytype and algorithm support +EVP_PKEY-DH, EVP_PKEY-DHX, EVP_KEYMGMT-DH +- EVP_PKEY DH and DHX keytype and algorithm support =head1 DESCRIPTION @@ -14,25 +15,30 @@ applications that cannot be upgraded to use the approved safe-prime groups. See L<EVP_PKEY-FFC(7)> for more information about FFC keys. -For B<DH> that is not a named group the FIPS186-4 standard specifies that the +The B<DH> key type uses PKCS#3 format which saves p and g, but not the 'q' value. +The B<DHX> key type uses X9.42 format which saves the value of 'q' and this +must be used for FIPS186-4. + +For B<DHX> that is 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> may need to be stored for validation purposes. -For B<DH> the I<seed> and I<pcounter> can be stored in ASN1 data -(but the I<gindex> is not). +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> can not be stored). -=head2 DH parameters +=head2 DH and DHX domain parameters In addition to the common FCC parameters that all FFC keytypes should support -(see L<EVP_PKEY-FFC(7)/FFC parameters>) the B<DH> keytype -implementation supports the following: +(see L<EVP_PKEY-FFC(7)/FFC parameters>) the B<DHX> and B<DH> keytype +implementations support the following: =over 4 =item "group" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <UTF8 string> -Set or gets a string that associates a B<DH> named safe prime group with known -values for I<p>, I<q> and I<g>. +Sets or gets a string that associates a B<DH> or B<DHX> named safe prime group +with known values for I<p>, I<q> and I<g>. The following values can be used by the OpenSSL's default and FIPS providers: "ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192", @@ -41,31 +47,46 @@ The following values can be used by the OpenSSL's default and FIPS providers: The following additional values can also be used by OpenSSL's default provider: "modp_1536", "dh_1024_160", "dh_2048_224", "dh_2048_256". -DH named groups can be easily validated since the parameters are well known. +DH/DHX named groups can be easily validated since the parameters are well known. For protocols that only transfer I<p> and I<g> the value of I<q> can also be retrieved. -=item "safeprime-generator" (B<OSSL_PKEY_PARAM_DH_GENERATOR>) <integer> +=back -Used for DH generation of safe primes using the old generator code. -It is recommended to use a named safe prime group instead, if domain parameter -validation is required. The default value is 2. +=head2 DH and DHX additional parameters -These are not named safe prime groups so setting this value for the OpenSSL FIPS -provider will instead choose a named safe prime group based on the size of I<p>. +=over 4 =item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string> Used for getting and setting the encoding of the DH public key used in a key exchange message for the TLS protocol. +See EVP_PKEY_set1_encoded_public_key() and EVP_PKEY_get1_encoded_public_key(). + +=back + +=head2 DH additional domain parameters + +=over 4 + +=item "safeprime-generator" (B<OSSL_PKEY_PARAM_DH_GENERATOR>) <integer> + +Used for DH generation of safe primes using the old safe prime generator code. +The default value is 2. +It is recommended to use a named safe prime group instead, if domain parameter +validation is required. + +Randomly generated safe primes are not allowed by FIPS, so setting this value +for the OpenSSL FIPS provider will instead choose a named safe prime group +based on the size of I<p>. =back -=head2 DH domain parameter / key generation parameters +=head2 DH and DHX domain parameter / key generation parameters In addition to the common FFC key generation parameters that all FFC key types should support (see L<EVP_PKEY-FFC(7)/FFC key generation parameters>) the -B<DH> keytype implementation supports the following: +B<DH> and B<DHX> keytype implementation supports the following: =over 4 @@ -91,6 +112,7 @@ type. =item "generator" A safe prime generator. See the "safeprime-generator" type above. +This is only valid for B<DH> keys. =back |