@@ -2,7 +2,7 @@ OpenSSL FIPS support
2
2
====================
3
3
4
4
This 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.
6
6
A provider is essentially a dynamically loadable module which implements
7
7
cryptographic algorithms, see the [ README-PROVIDERS] ( README-PROVIDERS.md ) file
8
8
for further details.
@@ -28,8 +28,16 @@ resp. `fips.dll` (on Windows). The FIPS provider does not get built and
28
28
installed automatically. To enable it, you need to configure OpenSSL using
29
29
the ` enable-fips ` option.
30
30
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.
33
41
34
42
The following is only a guide.
35
43
Please read the Security Policy for up to date installation instructions.
@@ -63,19 +71,93 @@ the installation by doing the following two things:
63
71
64
72
- Runs the FIPS module self tests
65
73
- 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).
67
76
68
77
The 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.
71
80
72
81
On Unix the ` openssl fipsinstall ` command will be invoked as follows by default:
73
82
74
83
$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so
75
84
76
85
If you configured OpenSSL to be installed to a different location, the paths will
77
86
vary 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
79
161
80
162
Using the FIPS Module in applications
81
163
=====================================
0 commit comments