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 for approved algorithms: 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 Approved algorithms 45 46Algorithms that are fetched using "fips=yes" may still be unapproved if certain 47conditions are not met. See L<fips_module(7)/FIPS indicators> for additional 48information. 49 50=head2 Provider parameters 51 52See L<provider-base(7)/Provider parameters> for a list of base parameters. 53The OpenSSL FIPS provider also handles FIPS indicator related parameters as 54specified by L<fips_config(5)/FIPS indicator options>. 55 56=head1 OPERATIONS AND ALGORITHMS 57 58The OpenSSL FIPS provider supports these operations and algorithms: 59 60=head2 Hashing Algorithms / Message Digests 61 62=over 4 63 64=item SHA1, see L<EVP_MD-SHA1(7)> 65 66=item SHA2, see L<EVP_MD-SHA2(7)> 67 68=item SHA3, see L<EVP_MD-SHA3(7)> 69 70=item SHAKE, see L<EVP_MD-SHAKE(7)> 71 72=item KECCAK-KMAC, see L<EVP_MD-KECCAK-KMAC(7)> 73 74KECCAK-KMAC is only used internally as a sub algorithm of KMAC. 75 76=back 77 78=head2 Symmetric Ciphers 79 80=over 4 81 82=item AES, see L<EVP_CIPHER-AES(7)> 83 84=item 3DES, see L<EVP_CIPHER-DES(7)> 85 86=back 87 88=head2 Message Authentication Code (MAC) 89 90=over 4 91 92=item CMAC, see L<EVP_MAC-CMAC(7)> 93 94=item GMAC, see L<EVP_MAC-GMAC(7)> 95 96=item HMAC, see L<EVP_MAC-HMAC(7)> 97 98=item KMAC, see L<EVP_MAC-KMAC(7)> 99 100=back 101 102=head2 Key Derivation Function (KDF) 103 104=over 4 105 106=item HKDF, see L<EVP_KDF-HKDF(7)> 107 108=item HKDF-SHA256, see L<EVP_KDF-HKDF(7)> 109 110=item HKDF-SHA384, see L<EVP_KDF-HKDF(7)> 111 112=item HKDF-SHA512, see L<EVP_KDF-HKDF(7)> 113 114=item TLS13-KDF, see L<EVP_KDF-TLS13_KDF(7)> 115 116=item SSKDF, see L<EVP_KDF-SS(7)> 117 118=item PBKDF2, see L<EVP_KDF-PBKDF2(7)> 119 120=item SSHKDF, see L<EVP_KDF-SSHKDF(7)> 121 122=item TLS1-PRF, see L<EVP_KDF-TLS1_PRF(7)> 123 124=item KBKDF, see L<EVP_KDF-KB(7)> 125 126=item X942KDF-ASN1, see L<EVP_KDF-X942-ASN1(7)> 127 128=item X942KDF-CONCAT, see L<EVP_KDF-X942-CONCAT(7)> 129 130=item X963KDF, see L<EVP_KDF-X963(7)> 131 132=back 133 134=head2 Key Exchange 135 136=over 4 137 138=item DH, see L<EVP_KEYEXCH-DH(7)> 139 140=item ECDH, see L<EVP_KEYEXCH-ECDH(7)> 141 142=item X25519, see L<EVP_KEYEXCH-X25519(7)> 143 144=item X448, see L<EVP_KEYEXCH-X448(7)> 145 146=item ML-KEM, see L<EVP_KEM-ML-KEM(7)> 147 148=item TLS1-PRF 149 150=item HKDF 151 152=back 153 154=head2 Asymmetric Signature 155 156=over 4 157 158=item RSA, see L<EVP_SIGNATURE-RSA(7)> 159 160The B<X931> padding mode "OSSL_PKEY_RSA_PAD_MODE_X931" is no longer supported 161for signature generation, but may be used for verification for legacy use cases. 162(This is a FIPS 140-3 requirement) 163 164=item DSA, see L<EVP_SIGNATURE-DSA(7)> 165 166=item ED25519, see L<EVP_SIGNATURE-ED25519(7)> 167 168=item ED448, see L<EVP_SIGNATURE-ED448(7)> 169 170=item ECDSA, see L<EVP_SIGNATURE-ECDSA(7)> 171 172=item ML-DSA-44, see L<EVP_SIGNATURE-ML-DSA(7)> 173 174=item ML-DSA-65, see L<EVP_SIGNATURE-ML-DSA(7)> 175 176=item ML-DSA-87, see L<EVP_SIGNATURE-ML-DSA(7)> 177 178=item SLH-DSA, see L<EVP_SIGNATURE-SLH-DSA(7)> 179 180=item HMAC, see L<EVP_SIGNATURE-HMAC(7)> 181 182=item CMAC, see L<EVP_SIGNATURE-CMAC(7)> 183 184=item LMS, see L<EVP_SIGNATURE-LMS(7)> 185 186=back 187 188=head2 Asymmetric Cipher 189 190=over 4 191 192=item RSA, see L<EVP_ASYM_CIPHER-RSA(7)> 193 194=back 195 196=head2 Asymmetric Key Encapsulation 197 198=over 4 199 200=item RSA, see L<EVP_KEM-RSA(7)> 201 202=back 203 204=head2 Asymmetric Key Management 205 206=over 4 207 208=item DH, see L<EVP_KEYMGMT-DH(7)> 209 210=item DHX, see L<EVP_KEYMGMT-DHX(7)> 211 212=item DSA, see L<EVP_KEYMGMT-DSA(7)> 213 214=item RSA, see L<EVP_KEYMGMT-RSA(7)> 215 216=item RSA-PSS 217 218=item EC, see L<EVP_KEYMGMT-EC(7)> 219 220=item ED25519, see L<EVP_KEYMGMT-ED25519(7)> 221 222=item ED448, see L<EVP_KEYMGMT-ED448(7)> 223 224=item X25519, see L<EVP_KEYMGMT-X25519(7)> 225 226This is an unapproved algorithm. 227The FIPS 140-3 IG states that "Curves that are included in SP 800-186 but not 228included in SP 800-56Arev3 are not approved for key agreement". 229 230=item X448, see L<EVP_KEYMGMT-X448(7)> 231 232This is an unapproved algorithm. 233The FIPS 140-3 IG states that "Curves that are included in SP 800-186 but not" 234included in SP 800-56Arev3 are not approved for key agreement". 235 236=item TLS1-PRF 237 238=item HKDF 239 240=item HMAC, see L<EVP_KEYMGMT-HMAC(7)> 241 242=item CMAC, see L<EVP_KEYMGMT-CMAC(7)> 243 244=item ML-DSA-44, see L<EVP_KEYMGMT-ML-DSA(7)> 245 246=item ML-DSA-65, see L<EVP_KEYMGMT-ML-DSA(7)> 247 248=item ML-DSA-87, see L<EVP_KEYMGMT-ML-DSA(7)> 249 250=item SLH-DSA-SHA2-128s, see L<EVP_KEYMGMT-SLH-DSA(7)> 251 252=item SLH-DSA-SHA2-128f, see L<EVP_KEYMGMT-SLH-DSA(7)> 253 254=item SLH-DSA-SHA2-192s, see L<EVP_KEYMGMT-SLH-DSA(7)> 255 256=item SLH-DSA-SHA2-192f, see L<EVP_KEYMGMT-SLH-DSA(7)> 257 258=item SLH-DSA-SHA2-256s, see L<EVP_KEYMGMT-SLH-DSA(7)> 259 260=item SLH-DSA-SHA2-256f, see L<EVP_KEYMGMT-SLH-DSA(7)> 261 262=item SLH-DSA-SHAKE-128s, see L<EVP_KEYMGMT-SLH-DSA(7)> 263 264=item SLH-DSA-SHAKE-128f, see L<EVP_KEYMGMT-SLH-DSA(7)> 265 266=item SLH-DSA-SHAKE-192s, see L<EVP_KEYMGMT-SLH-DSA(7)> 267 268=item SLH-DSA-SHAKE-192f, see L<EVP_KEYMGMT-SLH-DSA(7)> 269 270=item SLH-DSA-SHAKE-256s, see L<EVP_KEYMGMT-SLH-DSA(7)> 271 272=item SLH-DSA-SHAKE-256f, see L<EVP_KEYMGMT-SLH-DSA(7)> 273 274=back 275 276=head2 Random Number Generation 277 278=over 4 279 280=item CRNG-TEST, see L<EVP_RAND-CRNG-TEST(7)> 281 282=item CTR-DRBG, see L<EVP_RAND-CTR-DRBG(7)> 283 284=item HASH-DRBG, see L<EVP_RAND-HASH-DRBG(7)> 285 286=item HMAC-DRBG, see L<EVP_RAND-HMAC-DRBG(7)> 287 288=item TEST-RAND, see L<EVP_RAND-TEST-RAND(7)> 289 290TEST-RAND is an unapproved algorithm. 291 292=back 293 294=head1 SELF TESTING 295 296A requirement of FIPS modules is to run cryptographic algorithm self tests. 297FIPS 140-3 requires known answer tests to be run on startup as well as 298conditional tests that run during cryptographic operations. 299 300An optional callback mechanism is available to return information to the user using 301L<OSSL_SELF_TEST_set_callback(3)>. 302 303The parameters passed to the callback are described in L<OSSL_SELF_TEST_new(3)> 304 305The OpenSSL FIPS module uses the following mechanism to provide information 306about the self tests as they run. 307This is useful for debugging if a self test is failing. 308The callback also allows forcing any self test to fail, in order to check that 309it operates correctly on failure. 310Note that all self tests run even if a self test failure occurs. 311 312The FIPS module passes the following type(s) to OSSL_SELF_TEST_onbegin(). 313 314=over 4 315 316=item "Module_Integrity" (B<OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY>) 317 318Uses HMAC SHA256 on the module file to validate that the module has not been 319modified. The integrity value is compared to a value written to a configuration 320file during installation. 321 322=item "KAT_Integrity" (B<OSSL_SELF_TEST_TYPE_KAT_INTEGRITY>) 323 324Used during the Module Integrity test to perform a known answer test on 325HMAC SHA256 prior to using it. 326 327=item "KAT_Cipher" (B<OSSL_SELF_TEST_TYPE_KAT_CIPHER>) 328 329Known answer test for a symmetric cipher. 330 331=item "KAT_AsymmetricCipher" (B<OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER>) 332 333Known answer test for a asymmetric cipher. 334 335=item "KAT_Digest" (B<OSSL_SELF_TEST_TYPE_KAT_DIGEST>) 336 337Known answer test for a digest. 338 339=item "KAT_AsymmetricKeyGeneration" (B<OSSL_SELF_TEST_TYPE_KAT_ASYM_KEYGEN>) 340 341Known answer test for asymmetric key generation. 342 343=item "KAT_Signature" (B<OSSL_SELF_TEST_TYPE_KAT_SIGNATURE>) 344 345Known answer test for a signature. 346 347=item "PCT_Signature" (B<OSSL_SELF_TEST_TYPE_PCT_SIGNATURE>) 348 349Pairwise Consistency check for a signature. 350 351=item "KAT_KDF" (B<OSSL_SELF_TEST_TYPE_KAT_KDF>) 352 353Known answer test for a key derivation function. 354 355=item "KAT_KA" (B<OSSL_SELF_TEST_TYPE_KAT_KA>) 356 357Known answer test for key agreement. 358 359=item "KAT_KEM" (B<OSSL_SELF_TEST_TYPE_KAT_KEM>) 360 361Known answer test for key encapsulation. 362 363=item "DRBG" (B<OSSL_SELF_TEST_TYPE_DRBG>) 364 365Known answer test for a Deterministic Random Bit Generator. 366 367=item "Conditional_PCT" (B<OSSL_SELF_TEST_TYPE_PCT>) 368 369Conditional test that is run during the generation or importing of key pairs. 370 371=item "Conditional_KAT" (B<OSSL_SELF_TEST_TYPE_PCT_KAT>) 372 373Conditional test run during generation that derive the public key from the 374private key and checks that the public key matches. This is a SP 800-56A requirement. 375 376=item "Continuous_RNG_Test" (B<OSSL_SELF_TEST_TYPE_CRNG>) 377 378Continuous random number generator test. 379 380=item "Install_Integrity" (B<OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY>) 381 382This is deprecated. The option is no longer used since FIPS 140-3 requires 383self tests to always run on startup. Previous FIPS 140-2 validations allowed 384the self tests to be run just once. 385 386=back 387 388The FIPS module passes the following descriptions(s) to OSSL_SELF_TEST_onbegin(). 389 390=over 4 391 392=item "HMAC" (B<OSSL_SELF_TEST_DESC_INTEGRITY_HMAC>) 393 394"Module_Integrity" uses this. 395 396=item "RSA" (B<OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1>) 397 398=item "RSA" (B<OSSL_SELF_TEST_DESC_PCT_RSA>) 399 400=item "ECDSA" (B<OSSL_SELF_TEST_DESC_PCT_ECDSA>) 401 402=item "EDDSA" (B<OSSL_SELF_TEST_DESC_PCT_EDDSA>) 403 404=item "DSA" (B<OSSL_SELF_TEST_DESC_PCT_DSA>) 405 406=item "ML-DSA" (B<OSSL_SELF_TEST_DESC_PCT_ML_DSA>) 407 408=item "ML-KEM" (B<OSSL_SELF_TEST_DESC_PCT_ML_KEM>) 409 410=item "SLH-DSA" (B<OSSL_SELF_TEST_DESC_PCT_SLH_DSA>) 411 412Key generation tests used with the "Pairwise_Consistency_Test" type. 413 414=item "RSA_Encrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_ENC>) 415 416=item "RSA_Decrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_DEC>) 417 418"KAT_AsymmetricCipher" uses this to indicate an encrypt or decrypt KAT. 419 420=item "ML-DSA" (B<OSSL_SELF_TEST_DESC_KEYGEN_ML_DSA>) 421 422=item "ML-KEM" (B<OSSL_SELF_TEST_DESC_KEYGEN_ML_KEM>) 423 424=item "SLH-DSA" (B<OSSL_SELF_TEST_DESC_KEYGEN_SLH_DSA>) 425 426"KAT_AsymmetricKeyGeneration" uses this to indicate a key generation KAT. 427 428=item "AES_GCM" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_GCM>) 429 430=item "AES_ECB_Decrypt" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_ECB>) 431 432=item "TDES" (B<OSSL_SELF_TEST_DESC_CIPHER_TDES>) 433 434Symmetric cipher tests used with the "KAT_Cipher" type. 435 436=item "SHA1" (B<OSSL_SELF_TEST_DESC_MD_SHA1>) 437 438=item "SHA2" (B<OSSL_SELF_TEST_DESC_MD_SHA2>) 439 440=item "SHA3" (B<OSSL_SELF_TEST_DESC_MD_SHA3>) 441 442Digest tests used with the "KAT_Digest" type. 443 444=item "DSA" (B<OSSL_SELF_TEST_DESC_SIGN_DSA>) 445 446=item "RSA" (B<OSSL_SELF_TEST_DESC_SIGN_RSA>) 447 448=item "ECDSA" (B<OSSL_SELF_TEST_DESC_SIGN_ECDSA>) 449 450=item "DetECDSA" (B<OSSL_SELF_TEST_DESC_SIGN_DetECDSA>) 451 452=item "EDDSA" (B<OSSL_SELF_TEST_DESC_SIGN_EDDSA>) 453 454=item "LMS" (B<OSSL_SELF_TEST_DESC_SIGN_LMS>) 455 456=item "ML-DSA" (B<OSSL_SELF_TEST_DESC_SIGN_ML_DSA>) 457 458=item "SLH-DSA" (B<OSSL_SELF_TEST_DESC_SIGN_SLH_DSA>) 459 460Signature tests used with the "KAT_Signature" type. 461 462=item "ECDH" (B<OSSL_SELF_TEST_DESC_KA_ECDH>) 463 464=item "DH" (B<OSSL_SELF_TEST_DESC_KA_DH>) 465 466Key agreement tests used with the "KAT_KA" type. 467 468=item "HKDF" (B<OSSL_SELF_TEST_DESC_KDF_HKDF>) 469 470=item "TLS13_KDF_EXTRACT" (B<OSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT>) 471 472=item "TLS13_KDF_EXPAND" (B<OSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND>) 473 474=item "SSKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSKDF>) 475 476=item "X963KDF" (B<OSSL_SELF_TEST_DESC_KDF_X963KDF>) 477 478=item "X942KDF" (B<OSSL_SELF_TEST_DESC_KDF_X942KDF>) 479 480=item "PBKDF2" (B<OSSL_SELF_TEST_DESC_KDF_PBKDF2>) 481 482=item "SSHKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSHKDF>) 483 484=item "TLS12_PRF" (B<OSSL_SELF_TEST_DESC_KDF_TLS12_PRF>) 485 486=item "KBKDF" (B<OSSL_SELF_TEST_DESC_KDF_KBKDF>) 487 488Key Encapsulation Function tests used with the "KAT_KEM" type. 489 490=item "KEM_Encap" (B<OSSL_SELF_TEST_DESC_ENCAP_KEM>) 491 492=item "KEM_Decap" (B<OSSL_SELF_TEST_DESC_DECAP_KEM>) 493 494=item "KEM_Decap_Reject" (B<OSSL_SELF_TEST_DESC_DECAP_REJ_KEM>) 495 496Key Derivation Function tests used with the "KAT_KDF" type. 497 498=item "CTR" (B<OSSL_SELF_TEST_DESC_DRBG_CTR>) 499 500=item "HASH" (B<OSSL_SELF_TEST_DESC_DRBG_HASH>) 501 502=item "HMAC" (B<OSSL_SELF_TEST_DESC_DRBG_HMAC>) 503 504DRBG tests used with the "DRBG" type. 505 506=item "RNG" (B<OSSL_SELF_TEST_DESC_RNG>) 507 508"Continuous_RNG_Test" uses this. 509 510=back 511 512=head1 EXAMPLES 513 514A simple self test callback is shown below for illustrative purposes. 515 516 #include <openssl/self_test.h> 517 518 static OSSL_CALLBACK self_test_cb; 519 520 static int self_test_cb(const OSSL_PARAM params[], void *arg) 521 { 522 int ret = 0; 523 const OSSL_PARAM *p = NULL; 524 const char *phase = NULL, *type = NULL, *desc = NULL; 525 526 p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE); 527 if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) 528 goto err; 529 phase = (const char *)p->data; 530 531 p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC); 532 if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) 533 goto err; 534 desc = (const char *)p->data; 535 536 p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE); 537 if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) 538 goto err; 539 type = (const char *)p->data; 540 541 /* Do some logging */ 542 if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0) 543 BIO_printf(bio_out, "%s : (%s) : ", desc, type); 544 if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0 545 || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0) 546 BIO_printf(bio_out, "%s\n", phase); 547 548 /* Corrupt the SHA1 self test during the 'corrupt' phase by returning 0 */ 549 if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0 550 && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) { 551 BIO_printf(bio_out, "%s %s", phase, desc); 552 return 0; 553 } 554 ret = 1; 555 err: 556 return ret; 557 } 558 559=head1 NOTES 560 561Some released versions of OpenSSL do not include a validated 562FIPS provider. To determine which versions have undergone 563the validation process, please refer to the 564L<OpenSSL Downloads page|https://www.openssl.org/source/>. If you 565require FIPS-approved functionality, it is essential to build your FIPS 566provider using one of the validated versions listed there. Normally, 567it is possible to utilize a FIPS provider constructed from one of the 568validated versions alongside F<libcrypto> and F<libssl> compiled from any 569release within the same major release series. This flexibility enables 570you to address bug fixes and CVEs that fall outside the FIPS boundary. 571 572You can load the FIPS provider into multiple library contexts as any other 573provider. However the following restriction applies. The FIPS provider cannot 574be used by multiple copies of OpenSSL libcrypto in a single process. 575 576As the provider saves core callbacks to the libcrypto obtained in the 577OSSL_provider_init() call to global data it will fail if subsequent 578invocations of its OSSL_provider_init() function yield different addresses 579of these callbacks than in the initial call. This happens when different 580copies of libcrypto are present in the memory of the process and both try 581to load the same FIPS provider. A workaround is to have a different copy 582of the FIPS provider loaded for each of the libcrypto instances in the 583process. 584 585=head1 SEE ALSO 586 587L<openssl-fipsinstall(1)>, 588L<fips_config(5)>, 589L<OSSL_SELF_TEST_set_callback(3)>, 590L<OSSL_SELF_TEST_new(3)>, 591L<OSSL_PARAM(3)>, 592L<openssl-core.h(7)>, 593L<openssl-core_dispatch.h(7)>, 594L<provider(7)>, 595L<https://www.openssl.org/source/> 596 597=head1 HISTORY 598 599The HKDF-SHA256, HKDF-SHA384 and HKDF-SHA512 algorithms were added in OpenSSL 3.6. 600 601All other functionality was added in OpenSSL 3.0. 602 603=head1 COPYRIGHT 604 605Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved. 606 607Licensed under the Apache License 2.0 (the "License"). You may not use 608this file except in compliance with the License. You can obtain a copy 609in the file LICENSE in the source distribution or at 610L<https://www.openssl.org/source/license.html>. 611 612=cut 613