]>
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 | ||
57cd10dd | 9 | The OpenSSL FIPS provider is a special provider that conforms to the Federal |
8353b2df | 10 | Information Processing Standards (FIPS) specified in FIPS 140-3. This 'module' |
36fc5fc6 SL |
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 | ||
baa47ad3 | 21 | =item "provider=fips" |
c5926e93 | 22 | |
b8086652 | 23 | =item "fips=yes" |
c5926e93 RL |
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 | ||
0a81220a P |
32 | To be FIPS compliant, it is mandatory to include C<fips=yes> as |
33 | part of all property queries. This ensures that only FIPS approved | |
34 | implementations are used for cryptographic operations. The C<fips=yes> | |
35 | query may also include other non-crypto support operations that | |
36 | are not in the FIPS provider, such as asymmetric key encoders, see | |
37 | L<OSSL_PROVIDER-default(7)/Asymmetric Key Management>. | |
38 | ||
39 | It is not mandatory to include C<provider=fips> as part of your property | |
40 | query. Including C<provider=fips> in your property query guarantees | |
41 | that the OpenSSL FIPS provider is used for cryptographic operations | |
42 | rather than other FIPS capable providers. | |
c5926e93 | 43 | |
50ea5cdc | 44 | =head2 Provider parameters |
45 | ||
46 | See L<provider-base(7)/Provider parameters> for a list of base parameters. | |
47 | Additionally the OpenSSL FIPS provider also supports the following gettable | |
48 | parameters: | |
49 | ||
50 | =over 4 | |
51 | ||
52 | =item "security-checks" (B<OSSL_OSSL_PROV_PARAM_SECURITY_CHECKS>) <unsigned integer> | |
53 | ||
54 | For further information refer to the L<openssl-fipsinstall(1)> option | |
55 | B<-no_security_checks>. | |
56 | ||
57 | =back | |
58 | ||
c5926e93 RL |
59 | =head1 OPERATIONS AND ALGORITHMS |
60 | ||
61 | The OpenSSL FIPS provider supports these operations and algorithms: | |
62 | ||
63 | =head2 Hashing Algorithms / Message Digests | |
64 | ||
65 | =over 4 | |
66 | ||
67 | =item SHA1, see L<EVP_MD-SHA1(7)> | |
68 | ||
69 | =item SHA2, see L<EVP_MD-SHA2(7)> | |
70 | ||
71 | =item SHA3, see L<EVP_MD-SHA3(7)> | |
72 | ||
73 | =item KECCAK-KMAC, see L<EVP_MD-KECCAK-KMAC(7)> | |
74 | ||
75 | =back | |
76 | ||
77 | =head2 Symmetric Ciphers | |
78 | ||
79 | =over 4 | |
80 | ||
81 | =item AES, see L<EVP_CIPHER-AES(7)> | |
82 | ||
c5926e93 RL |
83 | =back |
84 | ||
85 | =head2 Message Authentication Code (MAC) | |
86 | ||
87 | =over 4 | |
88 | ||
89 | =item CMAC, see L<EVP_MAC-CMAC(7)> | |
90 | ||
91 | =item GMAC, see L<EVP_MAC-GMAC(7)> | |
92 | ||
93 | =item HMAC, see L<EVP_MAC-HMAC(7)> | |
94 | ||
95 | =item KMAC, see L<EVP_MAC-KMAC(7)> | |
96 | ||
97 | =back | |
98 | ||
99 | =head2 Key Derivation Function (KDF) | |
100 | ||
101 | =over 4 | |
102 | ||
103 | =item HKDF, see L<EVP_KDF-HKDF(7)> | |
104 | ||
5961aeda P |
105 | =item TLS13-KDF, see L<EVP_KDF-TLS13_KDF(7)> |
106 | ||
ad60cd52 | 107 | =item SSKDF, see L<EVP_KDF-SS(7)> |
c5926e93 RL |
108 | |
109 | =item PBKDF2, see L<EVP_KDF-PBKDF2(7)> | |
110 | ||
89cccbea SL |
111 | =item SSHKDF, see L<EVP_KDF-SSHKDF(7)> |
112 | ||
5961aeda | 113 | =item TLS1-PRF, see L<EVP_KDF-TLS1_PRF(7)> |
c5926e93 | 114 | |
ad60cd52 | 115 | =item KBKDF, see L<EVP_KDF-KB(7)> |
c5926e93 | 116 | |
89cccbea SL |
117 | =item X942KDF-ASN1, see L<EVP_KDF-X942-ASN1(7)> |
118 | ||
119 | =item X942KDF-CONCAT, see L<EVP_KDF-X942-CONCAT(7)> | |
120 | ||
121 | =item X963KDF, see L<EVP_KDF-X963(7)> | |
122 | ||
c5926e93 RL |
123 | =back |
124 | ||
125 | =head2 Key Exchange | |
126 | ||
127 | =over 4 | |
128 | ||
129 | =item DH, see L<EVP_KEYEXCH-DH(7)> | |
130 | ||
b8086652 SL |
131 | =item ECDH, see L<EVP_KEYEXCH-ECDH(7)> |
132 | ||
133 | =item X25519, see L<EVP_KEYEXCH-X25519(7)> | |
134 | ||
b8086652 SL |
135 | =item X448, see L<EVP_KEYEXCH-X448(7)> |
136 | ||
c5926e93 RL |
137 | =back |
138 | ||
139 | =head2 Asymmetric Signature | |
140 | ||
141 | =over 4 | |
142 | ||
820d87bc MC |
143 | =item RSA, see L<EVP_SIGNATURE-RSA(7)> |
144 | ||
5e892625 P |
145 | =item X25519, see L<EVP_SIGNATURE-ED25519(7)> |
146 | ||
147 | =item X448, see L<EVP_SIGNATURE-ED448(7)> | |
148 | ||
820d87bc MC |
149 | =item HMAC, see L<EVP_SIGNATURE-HMAC(7)> |
150 | ||
151 | =item CMAC, see L<EVP_SIGNATURE-CMAC(7)> | |
152 | ||
c5926e93 RL |
153 | =back |
154 | ||
155 | =head2 Asymmetric Cipher | |
156 | ||
157 | =over 4 | |
158 | ||
ad60cd52 | 159 | =item RSA, see L<EVP_ASYM_CIPHER-RSA(7)> |
c5926e93 RL |
160 | |
161 | =back | |
162 | ||
80f4fd18 SL |
163 | =head2 Asymmetric Key Encapsulation |
164 | ||
165 | =over 4 | |
166 | ||
167 | =item RSA, see L<EVP_KEM-RSA(7)> | |
168 | ||
169 | =back | |
170 | ||
c5926e93 RL |
171 | =head2 Asymmetric Key Management |
172 | ||
173 | =over 4 | |
174 | ||
175 | =item DH, see L<EVP_KEYMGMT-DH(7)> | |
176 | ||
0b3d2594 | 177 | =item DHX, see L<EVP_KEYMGMT-DHX(7)> |
178 | ||
c5926e93 RL |
179 | =item DSA, see L<EVP_KEYMGMT-DSA(7)> |
180 | ||
181 | =item RSA, see L<EVP_KEYMGMT-RSA(7)> | |
182 | ||
0b3d2594 | 183 | =item EC, see L<EVP_KEYMGMT-EC(7)> |
184 | ||
185 | =item X25519, see L<EVP_KEYMGMT-X25519(7)> | |
186 | ||
187 | =item X448, see L<EVP_KEYMGMT-X448(7)> | |
188 | ||
c5926e93 RL |
189 | =back |
190 | ||
7066c57d | 191 | =head2 Random Number Generation |
192 | ||
193 | =over 4 | |
194 | ||
195 | =item CTR-DRBG, see L<EVP_RAND-CTR-DRBG(7)> | |
196 | ||
197 | =item HASH-DRBG, see L<EVP_RAND-HASH-DRBG(7)> | |
198 | ||
199 | =item HMAC-DRBG, see L<EVP_RAND-HMAC-DRBG(7)> | |
200 | ||
201 | =item TEST-RAND, see L<EVP_RAND-TEST-RAND(7)> | |
202 | ||
203 | TEST-RAND is an unapproved algorithm. | |
204 | ||
205 | =back | |
206 | ||
36fc5fc6 SL |
207 | =head1 SELF TESTING |
208 | ||
209 | One of the requirements for the FIPS module is self testing. An optional callback | |
210 | mechanism is available to return information to the user using | |
fadb57e5 | 211 | L<OSSL_SELF_TEST_set_callback(3)>. |
36fc5fc6 | 212 | |
47c239c6 SL |
213 | The parameters passed to the callback are described in L<OSSL_SELF_TEST_new(3)> |
214 | ||
c5926e93 | 215 | The OpenSSL FIPS module uses the following mechanism to provide information |
36fc5fc6 SL |
216 | about the self tests as they run. |
217 | This is useful for debugging if a self test is failing. | |
218 | The callback also allows forcing any self test to fail, in order to check that | |
219 | it operates correctly on failure. | |
36fc5fc6 SL |
220 | Note that all self tests run even if a self test failure occurs. |
221 | ||
47c239c6 | 222 | The FIPS module passes the following type(s) to OSSL_SELF_TEST_onbegin(). |
36fc5fc6 SL |
223 | |
224 | =over 4 | |
225 | ||
226 | =item "Module_Integrity" (B<OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY>) | |
227 | ||
228 | Uses HMAC SHA256 on the module file to validate that the module has not been | |
229 | modified. The integrity value is compared to a value written to a configuration | |
230 | file during installation. | |
231 | ||
232 | =item "Install_Integrity" (B<OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY>) | |
233 | ||
234 | Uses HMAC SHA256 on a fixed string to validate that the installation process | |
235 | has already been performed and the self test KATS have already been tested, | |
236 | The integrity value is compared to a value written to a configuration | |
237 | file after successfully running the self tests during installation. | |
238 | ||
239 | =item "KAT_Cipher" (B<OSSL_SELF_TEST_TYPE_KAT_CIPHER>) | |
240 | ||
241 | Known answer test for a symmetric cipher. | |
242 | ||
4343a418 SL |
243 | =item "KAT_AsymmetricCipher" (B<OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER>) |
244 | ||
245 | Known answer test for a asymmetric cipher. | |
246 | ||
36fc5fc6 SL |
247 | =item "KAT_Digest" (B<OSSL_SELF_TEST_TYPE_KAT_DIGEST>) |
248 | ||
249 | Known answer test for a digest. | |
250 | ||
251 | =item "KAT_Signature" (B<OSSL_SELF_TEST_TYPE_KAT_SIGNATURE>) | |
252 | ||
253 | Known answer test for a signature. | |
254 | ||
57cd10dd | 255 | =item "PCT_Signature" (B<OSSL_SELF_TEST_TYPE_PCT_SIGNATURE>) |
55950587 | 256 | |
257 | Pairwise Consistency check for a signature. | |
258 | ||
36fc5fc6 SL |
259 | =item "KAT_KDF" (B<OSSL_SELF_TEST_TYPE_KAT_KDF>) |
260 | ||
261 | Known answer test for a key derivation function. | |
262 | ||
263 | =item "KAT_KA" (B<OSSL_SELF_TEST_TYPE_KAT_KA>) | |
264 | ||
265 | Known answer test for key agreement. | |
266 | ||
267 | =item "DRBG" (B<OSSL_SELF_TEST_TYPE_DRBG>) | |
268 | ||
269 | Known answer test for a Deterministic Random Bit Generator. | |
270 | ||
55950587 | 271 | =item "Conditional_PCT" (B<OSSL_SELF_TEST_TYPE_PCT>) |
36fc5fc6 SL |
272 | |
273 | Conditional test that is run during the generation of key pairs. | |
274 | ||
7f9e7440 SL |
275 | =item "Continuous_RNG_Test" (B<OSSL_SELF_TEST_TYPE_CRNG>) |
276 | ||
277 | Continuous random number generator test. | |
278 | ||
36fc5fc6 SL |
279 | =back |
280 | ||
281 | The "Module_Integrity" self test is always run at startup. | |
282 | The "Install_Integrity" self test is used to check if the self tests have | |
283 | already been run at installation time. If they have already run then the | |
284 | self tests are not run on subsequent startups. | |
285 | All other self test categories are run once at installation time, except for the | |
286 | "Pairwise_Consistency_Test". | |
287 | ||
288 | There is only one instance of the "Module_Integrity" and "Install_Integrity" | |
289 | self tests. All other self tests may have multiple instances. | |
290 | ||
36fc5fc6 | 291 | |
47c239c6 | 292 | The FIPS module passes the following descriptions(s) to OSSL_SELF_TEST_onbegin(). |
36fc5fc6 SL |
293 | |
294 | =over 4 | |
295 | ||
296 | =item "HMAC" (B<OSSL_SELF_TEST_DESC_INTEGRITY_HMAC>) | |
297 | ||
298 | "Module_Integrity" and "Install_Integrity" use this. | |
299 | ||
300 | =item "RSA" (B<OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1>) | |
301 | ||
302 | =item "ECDSA" (B<OSSL_SELF_TEST_DESC_PCT_ECDSA>) | |
303 | ||
304 | =item "DSA" (B<OSSL_SELF_TEST_DESC_PCT_DSA>) | |
305 | ||
306 | Key generation tests used with the "Pairwise_Consistency_Test" type. | |
307 | ||
4343a418 SL |
308 | =item "RSA_Encrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_ENC>) |
309 | ||
310 | =item "RSA_Decrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_DEC>) | |
311 | ||
312 | "KAT_AsymmetricCipher" uses this to indicate an encrypt or decrypt KAT. | |
313 | ||
3b1978e4 | 314 | =item "AES_GCM" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_GCM>) |
3fed2718 SL |
315 | |
316 | =item "AES_ECB_Decrypt" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_ECB>) | |
36fc5fc6 SL |
317 | |
318 | =item "TDES" (B<OSSL_SELF_TEST_DESC_CIPHER_TDES>) | |
319 | ||
320 | Symmetric cipher tests used with the "KAT_Cipher" type. | |
321 | ||
322 | =item "SHA1" (B<OSSL_SELF_TEST_DESC_MD_SHA1>) | |
323 | ||
324 | =item "SHA2" (B<OSSL_SELF_TEST_DESC_MD_SHA2>) | |
325 | ||
326 | =item "SHA3" (B<OSSL_SELF_TEST_DESC_MD_SHA3>) | |
327 | ||
328 | Digest tests used with the "KAT_Digest" type. | |
329 | ||
330 | =item "DSA" (B<OSSL_SELF_TEST_DESC_SIGN_DSA>) | |
331 | ||
332 | =item "RSA" (B<OSSL_SELF_TEST_DESC_SIGN_RSA>) | |
333 | ||
334 | =item "ECDSA" (B<OSSL_SELF_TEST_DESC_SIGN_ECDSA>) | |
335 | ||
336 | Signature tests used with the "KAT_Signature" type. | |
337 | ||
338 | =item "ECDH" (B<OSSL_SELF_TEST_DESC_KA_ECDH>) | |
339 | ||
ec4d1b8f | 340 | =item "DH" (B<OSSL_SELF_TEST_DESC_KA_DH>) |
36fc5fc6 SL |
341 | |
342 | Key agreement tests used with the "KAT_KA" type. | |
343 | ||
344 | =item "HKDF" (B<OSSL_SELF_TEST_DESC_KDF_HKDF>) | |
345 | ||
5961aeda P |
346 | =item "TLS13_KDF_EXTRACT" (B<OSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT>) |
347 | ||
348 | =item "TLS13_KDF_EXPAND" (B<OSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND>) | |
349 | ||
ec4d1b8f SL |
350 | =item "SSKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSKDF>) |
351 | ||
acd3e548 SL |
352 | =item "X963KDF" (B<OSSL_SELF_TEST_DESC_KDF_X963KDF>) |
353 | ||
354 | =item "X942KDF" (B<OSSL_SELF_TEST_DESC_KDF_X942KDF>) | |
355 | ||
356 | =item "PBKDF2" (B<OSSL_SELF_TEST_DESC_KDF_PBKDF2>) | |
357 | ||
358 | =item "SSHKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSHKDF>) | |
359 | ||
360 | =item "TLS12_PRF" (B<OSSL_SELF_TEST_DESC_KDF_TLS12_PRF>) | |
361 | ||
362 | =item "KBKDF" (B<OSSL_SELF_TEST_DESC_KDF_KBKDF>) | |
363 | ||
36fc5fc6 SL |
364 | Key Derivation Function tests used with the "KAT_KDF" type. |
365 | ||
366 | =item "CTR" (B<OSSL_SELF_TEST_DESC_DRBG_CTR>) | |
367 | ||
368 | =item "HASH" (B<OSSL_SELF_TEST_DESC_DRBG_HASH>) | |
369 | ||
370 | =item "HMAC" (B<OSSL_SELF_TEST_DESC_DRBG_HMAC>) | |
371 | ||
372 | DRBG tests used with the "DRBG" type. | |
373 | ||
7f9e7440 SL |
374 | = item "RNG" (B<OSSL_SELF_TEST_DESC_RNG>) |
375 | ||
376 | "Continuous_RNG_Test" uses this. | |
377 | ||
36fc5fc6 SL |
378 | =back |
379 | ||
36fc5fc6 SL |
380 | =head1 EXAMPLES |
381 | ||
382 | A simple self test callback is shown below for illustrative purposes. | |
383 | ||
384 | #include <openssl/self_test.h> | |
385 | ||
386 | static OSSL_CALLBACK self_test_cb; | |
387 | ||
388 | static int self_test_cb(const OSSL_PARAM params[], void *arg) | |
389 | { | |
390 | int ret = 0; | |
391 | const OSSL_PARAM *p = NULL; | |
392 | const char *phase = NULL, *type = NULL, *desc = NULL; | |
393 | ||
394 | p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE); | |
395 | if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) | |
396 | goto err; | |
397 | phase = (const char *)p->data; | |
398 | ||
399 | p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC); | |
400 | if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) | |
401 | goto err; | |
402 | desc = (const char *)p->data; | |
403 | ||
404 | p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE); | |
405 | if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) | |
406 | goto err; | |
407 | type = (const char *)p->data; | |
408 | ||
409 | /* Do some logging */ | |
410 | if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0) | |
411 | BIO_printf(bio_out, "%s : (%s) : ", desc, type); | |
412 | if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0 | |
413 | || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0) | |
414 | BIO_printf(bio_out, "%s\n", phase); | |
415 | ||
416 | /* Corrupt the SHA1 self test during the 'corrupt' phase by returning 0 */ | |
417 | if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0 | |
418 | && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) { | |
419 | BIO_printf(bio_out, "%s %s", phase, desc); | |
420 | return 0; | |
421 | } | |
422 | ret = 1; | |
423 | err: | |
424 | return ret; | |
425 | } | |
426 | ||
8353b2df P |
427 | =head1 NOTES |
428 | ||
429 | The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated algorithms, | |
430 | consequently the property query C<fips=yes> is mandatory for applications that | |
431 | want to operate in a FIPS approved manner. The algorithms are: | |
432 | ||
433 | =over 4 | |
434 | ||
92c0e33e | 435 | =item Triple DES ECB |
8353b2df | 436 | |
92c0e33e | 437 | =item Triple DES CBC |
8353b2df | 438 | |
fdd4716d P |
439 | =item EdDSA |
440 | ||
8353b2df P |
441 | =back |
442 | ||
36fc5fc6 SL |
443 | =head1 SEE ALSO |
444 | ||
445 | L<openssl-fipsinstall(1)>, | |
446 | L<fips_config(5)>, | |
fadb57e5 | 447 | L<OSSL_SELF_TEST_set_callback(3)>, |
47c239c6 | 448 | L<OSSL_SELF_TEST_new(3)>, |
36fc5fc6 | 449 | L<OSSL_PARAM(3)>, |
c5926e93 | 450 | L<openssl-core.h(7)>, |
23c48d94 | 451 | L<openssl-core_dispatch.h(7)>, |
c5926e93 | 452 | L<provider(7)> |
36fc5fc6 SL |
453 | |
454 | =head1 HISTORY | |
455 | ||
4741c80c | 456 | This functionality was added in OpenSSL 3.0. |
36fc5fc6 | 457 | |
8353b2df P |
458 | OpenSSL 3.0 includes a FIPS 140-2 approved FIPS provider. |
459 | ||
460 | OpenSSL 3.1 includes a FIPS 140-3 approved FIPS provider. | |
461 | ||
36fc5fc6 SL |
462 | =head1 COPYRIGHT |
463 | ||
f5afac4b | 464 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. |
36fc5fc6 SL |
465 | |
466 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
467 | this file except in compliance with the License. You can obtain a copy | |
468 | in the file LICENSE in the source distribution or at | |
469 | L<https://www.openssl.org/source/license.html>. | |
470 | ||
471 | =cut |