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-SSKDF(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-KBKDF(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 DSA, see L<EVP_KEYEXCH-DSA(7)> 128 129=item RSA, see L<EVP_SIGNATURE-RSA(7)> 130 131=item X25519, see L<EVP_SIGNATURE-ED25519(7)> 132 133=item X448, see L<EVP_SIGNATURE-ED448(7)> 134 135=item HMAC, see L<EVP_SIGNATURE-HMAC(7)> 136 137=item CMAC, see L<EVP_SIGNATURE-CMAC(7)> 138 139=back 140 141=head2 Asymmetric Cipher 142 143=over 4 144 145=item RSA, see L<EVP_KEYEXCH-RSA(7)> 146 147=back 148 149=head2 Asymmetric Key Encapsulation 150 151=over 4 152 153=item RSA, see L<EVP_KEM-RSA(7)> 154 155=back 156 157=head2 Asymmetric Key Management 158 159=over 4 160 161=item DH, see L<EVP_KEYMGMT-DH(7)> 162 163=item DHX, see L<EVP_KEYMGMT-DHX(7)> 164 165=item DSA, see L<EVP_KEYMGMT-DSA(7)> 166 167=item RSA, see L<EVP_KEYMGMT-RSA(7)> 168 169=item EC, see L<EVP_KEYMGMT-EC(7)> 170 171=item X25519, see L<EVP_KEYMGMT-X25519(7)> 172 173=item X448, see L<EVP_KEYMGMT-X448(7)> 174 175=back 176 177=head1 SELF TESTING 178 179One of the requirements for the FIPS module is self testing. An optional callback 180mechanism is available to return information to the user using 181L<OSSL_SELF_TEST_set_callback(3)>. 182 183The parameters passed to the callback are described in L<OSSL_SELF_TEST_new(3)> 184 185The OpenSSL FIPS module uses the following mechanism to provide information 186about the self tests as they run. 187This is useful for debugging if a self test is failing. 188The callback also allows forcing any self test to fail, in order to check that 189it operates correctly on failure. 190Note that all self tests run even if a self test failure occurs. 191 192The FIPS module passes the following type(s) to OSSL_SELF_TEST_onbegin(). 193 194=over 4 195 196=item "Module_Integrity" (B<OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY>) 197 198Uses HMAC SHA256 on the module file to validate that the module has not been 199modified. The integrity value is compared to a value written to a configuration 200file during installation. 201 202=item "Install_Integrity" (B<OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY>) 203 204Uses HMAC SHA256 on a fixed string to validate that the installation process 205has already been performed and the self test KATS have already been tested, 206The integrity value is compared to a value written to a configuration 207file after successfully running the self tests during installation. 208 209=item "KAT_Cipher" (B<OSSL_SELF_TEST_TYPE_KAT_CIPHER>) 210 211Known answer test for a symmetric cipher. 212 213=item "KAT_AsymmetricCipher" (B<OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER>) 214 215Known answer test for a asymmetric cipher. 216 217=item "KAT_Digest" (B<OSSL_SELF_TEST_TYPE_KAT_DIGEST>) 218 219Known answer test for a digest. 220 221=item "KAT_Signature" (B<OSSL_SELF_TEST_TYPE_KAT_SIGNATURE>) 222 223Known answer test for a signature. 224 225=item "PCT_Signature" (B<OSSL_SELF_TEST_TYPE_PCT_SIGNATURE>) 226 227Pairwise Consistency check for a signature. 228 229=item "KAT_KDF" (B<OSSL_SELF_TEST_TYPE_KAT_KDF>) 230 231Known answer test for a key derivation function. 232 233=item "KAT_KA" (B<OSSL_SELF_TEST_TYPE_KAT_KA>) 234 235Known answer test for key agreement. 236 237=item "DRBG" (B<OSSL_SELF_TEST_TYPE_DRBG>) 238 239Known answer test for a Deterministic Random Bit Generator. 240 241=item "Conditional_PCT" (B<OSSL_SELF_TEST_TYPE_PCT>) 242 243Conditional test that is run during the generation of key pairs. 244 245=item "Continuous_RNG_Test" (B<OSSL_SELF_TEST_TYPE_CRNG>) 246 247Continuous random number generator test. 248 249=back 250 251The "Module_Integrity" self test is always run at startup. 252The "Install_Integrity" self test is used to check if the self tests have 253already been run at installation time. If they have already run then the 254self tests are not run on subsequent startups. 255All other self test categories are run once at installation time, except for the 256"Pairwise_Consistency_Test". 257 258There is only one instance of the "Module_Integrity" and "Install_Integrity" 259self tests. All other self tests may have multiple instances. 260 261 262The FIPS module passes the following descriptions(s) to OSSL_SELF_TEST_onbegin(). 263 264=over 4 265 266=item "HMAC" (B<OSSL_SELF_TEST_DESC_INTEGRITY_HMAC>) 267 268"Module_Integrity" and "Install_Integrity" use this. 269 270=item "RSA" (B<OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1>) 271 272=item "ECDSA" (B<OSSL_SELF_TEST_DESC_PCT_ECDSA>) 273 274=item "DSA" (B<OSSL_SELF_TEST_DESC_PCT_DSA>) 275 276Key generation tests used with the "Pairwise_Consistency_Test" type. 277 278=item "RSA_Encrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_ENC>) 279 280=item "RSA_Decrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_DEC>) 281 282"KAT_AsymmetricCipher" uses this to indicate an encrypt or decrypt KAT. 283 284=item "AES_GCM" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_GCM>) 285 286=item "AES_ECB_Decrypt" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_ECB>) 287 288=item "TDES" (B<OSSL_SELF_TEST_DESC_CIPHER_TDES>) 289 290Symmetric cipher tests used with the "KAT_Cipher" type. 291 292=item "SHA1" (B<OSSL_SELF_TEST_DESC_MD_SHA1>) 293 294=item "SHA2" (B<OSSL_SELF_TEST_DESC_MD_SHA2>) 295 296=item "SHA3" (B<OSSL_SELF_TEST_DESC_MD_SHA3>) 297 298Digest tests used with the "KAT_Digest" type. 299 300=item "DSA" (B<OSSL_SELF_TEST_DESC_SIGN_DSA>) 301 302=item "RSA" (B<OSSL_SELF_TEST_DESC_SIGN_RSA>) 303 304=item "ECDSA" (B<OSSL_SELF_TEST_DESC_SIGN_ECDSA>) 305 306Signature tests used with the "KAT_Signature" type. 307 308=item "ECDH" (B<OSSL_SELF_TEST_DESC_KA_ECDH>) 309 310=item "DH" (B<OSSL_SELF_TEST_DESC_KA_DH>) 311 312Key agreement tests used with the "KAT_KA" type. 313 314=item "HKDF" (B<OSSL_SELF_TEST_DESC_KDF_HKDF>) 315 316=item "TLS13_KDF_EXTRACT" (B<OSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT>) 317 318=item "TLS13_KDF_EXPAND" (B<OSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND>) 319 320=item "SSKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSKDF>) 321 322=item "X963KDF" (B<OSSL_SELF_TEST_DESC_KDF_X963KDF>) 323 324=item "X942KDF" (B<OSSL_SELF_TEST_DESC_KDF_X942KDF>) 325 326=item "PBKDF2" (B<OSSL_SELF_TEST_DESC_KDF_PBKDF2>) 327 328=item "SSHKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSHKDF>) 329 330=item "TLS12_PRF" (B<OSSL_SELF_TEST_DESC_KDF_TLS12_PRF>) 331 332=item "KBKDF" (B<OSSL_SELF_TEST_DESC_KDF_KBKDF>) 333 334Key Derivation Function tests used with the "KAT_KDF" type. 335 336=item "CTR" (B<OSSL_SELF_TEST_DESC_DRBG_CTR>) 337 338=item "HASH" (B<OSSL_SELF_TEST_DESC_DRBG_HASH>) 339 340=item "HMAC" (B<OSSL_SELF_TEST_DESC_DRBG_HMAC>) 341 342DRBG tests used with the "DRBG" type. 343 344= item "RNG" (B<OSSL_SELF_TEST_DESC_RNG>) 345 346"Continuous_RNG_Test" uses this. 347 348=back 349 350=head1 EXAMPLES 351 352A simple self test callback is shown below for illustrative purposes. 353 354 #include <openssl/self_test.h> 355 356 static OSSL_CALLBACK self_test_cb; 357 358 static int self_test_cb(const OSSL_PARAM params[], void *arg) 359 { 360 int ret = 0; 361 const OSSL_PARAM *p = NULL; 362 const char *phase = NULL, *type = NULL, *desc = NULL; 363 364 p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE); 365 if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) 366 goto err; 367 phase = (const char *)p->data; 368 369 p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC); 370 if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) 371 goto err; 372 desc = (const char *)p->data; 373 374 p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE); 375 if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) 376 goto err; 377 type = (const char *)p->data; 378 379 /* Do some logging */ 380 if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0) 381 BIO_printf(bio_out, "%s : (%s) : ", desc, type); 382 if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0 383 || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0) 384 BIO_printf(bio_out, "%s\n", phase); 385 386 /* Corrupt the SHA1 self test during the 'corrupt' phase by returning 0 */ 387 if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0 388 && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) { 389 BIO_printf(bio_out, "%s %s", phase, desc); 390 return 0; 391 } 392 ret = 1; 393 err: 394 return ret; 395 } 396 397=head1 SEE ALSO 398 399L<openssl-fipsinstall(1)>, 400L<fips_config(5)>, 401L<OSSL_SELF_TEST_set_callback(3)>, 402L<OSSL_SELF_TEST_new(3)>, 403L<OSSL_PARAM(3)>, 404L<openssl-core.h(7)>, 405L<openssl-core_dispatch.h(7)>, 406L<provider(7)> 407 408=head1 HISTORY 409 410The type and functions described here were added in OpenSSL 3.0. 411 412=head1 COPYRIGHT 413 414Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. 415 416Licensed under the Apache License 2.0 (the "License"). You may not use 417this file except in compliance with the License. You can obtain a copy 418in the file LICENSE in the source distribution or at 419L<https://www.openssl.org/source/license.html>. 420 421=cut 422
