1=pod 2{- OpenSSL::safe::output_do_not_edit_headers(); -} 3 4=head1 NAME 5 6openssl-fipsinstall - perform FIPS configuration installation 7 8=head1 SYNOPSIS 9 10B<openssl fipsinstall> 11[B<-help>] 12[B<-in> I<configfilename>] 13[B<-out> I<configfilename>] 14[B<-module> I<modulefilename>] 15[B<-provider_name> I<providername>] 16[B<-section_name> I<sectionname>] 17[B<-verify>] 18[B<-mac_name> I<macname>] 19[B<-macopt> I<nm>:I<v>] 20[B<-noout>] 21[B<-quiet>] 22[B<-pedantic>] 23[B<-no_conditional_errors>] 24[B<-no_security_checks>] 25[B<-hmac_key_check>] 26[B<-kmac_key_check>] 27[B<-ems_check>] 28[B<-no_drbg_truncated_digests>] 29[B<-signature_digest_check>] 30[B<-hkdf_digest_check>] 31[B<-tls13_kdf_digest_check>] 32[B<-tls1_prf_digest_check>] 33[B<-sshkdf_digest_check>] 34[B<-sskdf_digest_check>] 35[B<-x963kdf_digest_check>] 36[B<-dsa_sign_disabled>] 37[B<-no_pbkdf2_lower_bound_check>] 38[B<-no_short_mac>] 39[B<-tdes_encrypt_disabled>] 40[B<-rsa_pkcs15_padding_disabled>] 41[B<-rsa_pss_saltlen_check>] 42[B<-rsa_sign_x931_disabled>] 43[B<-hkdf_key_check>] 44[B<-kbkdf_key_check>] 45[B<-tls13_kdf_key_check>] 46[B<-tls1_prf_key_check>] 47[B<-sshkdf_key_check>] 48[B<-sskdf_key_check>] 49[B<-x963kdf_key_check>] 50[B<-x942kdf_key_check>] 51[B<-ecdh_cofactor_check>] 52[B<-self_test_onload>] 53[B<-self_test_oninstall>] 54[B<-corrupt_desc> I<selftest_description>] 55[B<-corrupt_type> I<selftest_type>] 56[B<-config> I<parent_config>] 57 58=head1 DESCRIPTION 59 60This command is used to generate a FIPS module configuration file. 61This configuration file can be used each time a FIPS module is loaded 62in order to pass data to the FIPS module self tests. The FIPS module always 63verifies its MAC, but optionally only needs to run the KAT's once, 64at installation. 65 66The generated configuration file consists of: 67 68=over 4 69 70=item - A MAC of the FIPS module file. 71 72=item - A test status indicator. 73 74This indicates if the Known Answer Self Tests (KAT's) have successfully run. 75 76=item - A MAC of the status indicator. 77 78=item - A control for conditional self tests errors. 79 80By default if a continuous test (e.g a key pair test) fails then the FIPS module 81will enter an error state, and no services or cryptographic algorithms will be 82able to be accessed after this point. 83The default value of '1' will cause the fips module error state to be entered. 84If the value is '0' then the module error state will not be entered. 85Regardless of whether the error state is entered or not, the current operation 86(e.g. key generation) will return an error. The user is responsible for retrying 87the operation if the module error state is not entered. 88 89=item - A control to indicate whether run-time security checks are done. 90 91This indicates if run-time checks related to enforcement of security parameters 92such as minimum security strength of keys and approved curve names are used. 93The default value of '1' will perform the checks. 94If the value is '0' the checks are not performed and FIPS compliance must 95be done by procedures documented in the relevant Security Policy. 96 97=back 98 99This file is described in L<fips_config(5)>. 100 101=head1 OPTIONS 102 103=over 4 104 105=item B<-help> 106 107Print a usage message. 108 109=item B<-module> I<filename> 110 111Filename of the FIPS module to perform an integrity check on. 112The path provided in the filename is used to load the module when it is 113activated, and this overrides the environment variable B<OPENSSL_MODULES>. 114 115=item B<-out> I<configfilename> 116 117Filename to output the configuration data to; the default is standard output. 118 119=item B<-in> I<configfilename> 120 121Input filename to load configuration data from. 122Must be used if the B<-verify> option is specified. 123 124=item B<-verify> 125 126Verify that the input configuration file contains the correct information. 127 128=item B<-provider_name> I<providername> 129 130Name of the provider inside the configuration file. 131The default value is C<fips>. 132 133=item B<-section_name> I<sectionname> 134 135Name of the section inside the configuration file. 136The default value is C<fips_sect>. 137 138=item B<-mac_name> I<name> 139 140Specifies the name of a supported MAC algorithm which will be used. 141The MAC mechanisms that are available will depend on the options 142used when building OpenSSL. 143To see the list of supported MAC's use the command 144C<openssl list -mac-algorithms>. The default is B<HMAC>. 145 146=item B<-macopt> I<nm>:I<v> 147 148Passes options to the MAC algorithm. 149A comprehensive list of controls can be found in the EVP_MAC implementation 150documentation. 151Common control strings used for this command are: 152 153=over 4 154 155=item B<key>:I<string> 156 157Specifies the MAC key as an alphanumeric string (use if the key contains 158printable characters only). 159The string length must conform to any restrictions of the MAC algorithm. 160A key must be specified for every MAC algorithm. 161If no key is provided, the default that was specified when OpenSSL was 162configured is used. 163 164=item B<hexkey>:I<string> 165 166Specifies the MAC key in hexadecimal form (two hex digits per byte). 167The key length must conform to any restrictions of the MAC algorithm. 168A key must be specified for every MAC algorithm. 169If no key is provided, the default that was specified when OpenSSL was 170configured is used. 171 172=item B<digest>:I<string> 173 174Used by HMAC as an alphanumeric string (use if the key contains printable 175characters only). 176The string length must conform to any restrictions of the MAC algorithm. 177To see the list of supported digests, use the command 178C<openssl list -digest-commands>. 179The default digest is SHA-256. 180 181=back 182 183=item B<-noout> 184 185Disable logging of the self tests. 186 187=item B<-pedantic> 188 189Configure the module so that it is strictly FIPS compliant rather 190than being backwards compatible. This enables conditional errors, 191security checks etc. Note that any previous configuration options will 192be overwritten and any subsequent configuration options that violate 193FIPS compliance will result in an error. 194 195=item B<-no_conditional_errors> 196 197Configure the module to not enter an error state if a conditional self test 198fails as described above. 199 200=item B<-no_security_checks> 201 202Configure the module to not perform run-time security checks as described above. 203 204Enabling the configuration option "no-fips-securitychecks" provides another way to 205turn off the check at compile time. 206 207=item B<-ems_check> 208 209Configure the module to enable a run-time Extended Master Secret (EMS) check 210when using the TLS1_PRF KDF algorithm. This check is disabled by default. 211See RFC 7627 for information related to EMS. 212 213=item B<-no_short_mac> 214 215Configure the module to not allow short MAC outputs. 216See SP 800-185 8.4.2 and FIPS 140-3 ID C.D for details. 217 218=item B<-hmac_key_check> 219 220Configure the module to not allow small keys sizes when using HMAC. 221See SP 800-131Ar2 for details. 222 223=item B<-kmac_key_check> 224 225Configure the module to not allow small keys sizes when using KMAC. 226See SP 800-131Ar2 for details. 227 228=item B<-no_drbg_truncated_digests> 229 230Configure the module to not allow truncated digests to be used with Hash and 231HMAC DRBGs. See FIPS 140-3 IG D.R for details. 232 233=item B<-signature_digest_check> 234 235Configure the module to enforce signature algorithms to use digests that are 236explicitly permitted by the various standards. 237 238=item B<-hkdf_digest_check> 239 240Configure the module to enable a run-time digest check when deriving a key by 241HKDF. 242See NIST SP 800-56Cr2 for details. 243 244=item B<-tls13_kdf_digest_check> 245 246Configure the module to enable a run-time digest check when deriving a key by 247TLS13 KDF. 248See RFC 8446 for details. 249 250=item B<-tls1_prf_digest_check> 251 252Configure the module to enable a run-time digest check when deriving a key by 253TLS_PRF. 254See NIST SP 800-135r1 for details. 255 256=item B<-sshkdf_digest_check> 257 258Configure the module to enable a run-time digest check when deriving a key by 259SSHKDF. 260See NIST SP 800-135r1 for details. 261 262=item B<-sskdf_digest_check> 263 264Configure the module to enable a run-time digest check when deriving a key by 265SSKDF. 266See NIST SP 800-56Cr2 for details. 267 268=item B<-x963kdf_digest_check> 269 270Configure the module to enable a run-time digest check when deriving a key by 271X963KDF. 272See NIST SP 800-131Ar2 for details. 273 274=item B<-dsa_sign_disabled> 275 276Configure the module to not allow DSA signing (DSA signature verification is 277still allowed). See FIPS 140-3 IG C.K for details. 278 279=item B<-tdes_encrypt_disabled> 280 281Configure the module to not allow Triple-DES encryption. 282Triple-DES decryption is still allowed for legacy purposes. 283See SP800-131Ar2 for details. 284 285=item B<-rsa_pkcs15_padding_disabled> 286 287Configure the module to not allow PKCS#1 version 1.5 padding to be used with 288RSA for key transport and key agreement. See NIST's SP 800-131A Revision 2 289for details. 290 291=item B<-rsa_pss_saltlen_check> 292 293Configure the module to enable a run-time salt length check when generating or 294verifying a RSA-PSS signature. 295See FIPS 186-5 5.4 (g) for details. 296 297=item B<-rsa_sign_x931_disabled> 298 299Configure the module to not allow X9.31 padding to be used when signing with 300RSA. See FIPS 140-3 IG C.K for details. 301 302=item B<-hkdf_key_check> 303 304Configure the module to enable a run-time short key-derivation key check when 305deriving a key by HKDF. 306See NIST SP 800-131Ar2 for details. 307 308=item B<-kbkdf_key_check> 309 310Configure the module to enable a run-time short key-derivation key check when 311deriving a key by KBKDF. 312See NIST SP 800-131Ar2 for details. 313 314=item B<-tls13_kdf_key_check> 315 316Configure the module to enable a run-time short key-derivation key check when 317deriving a key by TLS13 KDF. 318See NIST SP 800-131Ar2 for details. 319 320=item B<-tls1_prf_key_check> 321 322Configure the module to enable a run-time short key-derivation key check when 323deriving a key by TLS_PRF. 324See NIST SP 800-131Ar2 for details. 325 326=item B<-sshkdf_key_check> 327 328Configure the module to enable a run-time short key-derivation key check when 329deriving a key by SSHKDF. 330See NIST SP 800-131Ar2 for details. 331 332=item B<-sskdf_key_check> 333 334Configure the module to enable a run-time short key-derivation key check when 335deriving a key by SSKDF. 336See NIST SP 800-131Ar2 for details. 337 338=item B<-x963kdf_key_check> 339 340Configure the module to enable a run-time short key-derivation key check when 341deriving a key by X963KDF. 342See NIST SP 800-131Ar2 for details. 343 344=item B<-x942kdf_key_check> 345 346Configure the module to enable a run-time short key-derivation key check when 347deriving a key by X942KDF. 348See NIST SP 800-131Ar2 for details. 349 350=item B<-no_pbkdf2_lower_bound_check> 351 352Configure the module to not perform run-time lower bound check for PBKDF2. 353See NIST SP 800-132 for details. 354 355=item B<-ecdh_cofactor_check> 356 357Configure the module to enable a run-time check that ECDH uses the EC curves 358cofactor value when deriving a key. This only affects the 'B' and 'K' curves. 359See SP 800-56A r3 Section 5.7.1.2 for details. 360 361=item B<-self_test_onload> 362 363Do not write the two fields related to the "test status indicator" and 364"MAC status indicator" to the output configuration file. Without these fields 365the self tests KATS will run each time the module is loaded. This option could be 366used for cross compiling, since the self tests need to run at least once on each 367target machine. Once the self tests have run on the target machine the user 368could possibly then add the 2 fields into the configuration using some other 369mechanism. 370 371This is the default. 372 373=item B<-self_test_oninstall> 374 375The converse of B<-self_test_oninstall>. The two fields related to the 376"test status indicator" and "MAC status indicator" are written to the 377output configuration file. 378 379=item B<-quiet> 380 381Do not output pass/fail messages. Implies B<-noout>. 382 383=item B<-corrupt_desc> I<selftest_description>, 384B<-corrupt_type> I<selftest_type> 385 386The corrupt options can be used to test failure of one or more self tests by 387name. 388Either option or both may be used to select the tests to corrupt. 389Refer to the entries for B<st-desc> and B<st-type> in L<OSSL_PROVIDER-FIPS(7)> for 390values that can be used. 391 392=item B<-config> I<parent_config> 393 394Test that a FIPS provider can be loaded from the specified configuration file. 395A previous call to this application needs to generate the extra configuration 396data that is included by the base C<parent_config> configuration file. 397See L<config(5)> for further information on how to set up a provider section. 398All other options are ignored if '-config' is used. 399 400=back 401 402=head1 NOTES 403 404Self tests results are logged by default if the options B<-quiet> and B<-noout> 405are not specified, or if either of the options B<-corrupt_desc> or 406B<-corrupt_type> are used. 407If the base configuration file is set up to autoload the fips module, then the 408fips module will be loaded and self tested BEFORE the fipsinstall application 409has a chance to set up its own self test callback. As a result of this the self 410test output and the options B<-corrupt_desc> and B<-corrupt_type> will be ignored. 411For normal usage the base configuration file should use the default provider 412when generating the fips configuration file. 413 414The B<-self_test_oninstall> option was added and the 415B<-self_test_onload> option was made the default in OpenSSL 3.1. 416 417The command and all remaining options were added in OpenSSL 3.0. 418 419=head1 EXAMPLES 420 421Calculate the mac of a FIPS module F<fips.so> and run a FIPS self test 422for the module, and save the F<fips.cnf> configuration file: 423 424 openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips 425 426Verify that the configuration file F<fips.cnf> contains the correct info: 427 428 openssl fipsinstall -module ./fips.so -in fips.cnf -provider_name fips -verify 429 430Corrupt any self tests which have the description C<SHA1>: 431 432 openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips \ 433 -corrupt_desc 'SHA1' 434 435Validate that the fips module can be loaded from a base configuration file: 436 437 export OPENSSL_CONF_INCLUDE=<path of configuration files> 438 export OPENSSL_MODULES=<provider-path> 439 openssl fipsinstall -config' 'default.cnf' 440 441 442=head1 SEE ALSO 443 444L<config(5)>, 445L<fips_config(5)>, 446L<OSSL_PROVIDER-FIPS(7)>, 447L<EVP_MAC(3)> 448 449=head1 HISTORY 450 451The B<openssl-fipsinstall> application was added in OpenSSL 3.0. 452 453The following options were added in OpenSSL 3.1: 454 455B<-ems_check>, 456B<-self_test_oninstall> 457 458The following options were added in OpenSSL 3.2: 459 460B<-pedantic>, 461B<-no_drbg_truncated_digests> 462 463The following options were added in OpenSSL 3.4: 464 465B<-hmac_key_check>, 466B<-kmac_key_check>, 467B<-signature_digest_check>, 468B<-hkdf_digest_check>, 469B<-tls13_kdf_digest_check>, 470B<-tls1_prf_digest_check>, 471B<-sshkdf_digest_check>, 472B<-sskdf_digest_check>, 473B<-x963kdf_digest_check>, 474B<-dsa_sign_disabled>, 475B<-no_pbkdf2_lower_bound_check>, 476B<-no_short_mac>, 477B<-tdes_encrypt_disabled>, 478B<-rsa_pkcs15_padding_disabled>, 479B<-rsa_pss_saltlen_check>, 480B<-rsa_sign_x931_disabled>, 481B<-hkdf_key_check>, 482B<-kbkdf_key_check>, 483B<-tls13_kdf_key_check>, 484B<-tls1_prf_key_check>, 485B<-sshkdf_key_check>, 486B<-sskdf_key_check>, 487B<-x963kdf_key_check>, 488B<-x942kdf_key_check>, 489B<-ecdh_cofactor_check> 490 491=head1 COPYRIGHT 492 493Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. 494 495Licensed under the Apache License 2.0 (the "License"). You may not use 496this file except in compliance with the License. You can obtain a copy 497in the file LICENSE in the source distribution or at 498L<https://www.openssl.org/source/license.html>. 499 500=cut 501