diff options
author | slontis <shane.lontis@oracle.com> | 2023-05-09 13:07:50 +1000 |
---|---|---|
committer | Pauli <pauli@openssl.org> | 2023-07-14 11:35:23 +1000 |
commit | 2b42290f08c0a75695021aeb7d5cd16068b3edc3 (patch) | |
tree | 75c58654843dd9e22f4448c88f9aae869474ee22 /README-FIPS.md | |
parent | 2fd82c228363cfd16c5047a348e7c853defa42eb (diff) |
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)
Diffstat (limited to 'README-FIPS.md')
-rw-r--r-- | README-FIPS.md | 96 |
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 ===================================== |