3dc6c35b89550005c3563eb5c760551f1fb5933b
[openssl.git] / README-FIPS.md
1 OpenSSL FIPS support
2 ====================
3
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.
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.
14
15 Installing the FIPS module
16 ==========================
17
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.
41
42 In the second step, the `openssl fipsinstall` command is executed, which completes
43 the installation by doing the following two things:
44
45 - Runs the FIPS module self tests
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.
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
53 On Unix the `openssl fipsinstall` command will be invoked as follows by default:
54
55     $ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so
56
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.
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.