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