]>
Commit | Line | Data |
---|---|---|
1dc1ea18 DDO |
1 | OpenSSL FIPS support |
2 | ==================== | |
3 | ||
e8241fb6 | 4 | This release of OpenSSL includes a cryptographic module that can be |
2b42290f | 5 | FIPS validated. The module is implemented as an OpenSSL provider. |
f2ea01d9 DMSP |
6 | A provider is essentially a dynamically loadable module which implements |
7 | cryptographic algorithms, see the [README-PROVIDERS](README-PROVIDERS.md) file | |
8 | for further details. | |
9 | ||
e8241fb6 | 10 | A cryptographic module is only FIPS validated after it has gone through the complex |
11 | FIPS 140 validation process. As this process takes a very long time, it is not | |
12 | possible to validate every minor release of OpenSSL. | |
13 | If you need a FIPS validated module then you must ONLY generate a FIPS provider | |
14 | using OpenSSL versions that have valid FIPS certificates. A FIPS certificate | |
15 | contains a link to a Security Policy, and you MUST follow the instructions | |
16 | in the Security Policy in order to be FIPS compliant. | |
17 | See <https://www.openssl.org/source/> for information related to OpenSSL | |
18 | FIPS certificates and Security Policies. | |
19 | ||
20 | Newer OpenSSL Releases that include security or bug fixes can be used to build | |
21 | all other components (such as the core API's, TLS and the default, base and | |
22 | legacy providers) without any restrictions, but the FIPS provider must be built | |
23 | as specified in the Security Policy (normally with a different version of the | |
24 | source code). | |
25 | ||
26 | The OpenSSL FIPS provider is a shared library called `fips.so` (on Unix), or | |
f2ea01d9 DMSP |
27 | resp. `fips.dll` (on Windows). The FIPS provider does not get built and |
28 | installed automatically. To enable it, you need to configure OpenSSL using | |
29 | the `enable-fips` option. | |
2154a7a7 | 30 | |
2b42290f | 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. | |
2154a7a7 | 41 | |
e8241fb6 | 42 | The following is only a guide. |
43 | Please read the Security Policy for up to date installation instructions. | |
44 | ||
f2ea01d9 DMSP |
45 | If the FIPS provider is enabled, it gets installed automatically during the |
46 | normal installation process. Simply follow the normal procedure (configure, | |
47 | make, make test, make install) as described in the [INSTALL](INSTALL.md) file. | |
48 | ||
49 | For example, on Unix the final command | |
50 | ||
51 | $ make install | |
52 | ||
53 | effectively 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 | ||
60 | The `install_fips` make target can also be invoked explicitly to install | |
61 | the FIPS provider independently, without installing the rest of OpenSSL. | |
62 | ||
63 | The Installation of the FIPS provider consists of two steps. In the first step, | |
64 | the 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. | |
2154a7a7 | 68 | |
f2ea01d9 DMSP |
69 | In the second step, the `openssl fipsinstall` command is executed, which completes |
70 | the installation by doing the following two things: | |
2154a7a7 MC |
71 | |
72 | - Runs the FIPS module self tests | |
f2ea01d9 | 73 | - Generates the so-called FIPS module configuration file containing information |
2b42290f | 74 | about the module such as the module checksum (and for OpenSSL 3.0 the |
75 | self test status). | |
2154a7a7 MC |
76 | |
77 | The FIPS module must have the self tests run, and the FIPS module config file | |
2b42290f | 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. | |
2154a7a7 | 80 | |
af33b200 | 81 | On Unix, the `openssl fipsinstall` command will be invoked as follows by default: |
2154a7a7 MC |
82 | |
83 | $ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so | |
84 | ||
f2ea01d9 DMSP |
85 | If you configured OpenSSL to be installed to a different location, the paths will |
86 | vary accordingly. In the rare case that you need to install the fipsmodule.cnf | |
2b42290f | 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 | |
2154a7a7 | 161 | |
2154a7a7 MC |
162 | Using the FIPS Module in applications |
163 | ===================================== | |
164 | ||
b7140b06 SL |
165 | Documentation about using the FIPS module is available on the [fips_module(7)] |
166 | manual page. | |
2154a7a7 | 167 | |
b7140b06 | 168 | [fips_module(7)]: https://www.openssl.org/docs/manmaster/man7/fips_module.html |