README-FIPS: document the installation of the FIPS provider
authorDr. Matthias St. Pierre <matthias.st.pierre@ncp-e.com>
Thu, 8 Apr 2021 19:06:23 +0000 (21:06 +0200)
committerDr. Matthias St. Pierre <matthias.st.pierre@ncp-e.com>
Thu, 29 Apr 2021 09:26:58 +0000 (11:26 +0200)
Note that configuration and installation procedure has changed:

- The FIPS provider is now disabled by default and needs to
  be enabled by configuring with `enable-fips`.
- If the FIPS provider is enabled, it gets installed automatically.
  There is no extra installation step required anymore.

This is more natural and coincides with the expectation of the
user, namely "what's configured, gets installed".

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

INSTALL.md
README-FIPS.md

index 039e1bd..f9b065d 100644 (file)
@@ -705,9 +705,9 @@ for further details.
 Don't compile in filename and line number information (e.g.  for errors and
 memory allocation).
 
 Don't compile in filename and line number information (e.g.  for errors and
 memory allocation).
 
-### no-fips
+### enable-fips
 
 
-Don't compile the FIPS provider
+Build (and install) the FIPS provider
 
 ### no-fips-securitychecks
 
 
 ### no-fips-securitychecks
 
index 0ea41da..3dc6c35 100644 (file)
@@ -2,38 +2,61 @@ OpenSSL FIPS support
 ====================
 
 This release of OpenSSL includes a cryptographic module that is intended to be
 ====================
 
 This release of OpenSSL includes a cryptographic module that is intended to be
-FIPS 140-2 validated. The module is implemented as an OpenSSL provider. See
-the [README-PROVIDERS](README-PROVIDERS.md) file for further details about
-providers.
+FIPS 140-2 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.
+
+The OpenSSL FIPS provider comes as shared library called `fips.so` (on Unix)
+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 module
 ==========================
 
-Once OpenSSL has been built and installed you will need to take explicit steps
-to complete the installation of the FIPS module (if you wish to use it). The
-OpenSSL 3.0 FIPS support is in the form of the FIPS provider which, on Unix, is
-in a `fips.so` file. On Windows this will be called `fips.dll`. Following
-installation of OpenSSL 3.0 the default location for this file is
-`/usr/local/lib/ossl-modules/fips.so` on Unix or
-`C:\Program Files\OpenSSL\lib\ossl-modules\fips.dll` on Windows.
+If the FIPS provider is enabled, it gets installed automatically during the
+normal installation process. Simply follow the normal procedure (configure,
+make, make test, make install) as described in the [INSTALL](INSTALL.md) file.
+
+For example, on Unix the final command
+
+    $ make install
+
+effectively executes the following install targets
+
+    $ make install_sw
+    $ make install_ssldirs
+    $ make install_docs
+    $ make install_fips     # for `enable-fips` only
+
+The `install_fips` make target can also be invoked explicitly to install
+the FIPS provider independently, without installing the rest of OpenSSL.
+
+The Installation of the FIPS provider consists of two steps. In the first step,
+the shared library is copied to its installed location, which by default is
+
+    /usr/local/lib/ossl-modules/fips.so                  on Unix, and
+    C:\Program Files\OpenSSL\lib\ossl-modules\fips.dll   on Windows.
 
 
-To complete the installation you need to run the `fipsinstall` command line
-application. This does 2 things:
+In the second step, the `openssl fipsinstall` command is executed, which completes
+the installation by doing the following two things:
 
 - Runs the FIPS module self tests
 
 - Runs the FIPS module self tests
-- Generates FIPS module config file output containing information about the
-module such as the self test status, and the module checksum.
+- Generates the so-called FIPS module configuration file containing information
+  about the module such as the self test status, and the module checksum.
 
 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.
 
 
 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.
 
-For example, to install the FIPS module to its default location on Unix:
+On Unix the `openssl fipsinstall` command will be invoked as follows by default:
 
     $ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so
 
 
     $ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so
 
-If you installed OpenSSL to a different location, you need to adjust the output
-and module path accordingly.
+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.
 
 
 Using the FIPS Module in applications
 
 
 Using the FIPS Module in applications