|
@@ -2,30 +2,25 @@
|
|
|
|
|
|
=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
|
|
|
|
|
@@ -134,6 +129,44 @@ Where s is the security strength of the key which has values of
|
|
|
|
|
|
=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:
|
|
@@ -159,7 +192,7 @@ A B<DH> key can be generated with a named safe prime group 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;
|
|
@@ -198,7 +231,7 @@ A B<DH> key can be generated using domain parameters by calling:
|
|
|
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.
|
|
|
|
|
@@ -270,7 +303,7 @@ The following sections of SP800-56Ar3:
|
|
|
|
|
|
=back
|
|
|
|
|
|
-The following sections of FIPS 186-4:
|
|
|
+The following sections of FIPS186-4:
|
|
|
|
|
|
=over 4
|
|
|
|