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<-ems_check>] 26[B<-no_drbg_truncated_digests>] 27[B<-self_test_onload>] 28[B<-self_test_oninstall>] 29[B<-corrupt_desc> I<selftest_description>] 30[B<-corrupt_type> I<selftest_type>] 31[B<-config> I<parent_config>] 32 33=head1 DESCRIPTION 34 35This command is used to generate a FIPS module configuration file. 36This configuration file can be used each time a FIPS module is loaded 37in order to pass data to the FIPS module self tests. The FIPS module always 38verifies its MAC, but optionally only needs to run the KAT's once, 39at installation. 40 41The generated configuration file consists of: 42 43=over 4 44 45=item - A MAC of the FIPS module file. 46 47=item - A test status indicator. 48 49This indicates if the Known Answer Self Tests (KAT's) have successfully run. 50 51=item - A MAC of the status indicator. 52 53=item - A control for conditional self tests errors. 54 55By default if a continuous test (e.g a key pair test) fails then the FIPS module 56will enter an error state, and no services or cryptographic algorithms will be 57able to be accessed after this point. 58The default value of '1' will cause the fips module error state to be entered. 59If the value is '0' then the module error state will not be entered. 60Regardless of whether the error state is entered or not, the current operation 61(e.g. key generation) will return an error. The user is responsible for retrying 62the operation if the module error state is not entered. 63 64=item - A control to indicate whether run-time security checks are done. 65 66This indicates if run-time checks related to enforcement of security parameters 67such as minimum security strength of keys and approved curve names are used. 68The default value of '1' will perform the checks. 69If the value is '0' the checks are not performed and FIPS compliance must 70be done by procedures documented in the relevant Security Policy. 71 72=back 73 74This file is described in L<fips_config(5)>. 75 76=head1 OPTIONS 77 78=over 4 79 80=item B<-help> 81 82Print a usage message. 83 84=item B<-module> I<filename> 85 86Filename of the FIPS module to perform an integrity check on. 87The path provided in the filename is used to load the module when it is 88activated, and this overrides the environment variable B<OPENSSL_MODULES>. 89 90=item B<-out> I<configfilename> 91 92Filename to output the configuration data to; the default is standard output. 93 94=item B<-in> I<configfilename> 95 96Input filename to load configuration data from. 97Must be used if the B<-verify> option is specified. 98 99=item B<-verify> 100 101Verify that the input configuration file contains the correct information. 102 103=item B<-provider_name> I<providername> 104 105Name of the provider inside the configuration file. 106The default value is C<fips>. 107 108=item B<-section_name> I<sectionname> 109 110Name of the section inside the configuration file. 111The default value is C<fips_sect>. 112 113=item B<-mac_name> I<name> 114 115Specifies the name of a supported MAC algorithm which will be used. 116The MAC mechanisms that are available will depend on the options 117used when building OpenSSL. 118To see the list of supported MAC's use the command 119C<openssl list -mac-algorithms>. The default is B<HMAC>. 120 121=item B<-macopt> I<nm>:I<v> 122 123Passes options to the MAC algorithm. 124A comprehensive list of controls can be found in the EVP_MAC implementation 125documentation. 126Common control strings used for this command are: 127 128=over 4 129 130=item B<key>:I<string> 131 132Specifies the MAC key as an alphanumeric string (use if the key contains 133printable characters only). 134The string length must conform to any restrictions of the MAC algorithm. 135A key must be specified for every MAC algorithm. 136If no key is provided, the default that was specified when OpenSSL was 137configured is used. 138 139=item B<hexkey>:I<string> 140 141Specifies the MAC key in hexadecimal form (two hex digits per byte). 142The key length must conform to any restrictions of the MAC algorithm. 143A key must be specified for every MAC algorithm. 144If no key is provided, the default that was specified when OpenSSL was 145configured is used. 146 147=item B<digest>:I<string> 148 149Used by HMAC as an alphanumeric string (use if the key contains printable 150characters only). 151The string length must conform to any restrictions of the MAC algorithm. 152To see the list of supported digests, use the command 153C<openssl list -digest-commands>. 154The default digest is SHA-256. 155 156=back 157 158=item B<-noout> 159 160Disable logging of the self tests. 161 162=item B<-pedantic> 163 164Configure the module so that it is strictly FIPS compliant rather 165than being backwards compatible. This enables conditional errors, 166security checks etc. Note that any previous configuration options will 167be overwritten and any subsequent configuration options that violate 168FIPS compliance will result in an error. 169 170=item B<-no_conditional_errors> 171 172Configure the module to not enter an error state if a conditional self test 173fails as described above. 174 175=item B<-no_security_checks> 176 177Configure the module to not perform run-time security checks as described above. 178 179Enabling the configuration option "no-fips-securitychecks" provides another way to 180turn off the check at compile time. 181 182=item B<-ems_check> 183 184Configure the module to enable a run-time Extended Master Secret (EMS) check 185when using the TLS1_PRF KDF algorithm. This check is disabled by default. 186See RFC 7627 for information related to EMS. 187 188=item B<-no_drbg_truncated_digests> 189 190Configure the module to not allow truncated digests to be used with Hash and 191HMAC DRBGs. See FIPS 140-3 IG D.R for details. 192 193=item B<-self_test_onload> 194 195Do not write the two fields related to the "test status indicator" and 196"MAC status indicator" to the output configuration file. Without these fields 197the self tests KATS will run each time the module is loaded. This option could be 198used for cross compiling, since the self tests need to run at least once on each 199target machine. Once the self tests have run on the target machine the user 200could possibly then add the 2 fields into the configuration using some other 201mechanism. 202 203This is the default. 204 205=item B<-self_test_oninstall> 206 207The converse of B<-self_test_oninstall>. The two fields related to the 208"test status indicator" and "MAC status indicator" are written to the 209output configuration file. 210 211=item B<-quiet> 212 213Do not output pass/fail messages. Implies B<-noout>. 214 215=item B<-corrupt_desc> I<selftest_description>, 216B<-corrupt_type> I<selftest_type> 217 218The corrupt options can be used to test failure of one or more self tests by 219name. 220Either option or both may be used to select the tests to corrupt. 221Refer to the entries for B<st-desc> and B<st-type> in L<OSSL_PROVIDER-FIPS(7)> for 222values that can be used. 223 224=item B<-config> I<parent_config> 225 226Test that a FIPS provider can be loaded from the specified configuration file. 227A previous call to this application needs to generate the extra configuration 228data that is included by the base C<parent_config> configuration file. 229See L<config(5)> for further information on how to set up a provider section. 230All other options are ignored if '-config' is used. 231 232=back 233 234=head1 NOTES 235 236Self tests results are logged by default if the options B<-quiet> and B<-noout> 237are not specified, or if either of the options B<-corrupt_desc> or 238B<-corrupt_type> are used. 239If the base configuration file is set up to autoload the fips module, then the 240fips module will be loaded and self tested BEFORE the fipsinstall application 241has a chance to set up its own self test callback. As a result of this the self 242test output and the options B<-corrupt_desc> and B<-corrupt_type> will be ignored. 243For normal usage the base configuration file should use the default provider 244when generating the fips configuration file. 245 246The B<-self_test_oninstall> option was added and the 247B<-self_test_onload> option was made the default in OpenSSL 3.1. 248 249The command and all remaining options were added in OpenSSL 3.0. 250 251=head1 EXAMPLES 252 253Calculate the mac of a FIPS module F<fips.so> and run a FIPS self test 254for the module, and save the F<fips.cnf> configuration file: 255 256 openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips 257 258Verify that the configuration file F<fips.cnf> contains the correct info: 259 260 openssl fipsinstall -module ./fips.so -in fips.cnf -provider_name fips -verify 261 262Corrupt any self tests which have the description C<SHA1>: 263 264 openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips \ 265 -corrupt_desc 'SHA1' 266 267Validate that the fips module can be loaded from a base configuration file: 268 269 export OPENSSL_CONF_INCLUDE=<path of configuration files> 270 export OPENSSL_MODULES=<provider-path> 271 openssl fipsinstall -config' 'default.cnf' 272 273 274=head1 SEE ALSO 275 276L<config(5)>, 277L<fips_config(5)>, 278L<OSSL_PROVIDER-FIPS(7)>, 279L<EVP_MAC(3)> 280 281=head1 COPYRIGHT 282 283Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. 284 285Licensed under the Apache License 2.0 (the "License"). You may not use 286this file except in compliance with the License. You can obtain a copy 287in the file LICENSE in the source distribution or at 288L<https://www.openssl.org/source/license.html>. 289 290=cut 291