1=pod 2 3=head1 NAME 4 5OSSL_PROVIDER-FIPS - OpenSSL FIPS provider 6 7=head1 DESCRIPTION 8 9The OpenSSL FIPS provider is a special provider that conforms to the Federal 10Information Processing Standards (FIPS) specified in FIPS 140-3. This 'module' 11contains an approved set of cryptographic algorithms that is validated by an 12accredited testing laboratory. 13 14=head2 Properties 15 16The implementations in this provider specifically have these properties 17defined: 18 19=over 4 20 21=item "provider=fips" 22 23=item "fips=yes" 24 25=back 26 27It may be used in a property query string with fetching functions such as 28L<EVP_MD_fetch(3)> or L<EVP_CIPHER_fetch(3)>, as well as with other 29functions that take a property query string, such as 30L<EVP_PKEY_CTX_new_from_name(3)>. 31 32To be FIPS compliant, it is mandatory to include C<fips=yes> as 33part of all property queries. This ensures that only FIPS approved 34implementations are used for cryptographic operations. The C<fips=yes> 35query may also include other non-crypto support operations that 36are not in the FIPS provider, such as asymmetric key encoders, see 37L<OSSL_PROVIDER-default(7)/Asymmetric Key Management>. 38 39It is not mandatory to include C<provider=fips> as part of your property 40query. Including C<provider=fips> in your property query guarantees 41that the OpenSSL FIPS provider is used for cryptographic operations 42rather than other FIPS capable providers. 43 44=head2 Provider parameters 45 46See L<provider-base(7)/Provider parameters> for a list of base parameters. 47Additionally the OpenSSL FIPS provider also supports the following gettable 48parameters: 49 50=over 4 51 52=item "security-checks" (B<OSSL_OSSL_PROV_PARAM_SECURITY_CHECKS>) <unsigned integer> 53 54For further information refer to the L<openssl-fipsinstall(1)> option 55B<-no_security_checks>. 56 57=back 58 59=head1 OPERATIONS AND ALGORITHMS 60 61The 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 87This 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 ML-KEM, see L<EVP_KEM-ML-KEM(7)> 144 145=item TLS1-PRF 146 147=item HKDF 148 149=back 150 151=head2 Asymmetric Signature 152 153=over 4 154 155=item RSA, see L<EVP_SIGNATURE-RSA(7)> 156 157The B<X931> padding mode "OSSL_PKEY_RSA_PAD_MODE_X931" is no longer supported 158for signature generation, but may be used for verification for legacy use cases. 159(This is a FIPS 140-3 requirement) 160 161=item DSA, see L<EVP_SIGNATURE-DSA(7)> 162 163=item ED25519, see L<EVP_SIGNATURE-ED25519(7)> 164 165=item ED448, see L<EVP_SIGNATURE-ED448(7)> 166 167=item ECDSA, see L<EVP_SIGNATURE-ECDSA(7)> 168 169=item ML-DSA-44, see L<EVP_SIGNATURE-ML-DSA(7)> 170 171=item ML-DSA-65, see L<EVP_SIGNATURE-ML-DSA(7)> 172 173=item ML-DSA-87, see L<EVP_SIGNATURE-ML-DSA(7)> 174 175=item SLH-DSA, see L<EVP_SIGNATURE-SLH-DSA(7)> 176 177=item HMAC, see L<EVP_SIGNATURE-HMAC(7)> 178 179=item CMAC, see L<EVP_SIGNATURE-CMAC(7)> 180 181=back 182 183=head2 Asymmetric Cipher 184 185=over 4 186 187=item RSA, see L<EVP_ASYM_CIPHER-RSA(7)> 188 189=back 190 191=head2 Asymmetric Key Encapsulation 192 193=over 4 194 195=item RSA, see L<EVP_KEM-RSA(7)> 196 197=back 198 199=head2 Asymmetric Key Management 200 201=over 4 202 203=item DH, see L<EVP_KEYMGMT-DH(7)> 204 205=item DHX, see L<EVP_KEYMGMT-DHX(7)> 206 207=item DSA, see L<EVP_KEYMGMT-DSA(7)> 208 209=item RSA, see L<EVP_KEYMGMT-RSA(7)> 210 211=item RSA-PSS 212 213=item EC, see L<EVP_KEYMGMT-EC(7)> 214 215=item X25519, see L<EVP_KEYMGMT-X25519(7)> 216 217This is an unapproved algorithm. 218 219=item X448, see L<EVP_KEYMGMT-X448(7)> 220 221This is an unapproved algorithm. 222 223=item ED25519, see L<EVP_KEYMGMT-ED25519(7)> 224 225This is an unapproved algorithm. 226 227=item ED448, see L<EVP_KEYMGMT-ED448(7)> 228 229This is an unapproved algorithm. 230 231=item TLS1-PRF 232 233=item HKDF 234 235=item HMAC, see L<EVP_KEYMGMT-HMAC(7)> 236 237=item CMAC, see L<EVP_KEYMGMT-CMAC(7)> 238 239=item ML-DSA-44, see L<EVP_KEYMGMT-ML-DSA(7)> 240 241=item ML-DSA-65, see L<EVP_KEYMGMT-ML-DSA(7)> 242 243=item ML-DSA-87, see L<EVP_KEYMGMT-ML-DSA(7)> 244 245=item SLH-DSA-SHA2-128s, see L<EVP_KEYMGMT-SLH-DSA(7)> 246 247=item SLH-DSA-SHA2-128f, see L<EVP_KEYMGMT-SLH-DSA(7)> 248 249=item SLH-DSA-SHA2-192s, see L<EVP_KEYMGMT-SLH-DSA(7)> 250 251=item SLH-DSA-SHA2-192f, see L<EVP_KEYMGMT-SLH-DSA(7)> 252 253=item SLH-DSA-SHA2-256s, see L<EVP_KEYMGMT-SLH-DSA(7)> 254 255=item SLH-DSA-SHA2-256f, see L<EVP_KEYMGMT-SLH-DSA(7)> 256 257=item SLH-DSA-SHAKE-128s, see L<EVP_KEYMGMT-SLH-DSA(7)> 258 259=item SLH-DSA-SHAKE-128f, see L<EVP_KEYMGMT-SLH-DSA(7)> 260 261=item SLH-DSA-SHAKE-192s, see L<EVP_KEYMGMT-SLH-DSA(7)> 262 263=item SLH-DSA-SHAKE-192f, see L<EVP_KEYMGMT-SLH-DSA(7)> 264 265=item SLH-DSA-SHAKE-256s, see L<EVP_KEYMGMT-SLH-DSA(7)> 266 267=item SLH-DSA-SHAKE-256f, see L<EVP_KEYMGMT-SLH-DSA(7)> 268 269=back 270 271=head2 Random Number Generation 272 273=over 4 274 275=item CRNG-TEST, see L<EVP_RAND-CRNG-TEST(7)> 276 277=item CTR-DRBG, see L<EVP_RAND-CTR-DRBG(7)> 278 279=item HASH-DRBG, see L<EVP_RAND-HASH-DRBG(7)> 280 281=item HMAC-DRBG, see L<EVP_RAND-HMAC-DRBG(7)> 282 283=item TEST-RAND, see L<EVP_RAND-TEST-RAND(7)> 284 285TEST-RAND is an unapproved algorithm. 286 287=back 288 289=head1 SELF TESTING 290 291One of the requirements for the FIPS module is self testing. An optional callback 292mechanism is available to return information to the user using 293L<OSSL_SELF_TEST_set_callback(3)>. 294 295The parameters passed to the callback are described in L<OSSL_SELF_TEST_new(3)> 296 297The OpenSSL FIPS module uses the following mechanism to provide information 298about the self tests as they run. 299This is useful for debugging if a self test is failing. 300The callback also allows forcing any self test to fail, in order to check that 301it operates correctly on failure. 302Note that all self tests run even if a self test failure occurs. 303 304The FIPS module passes the following type(s) to OSSL_SELF_TEST_onbegin(). 305 306=over 4 307 308=item "Module_Integrity" (B<OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY>) 309 310Uses HMAC SHA256 on the module file to validate that the module has not been 311modified. The integrity value is compared to a value written to a configuration 312file during installation. 313 314=item "Install_Integrity" (B<OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY>) 315 316Uses HMAC SHA256 on a fixed string to validate that the installation process 317has already been performed and the self test KATS have already been tested, 318The integrity value is compared to a value written to a configuration 319file after successfully running the self tests during installation. 320 321=item "KAT_Cipher" (B<OSSL_SELF_TEST_TYPE_KAT_CIPHER>) 322 323Known answer test for a symmetric cipher. 324 325=item "KAT_AsymmetricCipher" (B<OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER>) 326 327Known answer test for a asymmetric cipher. 328 329=item "KAT_Digest" (B<OSSL_SELF_TEST_TYPE_KAT_DIGEST>) 330 331Known answer test for a digest. 332 333=item "KAT_AsymmetricKeyGeneration" (B<OSSL_SELF_TEST_TYPE_KAT_ASYM_KEYGEN>) 334 335Known answer test for asymmetric key generation. 336 337=item "KAT_Signature" (B<OSSL_SELF_TEST_TYPE_KAT_SIGNATURE>) 338 339Known answer test for a signature. 340 341=item "PCT_Signature" (B<OSSL_SELF_TEST_TYPE_PCT_SIGNATURE>) 342 343Pairwise Consistency check for a signature. 344 345=item "KAT_KDF" (B<OSSL_SELF_TEST_TYPE_KAT_KDF>) 346 347Known answer test for a key derivation function. 348 349=item "KAT_KA" (B<OSSL_SELF_TEST_TYPE_KAT_KA>) 350 351Known answer test for key agreement. 352 353=item "KAT_KEM" (B<OSSL_SELF_TEST_TYPE_KAT_KEM>) 354 355Known answer test for key encapsulation. 356 357=item "DRBG" (B<OSSL_SELF_TEST_TYPE_DRBG>) 358 359Known answer test for a Deterministic Random Bit Generator. 360 361=item "Conditional_PCT" (B<OSSL_SELF_TEST_TYPE_PCT>) 362 363Conditional test that is run during the generation or importing of key pairs. 364 365=item "Continuous_RNG_Test" (B<OSSL_SELF_TEST_TYPE_CRNG>) 366 367Continuous random number generator test. 368 369=back 370 371The "Module_Integrity" self test is always run at startup. 372The "Install_Integrity" self test is used to check if the self tests have 373already been run at installation time. If they have already run then the 374self tests are not run on subsequent startups. 375All other self test categories are run once at installation time, except for the 376"Pairwise_Consistency_Test". 377 378There is only one instance of the "Module_Integrity" and "Install_Integrity" 379self tests. All other self tests may have multiple instances. 380 381 382The FIPS module passes the following descriptions(s) to OSSL_SELF_TEST_onbegin(). 383 384=over 4 385 386=item "HMAC" (B<OSSL_SELF_TEST_DESC_INTEGRITY_HMAC>) 387 388"Module_Integrity" and "Install_Integrity" use this. 389 390=item "RSA" (B<OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1>) 391 392=item "RSA" (B<OSSL_SELF_TEST_DESC_PCT_RSA>) 393 394=item "ECDSA" (B<OSSL_SELF_TEST_DESC_PCT_ECDSA>) 395 396=item "EDDSA" (B<OSSL_SELF_TEST_DESC_PCT_EDDSA>) 397 398=item "DSA" (B<OSSL_SELF_TEST_DESC_PCT_DSA>) 399 400=item "ML-DSA" (B<OSSL_SELF_TEST_DESC_PCT_ML_DSA>) 401 402=item "ML-KEM" (B<OSSL_SELF_TEST_DESC_PCT_ML_KEM>) 403 404=item "SLH-DSA" (B<OSSL_SELF_TEST_DESC_PCT_SLH_DSA>) 405 406Key generation tests used with the "Pairwise_Consistency_Test" type. 407 408=item "RSA_Encrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_ENC>) 409 410=item "RSA_Decrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_DEC>) 411 412"KAT_AsymmetricCipher" uses this to indicate an encrypt or decrypt KAT. 413 414=item "ML-DSA" (B<OSSL_SELF_TEST_DESC_KEYGEN_ML_DSA>) 415 416=item "ML-KEM" (B<OSSL_SELF_TEST_DESC_KEYGEN_ML_KEM>) 417 418=item "SLH-DSA" (B<OSSL_SELF_TEST_DESC_KEYGEN_SLH_DSA>) 419 420"KAT_AsymmetricKeyGeneration" uses this to indicate a key generation KAT. 421 422=item "AES_GCM" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_GCM>) 423 424=item "AES_ECB_Decrypt" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_ECB>) 425 426=item "TDES" (B<OSSL_SELF_TEST_DESC_CIPHER_TDES>) 427 428Symmetric cipher tests used with the "KAT_Cipher" type. 429 430=item "SHA1" (B<OSSL_SELF_TEST_DESC_MD_SHA1>) 431 432=item "SHA2" (B<OSSL_SELF_TEST_DESC_MD_SHA2>) 433 434=item "SHA3" (B<OSSL_SELF_TEST_DESC_MD_SHA3>) 435 436Digest tests used with the "KAT_Digest" type. 437 438=item "DSA" (B<OSSL_SELF_TEST_DESC_SIGN_DSA>) 439 440=item "RSA" (B<OSSL_SELF_TEST_DESC_SIGN_RSA>) 441 442=item "ECDSA" (B<OSSL_SELF_TEST_DESC_SIGN_ECDSA>) 443 444=item "EDDSA" (B<OSSL_SELF_TEST_DESC_SIGN_EDDSA>) 445 446=item "ML-DSA" (B<OSSL_SELF_TEST_DESC_SIGN_ML_DSA>) 447 448=item "SLH-DSA" (B<OSSL_SELF_TEST_DESC_SIGN_SLH_DSA>) 449 450Signature tests used with the "KAT_Signature" type. 451 452=item "ECDH" (B<OSSL_SELF_TEST_DESC_KA_ECDH>) 453 454=item "DH" (B<OSSL_SELF_TEST_DESC_KA_DH>) 455 456Key agreement tests used with the "KAT_KA" type. 457 458=item "HKDF" (B<OSSL_SELF_TEST_DESC_KDF_HKDF>) 459 460=item "TLS13_KDF_EXTRACT" (B<OSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT>) 461 462=item "TLS13_KDF_EXPAND" (B<OSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND>) 463 464=item "SSKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSKDF>) 465 466=item "X963KDF" (B<OSSL_SELF_TEST_DESC_KDF_X963KDF>) 467 468=item "X942KDF" (B<OSSL_SELF_TEST_DESC_KDF_X942KDF>) 469 470=item "PBKDF2" (B<OSSL_SELF_TEST_DESC_KDF_PBKDF2>) 471 472=item "SSHKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSHKDF>) 473 474=item "TLS12_PRF" (B<OSSL_SELF_TEST_DESC_KDF_TLS12_PRF>) 475 476=item "KBKDF" (B<OSSL_SELF_TEST_DESC_KDF_KBKDF>) 477 478Key Encapsulation Function tests used with the "KAT_KEM" type. 479 480=item "KEM_Encap" (B<OSSL_SELF_TEST_DESC_ENCAP_KEM>) 481 482=item "KEM_Decap" (B<OSSL_SELF_TEST_DESC_DECAP_KEM>) 483 484=item "KEM_Decap_Reject" (B<OSSL_SELF_TEST_DESC_DECAP_REJ_KEM>) 485 486Key Derivation Function tests used with the "KAT_KDF" type. 487 488=item "CTR" (B<OSSL_SELF_TEST_DESC_DRBG_CTR>) 489 490=item "HASH" (B<OSSL_SELF_TEST_DESC_DRBG_HASH>) 491 492=item "HMAC" (B<OSSL_SELF_TEST_DESC_DRBG_HMAC>) 493 494DRBG tests used with the "DRBG" type. 495 496=item "RNG" (B<OSSL_SELF_TEST_DESC_RNG>) 497 498"Continuous_RNG_Test" uses this. 499 500=back 501 502=head1 EXAMPLES 503 504A simple self test callback is shown below for illustrative purposes. 505 506 #include <openssl/self_test.h> 507 508 static OSSL_CALLBACK self_test_cb; 509 510 static int self_test_cb(const OSSL_PARAM params[], void *arg) 511 { 512 int ret = 0; 513 const OSSL_PARAM *p = NULL; 514 const char *phase = NULL, *type = NULL, *desc = NULL; 515 516 p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE); 517 if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) 518 goto err; 519 phase = (const char *)p->data; 520 521 p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC); 522 if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) 523 goto err; 524 desc = (const char *)p->data; 525 526 p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE); 527 if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) 528 goto err; 529 type = (const char *)p->data; 530 531 /* Do some logging */ 532 if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0) 533 BIO_printf(bio_out, "%s : (%s) : ", desc, type); 534 if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0 535 || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0) 536 BIO_printf(bio_out, "%s\n", phase); 537 538 /* Corrupt the SHA1 self test during the 'corrupt' phase by returning 0 */ 539 if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0 540 && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) { 541 BIO_printf(bio_out, "%s %s", phase, desc); 542 return 0; 543 } 544 ret = 1; 545 err: 546 return ret; 547 } 548 549=head1 NOTES 550 551Some released versions of OpenSSL do not include a validated 552FIPS provider. To determine which versions have undergone 553the validation process, please refer to the 554L<OpenSSL Downloads page|https://www.openssl.org/source/>. If you 555require FIPS-approved functionality, it is essential to build your FIPS 556provider using one of the validated versions listed there. Normally, 557it is possible to utilize a FIPS provider constructed from one of the 558validated versions alongside F<libcrypto> and F<libssl> compiled from any 559release within the same major release series. This flexibility enables 560you to address bug fixes and CVEs that fall outside the FIPS boundary. 561 562The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated algorithms, 563consequently the property query C<fips=yes> is mandatory for applications that 564want to operate in a FIPS approved manner. The algorithms are: 565 566=over 4 567 568=item Triple DES ECB 569 570=item Triple DES CBC 571 572=item EdDSA 573 574=back 575 576You can load the FIPS provider into multiple library contexts as any other 577provider. However the following restriction applies. The FIPS provider cannot 578be used by multiple copies of OpenSSL libcrypto in a single process. 579 580As the provider saves core callbacks to the libcrypto obtained in the 581OSSL_provider_init() call to global data it will fail if subsequent 582invocations of its OSSL_provider_init() function yield different addresses 583of these callbacks than in the initial call. This happens when different 584copies of libcrypto are present in the memory of the process and both try 585to load the same FIPS provider. A workaround is to have a different copy 586of the FIPS provider loaded for each of the libcrypto instances in the 587process. 588 589=head1 SEE ALSO 590 591L<openssl-fipsinstall(1)>, 592L<fips_config(5)>, 593L<OSSL_SELF_TEST_set_callback(3)>, 594L<OSSL_SELF_TEST_new(3)>, 595L<OSSL_PARAM(3)>, 596L<openssl-core.h(7)>, 597L<openssl-core_dispatch.h(7)>, 598L<provider(7)>, 599L<https://www.openssl.org/source/> 600 601=head1 HISTORY 602 603This functionality was added in OpenSSL 3.0. 604 605=head1 COPYRIGHT 606 607Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved. 608 609Licensed under the Apache License 2.0 (the "License"). You may not use 610this file except in compliance with the License. You can obtain a copy 611in the file LICENSE in the source distribution or at 612L<https://www.openssl.org/source/license.html>. 613 614=cut 615