=head1 NAME
-EVP_PKEY-DH, EVP_PKEY-DHX, EVP_KEYMGMT-DH
+EVP_PKEY-DH, EVP_PKEY-DHX, EVP_KEYMGMT-DH, EVP_KEYMGMT-DHX
- EVP_PKEY DH and DHX keytype and algorithm support
=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 "FIPS 186-type" domain parameters. FIPS 186-type domain
+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.
-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> 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).
+The B<DH> key type uses PKCS#3 format which saves I<p> and I<g>, but not the
+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>.
=head2 DH and DHX domain parameters
=back
+=head2 DH key validation
+
+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> 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.
+
+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.
+
+For DH keys, L<EVP_PKEY_param_check_quick(3)> is equivalent to
+L<EVP_PKEY_param_check(3)>.
+
+For DH keys, 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)>.
+
+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).
+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>.
+
=head1 EXAMPLES
An B<EVP_PKEY> context can be obtained by calling:
EVP_PKEY_free(pkey);
EVP_PKEY_CTX_free(pctx);
-B<DHX> domain parameters can be generated according to B<FIPS 186-4> by calling:
+B<DHX> domain parameters can be generated according to B<FIPS186-4> by calling:
int gindex = 2;
unsigned int pbits = 2048;
EVP_PKEY_free(key);
EVP_PKEY_CTX_free(gctx);
-To validate B<FIPS 186-4> B<DHX> domain parameters decoded from B<PEM> or
+To validate B<FIPS186-4> B<DHX> domain parameters decoded from B<PEM> or
B<DER> data, additional values used during generation may be required to
be set into the key.
=back
-The following sections of FIPS 186-4:
+The following sections of FIPS186-4:
=over 4