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)

1 files changed, 89 insertions, 7 deletions

diff --git a/README-FIPS.md b/README-FIPS.md
index e9c81e2c2c..66fd18030a 100644
--- a/README-FIPS.md
+++ b/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
-the FIPS module config file output data from one machine to another.
+output generated on every machine that it is to be used on. For OpenSSL 3.0,
+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
 =====================================