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