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