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