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