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. Any FIPS validated version may be 38used with any other openssl library. Please see <https://www.openssl.org/source/> 39To determine which FIPS validated library version may be appropriate for you. 40 41If you want to use a validated FIPS provider, but also want to use the latest 42OpenSSL release to build everything else, then refer to the next section. 43 44The following is only a guide. 45Please read the Security Policy for up to date installation instructions. 46 47If the FIPS provider is enabled, it gets installed automatically during the 48normal installation process. Simply follow the normal procedure (configure, 49make, make test, make install) as described in the [INSTALL](INSTALL.md) file. 50 51For example, on Unix the final command 52 53 $ make install 54 55effectively executes the following install targets 56 57 $ make install_sw 58 $ make install_ssldirs 59 $ make install_docs 60 $ make install_fips # for `enable-fips` only 61 62The `install_fips` make target can also be invoked explicitly to install 63the FIPS provider independently, without installing the rest of OpenSSL. 64 65The Installation of the FIPS provider consists of two steps. In the first step, 66the shared library is copied to its installed location, which by default is 67 68 /usr/local/lib/ossl-modules/fips.so on Unix, and 69 C:\Program Files\OpenSSL\lib\ossl-modules\fips.dll on Windows. 70 71In the second step, the `openssl fipsinstall` command is executed, which completes 72the installation by doing the following two things: 73 74- Runs the FIPS module self tests 75- Generates the so-called FIPS module configuration file containing information 76 about the module such as the module checksum (and for OpenSSL 3.1.2 the 77 self test status). 78 79The FIPS module must have the self tests run, and the FIPS module config file 80output generated on every machine that it is to be used on. For OpenSSL 3.1.2 81you must not copy the FIPS module config file output data from one machine to another. 82 83On Unix, the `openssl fipsinstall` command will be invoked as follows by default: 84 85 $ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so 86 87If you configured OpenSSL to be installed to a different location, the paths will 88vary accordingly. In the rare case that you need to install the fipsmodule.cnf 89to a non-standard location, you can execute the `openssl fipsinstall` command manually. 90 91Installing the FIPS provider and using it with the latest release 92================================================================= 93 94This normally requires you to download 2 copies of the OpenSSL source code. 95 96Download and build a validated FIPS provider 97-------------------------------------------- 98 99Refer to <https://www.openssl.org/source/> for information related to 100which versions are FIPS validated. For this example we use OpenSSL 3.1.2. 101 102 $ wget https://www.openssl.org/source/openssl-3.1.2.tar.gz 103 $ tar -xf openssl-3.1.2.tar.gz 104 $ cd openssl-3.1.2 105 $ ./Configure enable-fips 106 $ make 107 $ cd .. 108 109Download and build the latest release of OpenSSL 110------------------------------------------------ 111 112We use OpenSSL 3.5.0 here, (but you could also use the latest 3.5.X) 113 114 $ wget https://www.openssl.org/source/openssl-3.5.0.tar.gz 115 $ tar -xf openssl-3.5.0.tar.gz 116 $ cd openssl-3.5.0 117 $ ./Configure enable-fips 118 $ make 119 120Use the OpenSSL FIPS provider for testing 121----------------------------------------- 122 123We do this by replacing the artifact for the OpenSSL 3.5.0 FIPS provider. 124Note that the OpenSSL 3.5.0 FIPS provider has not been validated 125so it must not be used for FIPS purposes. 126 127 $ cp ../openssl-3.1.2/providers/fips.so providers/. 128 $ cp ../openssl-3.1.2/providers/fipsmodule.cnf providers/. 129 // Note that for OpenSSL 3.1.2 that the `fipsmodule.cnf` file should not 130 // be copied across multiple machines if it contains an entry for 131 // `install-status`. (Otherwise the self tests would be skipped). 132 133 // Validate the output of the following to make sure we are using the 134 // OpenSSL 3.1.2 FIPS provider 135 $ ./util/wrap.pl -fips apps/openssl list -provider-path providers \ 136 -provider fips -providers 137 138 // Now run the current tests using the OpenSSL 3.1.2 FIPS provider. 139 $ make tests 140 141Copy the FIPS provider artifacts (`fips.so` & `fipsmodule.cnf`) to known locations 142------------------------------------------------------------------------------------- 143 144 $ cd ../openssl-3.1.2 145 $ sudo make install_fips 146 147Check that the correct FIPS provider is being used 148-------------------------------------------------- 149 150 $ cd ../openssl-3.5.0 151 $./util/wrap.pl -fips apps/openssl list -provider-path providers \ 152 -provider fips -providers 153 154 // This should produce the following output 155 Providers: 156 base 157 name: OpenSSL Base Provider 158 version: 3.5.0 159 status: active 160 fips 161 name: OpenSSL FIPS Provider 162 version: 3.1.2 163 status: active 164 165Using the FIPS Module in applications 166===================================== 167 168Documentation about using the FIPS module is available on the [fips_module(7)] 169manual page. 170 171 [fips_module(7)]: https://www.openssl.org/docs/manmaster/man7/fips_module.html 172 173Entropy Source 174============== 175 176The FIPS provider typically relies on an external entropy source, 177specified during OpenSSL build configuration (default: `os`). However, by 178enabling the `enable-fips-jitter` option during configuration, an internal 179jitter entropy source will be used instead. Note that this will cause 180the FIPS provider to operate in a non-compliant mode unless an entropy 181assessment [ESV] and validation through the [CMVP] are additionally conducted. 182 183Note that the `enable-fips-jitter` option is only available in OpenSSL 184versions 3.5 and later. 185 186 [CMVP]: https://csrc.nist.gov/projects/cryptographic-module-validation-program 187 [ESV]: https://csrc.nist.gov/Projects/cryptographic-module-validation-program/entropy-validations 188 1893rd-Party Vendor Builds 190===================================== 191 192Some Vendors choose to patch/modify/build their own FIPS provider, 193test it with a Security Laboratory and submit it under their own CMVP 194certificate, instead of using OpenSSL Project submissions. When doing 195so, FIPS provider should uniquely identify its own name and version 196number. The build infrastructure allows to customize FIPS provider 197build information via changes to strings in `VERSION.dat`. 198 199Setting "PRE_RELEASE_TAG" (dashed suffix), "BUILD_METADATA" (plus 200suffix), and "FIPS_VENDOR" allow to control reported FIPS provider 201name and build version as required for CMVP submission. 202