]>
Commit | Line | Data |
---|---|---|
95214b43 SL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | openssl-fipsinstall - perform FIPS configuration installation | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | B<openssl fipsinstall> | |
10 | [B<-help>] | |
e8769719 RS |
11 | [B<-in> I<configfilename>] |
12 | [B<-out> I<configfilename>] | |
13 | [B<-module> I<modulefilename>] | |
14 | [B<-provider_name> I<providername>] | |
15 | [B<-section_name> I<sectionname>] | |
95214b43 | 16 | [B<-verify>] |
e8769719 RS |
17 | [B<-mac_name> I<macname>] |
18 | [B<-macopt> I<nm>:I<v>] | |
36fc5fc6 SL |
19 | [B<-noout>] |
20 | [B<-corrupt_desc> I<selftest_description>] | |
21 | [B<-corrupt_type> I<selftest_type>] | |
95214b43 | 22 | |
95214b43 SL |
23 | =head1 DESCRIPTION |
24 | ||
35a810bb | 25 | This command is used to generate a FIPS module configuration file. |
95214b43 SL |
26 | The generated configuration file consists of: |
27 | ||
28 | =over 4 | |
29 | ||
30 | =item - A mac of the FIPS module file. | |
31 | ||
32 | =item - A status indicator that indicates if the known answer Self Tests (KAT's) | |
33 | have successfully run. | |
34 | ||
35 | =back | |
36 | ||
37 | This configuration file can be used each time a FIPS module is loaded | |
38 | in order to pass data to the FIPS modules self tests. The FIPS module always | |
39 | verifies the modules MAC, but only needs to run the KATS once during install. | |
40 | ||
41 | =head1 OPTIONS | |
42 | ||
43 | =over 4 | |
44 | ||
45 | =item B<-help> | |
46 | ||
47 | Print a usage message. | |
48 | ||
e8769719 | 49 | =item B<-module> I<filename> |
95214b43 SL |
50 | |
51 | Filename of a fips module to perform an integrity check on. | |
52 | ||
e8769719 | 53 | =item B<-out> I<configfilename> |
95214b43 SL |
54 | |
55 | Filename to output the configuration data to, or standard output by default. | |
56 | ||
e8769719 | 57 | =item B<-in> I<configfilename> |
95214b43 SL |
58 | |
59 | Input filename to load configuration data from. Used with the '-verify' option. | |
60 | Standard input is used if the filename is '-'. | |
61 | ||
62 | =item B<-verify> | |
63 | ||
64 | Verify that the input configuration file contains the correct information | |
65 | ||
e8769719 | 66 | =item B<-provider_name> I<providername> |
95214b43 SL |
67 | |
68 | Name of the provider inside the configuration file. | |
69 | ||
e8769719 | 70 | =item B<-section_name> I<sectionname> |
95214b43 SL |
71 | |
72 | Name of the section inside the configuration file. | |
73 | ||
e8769719 | 74 | =item B<-mac_name> I<name> |
95214b43 SL |
75 | |
76 | Specifies the name of a supported MAC algorithm which will be used. | |
35a810bb RL |
77 | To see the list of supported MAC's use the command |
78 | C<openssl list -mac-algorithms>. The default is B<HMAC>. | |
95214b43 | 79 | |
e8769719 | 80 | =item B<-macopt> I<nm>:I<v> |
95214b43 SL |
81 | |
82 | Passes options to the MAC algorithm. | |
83 | A comprehensive list of controls can be found in the EVP_MAC implementation | |
84 | documentation. | |
85 | Common control strings used for fipsinstall are: | |
86 | ||
87 | =over 4 | |
88 | ||
2f0ea936 | 89 | =item B<key>:I<string> |
95214b43 SL |
90 | |
91 | Specifies the MAC key as an alphanumeric string (use if the key contains | |
92 | printable characters only). | |
93 | The string length must conform to any restrictions of the MAC algorithm. | |
94 | A key must be specified for every MAC algorithm. | |
95 | ||
2f0ea936 | 96 | =item B<hexkey>:I<string> |
95214b43 SL |
97 | |
98 | Specifies the MAC key in hexadecimal form (two hex digits per byte). | |
99 | The key length must conform to any restrictions of the MAC algorithm. | |
100 | A key must be specified for every MAC algorithm. | |
101 | ||
2f0ea936 | 102 | =item B<digest>:I<string> |
95214b43 SL |
103 | |
104 | Used by HMAC as an alphanumeric string (use if the key contains printable | |
105 | characters only). | |
106 | The string length must conform to any restrictions of the MAC algorithm. | |
35a810bb RL |
107 | To see the list of supported digests, use the command |
108 | C<openssl list -digest-commands>. | |
95214b43 SL |
109 | |
110 | =back | |
111 | ||
36fc5fc6 SL |
112 | =item B<-noout> |
113 | ||
114 | Disable logging of the self tests. | |
115 | ||
116 | =item B<-corrupt_desc> I<selftest_description> | |
117 | ||
118 | =item B<-corrupt_type> I<selftest_type> | |
119 | ||
120 | The corrupt options can be used to test failure of one or more self test(s) by | |
121 | name. | |
122 | Either option or both may be used to select the self test(s) to corrupt. | |
123 | Refer to the entries for "st-desc" and "st-type" in L<OSSL_PROVIDER-FIPS(7)> for | |
124 | values that can be used. | |
125 | ||
95214b43 SL |
126 | =back |
127 | ||
128 | =head1 EXAMPLES | |
129 | ||
1948394d RL |
130 | Calculate the mac of a FIPS module F<fips.so> and run a FIPS self test |
131 | for the module, and save the F<fips.conf> configuration file: | |
95214b43 SL |
132 | |
133 | openssl fipsinstall -module ./fips.so -out fips.conf -provider_name fips \ | |
134 | -section_name fipsinstall -mac_name HMAC -macopt digest:SHA256 \ | |
135 | -macopt hexkey:000102030405060708090A0B0C0D0E0F10111213 | |
136 | ||
1948394d | 137 | Verify that the configuration file F<fips.conf> contains the correct info: |
95214b43 SL |
138 | |
139 | openssl fipsinstall -module ./fips.so -in fips.conf -provider_name fips \ | |
140 | -section_name fips_install -mac_name HMAC -macopt digest:SHA256 \ | |
141 | -macopt hexkey:000102030405060708090A0B0C0D0E0F10111213 -verify | |
142 | ||
36fc5fc6 SL |
143 | Corrupt any self tests which have the description 'SHA1': |
144 | ||
145 | openssl fipsinstall -module ./fips.so -out fips.conf -provider_name fips \ | |
146 | -section_name fipsinstall -mac_name HMAC -macopt digest:SHA256 \ | |
147 | -macopt hexkey:000102030405060708090A0B0C0D0E0F10111213 \ | |
148 | -corrupt_desc', 'SHA1' | |
149 | ||
95214b43 SL |
150 | =head1 NOTES |
151 | ||
152 | The MAC mechanisms that are available will depend on the options | |
153 | used when building OpenSSL. | |
35a810bb | 154 | The command C<openssl list -mac-algorithms> command can be used to list them. |
95214b43 SL |
155 | |
156 | =head1 SEE ALSO | |
157 | ||
158 | L<fips_config(5)>, | |
36fc5fc6 | 159 | L<OSSL_PROVIDER-FIPS(7)>, |
95214b43 SL |
160 | L<EVP_MAC(3)> |
161 | ||
162 | =head1 COPYRIGHT | |
163 | ||
164 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
165 | ||
166 | Licensed under the OpenSSL license (the "License"). You may not use | |
167 | this file except in compliance with the License. You can obtain a copy | |
168 | in the file LICENSE in the source distribution or at | |
169 | L<https://www.openssl.org/source/license.html>. | |
170 | ||
171 | =cut |