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)

6 files changed, 22 insertions, 9 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