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 "DSA" (B<OSSL_SELF_TEST_DESC_PCT_DSA>)
 341
 342 Key generation tests used with the "Pairwise_Consistency_Test" type.
 343
 344 =item "RSA_Encrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_ENC>)
 345
 346 =item "RSA_Decrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_DEC>)
 347
 348 "KAT_AsymmetricCipher" uses this to indicate an encrypt or decrypt KAT.
 349
 350 =item "AES_GCM" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_GCM>)
 351
 352 =item "AES_ECB_Decrypt" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_ECB>)
 353
 354 =item "TDES" (B<OSSL_SELF_TEST_DESC_CIPHER_TDES>)
 355
 356 Symmetric cipher tests used with the "KAT_Cipher" type.
 357
 358 =item "SHA1" (B<OSSL_SELF_TEST_DESC_MD_SHA1>)
 359
 360 =item "SHA2" (B<OSSL_SELF_TEST_DESC_MD_SHA2>)
 361
 362 =item "SHA3" (B<OSSL_SELF_TEST_DESC_MD_SHA3>)
 363
 364 Digest tests used with the "KAT_Digest" type.
 365
 366 =item "DSA" (B<OSSL_SELF_TEST_DESC_SIGN_DSA>)
 367
 368 =item "RSA" (B<OSSL_SELF_TEST_DESC_SIGN_RSA>)
 369
 370 =item "ECDSA" (B<OSSL_SELF_TEST_DESC_SIGN_ECDSA>)
 371
 372 Signature tests used with the "KAT_Signature" type.
 373
 374 =item "ECDH" (B<OSSL_SELF_TEST_DESC_KA_ECDH>)
 375
 376 =item "DH" (B<OSSL_SELF_TEST_DESC_KA_DH>)
 377
 378 Key agreement tests used with the "KAT_KA" type.
 379
 380 =item "HKDF" (B<OSSL_SELF_TEST_DESC_KDF_HKDF>)
 381
 382 =item "TLS13_KDF_EXTRACT" (B<OSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT>)
 383
 384 =item "TLS13_KDF_EXPAND" (B<OSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND>)
 385
 386 =item "SSKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSKDF>)
 387
 388 =item "X963KDF" (B<OSSL_SELF_TEST_DESC_KDF_X963KDF>)
 389
 390 =item "X942KDF" (B<OSSL_SELF_TEST_DESC_KDF_X942KDF>)
 391
 392 =item "PBKDF2" (B<OSSL_SELF_TEST_DESC_KDF_PBKDF2>)
 393
 394 =item "SSHKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSHKDF>)
 395
 396 =item "TLS12_PRF" (B<OSSL_SELF_TEST_DESC_KDF_TLS12_PRF>)
 397
 398 =item "KBKDF" (B<OSSL_SELF_TEST_DESC_KDF_KBKDF>)
 399
 400 Key Derivation Function tests used with the "KAT_KDF" type.
 401
 402 =item "CTR" (B<OSSL_SELF_TEST_DESC_DRBG_CTR>)
 403
 404 =item "HASH" (B<OSSL_SELF_TEST_DESC_DRBG_HASH>)
 405
 406 =item "HMAC" (B<OSSL_SELF_TEST_DESC_DRBG_HMAC>)
 407
 408 DRBG tests used with the "DRBG" type.
 409
 410 =item "RNG" (B<OSSL_SELF_TEST_DESC_RNG>)
 411
 412 "Continuous_RNG_Test" uses this.
 413
 414 =back
 415
 416 =head1 EXAMPLES
 417
 418 A simple self test callback is shown below for illustrative purposes.
 419
 420   #include <openssl/self_test.h>
 421
 422   static OSSL_CALLBACK self_test_cb;
 423
 424   static int self_test_cb(const OSSL_PARAM params[], void *arg)
 425   {
 426     int ret = 0;
 427     const OSSL_PARAM *p = NULL;
 428     const char *phase = NULL, *type = NULL, *desc = NULL;
 429
 430     p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE);
 431     if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
 432         goto err;
 433     phase = (const char *)p->data;
 434
 435     p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC);
 436     if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
 437         goto err;
 438     desc = (const char *)p->data;
 439
 440     p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE);
 441     if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
 442         goto err;
 443     type = (const char *)p->data;
 444
 445     /* Do some logging */
 446     if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0)
 447         BIO_printf(bio_out, "%s : (%s) : ", desc, type);
 448     if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0
 449             || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0)
 450         BIO_printf(bio_out, "%s\n", phase);
 451
 452     /* Corrupt the SHA1 self test during the 'corrupt' phase by returning 0 */
 453     if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0
 454             && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) {
 455         BIO_printf(bio_out, "%s %s", phase, desc);
 456         return 0;
 457     }
 458     ret = 1;
 459   err:
 460     return ret;
 461   }
 462
 463 =head1 NOTES
 464
 465 Some released versions of OpenSSL do not include a validated
 466 FIPS provider.  To determine which versions have undergone
 467 the validation process, please refer to the
 468 L<OpenSSL Downloads page|https://www.openssl.org/source/>.  If you
 469 require FIPS-approved functionality, it is essential to build your FIPS
 470 provider using one of the validated versions listed there.  Normally,
 471 it is possible to utilize a FIPS provider constructed from one of the
 472 validated versions alongside F<libcrypto> and F<libssl> compiled from any
 473 release within the same major release series.  This flexibility enables
 474 you to address bug fixes and CVEs that fall outside the FIPS boundary.
 475
 476 The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated algorithms,
 477 consequently the property query C<fips=yes> is mandatory for applications that
 478 want to operate in a FIPS approved manner.  The algorithms are:
 479
 480 =over 4
 481
 482 =item Triple DES ECB
 483
 484 =item Triple DES CBC
 485
 486 =item EdDSA
 487
 488 =back
 489
 490 =head1 SEE ALSO
 491
 492 L<openssl-fipsinstall(1)>,
 493 L<fips_config(5)>,
 494 L<OSSL_SELF_TEST_set_callback(3)>,
 495 L<OSSL_SELF_TEST_new(3)>,
 496 L<OSSL_PARAM(3)>,
 497 L<openssl-core.h(7)>,
 498 L<openssl-core_dispatch.h(7)>,
 499 L<provider(7)>,
 500 L<https://www.openssl.org/source/>
 501
 502 =head1 HISTORY
 503
 504 This functionality was added in OpenSSL 3.0.
 505
 506 =head1 COPYRIGHT
 507
 508 Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
 509
 510 Licensed under the Apache License 2.0 (the "License").  You may not use
 511 this file except in compliance with the License.  You can obtain a copy
 512 in the file LICENSE in the source distribution or at
 513 L<https://www.openssl.org/source/license.html>.
 514
 515 =cut