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