@@ -2,7 +2,7 @@ OpenSSL FIPS support
22====================
33
44This release of OpenSSL includes a cryptographic module that can be
5- FIPS 140-2 validated. The module is implemented as an OpenSSL provider.
5+ FIPS validated. The module is implemented as an OpenSSL provider.
66A provider is essentially a dynamically loadable module which implements
77cryptographic algorithms, see the [ README-PROVIDERS] ( README-PROVIDERS.md ) file
88for further details.
@@ -28,8 +28,16 @@ resp. `fips.dll` (on Windows). The FIPS provider does not get built and
2828installed automatically. To enable it, you need to configure OpenSSL using
2929the ` enable-fips ` option.
3030
31- Installing the FIPS module
32- ==========================
31+ Installing the FIPS provider
32+ ============================
33+
34+ In order to be FIPS compliant you must only use FIPS validated source code.
35+ Refer to < https://www.openssl.org/source/ > for information related to
36+ which versions are FIPS validated. The instructions given below build OpenSSL
37+ just using the FIPS validated source code.
38+
39+ If you want to use a validated FIPS provider, but also want to use the latest
40+ OpenSSL release to build everything else, then refer to the next section.
3341
3442The following is only a guide.
3543Please read the Security Policy for up to date installation instructions.
@@ -63,19 +71,93 @@ the installation by doing the following two things:
6371
6472- Runs the FIPS module self tests
6573- Generates the so-called FIPS module configuration file containing information
66- about the module such as the self test status, and the module checksum.
74+ about the module such as the module checksum (and for OpenSSL 3.0 the
75+ self test status).
6776
6877The FIPS module must have the self tests run, and the FIPS module config file
69- output generated on every machine that it is to be used on. You must not copy
70- the FIPS module config file output data from one machine to another.
78+ output generated on every machine that it is to be used on. For OpenSSL 3.0,
79+ you must not copy the FIPS module config file output data from one machine to another.
7180
7281On Unix the ` openssl fipsinstall ` command will be invoked as follows by default:
7382
7483 $ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so
7584
7685If you configured OpenSSL to be installed to a different location, the paths will
7786vary accordingly. In the rare case that you need to install the fipsmodule.cnf
78- to non-standard location, you can execute the ` openssl fipsinstall ` command manually.
87+ to a non-standard location, you can execute the ` openssl fipsinstall ` command manually.
88+
89+ Installing the FIPS provider and using it with the latest release
90+ =================================================================
91+
92+ This normally requires you to download 2 copies of the OpenSSL source code.
93+
94+ Download and build a validated FIPS provider
95+ --------------------------------------------
96+
97+ Refer to < https://www.openssl.org/source/ > for information related to
98+ which 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+
107+ Download and build the latest release of OpenSSL
108+ ------------------------------------------------
109+
110+ We 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+
118+ Use the OpenSSL FIPS provider for testing
119+ -----------------------------------------
120+
121+ We do this by replacing the artifact for the OpenSSL 3.1.0 FIPS provider.
122+ Note that the OpenSSL 3.1.0 FIPS provider has not been validated
123+ so 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+
139+ Copy 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+
145+ Check 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
79161
80162Using the FIPS Module in applications
81163=====================================
0 commit comments