doc/man7/OSSL_PROVIDER-FIPS.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_PROVIDER-FIPS - OpenSSL FIPS provider
   6
   7 =head1 DESCRIPTION
   8
   9 The OpenSSL FIPS provider is a special provider that conforms to the Federal
  10 Information Processing Standards (FIPS) specified in FIPS 140-3. This 'module'
  11 contains an approved set of cryptographic algorithms that is validated by an
  12 accredited testing laboratory.
  13
  14 =head2 Properties
  15
  16 The implementations in this provider specifically have these properties
  17 defined:
  18
  19 =over 4
  20
  21 =item "provider=fips"
  22
  23 =item "fips=yes"
  24
  25 =back
  26
  27 It may be used in a property query string with fetching functions such as
  28 L<EVP_MD_fetch(3)> or L<EVP_CIPHER_fetch(3)>, as well as with other
  29 functions that take a property query string, such as
  30 L<EVP_PKEY_CTX_new_from_name(3)>.
  31
  32 To be FIPS compliant, it is mandatory to include C<fips=yes> as
  33 part of all property queries.  This ensures that only FIPS approved
  34 implementations are used for cryptographic operations.  The C<fips=yes>
  35 query may also include other non-crypto support operations that
  36 are not in the FIPS provider, such as asymmetric key encoders, see
  37 L<OSSL_PROVIDER-default(7)/Asymmetric Key Management>.
  38
  39 It is not mandatory to include C<provider=fips> as part of your property
  40 query.  Including C<provider=fips> in your property query guarantees
  41 that the OpenSSL FIPS provider is used for cryptographic operations
  42 rather than other FIPS capable providers.
  43
  44 =head2 Provider parameters
  45
  46 See L<provider-base(7)/Provider parameters> for a list of base parameters.
  47 Additionally the OpenSSL FIPS provider also supports the following gettable
  48 parameters:
  49
  50 =over 4
  51
  52 =item "security-checks" (B<OSSL_OSSL_PROV_PARAM_SECURITY_CHECKS>) <unsigned integer>
  53
  54 For further information refer to the L<openssl-fipsinstall(1)> option
  55 B<-no_security_checks>.
  56
  57 =back
  58
  59 =head1 OPERATIONS AND ALGORITHMS
  60
  61 The OpenSSL FIPS provider supports these operations and algorithms:
  62
  63 =head2 Hashing Algorithms / Message Digests
  64
  65 =over 4
  66
  67 =item SHA1, see L<EVP_MD-SHA1(7)>
  68
  69 =item SHA2, see L<EVP_MD-SHA2(7)>
  70
  71 =item SHA3, see L<EVP_MD-SHA3(7)>
  72
  73 =item KECCAK-KMAC, see L<EVP_MD-KECCAK-KMAC(7)>
  74
  75 =item SHAKE, see L<EVP_MD-SHAKE(7)>
  76
  77 =back
  78
  79 =head2 Symmetric Ciphers
  80
  81 =over 4
  82
  83 =item AES, see L<EVP_CIPHER-AES(7)>
  84
  85 =item 3DES, see L<EVP_CIPHER-DES(7)>
  86
  87 This is an unapproved algorithm.
  88
  89 =back
  90
  91 =head2 Message Authentication Code (MAC)
  92
  93 =over 4
  94
  95 =item CMAC, see L<EVP_MAC-CMAC(7)>
  96
  97 =item GMAC, see L<EVP_MAC-GMAC(7)>
  98
  99 =item HMAC, see L<EVP_MAC-HMAC(7)>
 100
 101 =item KMAC, see L<EVP_MAC-KMAC(7)>
 102
 103 =back
 104
 105 =head2 Key Derivation Function (KDF)
 106
 107 =over 4
 108
 109 =item HKDF, see L<EVP_KDF-HKDF(7)>
 110
 111 =item TLS13-KDF, see L<EVP_KDF-TLS13_KDF(7)>
 112
 113 =item SSKDF, see L<EVP_KDF-SS(7)>
 114
 115 =item PBKDF2, see L<EVP_KDF-PBKDF2(7)>
 116
 117 =item SSHKDF, see L<EVP_KDF-SSHKDF(7)>
 118
 119 =item TLS1-PRF, see L<EVP_KDF-TLS1_PRF(7)>
 120
 121 =item KBKDF, see L<EVP_KDF-KB(7)>
 122
 123 =item X942KDF-ASN1, see L<EVP_KDF-X942-ASN1(7)>
 124
 125 =item X942KDF-CONCAT, see L<EVP_KDF-X942-CONCAT(7)>
 126
 127 =item X963KDF, see L<EVP_KDF-X963(7)>
 128
 129 =back
 130
 131 =head2 Key Exchange
 132
 133 =over 4
 134
 135 =item DH, see L<EVP_KEYEXCH-DH(7)>
 136
 137 =item ECDH, see L<EVP_KEYEXCH-ECDH(7)>
 138
 139 =item X25519, see L<EVP_KEYEXCH-X25519(7)>
 140
 141 =item X448, see L<EVP_KEYEXCH-X448(7)>
 142
 143 =item TLS1-PRF
 144
 145 =item HKDF
 146
 147 =back
 148
 149 =head2 Asymmetric Signature
 150
 151 =over 4
 152
 153 =item RSA, see L<EVP_SIGNATURE-RSA(7)>
 154
 155 =item DSA, see L<EVP_SIGNATURE-DSA(7)>
 156
 157 =item ED25519, see L<EVP_SIGNATURE-ED25519(7)>
 158
 159 This is an unapproved algorithm.
 160
 161 =item ED448, see L<EVP_SIGNATURE-ED448(7)>
 162
 163 This is an unapproved algorithm.
 164
 165 =item ECDSA, see L<EVP_SIGNATURE-ECDSA(7)>
 166
 167 =item HMAC, see L<EVP_SIGNATURE-HMAC(7)>
 168
 169 =item CMAC, see L<EVP_SIGNATURE-CMAC(7)>
 170
 171 =back
 172
 173 =head2 Asymmetric Cipher
 174
 175 =over 4
 176
 177 =item RSA, see L<EVP_ASYM_CIPHER-RSA(7)>
 178
 179 =back
 180
 181 =head2 Asymmetric Key Encapsulation
 182
 183 =over 4
 184
 185 =item RSA, see L<EVP_KEM-RSA(7)>
 186
 187 =back
 188
 189 =head2 Asymmetric Key Management
 190
 191 =over 4
 192
 193 =item DH, see L<EVP_KEYMGMT-DH(7)>
 194
 195 =item DHX, see L<EVP_KEYMGMT-DHX(7)>
 196
 197 =item DSA, see L<EVP_KEYMGMT-DSA(7)>
 198
 199 =item RSA, see L<EVP_KEYMGMT-RSA(7)>
 200
 201 =item RSA-PSS
 202
 203 =item EC, see L<EVP_KEYMGMT-EC(7)>
 204
 205 =item X25519, see L<EVP_KEYMGMT-X25519(7)>
 206
 207 =item X448, see L<EVP_KEYMGMT-X448(7)>
 208
 209 =item ED25519, see L<EVP_KEYMGMT-ED25519(7)>
 210
 211 This is an unapproved algorithm.
 212
 213 =item ED448, see L<EVP_KEYMGMT-ED448(7)>
 214
 215 This is an unapproved algorithm.
 216
 217 =item TLS1-PRF
 218
 219 =item HKDF
 220
 221 =item HMAC, see L<EVP_KEYMGMT-HMAC(7)>
 222
 223 =item CMAC, see L<EVP_KEYMGMT-CMAC(7)>
 224
 225 =back
 226
 227 =head2 Random Number Generation
 228
 229 =over 4
 230
 231 =item CTR-DRBG, see L<EVP_RAND-CTR-DRBG(7)>
 232
 233 =item HASH-DRBG, see L<EVP_RAND-HASH-DRBG(7)>
 234
 235 =item HMAC-DRBG, see L<EVP_RAND-HMAC-DRBG(7)>
 236
 237 =item TEST-RAND, see L<EVP_RAND-TEST-RAND(7)>
 238
 239 TEST-RAND is an unapproved algorithm.
 240
 241 =back
 242
 243 =head1 SELF TESTING
 244
 245 One of the requirements for the FIPS module is self testing. An optional callback
 246 mechanism is available to return information to the user using
 247 L<OSSL_SELF_TEST_set_callback(3)>.
 248
 249 The parameters passed to the callback are described in L<OSSL_SELF_TEST_new(3)>
 250
 251 The OpenSSL FIPS module uses the following mechanism to provide information
 252 about the self tests as they run.
 253 This is useful for debugging if a self test is failing.
 254 The callback also allows forcing any self test to fail, in order to check that
 255 it operates correctly on failure.
 256 Note that all self tests run even if a self test failure occurs.
 257
 258 The FIPS module passes the following type(s) to OSSL_SELF_TEST_onbegin().
 259
 260 =over 4
 261
 262 =item "Module_Integrity" (B<OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY>)
 263
 264 Uses HMAC SHA256 on the module file to validate that the module has not been
 265 modified. The integrity value is compared to a value written to a configuration
 266 file during installation.
 267
 268 =item "Install_Integrity" (B<OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY>)
 269
 270 Uses HMAC SHA256 on a fixed string to validate that the installation process
 271 has already been performed and the self test KATS have already been tested,
 272 The integrity value is compared to a value written to a configuration
 273 file after successfully running the self tests during installation.
 274
 275 =item "KAT_Cipher" (B<OSSL_SELF_TEST_TYPE_KAT_CIPHER>)
 276
 277 Known answer test for a symmetric cipher.
 278
 279 =item "KAT_AsymmetricCipher" (B<OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER>)
 280
 281 Known answer test for a asymmetric cipher.
 282
 283 =item "KAT_Digest" (B<OSSL_SELF_TEST_TYPE_KAT_DIGEST>)
 284
 285 Known answer test for a digest.
 286
 287 =item "KAT_Signature" (B<OSSL_SELF_TEST_TYPE_KAT_SIGNATURE>)
 288
 289 Known answer test for a signature.
 290
 291 =item "PCT_Signature" (B<OSSL_SELF_TEST_TYPE_PCT_SIGNATURE>)
 292
 293 Pairwise Consistency check for a signature.
 294
 295 =item "KAT_KDF" (B<OSSL_SELF_TEST_TYPE_KAT_KDF>)
 296
 297 Known answer test for a key derivation function.
 298
 299 =item "KAT_KA" (B<OSSL_SELF_TEST_TYPE_KAT_KA>)
 300
 301 Known answer test for key agreement.
 302
 303 =item "DRBG" (B<OSSL_SELF_TEST_TYPE_DRBG>)
 304
 305 Known answer test for a Deterministic Random Bit Generator.
 306
 307 =item "Conditional_PCT" (B<OSSL_SELF_TEST_TYPE_PCT>)
 308
 309 Conditional test that is run during the generation of key pairs.
 310
 311 =item "Continuous_RNG_Test" (B<OSSL_SELF_TEST_TYPE_CRNG>)
 312
 313 Continuous random number generator test.
 314
 315 =back
 316
 317 The "Module_Integrity" self test is always run at startup.
 318 The "Install_Integrity" self test is used to check if the self tests have
 319 already been run at installation time. If they have already run then the
 320 self tests are not run on subsequent startups.
 321 All other self test categories are run once at installation time, except for the
 322 "Pairwise_Consistency_Test".
 323
 324 There is only one instance of the "Module_Integrity" and "Install_Integrity"
 325 self tests. All other self tests may have multiple instances.
 326
 327
 328 The FIPS module passes the following descriptions(s) to OSSL_SELF_TEST_onbegin().
 329
 330 =over 4
 331
 332 =item "HMAC" (B<OSSL_SELF_TEST_DESC_INTEGRITY_HMAC>)
 333
 334 "Module_Integrity" and "Install_Integrity" use this.
 335
 336 =item "RSA" (B<OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1>)
 337
 338 =item "ECDSA" (B<OSSL_SELF_TEST_DESC_PCT_ECDSA>)
 339
 340 =item "EDDSA" (B<OSSL_SELF_TEST_DESC_PCT_EDDSA>)
 341
 342 =item "DSA" (B<OSSL_SELF_TEST_DESC_PCT_DSA>)
 343
 344 Key generation tests used with the "Pairwise_Consistency_Test" type.
 345
 346 =item "RSA_Encrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_ENC>)
 347
 348 =item "RSA_Decrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_DEC>)
 349
 350 "KAT_AsymmetricCipher" uses this to indicate an encrypt or decrypt KAT.
 351
 352 =item "AES_GCM" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_GCM>)
 353
 354 =item "AES_ECB_Decrypt" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_ECB>)
 355
 356 =item "TDES" (B<OSSL_SELF_TEST_DESC_CIPHER_TDES>)
 357
 358 Symmetric cipher tests used with the "KAT_Cipher" type.
 359
 360 =item "SHA1" (B<OSSL_SELF_TEST_DESC_MD_SHA1>)
 361
 362 =item "SHA2" (B<OSSL_SELF_TEST_DESC_MD_SHA2>)
 363
 364 =item "SHA3" (B<OSSL_SELF_TEST_DESC_MD_SHA3>)
 365
 366 Digest tests used with the "KAT_Digest" type.
 367
 368 =item "DSA" (B<OSSL_SELF_TEST_DESC_SIGN_DSA>)
 369
 370 =item "RSA" (B<OSSL_SELF_TEST_DESC_SIGN_RSA>)
 371
 372 =item "ECDSA" (B<OSSL_SELF_TEST_DESC_SIGN_ECDSA>)
 373
 374 Signature tests used with the "KAT_Signature" type.
 375
 376 =item "ECDH" (B<OSSL_SELF_TEST_DESC_KA_ECDH>)
 377
 378 =item "DH" (B<OSSL_SELF_TEST_DESC_KA_DH>)
 379
 380 Key agreement tests used with the "KAT_KA" type.
 381
 382 =item "HKDF" (B<OSSL_SELF_TEST_DESC_KDF_HKDF>)
 383
 384 =item "TLS13_KDF_EXTRACT" (B<OSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT>)
 385
 386 =item "TLS13_KDF_EXPAND" (B<OSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND>)
 387
 388 =item "SSKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSKDF>)
 389
 390 =item "X963KDF" (B<OSSL_SELF_TEST_DESC_KDF_X963KDF>)
 391
 392 =item "X942KDF" (B<OSSL_SELF_TEST_DESC_KDF_X942KDF>)
 393
 394 =item "PBKDF2" (B<OSSL_SELF_TEST_DESC_KDF_PBKDF2>)
 395
 396 =item "SSHKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSHKDF>)
 397
 398 =item "TLS12_PRF" (B<OSSL_SELF_TEST_DESC_KDF_TLS12_PRF>)
 399
 400 =item "KBKDF" (B<OSSL_SELF_TEST_DESC_KDF_KBKDF>)
 401
 402 Key Derivation Function tests used with the "KAT_KDF" type.
 403
 404 =item "CTR" (B<OSSL_SELF_TEST_DESC_DRBG_CTR>)
 405
 406 =item "HASH" (B<OSSL_SELF_TEST_DESC_DRBG_HASH>)
 407
 408 =item "HMAC" (B<OSSL_SELF_TEST_DESC_DRBG_HMAC>)
 409
 410 DRBG tests used with the "DRBG" type.
 411
 412 =item "RNG" (B<OSSL_SELF_TEST_DESC_RNG>)
 413
 414 "Continuous_RNG_Test" uses this.
 415
 416 =back
 417
 418 =head1 EXAMPLES
 419
 420 A simple self test callback is shown below for illustrative purposes.
 421
 422   #include <openssl/self_test.h>
 423
 424   static OSSL_CALLBACK self_test_cb;
 425
 426   static int self_test_cb(const OSSL_PARAM params[], void *arg)
 427   {
 428     int ret = 0;
 429     const OSSL_PARAM *p = NULL;
 430     const char *phase = NULL, *type = NULL, *desc = NULL;
 431
 432     p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE);
 433     if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
 434         goto err;
 435     phase = (const char *)p->data;
 436
 437     p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC);
 438     if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
 439         goto err;
 440     desc = (const char *)p->data;
 441
 442     p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE);
 443     if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
 444         goto err;
 445     type = (const char *)p->data;
 446
 447     /* Do some logging */
 448     if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0)
 449         BIO_printf(bio_out, "%s : (%s) : ", desc, type);
 450     if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0
 451             || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0)
 452         BIO_printf(bio_out, "%s\n", phase);
 453
 454     /* Corrupt the SHA1 self test during the 'corrupt' phase by returning 0 */
 455     if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0
 456             && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) {
 457         BIO_printf(bio_out, "%s %s", phase, desc);
 458         return 0;
 459     }
 460     ret = 1;
 461   err:
 462     return ret;
 463   }
 464
 465 =head1 NOTES
 466
 467 Some released versions of OpenSSL do not include a validated
 468 FIPS provider.  To determine which versions have undergone
 469 the validation process, please refer to the
 470 L<OpenSSL Downloads page|https://www.openssl.org/source/>.  If you
 471 require FIPS-approved functionality, it is essential to build your FIPS
 472 provider using one of the validated versions listed there.  Normally,
 473 it is possible to utilize a FIPS provider constructed from one of the
 474 validated versions alongside F<libcrypto> and F<libssl> compiled from any
 475 release within the same major release series.  This flexibility enables
 476 you to address bug fixes and CVEs that fall outside the FIPS boundary.
 477
 478 The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated algorithms,
 479 consequently the property query C<fips=yes> is mandatory for applications that
 480 want to operate in a FIPS approved manner.  The algorithms are:
 481
 482 =over 4
 483
 484 =item Triple DES ECB
 485
 486 =item Triple DES CBC
 487
 488 =item EdDSA
 489
 490 =back
 491
 492 =head1 SEE ALSO
 493
 494 L<openssl-fipsinstall(1)>,
 495 L<fips_config(5)>,
 496 L<OSSL_SELF_TEST_set_callback(3)>,
 497 L<OSSL_SELF_TEST_new(3)>,
 498 L<OSSL_PARAM(3)>,
 499 L<openssl-core.h(7)>,
 500 L<openssl-core_dispatch.h(7)>,
 501 L<provider(7)>,
 502 L<https://www.openssl.org/source/>
 503
 504 =head1 HISTORY
 505
 506 This functionality was added in OpenSSL 3.0.
 507
 508 =head1 COPYRIGHT
 509
 510 Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved.
 511
 512 Licensed under the Apache License 2.0 (the "License").  You may not use
 513 this file except in compliance with the License.  You can obtain a copy
 514 in the file LICENSE in the source distribution or at
 515 L<https://www.openssl.org/source/license.html>.
 516
 517 =cut