]>
Commit | Line | Data |
---|---|---|
36fc5fc6 SL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c5926e93 | 5 | OSSL_PROVIDER-FIPS - OpenSSL FIPS provider |
36fc5fc6 SL |
6 | |
7 | =head1 DESCRIPTION | |
8 | ||
c5926e93 | 9 | The OpenSSL FIPS provider is a special provider that conforms to the Federal |
36fc5fc6 SL |
10 | Information Processing Standards (FIPS) specified in FIPS 140-2. This 'module' |
11 | contains an approved set of cryptographic algorithms that is validated by an | |
12 | accredited testing laboratory. | |
13 | ||
c5926e93 RL |
14 | =head2 Properties |
15 | ||
16 | The implementations in this provider specifically have these properties | |
17 | defined: | |
18 | ||
19 | =over 4 | |
20 | ||
21 | "provider=default" | |
22 | ||
23 | "fips=yes" | |
24 | ||
25 | =back | |
26 | ||
27 | It may be used in a property query string with fetching functions such as | |
28 | L<EVP_MD_fetch(3)> or L<EVP_CIPHER_fetch(3)>, as well as with other | |
29 | functions that take a property query string, such as | |
30 | L<EVP_PKEY_CTX_new_from_name(3)>. | |
31 | ||
32 | It isn't mandatory to query for any of these properties, except to | |
33 | make sure to get implementations of this provider and none other. | |
34 | ||
35 | The "fips=yes" property can be use to make sure only FIPS approved | |
36 | implementations are used for crypto operations. This may also include | |
37 | other non-crypto support operations that are not in the fips provider, | |
38 | such as asymmetric key serializers, | |
39 | see L<OSSL_PROVIDER-default(7)/Asymmetric Key Management>. | |
40 | ||
41 | =head1 OPERATIONS AND ALGORITHMS | |
42 | ||
43 | The OpenSSL FIPS provider supports these operations and algorithms: | |
44 | ||
45 | =head2 Hashing Algorithms / Message Digests | |
46 | ||
47 | =over 4 | |
48 | ||
49 | =item SHA1, see L<EVP_MD-SHA1(7)> | |
50 | ||
51 | =item SHA2, see L<EVP_MD-SHA2(7)> | |
52 | ||
53 | =item SHA3, see L<EVP_MD-SHA3(7)> | |
54 | ||
55 | =item KECCAK-KMAC, see L<EVP_MD-KECCAK-KMAC(7)> | |
56 | ||
57 | =back | |
58 | ||
59 | =head2 Symmetric Ciphers | |
60 | ||
61 | =over 4 | |
62 | ||
63 | =item AES, see L<EVP_CIPHER-AES(7)> | |
64 | ||
65 | =item DES-EDE3 (TrippleDES), see L<EVP_CIPHER-DES(7)> | |
66 | ||
67 | =back | |
68 | ||
69 | =head2 Message Authentication Code (MAC) | |
70 | ||
71 | =over 4 | |
72 | ||
73 | =item CMAC, see L<EVP_MAC-CMAC(7)> | |
74 | ||
75 | =item GMAC, see L<EVP_MAC-GMAC(7)> | |
76 | ||
77 | =item HMAC, see L<EVP_MAC-HMAC(7)> | |
78 | ||
79 | =item KMAC, see L<EVP_MAC-KMAC(7)> | |
80 | ||
81 | =back | |
82 | ||
83 | =head2 Key Derivation Function (KDF) | |
84 | ||
85 | =over 4 | |
86 | ||
87 | =item HKDF, see L<EVP_KDF-HKDF(7)> | |
88 | ||
89 | =item SSKDF, see L<EVP_KDF-SSKDF(7)> | |
90 | ||
91 | =item PBKDF2, see L<EVP_KDF-PBKDF2(7)> | |
92 | ||
93 | =item TLS1-PRF, see L<EVP_KDF-TLS1-PRF(7)> | |
94 | ||
95 | =item KBKDF, see L<EVP_KDF-KBKDF(7)> | |
96 | ||
97 | =back | |
98 | ||
99 | =head2 Key Exchange | |
100 | ||
101 | =over 4 | |
102 | ||
103 | =item DH, see L<EVP_KEYEXCH-DH(7)> | |
104 | ||
105 | =back | |
106 | ||
107 | =head2 Asymmetric Signature | |
108 | ||
109 | =over 4 | |
110 | ||
111 | =item DSA, see L<EVP_KEYEXCH-DSA(7)> | |
112 | ||
113 | =back | |
114 | ||
115 | =head2 Asymmetric Cipher | |
116 | ||
117 | =over 4 | |
118 | ||
119 | =item RSA, see L<EVP_KEYEXCH-RSA(7)> | |
120 | ||
121 | =back | |
122 | ||
123 | =head2 Asymmetric Key Management | |
124 | ||
125 | =over 4 | |
126 | ||
127 | =item DH, see L<EVP_KEYMGMT-DH(7)> | |
128 | ||
129 | =item DSA, see L<EVP_KEYMGMT-DSA(7)> | |
130 | ||
131 | =item RSA, see L<EVP_KEYMGMT-RSA(7)> | |
132 | ||
133 | =back | |
134 | ||
36fc5fc6 SL |
135 | =head1 SELF TESTING |
136 | ||
137 | One of the requirements for the FIPS module is self testing. An optional callback | |
138 | mechanism is available to return information to the user using | |
fadb57e5 | 139 | L<OSSL_SELF_TEST_set_callback(3)>. |
36fc5fc6 | 140 | |
47c239c6 SL |
141 | The parameters passed to the callback are described in L<OSSL_SELF_TEST_new(3)> |
142 | ||
c5926e93 | 143 | The OpenSSL FIPS module uses the following mechanism to provide information |
36fc5fc6 SL |
144 | about the self tests as they run. |
145 | This is useful for debugging if a self test is failing. | |
146 | The callback also allows forcing any self test to fail, in order to check that | |
147 | it operates correctly on failure. | |
36fc5fc6 SL |
148 | Note that all self tests run even if a self test failure occurs. |
149 | ||
47c239c6 | 150 | The FIPS module passes the following type(s) to OSSL_SELF_TEST_onbegin(). |
36fc5fc6 SL |
151 | |
152 | =over 4 | |
153 | ||
154 | =item "Module_Integrity" (B<OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY>) | |
155 | ||
156 | Uses HMAC SHA256 on the module file to validate that the module has not been | |
157 | modified. The integrity value is compared to a value written to a configuration | |
158 | file during installation. | |
159 | ||
160 | =item "Install_Integrity" (B<OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY>) | |
161 | ||
162 | Uses HMAC SHA256 on a fixed string to validate that the installation process | |
163 | has already been performed and the self test KATS have already been tested, | |
164 | The integrity value is compared to a value written to a configuration | |
165 | file after successfully running the self tests during installation. | |
166 | ||
167 | =item "KAT_Cipher" (B<OSSL_SELF_TEST_TYPE_KAT_CIPHER>) | |
168 | ||
169 | Known answer test for a symmetric cipher. | |
170 | ||
171 | =item "KAT_Digest" (B<OSSL_SELF_TEST_TYPE_KAT_DIGEST>) | |
172 | ||
173 | Known answer test for a digest. | |
174 | ||
175 | =item "KAT_Signature" (B<OSSL_SELF_TEST_TYPE_KAT_SIGNATURE>) | |
176 | ||
177 | Known answer test for a signature. | |
178 | ||
179 | =item "KAT_KDF" (B<OSSL_SELF_TEST_TYPE_KAT_KDF>) | |
180 | ||
181 | Known answer test for a key derivation function. | |
182 | ||
183 | =item "KAT_KA" (B<OSSL_SELF_TEST_TYPE_KAT_KA>) | |
184 | ||
185 | Known answer test for key agreement. | |
186 | ||
187 | =item "DRBG" (B<OSSL_SELF_TEST_TYPE_DRBG>) | |
188 | ||
189 | Known answer test for a Deterministic Random Bit Generator. | |
190 | ||
191 | =item "Pairwise_Consistency_Test" (B<OSSL_SELF_TEST_TYPE_PCT>) | |
192 | ||
193 | Conditional test that is run during the generation of key pairs. | |
194 | ||
195 | =back | |
196 | ||
197 | The "Module_Integrity" self test is always run at startup. | |
198 | The "Install_Integrity" self test is used to check if the self tests have | |
199 | already been run at installation time. If they have already run then the | |
200 | self tests are not run on subsequent startups. | |
201 | All other self test categories are run once at installation time, except for the | |
202 | "Pairwise_Consistency_Test". | |
203 | ||
204 | There is only one instance of the "Module_Integrity" and "Install_Integrity" | |
205 | self tests. All other self tests may have multiple instances. | |
206 | ||
36fc5fc6 | 207 | |
47c239c6 | 208 | The FIPS module passes the following descriptions(s) to OSSL_SELF_TEST_onbegin(). |
36fc5fc6 SL |
209 | |
210 | =over 4 | |
211 | ||
212 | =item "HMAC" (B<OSSL_SELF_TEST_DESC_INTEGRITY_HMAC>) | |
213 | ||
214 | "Module_Integrity" and "Install_Integrity" use this. | |
215 | ||
216 | =item "RSA" (B<OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1>) | |
217 | ||
218 | =item "ECDSA" (B<OSSL_SELF_TEST_DESC_PCT_ECDSA>) | |
219 | ||
220 | =item "DSA" (B<OSSL_SELF_TEST_DESC_PCT_DSA>) | |
221 | ||
222 | Key generation tests used with the "Pairwise_Consistency_Test" type. | |
223 | ||
224 | =item "AES_GCM" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_GCM>) | |
225 | ||
226 | =item "TDES" (B<OSSL_SELF_TEST_DESC_CIPHER_TDES>) | |
227 | ||
228 | Symmetric cipher tests used with the "KAT_Cipher" type. | |
229 | ||
230 | =item "SHA1" (B<OSSL_SELF_TEST_DESC_MD_SHA1>) | |
231 | ||
232 | =item "SHA2" (B<OSSL_SELF_TEST_DESC_MD_SHA2>) | |
233 | ||
234 | =item "SHA3" (B<OSSL_SELF_TEST_DESC_MD_SHA3>) | |
235 | ||
236 | Digest tests used with the "KAT_Digest" type. | |
237 | ||
238 | =item "DSA" (B<OSSL_SELF_TEST_DESC_SIGN_DSA>) | |
239 | ||
240 | =item "RSA" (B<OSSL_SELF_TEST_DESC_SIGN_RSA>) | |
241 | ||
242 | =item "ECDSA" (B<OSSL_SELF_TEST_DESC_SIGN_ECDSA>) | |
243 | ||
244 | Signature tests used with the "KAT_Signature" type. | |
245 | ||
246 | =item "ECDH" (B<OSSL_SELF_TEST_DESC_KA_ECDH>) | |
247 | ||
ec4d1b8f | 248 | =item "DH" (B<OSSL_SELF_TEST_DESC_KA_DH>) |
36fc5fc6 SL |
249 | |
250 | Key agreement tests used with the "KAT_KA" type. | |
251 | ||
252 | =item "HKDF" (B<OSSL_SELF_TEST_DESC_KDF_HKDF>) | |
253 | ||
ec4d1b8f SL |
254 | =item "SSKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSKDF>) |
255 | ||
36fc5fc6 SL |
256 | Key Derivation Function tests used with the "KAT_KDF" type. |
257 | ||
258 | =item "CTR" (B<OSSL_SELF_TEST_DESC_DRBG_CTR>) | |
259 | ||
260 | =item "HASH" (B<OSSL_SELF_TEST_DESC_DRBG_HASH>) | |
261 | ||
262 | =item "HMAC" (B<OSSL_SELF_TEST_DESC_DRBG_HMAC>) | |
263 | ||
264 | DRBG tests used with the "DRBG" type. | |
265 | ||
266 | =back | |
267 | ||
36fc5fc6 SL |
268 | =head1 EXAMPLES |
269 | ||
270 | A simple self test callback is shown below for illustrative purposes. | |
271 | ||
272 | #include <openssl/self_test.h> | |
273 | ||
274 | static OSSL_CALLBACK self_test_cb; | |
275 | ||
276 | static int self_test_cb(const OSSL_PARAM params[], void *arg) | |
277 | { | |
278 | int ret = 0; | |
279 | const OSSL_PARAM *p = NULL; | |
280 | const char *phase = NULL, *type = NULL, *desc = NULL; | |
281 | ||
282 | p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE); | |
283 | if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) | |
284 | goto err; | |
285 | phase = (const char *)p->data; | |
286 | ||
287 | p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC); | |
288 | if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) | |
289 | goto err; | |
290 | desc = (const char *)p->data; | |
291 | ||
292 | p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE); | |
293 | if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) | |
294 | goto err; | |
295 | type = (const char *)p->data; | |
296 | ||
297 | /* Do some logging */ | |
298 | if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0) | |
299 | BIO_printf(bio_out, "%s : (%s) : ", desc, type); | |
300 | if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0 | |
301 | || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0) | |
302 | BIO_printf(bio_out, "%s\n", phase); | |
303 | ||
304 | /* Corrupt the SHA1 self test during the 'corrupt' phase by returning 0 */ | |
305 | if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0 | |
306 | && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) { | |
307 | BIO_printf(bio_out, "%s %s", phase, desc); | |
308 | return 0; | |
309 | } | |
310 | ret = 1; | |
311 | err: | |
312 | return ret; | |
313 | } | |
314 | ||
315 | =head1 SEE ALSO | |
316 | ||
317 | L<openssl-fipsinstall(1)>, | |
318 | L<fips_config(5)>, | |
fadb57e5 | 319 | L<OSSL_SELF_TEST_set_callback(3)>, |
47c239c6 | 320 | L<OSSL_SELF_TEST_new(3)>, |
36fc5fc6 | 321 | L<OSSL_PARAM(3)>, |
c5926e93 RL |
322 | L<openssl-core.h(7)>, |
323 | L<openssl-core_numbers.h(7)>, | |
324 | L<provider(7)> | |
36fc5fc6 SL |
325 | |
326 | =head1 HISTORY | |
327 | ||
328 | The type and functions described here were added in OpenSSL 3.0. | |
329 | ||
330 | =head1 COPYRIGHT | |
331 | ||
47c239c6 | 332 | Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. |
36fc5fc6 SL |
333 | |
334 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
335 | this file except in compliance with the License. You can obtain a copy | |
336 | in the file LICENSE in the source distribution or at | |
337 | L<https://www.openssl.org/source/license.html>. | |
338 | ||
339 | =cut |