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