xref: /openssl/README-FIPS.md (revision fc5fb3c9) 
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/manmaster/man7/fips_module.html
169
170Entropy Source
171==============
172
173The FIPS provider typically relies on an external entropy source,
174specified during OpenSSL build configuration (default: `os`).  However, by
175enabling the `enable-fips-jitter` option during configuration, an internal
176jitter entropy source will be used instead.  Note that this will cause
177the FIPS provider to operate in a non-compliant mode unless an entropy
178assessment [ESV] and validation through the [CMVP] are additionally conducted.
179
180Note that the `enable-fips-jitter` option is only available in OpenSSL
181versions 3.5 and later.
182
183 [CMVP]: https://csrc.nist.gov/projects/cryptographic-module-validation-program
184 [ESV]: https://csrc.nist.gov/Projects/cryptographic-module-validation-program/entropy-validations
185
1863rd-Party Vendor Builds
187=====================================
188
189Some Vendors choose to patch/modify/build their own FIPS provider,
190test it with a Security Laboratory and submit it under their own CMVP
191certificate, instead of using OpenSSL Project submissions. When doing
192so, FIPS provider should uniquely identify its own name and version
193number. The build infrastructure allows to customize FIPS provider
194build information via changes to strings in `VERSION.dat`.
195
196Setting "PRE_RELEASE_TAG" (dashed suffix), "BUILD_METADATA" (plus
197suffix), and "FIPS_VENDOR" allow to control reported FIPS provider
198name and build version as required for CMVP submission.
199