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.
370This option defaults to 0 for any OpenSSL FIPS 140-2 provider (OpenSSL 3.0.X).
371and is not relevant for an OpenSSL FIPS 140-3 provider, since this is no
372longer allowed.
373
374=item B<-self_test_oninstall>
375
376The converse of B<-self_test_oninstall>.  The two fields related to the
377"test status indicator" and "MAC status indicator" are written to the
378output configuration file.
379This field is not relevant for an OpenSSL FIPS 140-3 provider, since this is no
380longer allowed.
381
382=item B<-quiet>
383
384Do not output pass/fail messages. Implies B<-noout>.
385
386=item B<-corrupt_desc> I<selftest_description>,
387B<-corrupt_type> I<selftest_type>
388
389The corrupt options can be used to test failure of one or more self tests by
390name.
391Either option or both may be used to select the tests to corrupt.
392Refer to the entries for B<st-desc> and B<st-type> in L<OSSL_PROVIDER-FIPS(7)> for
393values that can be used.
394
395=item B<-config> I<parent_config>
396
397Test that a FIPS provider can be loaded from the specified configuration file.
398A previous call to this application needs to generate the extra configuration
399data that is included by the base C<parent_config> configuration file.
400See L<config(5)> for further information on how to set up a provider section.
401All other options are ignored if '-config' is used.
402
403=back
404
405=head1 NOTES
406
407Self tests results are logged by default if the options B<-quiet> and B<-noout>
408are not specified, or if either of the options B<-corrupt_desc> or
409B<-corrupt_type> are used.
410If the base configuration file is set up to autoload the fips module, then the
411fips module will be loaded and self tested BEFORE the fipsinstall application
412has a chance to set up its own self test callback. As a result of this the self
413test output and the options B<-corrupt_desc> and B<-corrupt_type> will be ignored.
414For normal usage the base configuration file should use the default provider
415when generating the fips configuration file.
416
417The B<-self_test_oninstall> option was added and the
418B<-self_test_onload> option was made the default in OpenSSL 3.1.
419
420The command and all remaining options were added in OpenSSL 3.0.
421
422=head1 EXAMPLES
423
424Calculate the mac of a FIPS module F<fips.so> and run a FIPS self test
425for the module, and save the F<fips.cnf> configuration file:
426
427 openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips
428
429Verify that the configuration file F<fips.cnf> contains the correct info:
430
431 openssl fipsinstall -module ./fips.so -in fips.cnf  -provider_name fips -verify
432
433Corrupt any self tests which have the description C<SHA1>:
434
435 openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips \
436         -corrupt_desc 'SHA1'
437
438Validate that the fips module can be loaded from a base configuration file:
439
440 export OPENSSL_CONF_INCLUDE=<path of configuration files>
441 export OPENSSL_MODULES=<provider-path>
442 openssl fipsinstall -config' 'default.cnf'
443
444
445=head1 SEE ALSO
446
447L<config(5)>,
448L<fips_config(5)>,
449L<OSSL_PROVIDER-FIPS(7)>,
450L<EVP_MAC(3)>
451
452=head1 HISTORY
453
454The B<openssl-fipsinstall> application was added in OpenSSL 3.0.
455
456The following options were added in OpenSSL 3.1:
457
458B<-ems_check>,
459B<-self_test_oninstall>
460
461The following options were added in OpenSSL 3.2:
462
463B<-pedantic>,
464B<-no_drbg_truncated_digests>
465
466The following options were added in OpenSSL 3.4:
467
468B<-hmac_key_check>,
469B<-kmac_key_check>,
470B<-signature_digest_check>,
471B<-hkdf_digest_check>,
472B<-tls13_kdf_digest_check>,
473B<-tls1_prf_digest_check>,
474B<-sshkdf_digest_check>,
475B<-sskdf_digest_check>,
476B<-x963kdf_digest_check>,
477B<-dsa_sign_disabled>,
478B<-no_pbkdf2_lower_bound_check>,
479B<-no_short_mac>,
480B<-tdes_encrypt_disabled>,
481B<-rsa_pkcs15_padding_disabled>,
482B<-rsa_pss_saltlen_check>,
483B<-rsa_sign_x931_disabled>,
484B<-hkdf_key_check>,
485B<-kbkdf_key_check>,
486B<-tls13_kdf_key_check>,
487B<-tls1_prf_key_check>,
488B<-sshkdf_key_check>,
489B<-sskdf_key_check>,
490B<-x963kdf_key_check>,
491B<-x942kdf_key_check>,
492B<-ecdh_cofactor_check>
493
494=head1 COPYRIGHT
495
496Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved.
497
498Licensed under the Apache License 2.0 (the "License").  You may not use
499this file except in compliance with the License.  You can obtain a copy
500in the file LICENSE in the source distribution or at
501L<https://www.openssl.org/source/license.html>.
502
503=cut
504