1OpenSSL FIPS support 2==================== 3 4This release of OpenSSL includes a cryptographic module that can be 5FIPS validated. The module is implemented as an OpenSSL provider. 6A provider is essentially a dynamically loadable module which implements 7cryptographic algorithms, see the [README-PROVIDERS](README-PROVIDERS.md) file 8for further details. 9 10A cryptographic module is only FIPS validated after it has gone through the complex 11FIPS 140 validation process. As this process takes a very long time, it is not 12possible to validate every minor release of OpenSSL. 13If you need a FIPS validated module then you must ONLY generate a FIPS provider 14using OpenSSL versions that have valid FIPS certificates. A FIPS certificate 15contains a link to a Security Policy, and you MUST follow the instructions 16in the Security Policy in order to be FIPS compliant. 17See <https://www.openssl.org/source/> for information related to OpenSSL 18FIPS certificates and Security Policies. 19 20Newer OpenSSL Releases that include security or bug fixes can be used to build 21all other components (such as the core API's, TLS and the default, base and 22legacy providers) without any restrictions, but the FIPS provider must be built 23as specified in the Security Policy (normally with a different version of the 24source code). 25 26The OpenSSL FIPS provider is a shared library called `fips.so` (on Unix), or 27resp. `fips.dll` (on Windows). The FIPS provider does not get built and 28installed automatically. To enable it, you need to configure OpenSSL using 29the `enable-fips` option. 30 31Installing the FIPS provider 32============================ 33 34In order to be FIPS compliant you must only use FIPS validated source code. 35Refer to <https://www.openssl.org/source/> for information related to 36which versions are FIPS validated. The instructions given below build OpenSSL 37just using the FIPS validated source code. 38 39If you want to use a validated FIPS provider, but also want to use the latest 40OpenSSL release to build everything else, then refer to the next section. 41 42The following is only a guide. 43Please read the Security Policy for up to date installation instructions. 44 45If the FIPS provider is enabled, it gets installed automatically during the 46normal installation process. Simply follow the normal procedure (configure, 47make, make test, make install) as described in the [INSTALL](INSTALL.md) file. 48 49For example, on Unix the final command 50 51 $ make install 52 53effectively executes the following install targets 54 55 $ make install_sw 56 $ make install_ssldirs 57 $ make install_docs 58 $ make install_fips # for `enable-fips` only 59 60The `install_fips` make target can also be invoked explicitly to install 61the FIPS provider independently, without installing the rest of OpenSSL. 62 63The Installation of the FIPS provider consists of two steps. In the first step, 64the shared library is copied to its installed location, which by default is 65 66 /usr/local/lib/ossl-modules/fips.so on Unix, and 67 C:\Program Files\OpenSSL\lib\ossl-modules\fips.dll on Windows. 68 69In the second step, the `openssl fipsinstall` command is executed, which completes 70the installation by doing the following two things: 71 72- Runs the FIPS module self tests 73- Generates the so-called FIPS module configuration file containing information 74 about the module such as the module checksum (and for OpenSSL 3.0 the 75 self test status). 76 77The FIPS module must have the self tests run, and the FIPS module config file 78output generated on every machine that it is to be used on. For OpenSSL 3.0, 79you must not copy the FIPS module config file output data from one machine to another. 80 81On Unix the `openssl fipsinstall` command will be invoked as follows by default: 82 83 $ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so 84 85If you configured OpenSSL to be installed to a different location, the paths will 86vary accordingly. In the rare case that you need to install the fipsmodule.cnf 87to a non-standard location, you can execute the `openssl fipsinstall` command manually. 88 89Installing the FIPS provider and using it with the latest release 90================================================================= 91 92This normally requires you to download 2 copies of the OpenSSL source code. 93 94Download and build a validated FIPS provider 95-------------------------------------------- 96 97Refer to <https://www.openssl.org/source/> for information related to 98which versions are FIPS validated. For this example we use OpenSSL 3.0.0. 99 100 $ wget https://www.openssl.org/source/openssl-3.0.0.tar.gz 101 $ tar -xf openssl-3.0.0.tar.gz 102 $ cd openssl-3.0.0 103 $ ./Configure enable-fips 104 $ make 105 $ cd .. 106 107Download and build the latest release of OpenSSL 108------------------------------------------------ 109 110We use OpenSSL 3.1.0 here, (but you could also use the latest 3.0.X) 111 112 $ wget https://www.openssl.org/source/openssl-3.1.0.tar.gz 113 $ tar -xf openssl-3.1.0.tar.gz 114 $ cd openssl-3.1.0 115 $ ./Configure enable-fips 116 $ make 117 118Use the OpenSSL FIPS provider for testing 119----------------------------------------- 120 121We do this by replacing the artifact for the OpenSSL 3.1.0 FIPS provider. 122Note that the OpenSSL 3.1.0 FIPS provider has not been validated 123so it must not be used for FIPS purposes. 124 125 $ cp ../openssl-3.0.0/providers/fips.so providers/. 126 $ cp ../openssl-3.0.0/providers/fipsmodule.cnf providers/. 127 // Note that for OpenSSL 3.0 that the `fipsmodule.cnf` file should not 128 // be copied across multiple machines if it contains an entry for 129 // `install-status`. (Otherwise the self tests would be skipped). 130 131 // Validate the output of the following to make sure we are using the 132 // OpenSSL 3.0.0 FIPS provider 133 $ ./util/wrap.pl -fips apps/openssl list -provider-path providers \ 134 -provider fips -providers 135 136 // Now run the current tests using the OpenSSL 3.0 FIPS provider. 137 $ make tests 138 139Copy the FIPS provider artifacts (`fips.so` & `fipsmodule.cnf`) to known locations 140------------------------------------------------------------------------------------- 141 142 $ cd ../openssl-3.0.0 143 $ sudo make install_fips 144 145Check that the correct FIPS provider is being used 146-------------------------------------------------- 147 148 $./util/wrap.pl -fips apps/openssl list -provider-path providers \ 149 -provider fips -providers 150 151 // This should produce the following output 152 Providers: 153 base 154 name: OpenSSL Base Provider 155 version: 3.1.0 156 status: active 157 fips 158 name: OpenSSL FIPS Provider 159 version: 3.0.0 160 status: active 161 162Using the FIPS Module in applications 163===================================== 164 165Documentation about using the FIPS module is available on the [fips_module(7)] 166manual page. 167 168 [fips_module(7)]: https://www.openssl.org/docs/man3.0/man7/fips_module.html 169