169 lines
6.7 KiB
Markdown
169 lines
6.7 KiB
Markdown
|
OpenSSL FIPS support
|
||
|
====================
|
||
|
|
||
|
This release of OpenSSL includes a cryptographic module that can be
|
||
|
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.
|
||
|
|
||
|
A cryptographic module is only FIPS validated after it has gone through the complex
|
||
|
FIPS 140 validation process. As this process takes a very long time, it is not
|
||
|
possible to validate every minor release of OpenSSL.
|
||
|
If you need a FIPS validated module then you must ONLY generate a FIPS provider
|
||
|
using OpenSSL versions that have valid FIPS certificates. A FIPS certificate
|
||
|
contains a link to a Security Policy, and you MUST follow the instructions
|
||
|
in the Security Policy in order to be FIPS compliant.
|
||
|
See <https://www.openssl.org/source/> for information related to OpenSSL
|
||
|
FIPS certificates and Security Policies.
|
||
|
|
||
|
Newer OpenSSL Releases that include security or bug fixes can be used to build
|
||
|
all other components (such as the core API's, TLS and the default, base and
|
||
|
legacy providers) without any restrictions, but the FIPS provider must be built
|
||
|
as specified in the Security Policy (normally with a different version of the
|
||
|
source code).
|
||
|
|
||
|
The OpenSSL FIPS provider is a shared library called `fips.so` (on Unix), or
|
||
|
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 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.
|
||
|
|
||
|
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.
|
||
|
|
||
|
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
|
||
|
- Generates the so-called FIPS module configuration file containing information
|
||
|
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. 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:
|
||
|
|
||
|
$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so
|
||
|
|
||
|
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 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
|
||
|
=====================================
|
||
|
|
||
|
Documentation about using the FIPS module is available on the [fips_module(7)]
|
||
|
manual page.
|
||
|
|
||
|
[fips_module(7)]: https://www.openssl.org/docs/manmaster/man7/fips_module.html
|