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