Add FIPS build instructions

If you are building the latest release source code with enable-fips configured
then the FIPS provider you are using is not likely to be FIPS compliant.

This update demonstrates how to build a FIPS provider that is compliant
and use it with the latest source code.

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

README-FIPS.md

@@ -2,7 +2,7 @@ OpenSSL FIPS support
 ====================
 
 This release of OpenSSL includes a cryptographic module that can be
-FIPS 140-2 validated. The module is implemented as an OpenSSL provider.
+FIPS validated. The module is implemented as an OpenSSL provider.
 A provider is essentially a dynamically loadable module which implements
 cryptographic algorithms, see the [README-PROVIDERS](README-PROVIDERS.md) file
 for further details.
@@ -28,8 +28,16 @@ resp. `fips.dll` (on Windows). The FIPS provider does not get built and
 installed automatically. To enable it, you need to configure OpenSSL using
 the `enable-fips` option.
 
-Installing the FIPS module
+Installing the FIPS provider
-==========================
+============================
+
+In order to be FIPS compliant you must only use FIPS validated source code.
+Refer to <https://www.openssl.org/source/> for information related to
+which versions are FIPS validated. The instructions given below build OpenSSL
+just using the FIPS validated source code.
+
+If you want to use a validated FIPS provider, but also want to use the latest
+OpenSSL release to build everything else, then refer to the next section.
 
 The following is only a guide.
 Please read the Security Policy for up to date installation instructions.
@@ -63,11 +71,12 @@ the installation by doing the following two things:
 
 - Runs the FIPS module self tests
 - Generates the so-called FIPS module configuration file containing information
-  about the module such as the self test status, and the module checksum.
+  about the module such as the module checksum (and for OpenSSL 3.0 the
+  self test status).
 
 The FIPS module must have the self tests run, and the FIPS module config file
-output generated on every machine that it is to be used on. You must not copy
+output generated on every machine that it is to be used on. For OpenSSL 3.0,
-the FIPS module config file output data from one machine to another.
+you must not copy the FIPS module config file output data from one machine to another.
 
 On Unix, the `openssl fipsinstall` command will be invoked as follows by default:
 
@@ -75,7 +84,80 @@ On Unix, the `openssl fipsinstall` command will be invoked as follows by default
 
 If you configured OpenSSL to be installed to a different location, the paths will
 vary accordingly. In the rare case that you need to install the fipsmodule.cnf
-to non-standard location, you can execute the `openssl fipsinstall` command manually.
+to a non-standard location, you can execute the `openssl fipsinstall` command manually.
+
+Installing the FIPS provider and using it with the latest release
+=================================================================
+
+This normally requires you to download 2 copies of the OpenSSL source code.
+
+Download and build a validated FIPS provider
+--------------------------------------------
+
+Refer to <https://www.openssl.org/source/> for information related to
+which versions are FIPS validated. For this example we use OpenSSL 3.0.0.
+
+    $ wget https://www.openssl.org/source/openssl-3.0.0.tar.gz
+    $ tar -xf openssl-3.0.0.tar.gz
+    $ cd openssl-3.0.0
+    $ ./Configure enable-fips
+    $ make
+    $ cd ..
+
+Download and build the latest release of OpenSSL
+------------------------------------------------
+
+We use OpenSSL 3.1.0 here, (but you could also use the latest 3.0.X)
+
+    $ wget https://www.openssl.org/source/openssl-3.1.0.tar.gz
+    $ tar -xf openssl-3.1.0.tar.gz
+    $ cd openssl-3.1.0
+    $ ./Configure enable-fips
+    $ make
+
+Use the OpenSSL FIPS provider for testing
+-----------------------------------------
+
+We do this by replacing the artifact for the OpenSSL 3.1.0 FIPS provider.
+Note that the OpenSSL 3.1.0 FIPS provider has not been validated
+so it must not be used for FIPS purposes.
+
+    $ cp ../openssl-3.0.0/providers/fips.so providers/.
+    $ cp ../openssl-3.0.0/providers/fipsmodule.cnf providers/.
+    // Note that for OpenSSL 3.0 that the `fipsmodule.cnf` file should not
+    // be copied across multiple machines if it contains an entry for
+    // `install-status`. (Otherwise the self tests would be skipped).
+
+    // Validate the output of the following to make sure we are using the
+    // OpenSSL 3.0.0 FIPS provider
+    $ ./util/wrap.pl -fips apps/openssl list -provider-path providers \
+    -provider fips -providers
+
+    // Now run the current tests using the OpenSSL 3.0 FIPS provider.
+    $ make tests
+
+Copy the FIPS provider artifacts (`fips.so` & `fipsmodule.cnf`) to known locations
+-------------------------------------------------------------------------------------
+
+    $ cd ../openssl-3.0.0
+    $ sudo make install_fips
+
+Check that the correct FIPS provider is being used
+--------------------------------------------------
+
+    $./util/wrap.pl -fips apps/openssl list -provider-path providers \
+    -provider fips -providers
+
+    // This should produce the following output
+    Providers:
+      base
+        name: OpenSSL Base Provider
+        version: 3.1.0
+        status: active
+      fips
+        name: OpenSSL FIPS Provider
+        version: 3.0.0
+        status: active
 
 Using the FIPS Module in applications
 =====================================

doc/man7/fips_module.pod

@@ -14,6 +14,9 @@ This guide details different ways that OpenSSL can be used in conjunction
 with the FIPS module. Which is the correct approach to use will depend on your
 own specific circumstances and what you are attempting to achieve.
 
+For information related to installing the FIPS module see
+L<https://github.com/openssl/openssl/blob/master/README-FIPS.md>.
+
 Note that the old functions FIPS_mode() and FIPS_mode_set() are no longer
 present so you must remove them from your application if you use them.