]>
Commit | Line | Data |
---|---|---|
1dc1ea18 DDO |
1 | OpenSSL FIPS support |
2 | ==================== | |
3 | ||
2154a7a7 | 4 | This release of OpenSSL includes a cryptographic module that is intended to be |
f2ea01d9 DMSP |
5 | FIPS 140-2 validated. The module is implemented as an OpenSSL provider. |
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 | ||
10 | The OpenSSL FIPS provider comes as shared library called `fips.so` (on Unix) | |
11 | resp. `fips.dll` (on Windows). The FIPS provider does not get built and | |
12 | installed automatically. To enable it, you need to configure OpenSSL using | |
13 | the `enable-fips` option. | |
2154a7a7 MC |
14 | |
15 | Installing the FIPS module | |
16 | ========================== | |
17 | ||
f2ea01d9 DMSP |
18 | If the FIPS provider is enabled, it gets installed automatically during the |
19 | normal installation process. Simply follow the normal procedure (configure, | |
20 | make, make test, make install) as described in the [INSTALL](INSTALL.md) file. | |
21 | ||
22 | For example, on Unix the final command | |
23 | ||
24 | $ make install | |
25 | ||
26 | effectively executes the following install targets | |
27 | ||
28 | $ make install_sw | |
29 | $ make install_ssldirs | |
30 | $ make install_docs | |
31 | $ make install_fips # for `enable-fips` only | |
32 | ||
33 | The `install_fips` make target can also be invoked explicitly to install | |
34 | the FIPS provider independently, without installing the rest of OpenSSL. | |
35 | ||
36 | The Installation of the FIPS provider consists of two steps. In the first step, | |
37 | the shared library is copied to its installed location, which by default is | |
38 | ||
39 | /usr/local/lib/ossl-modules/fips.so on Unix, and | |
40 | C:\Program Files\OpenSSL\lib\ossl-modules\fips.dll on Windows. | |
2154a7a7 | 41 | |
f2ea01d9 DMSP |
42 | In the second step, the `openssl fipsinstall` command is executed, which completes |
43 | the installation by doing the following two things: | |
2154a7a7 MC |
44 | |
45 | - Runs the FIPS module self tests | |
f2ea01d9 DMSP |
46 | - Generates the so-called FIPS module configuration file containing information |
47 | about the module such as the self test status, and the module checksum. | |
2154a7a7 MC |
48 | |
49 | The FIPS module must have the self tests run, and the FIPS module config file | |
50 | output generated on every machine that it is to be used on. You must not copy | |
51 | the FIPS module config file output data from one machine to another. | |
52 | ||
f2ea01d9 | 53 | On Unix the `openssl fipsinstall` command will be invoked as follows by default: |
2154a7a7 MC |
54 | |
55 | $ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so | |
56 | ||
f2ea01d9 DMSP |
57 | If you configured OpenSSL to be installed to a different location, the paths will |
58 | vary accordingly. In the rare case that you need to install the fipsmodule.cnf | |
59 | to non-standard location, you can execute the `openssl fipsinstall` command manually. | |
2154a7a7 MC |
60 | |
61 | ||
62 | Using the FIPS Module in applications | |
63 | ===================================== | |
64 | ||
65 | There are a number of different ways that OpenSSL can be used in conjunction | |
66 | with the FIPS module. Which is the correct approach to use will depend on your | |
67 | own specific circumstances and what you are attempting to achieve. Note that the | |
68 | old functions `FIPS_mode()` and `FIPS_mode_set()` are no longer present so you | |
69 | must remove them from your application if you use them. | |
70 | ||
71 | Applications written to use the OpenSSL 3.0 FIPS module should not use any | |
72 | legacy APIs or features that avoid the FIPS module. Specifically this includes: | |
73 | ||
74 | - Low level cryptographic APIs (use the high level APIs, such as EVP, instead) | |
75 | - Engines | |
76 | - Any functions that create or modify custom "METHODS" (for example | |
77 | `EVP_MD_meth_new`, `EVP_CIPHER_meth_new`, `EVP_PKEY_meth_new`, `RSA_meth_new`, | |
78 | `EC_KEY_METHOD_new`, etc.) | |
79 | ||
80 | All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to | |
81 | avoid using all deprecated functions. | |
82 | ||
83 | Making all applications use the FIPS module by default | |
84 | ------------------------------------------------------ | |
85 | ||
86 | One simple approach is to cause all applications that are using OpenSSL to only | |
87 | use the FIPS module for cryptographic algorithms by default. | |
88 | ||
89 | This approach can be done purely via configuration. As long as applications are | |
90 | built and linked against OpenSSL 3.0 and do not override the loading of the | |
91 | default config file or its settings then they can automatically start using the | |
92 | FIPS module without the need for any further code changes. | |
93 | ||
94 | To do this the default OpenSSL config file will have to be modified. The | |
95 | location of this config file will depend on the platform, and any options that | |
96 | were given during the build process. You can check the location of the config | |
97 | file by running this command: | |
98 | ||
99 | $ openssl version -d | |
100 | OPENSSLDIR: "/usr/local/ssl" | |
101 | ||
102 | Caution: Many Operating Systems install OpenSSL by default. It is a common error | |
103 | to not have the correct version of OpenSSL on your $PATH. Check that you are | |
104 | running an OpenSSL 3.0 version like this: | |
105 | ||
106 | $ openssl version -v | |
107 | OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx) | |
108 | ||
109 | The OPENSSLDIR value above gives the directory name for where the default config | |
110 | file is stored. So in this case the default config file will be called | |
111 | `/usr/local/ssl/openssl.cnf` | |
112 | ||
113 | Edit the config file to add the following lines near the beginning: | |
114 | ||
115 | openssl_conf = openssl_init | |
116 | ||
117 | .include /usr/local/ssl/fipsmodule.cnf | |
118 | ||
119 | [openssl_init] | |
120 | providers = provider_sect | |
121 | ||
122 | [provider_sect] | |
123 | fips = fips_sect | |
124 | base = base_sect | |
125 | ||
126 | [base_sect] | |
127 | activate = 1 | |
128 | ||
129 | Obviously the include file location above should match the name of the FIPS | |
130 | module config file that you installed earlier. | |
131 | ||
132 | Any applications that use OpenSSL 3.0 and are started after these changes are | |
133 | made will start using only the FIPS module unless those applications take | |
134 | explicit steps to avoid this default behaviour. Note that this configuration | |
135 | also activates the "base" provider. The base provider does not include any | |
136 | cryptographic algorithms (and therefore does not impact the validation status of | |
137 | any cryptographic operations), but does include other supporting algorithms that | |
138 | may be required. It is designed to be used in conjunction with the FIPS module. | |
139 | ||
140 | This approach has the primary advantage that it is simple, and no code changes | |
141 | are required in applications in order to benefit from the FIPS module. There are | |
142 | some disadvantages to this approach: | |
143 | ||
144 | - You may not want all applications to use the FIPS module. It may be the case | |
145 | that some applications should and some should not. | |
146 | - If applications take explicit steps to not load the default config file or set | |
147 | different settings then this method will not work for them | |
148 | - The algorithms available in the FIPS module are a subset of the algorithms | |
149 | that are available in the default OpenSSL Provider. If those applications | |
150 | attempt to use any algorithms that are not present, then they will fail. | |
151 | - Usage of certain deprecated APIs avoids the use of the FIPS module. If any | |
152 | applications use those APIs then the FIPS module will not be used. | |
153 | ||
154 | Selectively making applications use the FIPS module by default | |
155 | -------------------------------------------------------------- | |
156 | ||
157 | A variation on the above approach is to do the same thing on an individual | |
158 | application basis. The default OpenSSL config file depends on the compiled in | |
159 | value for OPENSSLDIR as described in the section above. However it is also | |
160 | possible to override the config file to be used via the `OPENSSL_CONF` | |
161 | environment variable. For example the following on Unix will cause the | |
162 | application to be executed with a non-standard config file location: | |
163 | ||
164 | $ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication | |
165 | ||
166 | Using this mechanism you can control which config file is loaded (and hence | |
167 | whether the FIPS module is loaded) on an application by application basis. | |
168 | ||
169 | This removes the disadvantage listed above that you may not want all | |
170 | applications to use the FIPS module. All the other advantages and disadvantages | |
171 | still apply. | |
172 | ||
173 | Programmatically loading the FIPS module (default library context) | |
174 | ------------------------------------------------------------------ | |
175 | ||
176 | Applications may choose to load the FIPS provider explicitly rather than relying | |
177 | on config to do this. The config file is still necessary in order to hold the | |
178 | FIPS module config data (such as its self test status and integrity data). But | |
179 | in this case we do not automatically activate the FIPS provider via that config | |
180 | file. | |
181 | ||
182 | To do things this way configure as per the section "Making all applications use | |
183 | the FIPS module by default" above, but edit the `fipsmodule.cnf` file to remove | |
184 | or comment out the line which says `activate = 1` (note that setting this value | |
185 | to 0 is **not** sufficient). This means all the required config information will | |
186 | be available to load the FIPS module, but it is not actually automatically | |
187 | loaded when the application starts. The FIPS provider can then be loaded | |
188 | programmatically like this: | |
189 | ||
190 | #include <openssl/provider.h> | |
191 | ||
192 | int main(void) | |
193 | { | |
194 | OSSL_PROVIDER *fips; | |
195 | OSSL_PROVIDER *base; | |
196 | ||
197 | fips = OSSL_PROVIDER_load(NULL, "fips"); | |
198 | if (fips == NULL) { | |
199 | printf("Failed to load FIPS provider\n"); | |
200 | exit(EXIT_FAILURE); | |
201 | } | |
202 | base = OSSL_PROVIDER_load(NULL, "base"); | |
203 | if (base == NULL) { | |
204 | OSSL_PROVIDER_unload(fips); | |
205 | printf("Failed to load base provider\n"); | |
206 | exit(EXIT_FAILURE); | |
207 | } | |
208 | ||
209 | /* Rest of application */ | |
210 | ||
211 | OSSL_PROVIDER_unload(base); | |
212 | OSSL_PROVIDER_unload(fips); | |
213 | exit(EXIT_SUCCESS); | |
214 | } | |
215 | ||
216 | Note that this should be one of the first things that you do in your | |
217 | application. If any OpenSSL functions get called that require the use of | |
218 | cryptographic functions before this occurs then, if no provider has yet been | |
219 | loaded, then the default provider will be automatically loaded. If you then | |
220 | later explicitly load the FIPS provider then you will have both the FIPS and the | |
221 | default provider loaded at the same time. It is undefined which implementation | |
222 | of an algorithm will be used if multiple implementations are available and you | |
223 | have not explicitly specified via a property query (see below) which one should | |
224 | be used. | |
225 | ||
226 | Also note that in this example we have additionally loaded the "base" provider. | |
227 | This loads a sub-set of algorithms that are also available in the default | |
228 | provider - specifically non cryptographic ones which may be used in conjunction | |
229 | with the FIPS provider. For example this contains algorithms for encoding and | |
230 | decoding keys. If you decide not to load the default provider then you | |
231 | will usually want to load the base provider instead. | |
232 | ||
233 | In this example we are using the "default" library context. OpenSSL functions | |
234 | operate within the scope of a library context. If no library context is | |
235 | explicitly specified then the default library context is used. For further | |
236 | details about library contexts see the `OSSL_LIB_CTX(3)` man page. | |
237 | ||
238 | Loading the FIPS module at the same time as other providers | |
239 | ----------------------------------------------------------- | |
240 | ||
241 | It is possible to have the FIPS provider and other providers (such as the | |
242 | default provider) all loaded at the same time into the same library context. You | |
243 | can use a property query string during algorithm fetches to specify which | |
244 | implementation you would like to use. | |
245 | ||
246 | For example to fetch an implementation of SHA256 which conforms to FIPS | |
247 | standards you can specify the property query `fips=yes` like this: | |
248 | ||
249 | EVP_MD *sha256; | |
250 | ||
251 | sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes"); | |
252 | ||
253 | If no property query is specified, or more than one implementation matches the | |
254 | property query then it is undefined which implementation of a particular | |
255 | algorithm will be returned. | |
256 | ||
257 | This example shows an explicit request for an implementation of SHA256 from the | |
258 | default provider: | |
259 | ||
260 | EVP_MD *sha256; | |
261 | ||
262 | sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default"); | |
263 | ||
264 | It is also possible to set a default property query string. The following | |
265 | example sets the default property query of "fips=yes" for all fetches within the | |
266 | default library context: | |
267 | ||
268 | EVP_set_default_properties(NULL, "fips=yes"); | |
269 | ||
270 | If a fetch function has both an explicit property query specified, and a | |
271 | default property query is defined then the two queries are merged together and | |
272 | both apply. The local property query overrides the default properties if the | |
273 | same property name is specified in both. | |
274 | ||
275 | There are two important built-in properties that you should be aware of: | |
276 | ||
277 | The "provider" property enables you to specify which provider you want an | |
278 | implementation to be fetched from, e.g. `provider=default` or `provider=fips`. | |
279 | All algorithms implemented in a provider have this property set on them. | |
280 | ||
281 | There is also the `fips` property. All FIPS algorithms match against the | |
282 | property query `fips=yes`. There are also some non-cryptographic algorithms | |
283 | available in the default and base providers that also have the `fips=yes` | |
284 | property defined for them. These are the encoder and decoder algorithms that | |
285 | can (for example) be used to write out a key generated in the FIPS provider to a | |
286 | file. The encoder and decoder algorithms are not in the FIPS module itself but | |
287 | are allowed to be used in conjunction with the FIPS algorithms. | |
288 | ||
289 | It is possible to specify default properties within a config file. For example | |
290 | the following config file automatically loads the default and fips providers and | |
291 | sets the default property value to be `fips=yes`. Note that this config file | |
292 | does not load the "base" provider. All supporting algorithms that are in "base" | |
293 | are also in "default", so it is unnecessary in this case: | |
294 | ||
295 | openssl_conf = openssl_init | |
296 | ||
297 | .include /usr/local/ssl/fipsmodule.cnf | |
298 | ||
299 | [openssl_init] | |
300 | providers = provider_sect | |
301 | alg_section = algorithm_sect | |
302 | ||
303 | [provider_sect] | |
304 | fips = fips_sect | |
305 | default = default_sect | |
306 | ||
307 | [default_sect] | |
308 | activate = 1 | |
309 | ||
310 | [algorithm_sect] | |
311 | default_properties = fips=yes | |
312 | ||
313 | Programmatically loading the FIPS module (non-default library context) | |
314 | ---------------------------------------------------------------------- | |
315 | ||
316 | In addition to using properties to separate usage of the FIPS module from other | |
317 | usages this can also be achieved using library contexts. In this example we | |
318 | create two library contexts. In one we assume the existence of a config file | |
319 | called "openssl-fips.cnf" that automatically loads and configures the FIPS and | |
320 | base providers. The other library context will just use the default provider. | |
321 | ||
322 | OSSL_LIB_CTX *fipslibctx, *nonfipslibctx; | |
323 | OSSL_PROVIDER *defctxnull = NULL; | |
324 | EVP_MD *fipssha256 = NULL, *nonfipssha256 = NULL; | |
325 | int ret = 1; | |
326 | ||
327 | /* | |
328 | * Create two non-default library contexts. One for fips usage and one for | |
329 | * non-fips usage | |
330 | */ | |
331 | fipslibctx = OSSL_LIB_CTX_new(); | |
332 | nonfipslibctx = OSSL_LIB_CTX_new(); | |
333 | if (fipslibctx == NULL || nonfipslibctx == NULL) | |
334 | goto err; | |
335 | ||
336 | /* Prevent anything from using the default library context */ | |
337 | defctxnull = OSSL_PROVIDER_load(NULL, "null"); | |
338 | ||
339 | /* | |
340 | * Load config file for the FIPS library context. We assume that this | |
341 | * config file will automatically activate the FIPS and base providers so we | |
342 | * don't need to explicitly load them here. | |
343 | */ | |
344 | if (!OSSL_LIB_CTX_load_config(fipslibctx, "openssl-fips.cnf")) | |
345 | goto err; | |
346 | ||
347 | /* | |
348 | * We don't need to do anything special to load the default provider into | |
349 | * nonfipslibctx. This happens automatically if no other providers are | |
350 | * loaded. Because we don't call OSSL_LIB_CTX_load_config() explicitly for | |
351 | * nonfipslibctx it will just use the default config file. | |
352 | */ | |
353 | ||
354 | /* As an example get some digests */ | |
355 | ||
356 | /* Get a FIPS validated digest */ | |
357 | fipssha256 = EVP_MD_fetch(fipslibctx, "SHA2-256", NULL); | |
358 | if (fipssha256 == NULL) | |
359 | goto err; | |
360 | ||
361 | /* Get a non-FIPS validated digest */ | |
362 | nonfipssha256 = EVP_MD_fetch(nonfipslibctx, "SHA2-256", NULL); | |
363 | if (nonfipssha256 == NULL) | |
364 | goto err; | |
365 | ||
366 | /* Use the digests */ | |
367 | ||
368 | printf("Success\n"); | |
369 | ret = 0; | |
370 | ||
371 | err: | |
372 | EVP_MD_free(fipssha256); | |
373 | EVP_MD_free(nonfipssha256); | |
374 | OSSL_LIB_CTX_free(fipslibctx); | |
375 | OSSL_LIB_CTX_free(nonfipslibctx); | |
376 | OSSL_PROVIDER_unload(defctxnull); | |
377 | ||
378 | return ret; | |
379 | ||
380 | Note that we have made use of the special "null" provider here which we load | |
381 | into the default library context. We could have chosen to use the default | |
382 | library context for FIPS usage, and just create one additional library context | |
383 | for other usages - or vice versa. However if code has not been converted to use | |
384 | library contexts then the default library context will be automatically used. | |
385 | This could be the case for your own existing applications as well as certain | |
386 | parts of OpenSSL itself. Not all parts of OpenSSL are library context aware. If | |
387 | this happens then you could "accidentally" use the wrong library context for a | |
388 | particular operation. To be sure this doesn't happen you can load the "null" | |
389 | provider into the default library context. Because a provider has been | |
390 | explicitly loaded, the default provider will not automatically load. This means | |
391 | code using the default context by accident will fail because no algorithms will | |
392 | be available. | |
393 | ||
394 | Using Encoders and Decoders with the FIPS module | |
395 | ------------------------------------------------ | |
396 | ||
397 | Encoders and decoders are used to read and write keys or parameters from or to | |
398 | some external format (for example a PEM file). If your application generates | |
399 | keys or parameters that then need to be written into PEM or DER format | |
400 | then it is likely that you will need to use an encoder to do this. Similarly | |
401 | you need a decoder to read previously saved keys and parameters. In most cases | |
402 | this will be invisible to you if you are using APIs that existed in | |
403 | OpenSSL 1.1.1 or earlier such as i2d_PrivateKey. However the appropriate | |
404 | encoder/decoder will need to be available in the library context associated with | |
405 | the key or parameter object. The built-in OpenSSL encoders and decoders are | |
406 | implemented in both the default and base providers and are not in the FIPS | |
407 | module boundary. However since they are not cryptographic algorithms themselves | |
408 | it is still possible to use them in conjunction with the FIPS module, and | |
409 | therefore these encoders/decoders have the "fips=yes" property against them. | |
410 | You should ensure that either the default or base provider is loaded into the | |
411 | library context in this case. | |
412 | ||
413 | Using the FIPS module in SSL/TLS | |
414 | -------------------------------- | |
415 | ||
416 | Writing an application that uses libssl in conjunction with the FIPS module is | |
417 | much the same as writing a normal libssl application. If you are using global | |
418 | properties and the default library context to specify usage of FIPS validated | |
419 | algorithms then this will happen automatically for all cryptographic algorithms | |
420 | in libssl. If you are using a non-default library context to load the FIPS | |
421 | provider then you can supply this to libssl using the function | |
422 | `SSL_CTX_new_ex()`. This works as a drop in replacement for the function | |
423 | `SSL_CTX_new()` except it provides you with the capability to specify the | |
424 | library context to be used. You can also use the same function to specify | |
425 | libssl specific properties to use. | |
426 | ||
427 | In this first example we create two SSL_CTX objects using two different library | |
428 | contexts. | |
429 | ||
430 | /* | |
431 | * We assume that a non-default library context with the FIPS provider | |
432 | * loaded has been created called fips_libctx. | |
433 | / | |
434 | SSL_CTX *fips_ssl_ctx = SSL_CTX_new_ex(fips_libctx, NULL, TLS_method()); | |
435 | /* | |
436 | * We assume that a non-default library context with the default provider | |
437 | * loaded has been created called non_fips_libctx. | |
438 | */ | |
439 | SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_ex(non_fips_libctx, NULL, | |
440 | TLS_method()); | |
441 | ||
442 | In this second example we create two SSL_CTX objects using different properties | |
443 | to specify FIPS usage: | |
444 | ||
445 | /* | |
446 | * The "fips=yes" property includes all FIPS approved algorithms as well as | |
447 | * encoders from the default provider that are allowed to be used. The NULL | |
448 | * below indicates that we are using the default library context. | |
449 | */ | |
450 | SSL_CTX *fips_ssl_ctx = SSL_CTX_new_ex(NULL, "fips=yes", TLS_method()); | |
451 | /* | |
452 | * The "provider!=fips" property allows algorithms from any provider except | |
453 | * the FIPS provider | |
454 | */ | |
455 | SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_ex(NULL, "provider!=fips", | |
456 | TLS_method()); | |
457 | ||
458 | Confirming that an algorithm is being provided by the FIPS module | |
459 | ----------------------------------------------------------------- | |
460 | ||
461 | A chain of links needs to be followed to go from an algorithm instance to the | |
462 | provider that implements it. The process is similar for all algorithms. Here the | |
463 | example of a digest is used. | |
464 | ||
465 | To go from an `EVP_MD_CTX` to an `EVP_MD`, use the `EVP_MD_CTX_md()` call. To go | |
466 | from the `EVP_MD` to its `OSSL_PROVIDER`, use the `EVP_MD_provider()` call. To | |
467 | extract the name from the `OSSL_PROVIDER`, use the `OSSL_PROVIDER_name()` call. | |
468 | Finally, use `strcmp(3)` or `printf(3)` on the name. |