Add documentation for key validation that indicates the difference between the

EVP_PKEY_XXX_check() calls for the default and fips providers.

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/18235)

(cherry picked from commit 0b3d2594d060dc19269d3740ad672f065ec6398a)

16 files changed, 145 insertions, 33 deletions

diff --git a/doc/man3/DSA_sign.pod b/doc/man3/DSA_sign.pod
index ad5f108c90..dadd6d5cbf 100644
--- a/doc/man3/DSA_sign.pod
+++ b/doc/man3/DSA_sign.pod
@@ -58,7 +58,7 @@ L<ERR_get_error(3)>.
 
 =head1 CONFORMING TO
 
-US Federal Information Processing Standard FIPS 186 (Digital Signature
+US Federal Information Processing Standard FIPS186-4 (Digital Signature
 Standard, DSS), ANSI X9.30
 
 =head1 SEE ALSO
diff --git a/doc/man3/ECDSA_SIG_new.pod b/doc/man3/ECDSA_SIG_new.pod
index 12f0d4af8d..d66deab385 100644
--- a/doc/man3/ECDSA_SIG_new.pod
+++ b/doc/man3/ECDSA_SIG_new.pod
@@ -46,7 +46,7 @@ see L<openssl_user_macros(7)>:
 =head1 DESCRIPTION
 
 B<ECDSA_SIG> is an opaque structure consisting of two BIGNUMs for the
-I<r> and I<s> value of an ECDSA signature (see X9.62 or FIPS 186-2).
+I<r> and I<s> value of an ECDSA signature (see X9.62 or FIPS186-2).
 
 ECDSA_SIG_new() allocates an empty B<ECDSA_SIG> structure. Note: before
 OpenSSL 1.1.0 the: the I<r> and I<s> components were initialised.
@@ -191,7 +191,7 @@ and finally evaluate the return value:
 
 =head1 CONFORMING TO
 
-ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
+ANSI X9.62, US Federal Information Processing Standard FIPS186-2
 (Digital Signature Standard, DSS)
 
 =head1 SEE ALSO
diff --git a/doc/man3/EC_GROUP_copy.pod b/doc/man3/EC_GROUP_copy.pod
index 3702f7368c..2f776cc8c5 100644
--- a/doc/man3/EC_GROUP_copy.pod
+++ b/doc/man3/EC_GROUP_copy.pod
@@ -159,9 +159,10 @@ The function EC_GROUP_check_discriminant() calculates the discriminant for the c
 For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is
 simply b. In either case for the curve to be valid the discriminant must be non zero.
 
-The function EC_GROUP_check() performs a number of checks on a curve to verify that it is valid. Checks performed include
+The function EC_GROUP_check() behaves in the following way:
+For the OpenSSL default provider it performs a number of checks on a curve to verify that it is valid. Checks performed include
 verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has
-the correct order.
+the correct order. For the OpenSSL FIPS provider it uses EC_GROUP_check_named_curve() to conform to SP800-56Ar3.
 
 The function EC_GROUP_check_named_curve() determines if the group's domain parameters match one of the built-in curves supported by the library.
 The curve name is returned as a B<NID> if it matches. If the group's domain parameters have been modified then no match will be found.
diff --git a/doc/man3/EVP_DigestSignInit.pod b/doc/man3/EVP_DigestSignInit.pod
index 228e9d1c5f..f770631c5c 100644
--- a/doc/man3/EVP_DigestSignInit.pod
+++ b/doc/man3/EVP_DigestSignInit.pod
@@ -42,9 +42,9 @@ be used for the actual signing. See L<provider(7)/Implicit fetch> for
 more information about implicit fetches.
 
 The OpenSSL default and legacy providers support fetching digests and can fetch
-those digests from any available provider. The OpenSSL fips provider also
+those digests from any available provider. The OpenSSL FIPS provider also
 supports fetching digests but will only fetch digests that are themselves
-implemented inside the fips provider.
+implemented inside the FIPS provider.
 
 I<ctx> must be created with EVP_MD_CTX_new() before calling this function. If
 I<pctx> is not NULL, the EVP_PKEY_CTX of the signing operation will be written
diff --git a/doc/man3/EVP_DigestVerifyInit.pod b/doc/man3/EVP_DigestVerifyInit.pod
index 398146b5b8..d83c2ba524 100644
--- a/doc/man3/EVP_DigestVerifyInit.pod
+++ b/doc/man3/EVP_DigestVerifyInit.pod
@@ -41,9 +41,9 @@ be used for the actual signing. See L<provider(7)/Implicit fetch> for
 more information about implicit fetches.
 
 The OpenSSL default and legacy providers support fetching digests and can fetch
-those digests from any available provider. The OpenSSL fips provider also
+those digests from any available provider. The OpenSSL FIPS provider also
 supports fetching digests but will only fetch digests that are themselves
-implemented inside the fips provider.
+implemented inside the FIPS provider.
 
 B<ctx> must be created with EVP_MD_CTX_new() before calling this function. If
 B<pctx> is not NULL, the EVP_PKEY_CTX of the verification operation will be
diff --git a/doc/man3/EVP_PKEY_check.pod b/doc/man3/EVP_PKEY_check.pod
index 1ba656fd22..485d350529 100644
--- a/doc/man3/EVP_PKEY_check.pod
+++ b/doc/man3/EVP_PKEY_check.pod
@@ -48,6 +48,13 @@ EVP_PKEY_check() is an alias for the EVP_PKEY_pairwise_check() function.
 
 =head1 NOTES
 
+Key validation used by the OpenSSL FIPS provider complies with the rules
+within SP800-56A and SP800-56B. For backwards compatibility reasons the OpenSSL
+default provider may use checks that are not as restrictive for certain key types.
+For further information see L<EVP_PKEY-DSA(7)/DSA key validation>,
+L<EVP_PKEY-DH(7)/DH key validation>, L<EVP_PKEY-EC(7)/EC key validation> and
+L<EVP_PKEY-RSA(7)/RSA key validation>.
+
 Refer to SP800-56A and SP800-56B for rules relating to when these functions
 should be called during key establishment.
 It is not necessary to call these functions after locally calling an approved key
@@ -63,6 +70,11 @@ They return -2 if the operation is not supported for the specific algorithm.
 
 L<EVP_PKEY_CTX_new(3)>,
 L<EVP_PKEY_fromdata(3)>,
+L<EVP_PKEY-DH(7)>,
+L<EVP_PKEY-FFC(7)>,
+L<EVP_PKEY-DSA(7)>,
+L<EVP_PKEY-EC(7)>,
+L<EVP_PKEY-RSA(7)>,
 
 =head1 HISTORY
 
diff --git a/doc/man7/EVP_KDF-PBKDF2.pod b/doc/man7/EVP_KDF-PBKDF2.pod
index b0b7ac1d65..79af4be220 100644
--- a/doc/man7/EVP_KDF-PBKDF2.pod
+++ b/doc/man7/EVP_KDF-PBKDF2.pod
@@ -56,7 +56,7 @@ The checks performed are:
 =back
 
 The default provider uses a default mode of 1 for backwards compatibility,
-and the fips provider uses a default mode of 0.
+and the FIPS provider uses a default mode of 0.
 
 The value string is expected to be a decimal number 0 or 1.
 
diff --git a/doc/man7/EVP_PKEY-DH.pod b/doc/man7/EVP_PKEY-DH.pod
index cd34d323ee..1662b152ed 100644
--- a/doc/man7/EVP_PKEY-DH.pod
+++ b/doc/man7/EVP_PKEY-DH.pod
@@ -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
 
diff --git a/doc/man7/EVP_PKEY-DSA.pod b/doc/man7/EVP_PKEY-DSA.pod
index 6a335510d3..f51b43b2a6 100644
--- a/doc/man7/EVP_PKEY-DSA.pod
+++ b/doc/man7/EVP_PKEY-DSA.pod
@@ -29,6 +29,22 @@ For "fips186_4" this must be either 2048 or 3072.
 For "fips186_2" this must be 1024.
 For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.
 
+=head2 DSA key validation
+
+For DSA keys, L<EVP_PKEY_param_check(3)> behaves in the following way:
+The OpenSSL FIPS provider conforms to the rules within the FIPS186-4
+standard for FFC parameter validation. For backwards compatibility the OpenSSL
+default provider uses a much simpler check (see below) for parameter validation,
+unless the seed parameter is set.
+
+For DSA keys, L<EVP_PKEY_param_check_quick(3)> behaves in the following way:
+A simple check of L and N and partial g is performed. The default provider
+also supports validation of legacy "fips186_2" keys.
+
+For DSA keys, L<EVP_PKEY_public_check(3)>, L<EVP_PKEY_private_check(3)> and
+L<EVP_PKEY_pairwise_check(3)> the OpenSSL default and FIPS providers conform to
+the rules within SP800-56Ar3 for public, private and pairwise tests respectively.
+
 =head1 EXAMPLES
 
 An B<EVP_PKEY> context can be obtained by calling:
@@ -73,7 +89,7 @@ A B<DSA> key can be generated using domain parameters by calling:
 
 =head1 CONFORMING TO
 
-The following sections of FIPS 186-4:
+The following sections of FIPS186-4:
 
 =over 4
 
diff --git a/doc/man7/EVP_PKEY-EC.pod b/doc/man7/EVP_PKEY-EC.pod
index a3c3ccb705..0255a5bc65 100644
--- a/doc/man7/EVP_PKEY-EC.pod
+++ b/doc/man7/EVP_PKEY-EC.pod
@@ -97,7 +97,7 @@ Valid values are "default", "named" and "named-nist".
 The "named" type checks that the domain parameters match the inbuilt curve parameters,
 "named-nist" is similiar but also checks that the named curve is a nist curve.
 The "default" type does domain parameter validation for the OpenSSL default provider,
-but is equivalent to "named-nist" for the OpenSSL fips provider.
+but is equivalent to "named-nist" for the OpenSSL FIPS provider.
 
 =item "include-public" (B<OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC>) <integer>
 
@@ -167,6 +167,26 @@ that m > k3 > k2 > k1 > 0
 
 =back
 
+=head2 EC key validation
+
+For EC keys, L<EVP_PKEY_param_check(3)> behaves in the following way:
+For the OpenSSL default provider it uses either
+L<EC_GROUP_check(3)> or L<EC_GROUP_check_named_curve(3)> depending on the flag
+EC_FLAG_CHECK_NAMED_GROUP.
+The OpenSSL FIPS provider uses L<EC_GROUP_check_named_curve(3)> in order to
+conform to SP800-56Ar3 I<Assurances of Domain-Parameter Validity>.
+
+For EC keys, L<EVP_PKEY_param_check_quick(3)> is equivalent to
+L<EVP_PKEY_param_check(3)>.
+
+For EC keys, L<EVP_PKEY_public_check(3)> and L<EVP_PKEY_public_check_quick(3)>
+conform to SP800-56Ar3 I<ECC Full Public-Key Validation> and
+I<ECC Partial Public-Key Validation> respectively.
+
+For EC Keys, L<EVP_PKEY_private_check(3)> and L<EVP_PKEY_pairwise_check(3)>
+conform to SP800-56Ar3 I<Private key validity> and
+I<Owner Assurance of Pair-wise Consistency> respectively.
+
 =head1 EXAMPLES
 
 An B<EVP_PKEY> context can be obtained by calling:
diff --git a/doc/man7/EVP_PKEY-FFC.pod b/doc/man7/EVP_PKEY-FFC.pod
index dab7380fc2..7c9848676b 100644
--- a/doc/man7/EVP_PKEY-FFC.pod
+++ b/doc/man7/EVP_PKEY-FFC.pod
@@ -196,7 +196,7 @@ The following sections of SP800-56Ar3:
 
 =back
 
-The following sections of FIPS 186-4:
+The following sections of FIPS186-4:
 
 =over 4
 
diff --git a/doc/man7/EVP_PKEY-RSA.pod b/doc/man7/EVP_PKEY-RSA.pod
index 784d5a39b8..51103b8b29 100644
--- a/doc/man7/EVP_PKEY-RSA.pod
+++ b/doc/man7/EVP_PKEY-RSA.pod
@@ -179,6 +179,26 @@ The auxiliary probable primes.
 
 =back
 
+=head2 RSA key validation
+
+For RSA keys, L<EVP_PKEY_param_check(3)> and L<EVP_PKEY_param_check_quick(3)>
+both return 1 unconditionally.
+
+For RSA keys, L<EVP_PKEY_public_check(3)> conforms to the SP800-56Br1 I<public key
+check> when the OpenSSL FIPS provider is used. The OpenSSL default provider
+performs similiar tests but relaxes the keysize restrictions for backwards
+compatibility.
+
+For RSA keys, L<EVP_PKEY_public_check_quick(3)> is the same as
+L<EVP_PKEY_public_check(3)>.
+
+For RSA keys, L<EVP_PKEY_private_check(3)> conforms to the SP800-56Br1
+I<private key test>.
+
+For RSA keys, L<EVP_PKEY_pairwise_check(3)> conforms to the
+SP800-56Br1 I<KeyPair Validation check> for the OpenSSL FIPS provider. The
+OpenSSL default provider allows testing of the validity of multi-primes.
+
 =head1 CONFORMING TO
 
 =over 4
diff --git a/doc/man7/OSSL_PROVIDER-FIPS.pod b/doc/man7/OSSL_PROVIDER-FIPS.pod
index 00ab7977f4..899185974e 100644
--- a/doc/man7/OSSL_PROVIDER-FIPS.pod
+++ b/doc/man7/OSSL_PROVIDER-FIPS.pod
@@ -34,7 +34,7 @@ make sure to get implementations of this provider and none other.
 
 The "fips=yes" property can be use to make sure only FIPS approved
 implementations are used for crypto operations.  This may also include
-other non-crypto support operations that are not in the fips provider,
+other non-crypto support operations that are not in the FIPS provider,
 such as asymmetric key encoders,
 see L<OSSL_PROVIDER-default(7)/Asymmetric Key Management>.
 
@@ -160,10 +160,18 @@ The OpenSSL FIPS provider supports these operations and algorithms:
 
 =item DH, see L<EVP_KEYMGMT-DH(7)>
 
+=item DHX, see L<EVP_KEYMGMT-DHX(7)>
+
 =item DSA, see L<EVP_KEYMGMT-DSA(7)>
 
 =item RSA, see L<EVP_KEYMGMT-RSA(7)>
 
+=item EC, see L<EVP_KEYMGMT-EC(7)>
+
+=item X25519, see L<EVP_KEYMGMT-X25519(7)>
+
+=item X448, see L<EVP_KEYMGMT-X448(7)>
+
 =back
 
 =head1 SELF TESTING
diff --git a/doc/man7/OSSL_PROVIDER-default.pod b/doc/man7/OSSL_PROVIDER-default.pod
index 14d590cbde..23acbc37f7 100644
--- a/doc/man7/OSSL_PROVIDER-default.pod
+++ b/doc/man7/OSSL_PROVIDER-default.pod
@@ -200,6 +200,8 @@ The OpenSSL default provider supports these operations and algorithms:
 
 =item DH, see L<EVP_KEYMGMT-DH(7)>
 
+=item DHX, see L<EVP_KEYMGMT-DHX(7)>
+
 =item DSA, see L<EVP_KEYMGMT-DSA(7)>
 
 =item RSA, see L<EVP_KEYMGMT-RSA(7)>
diff --git a/doc/man7/fips_module.pod b/doc/man7/fips_module.pod
index e374651fa5..f37b3831c8 100644
--- a/doc/man7/fips_module.pod
+++ b/doc/man7/fips_module.pod
@@ -273,7 +273,7 @@ file. The encoder and decoder algorithms are not in the FIPS module itself but
 are allowed to be used in conjunction with the FIPS algorithms.
 
 It is possible to specify default properties within a config file. For example
-the following config file automatically loads the default and fips providers and
+the following config file automatically loads the default and FIPS providers and
 sets the default property value to be C<fips=yes>. Note that this config file
 does not load the "base" provider. All supporting algorithms that are in "base"
 are also in "default", so it is unnecessary in this case:
diff --git a/doc/man7/migration_guide.pod b/doc/man7/migration_guide.pod
index 67e102fa4c..f8d84ad7c1 100644
--- a/doc/man7/migration_guide.pod
+++ b/doc/man7/migration_guide.pod
@@ -350,7 +350,7 @@ The Miller-Rabin test now uses 64 rounds, which is used for all prime generation
 including RSA key generation. This affects the time for larger keys sizes.
 
 The default key generation method for the regular 2-prime RSA keys was changed
-to the FIPS 186-4 B.3.6 method (Generation of Probable Primes with Conditions
+to the FIPS186-4 B.3.6 method (Generation of Probable Primes with Conditions
 Based on Auxiliary Probable Primes). This method is slower than the original
 method.
 
@@ -359,7 +359,7 @@ method.
 This checks that the salt length is at least 128 bits, the derived key length is
 at least 112 bits, and that the iteration count is at least 1000.
 For backwards compatibility these checks are disabled by default in the
-default provider, but are enabled by default in the fips provider.
+default provider, but are enabled by default in the FIPS provider.
 
 To enable or disable the checks see B<OSSL_KDF_PARAM_PKCS5> in
 L<EVP_KDF-PBKDF2(7)>. The parameter can be set using L<EVP_KDF_derive(3)>.