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