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