fips: document that the EdDSA algorithms are not-validated

Ed25519 and Ed448 are included in the FIPS 140-3 provider for
compatibility purposes but are flagged as "fips=no" to prevent their accidental
use.  This therefore requires that applications always specify the "fips=yes"
property query to enforce FIPS correctness.

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Hugo Landau <hlandau@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/20079)

3 files changed, 64 insertions, 4 deletions

diff --git a/doc/man7/OSSL_PROVIDER-FIPS.pod b/doc/man7/OSSL_PROVIDER-FIPS.pod
index 494878a866..b73728e294 100644
--- a/doc/man7/OSSL_PROVIDER-FIPS.pod
+++ b/doc/man7/OSSL_PROVIDER-FIPS.pod
@@ -7,7 +7,7 @@ OSSL_PROVIDER-FIPS - OpenSSL FIPS provider
 =head1 DESCRIPTION
 
 The OpenSSL FIPS provider is a special provider that conforms to the Federal
-Information Processing Standards (FIPS) specified in FIPS 140-2. This 'module'
+Information Processing Standards (FIPS) specified in FIPS 140-3. This 'module'
 contains an approved set of cryptographic algorithms that is validated by an
 accredited testing laboratory.
 
@@ -32,7 +32,7 @@ L<EVP_PKEY_CTX_new_from_name(3)>.
 It isn't mandatory to query for any of these properties, except to
 make sure to get implementations of this provider and none other.
 
-The "fips=yes" property can be use to make sure only FIPS approved
+The C<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,
 such as asymmetric key encoders,
@@ -390,6 +390,20 @@ A simple self test callback is shown below for illustrative purposes.
     return ret;
   }
 
+=head1 NOTES
+
+The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated algorithms,
+consequently the property query C<fips=yes> is mandatory for applications that
+want to operate in a FIPS approved manner.  The algorithms are:
+
+=over 4
+
+=item Triple DES
+
+=item EdDSA
+
+=back
+
 =head1 SEE ALSO
 
 L<openssl-fipsinstall(1)>,
@@ -405,6 +419,10 @@ L<provider(7)>
 
 This functionality was added in OpenSSL 3.0.
 
+OpenSSL 3.0 includes a FIPS 140-2 approved FIPS provider.
+
+OpenSSL 3.1 includes a FIPS 140-3 approved FIPS provider.
+
 =head1 COPYRIGHT
 
 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man7/fips_module.pod b/doc/man7/fips_module.pod
index 3eda2b6ed9..8eee14ca55 100644
--- a/doc/man7/fips_module.pod
+++ b/doc/man7/fips_module.pod
@@ -80,6 +80,7 @@ Edit the config file to add the following lines near the beginning:
 
     [openssl_init]
     providers = provider_sect
+    alg_section = algorithm_sect
 
     [provider_sect]
     fips = fips_sect
@@ -88,6 +89,9 @@ Edit the config file to add the following lines near the beginning:
     [base_sect]
     activate = 1
 
+    [algorithm_sect]
+    default_properties = fips=yes
+
 Obviously the include file location above should match the path and name of the
 FIPS module config file that you installed earlier.
 See L<https://github.com/openssl/openssl/blob/master/README-FIPS.md>.
@@ -331,6 +335,14 @@ base providers. The other library context will just use the default provider.
         goto err;
 
     /*
+     * Set the default property query on the FIPS library context to
+     * ensure that only FIPS algorithms can be used.  There are a few non-FIPS
+     * approved algorithms in the FIPS provider for backward compatibility reasons.
+     */
+    if (!EVP_set_default_properties(fips_libctx, "fips=yes"))
+        goto err;
+
+    /*
      * We don't need to do anything special to load the default
      * provider into nonfips_libctx. This happens automatically if no
      * other providers are loaded.
@@ -419,7 +431,7 @@ contexts.
      * We assume that a nondefault library context with the FIPS
      * provider loaded has been created called fips_libctx.
      */
-    SSL_CTX *fips_ssl_ctx = SSL_CTX_new_ex(fips_libctx, NULL, TLS_method());
+    SSL_CTX *fips_ssl_ctx = SSL_CTX_new_ex(fips_libctx, "fips=yes", TLS_method());
     /*
      * We assume that a nondefault library context with the default
      * provider loaded has been created called non_fips_libctx.
@@ -456,6 +468,20 @@ use L<EVP_MD_get0_provider(3)>.
 To extract the name from the B<OSSL_PROVIDER>, use
 L<OSSL_PROVIDER_get0_name(3)>.
 
+=head1 NOTES
+
+The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated algorithms,
+consequently the property query C<fips=yes> is mandatory for applications that
+want to operate in a FIPS approved manner.  The algorithms are:
+
+=over 4
+
+=item Triple DES
+
+=item EdDSA
+
+=back
+
 =head1 SEE ALSO
 
 L<migration_guide(7)>, L<crypto(7)>, L<fips_config(5)>
@@ -465,6 +491,10 @@ L<migration_guide(7)>, L<crypto(7)>, L<fips_config(5)>
 The FIPS module guide was created for use with the new FIPS provider
 in OpenSSL 3.0.
 
+OpenSSL 3.0 includes a FIPS 140-2 approved FIPS provider.
+
+OpenSSL 3.1 includes a FIPS 140-3 approved FIPS provider.
+
 =head1 COPYRIGHT
 
 Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man7/migration_guide.pod b/doc/man7/migration_guide.pod
index 8bd44a6ce7..e82471370f 100644
--- a/doc/man7/migration_guide.pod
+++ b/doc/man7/migration_guide.pod
@@ -20,7 +20,19 @@ L<crypto(7)>.
 
 =head2 Main Changes from OpenSSL 3.0
 
-There are no changes requiring additional migration measures since OpenSSL 3.0.
+The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated algorithms,
+consequently the property query C<fips=yes> is mandatory for applications that
+want to operate in a FIPS approved manner.  The algorithms are:
+
+=over 4
+
+=item Triple DES
+
+=item EdDSA
+
+=back
+
+There are no other changes requiring additional migration measures since OpenSSL 3.0.
 
 =head1 OPENSSL 3.0