doc/man7/fips_module.pod

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