]>
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 | ||
b8086652 | 21 | =item "provider=default" |
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 | ||
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, | |
ece9304c | 38 | such as asymmetric key encoders, |
c5926e93 RL |
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 | ||
89cccbea SL |
93 | =item SSHKDF, see L<EVP_KDF-SSHKDF(7)> |
94 | ||
c5926e93 RL |
95 | =item TLS1-PRF, see L<EVP_KDF-TLS1-PRF(7)> |
96 | ||
97 | =item KBKDF, see L<EVP_KDF-KBKDF(7)> | |
98 | ||
89cccbea SL |
99 | =item X942KDF-ASN1, see L<EVP_KDF-X942-ASN1(7)> |
100 | ||
101 | =item X942KDF-CONCAT, see L<EVP_KDF-X942-CONCAT(7)> | |
102 | ||
103 | =item X963KDF, see L<EVP_KDF-X963(7)> | |
104 | ||
c5926e93 RL |
105 | =back |
106 | ||
107 | =head2 Key Exchange | |
108 | ||
109 | =over 4 | |
110 | ||
111 | =item DH, see L<EVP_KEYEXCH-DH(7)> | |
112 | ||
b8086652 SL |
113 | =item ECDH, see L<EVP_KEYEXCH-ECDH(7)> |
114 | ||
115 | =item X25519, see L<EVP_KEYEXCH-X25519(7)> | |
116 | ||
117 | This has the property "provider=fips,fips=no" | |
118 | ||
119 | =item X448, see L<EVP_KEYEXCH-X448(7)> | |
120 | ||
121 | This has the property "provider=fips,fips=no" | |
122 | ||
c5926e93 RL |
123 | =back |
124 | ||
125 | =head2 Asymmetric Signature | |
126 | ||
127 | =over 4 | |
128 | ||
129 | =item DSA, see L<EVP_KEYEXCH-DSA(7)> | |
130 | ||
820d87bc MC |
131 | =item RSA, see L<EVP_SIGNATURE-RSA(7)> |
132 | ||
133 | =item HMAC, see L<EVP_SIGNATURE-HMAC(7)> | |
134 | ||
135 | =item CMAC, see L<EVP_SIGNATURE-CMAC(7)> | |
136 | ||
c5926e93 RL |
137 | =back |
138 | ||
139 | =head2 Asymmetric Cipher | |
140 | ||
141 | =over 4 | |
142 | ||
143 | =item RSA, see L<EVP_KEYEXCH-RSA(7)> | |
144 | ||
145 | =back | |
146 | ||
80f4fd18 SL |
147 | =head2 Asymmetric Key Encapsulation |
148 | ||
149 | =over 4 | |
150 | ||
151 | =item RSA, see L<EVP_KEM-RSA(7)> | |
152 | ||
153 | =back | |
154 | ||
c5926e93 RL |
155 | =head2 Asymmetric Key Management |
156 | ||
157 | =over 4 | |
158 | ||
159 | =item DH, see L<EVP_KEYMGMT-DH(7)> | |
160 | ||
161 | =item DSA, see L<EVP_KEYMGMT-DSA(7)> | |
162 | ||
163 | =item RSA, see L<EVP_KEYMGMT-RSA(7)> | |
164 | ||
165 | =back | |
166 | ||
36fc5fc6 SL |
167 | =head1 SELF TESTING |
168 | ||
169 | One of the requirements for the FIPS module is self testing. An optional callback | |
170 | mechanism is available to return information to the user using | |
fadb57e5 | 171 | L<OSSL_SELF_TEST_set_callback(3)>. |
36fc5fc6 | 172 | |
47c239c6 SL |
173 | The parameters passed to the callback are described in L<OSSL_SELF_TEST_new(3)> |
174 | ||
c5926e93 | 175 | The OpenSSL FIPS module uses the following mechanism to provide information |
36fc5fc6 SL |
176 | about the self tests as they run. |
177 | This is useful for debugging if a self test is failing. | |
178 | The callback also allows forcing any self test to fail, in order to check that | |
179 | it operates correctly on failure. | |
36fc5fc6 SL |
180 | Note that all self tests run even if a self test failure occurs. |
181 | ||
47c239c6 | 182 | The FIPS module passes the following type(s) to OSSL_SELF_TEST_onbegin(). |
36fc5fc6 SL |
183 | |
184 | =over 4 | |
185 | ||
186 | =item "Module_Integrity" (B<OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY>) | |
187 | ||
188 | Uses HMAC SHA256 on the module file to validate that the module has not been | |
189 | modified. The integrity value is compared to a value written to a configuration | |
190 | file during installation. | |
191 | ||
192 | =item "Install_Integrity" (B<OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY>) | |
193 | ||
194 | Uses HMAC SHA256 on a fixed string to validate that the installation process | |
195 | has already been performed and the self test KATS have already been tested, | |
196 | The integrity value is compared to a value written to a configuration | |
197 | file after successfully running the self tests during installation. | |
198 | ||
199 | =item "KAT_Cipher" (B<OSSL_SELF_TEST_TYPE_KAT_CIPHER>) | |
200 | ||
201 | Known answer test for a symmetric cipher. | |
202 | ||
4343a418 SL |
203 | =item "KAT_AsymmetricCipher" (B<OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER>) |
204 | ||
205 | Known answer test for a asymmetric cipher. | |
206 | ||
36fc5fc6 SL |
207 | =item "KAT_Digest" (B<OSSL_SELF_TEST_TYPE_KAT_DIGEST>) |
208 | ||
209 | Known answer test for a digest. | |
210 | ||
211 | =item "KAT_Signature" (B<OSSL_SELF_TEST_TYPE_KAT_SIGNATURE>) | |
212 | ||
213 | Known answer test for a signature. | |
214 | ||
215 | =item "KAT_KDF" (B<OSSL_SELF_TEST_TYPE_KAT_KDF>) | |
216 | ||
217 | Known answer test for a key derivation function. | |
218 | ||
219 | =item "KAT_KA" (B<OSSL_SELF_TEST_TYPE_KAT_KA>) | |
220 | ||
221 | Known answer test for key agreement. | |
222 | ||
223 | =item "DRBG" (B<OSSL_SELF_TEST_TYPE_DRBG>) | |
224 | ||
225 | Known answer test for a Deterministic Random Bit Generator. | |
226 | ||
227 | =item "Pairwise_Consistency_Test" (B<OSSL_SELF_TEST_TYPE_PCT>) | |
228 | ||
229 | Conditional test that is run during the generation of key pairs. | |
230 | ||
7f9e7440 SL |
231 | =item "Continuous_RNG_Test" (B<OSSL_SELF_TEST_TYPE_CRNG>) |
232 | ||
233 | Continuous random number generator test. | |
234 | ||
36fc5fc6 SL |
235 | =back |
236 | ||
237 | The "Module_Integrity" self test is always run at startup. | |
238 | The "Install_Integrity" self test is used to check if the self tests have | |
239 | already been run at installation time. If they have already run then the | |
240 | self tests are not run on subsequent startups. | |
241 | All other self test categories are run once at installation time, except for the | |
242 | "Pairwise_Consistency_Test". | |
243 | ||
244 | There is only one instance of the "Module_Integrity" and "Install_Integrity" | |
245 | self tests. All other self tests may have multiple instances. | |
246 | ||
36fc5fc6 | 247 | |
47c239c6 | 248 | The FIPS module passes the following descriptions(s) to OSSL_SELF_TEST_onbegin(). |
36fc5fc6 SL |
249 | |
250 | =over 4 | |
251 | ||
252 | =item "HMAC" (B<OSSL_SELF_TEST_DESC_INTEGRITY_HMAC>) | |
253 | ||
254 | "Module_Integrity" and "Install_Integrity" use this. | |
255 | ||
256 | =item "RSA" (B<OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1>) | |
257 | ||
258 | =item "ECDSA" (B<OSSL_SELF_TEST_DESC_PCT_ECDSA>) | |
259 | ||
260 | =item "DSA" (B<OSSL_SELF_TEST_DESC_PCT_DSA>) | |
261 | ||
262 | Key generation tests used with the "Pairwise_Consistency_Test" type. | |
263 | ||
4343a418 SL |
264 | =item "RSA_Encrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_ENC>) |
265 | ||
266 | =item "RSA_Decrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_DEC>) | |
267 | ||
268 | "KAT_AsymmetricCipher" uses this to indicate an encrypt or decrypt KAT. | |
269 | ||
36fc5fc6 SL |
270 | =item "AES_GCM" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_GCM>) |
271 | ||
272 | =item "TDES" (B<OSSL_SELF_TEST_DESC_CIPHER_TDES>) | |
273 | ||
274 | Symmetric cipher tests used with the "KAT_Cipher" type. | |
275 | ||
276 | =item "SHA1" (B<OSSL_SELF_TEST_DESC_MD_SHA1>) | |
277 | ||
278 | =item "SHA2" (B<OSSL_SELF_TEST_DESC_MD_SHA2>) | |
279 | ||
280 | =item "SHA3" (B<OSSL_SELF_TEST_DESC_MD_SHA3>) | |
281 | ||
282 | Digest tests used with the "KAT_Digest" type. | |
283 | ||
284 | =item "DSA" (B<OSSL_SELF_TEST_DESC_SIGN_DSA>) | |
285 | ||
286 | =item "RSA" (B<OSSL_SELF_TEST_DESC_SIGN_RSA>) | |
287 | ||
288 | =item "ECDSA" (B<OSSL_SELF_TEST_DESC_SIGN_ECDSA>) | |
289 | ||
290 | Signature tests used with the "KAT_Signature" type. | |
291 | ||
292 | =item "ECDH" (B<OSSL_SELF_TEST_DESC_KA_ECDH>) | |
293 | ||
ec4d1b8f | 294 | =item "DH" (B<OSSL_SELF_TEST_DESC_KA_DH>) |
36fc5fc6 SL |
295 | |
296 | Key agreement tests used with the "KAT_KA" type. | |
297 | ||
298 | =item "HKDF" (B<OSSL_SELF_TEST_DESC_KDF_HKDF>) | |
299 | ||
ec4d1b8f SL |
300 | =item "SSKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSKDF>) |
301 | ||
36fc5fc6 SL |
302 | Key Derivation Function tests used with the "KAT_KDF" type. |
303 | ||
304 | =item "CTR" (B<OSSL_SELF_TEST_DESC_DRBG_CTR>) | |
305 | ||
306 | =item "HASH" (B<OSSL_SELF_TEST_DESC_DRBG_HASH>) | |
307 | ||
308 | =item "HMAC" (B<OSSL_SELF_TEST_DESC_DRBG_HMAC>) | |
309 | ||
310 | DRBG tests used with the "DRBG" type. | |
311 | ||
7f9e7440 SL |
312 | = item "RNG" (B<OSSL_SELF_TEST_DESC_RNG>) |
313 | ||
314 | "Continuous_RNG_Test" uses this. | |
315 | ||
36fc5fc6 SL |
316 | =back |
317 | ||
36fc5fc6 SL |
318 | =head1 EXAMPLES |
319 | ||
320 | A simple self test callback is shown below for illustrative purposes. | |
321 | ||
322 | #include <openssl/self_test.h> | |
323 | ||
324 | static OSSL_CALLBACK self_test_cb; | |
325 | ||
326 | static int self_test_cb(const OSSL_PARAM params[], void *arg) | |
327 | { | |
328 | int ret = 0; | |
329 | const OSSL_PARAM *p = NULL; | |
330 | const char *phase = NULL, *type = NULL, *desc = NULL; | |
331 | ||
332 | p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE); | |
333 | if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) | |
334 | goto err; | |
335 | phase = (const char *)p->data; | |
336 | ||
337 | p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC); | |
338 | if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) | |
339 | goto err; | |
340 | desc = (const char *)p->data; | |
341 | ||
342 | p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE); | |
343 | if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING) | |
344 | goto err; | |
345 | type = (const char *)p->data; | |
346 | ||
347 | /* Do some logging */ | |
348 | if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0) | |
349 | BIO_printf(bio_out, "%s : (%s) : ", desc, type); | |
350 | if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0 | |
351 | || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0) | |
352 | BIO_printf(bio_out, "%s\n", phase); | |
353 | ||
354 | /* Corrupt the SHA1 self test during the 'corrupt' phase by returning 0 */ | |
355 | if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0 | |
356 | && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) { | |
357 | BIO_printf(bio_out, "%s %s", phase, desc); | |
358 | return 0; | |
359 | } | |
360 | ret = 1; | |
361 | err: | |
362 | return ret; | |
363 | } | |
364 | ||
365 | =head1 SEE ALSO | |
366 | ||
367 | L<openssl-fipsinstall(1)>, | |
368 | L<fips_config(5)>, | |
fadb57e5 | 369 | L<OSSL_SELF_TEST_set_callback(3)>, |
47c239c6 | 370 | L<OSSL_SELF_TEST_new(3)>, |
36fc5fc6 | 371 | L<OSSL_PARAM(3)>, |
c5926e93 | 372 | L<openssl-core.h(7)>, |
23c48d94 | 373 | L<openssl-core_dispatch.h(7)>, |
c5926e93 | 374 | L<provider(7)> |
36fc5fc6 SL |
375 | |
376 | =head1 HISTORY | |
377 | ||
378 | The type and functions described here were added in OpenSSL 3.0. | |
379 | ||
380 | =head1 COPYRIGHT | |
381 | ||
47c239c6 | 382 | Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. |
36fc5fc6 SL |
383 | |
384 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
385 | this file except in compliance with the License. You can obtain a copy | |
386 | in the file LICENSE in the source distribution or at | |
387 | L<https://www.openssl.org/source/license.html>. | |
388 | ||
389 | =cut |