1=pod
2
3=head1 NAME
4
5OSSL_PROVIDER-FIPS - OpenSSL FIPS provider
6
7=head1 DESCRIPTION
8
9The OpenSSL FIPS provider is a special provider that conforms to the Federal
10Information Processing Standards (FIPS) specified in FIPS 140-2. This 'module'
11contains an approved set of cryptographic algorithms that is validated by an
12accredited testing laboratory.
13
14=head2 Properties
15
16The implementations in this provider specifically have these properties
17defined:
18
19=over 4
20
21=item "provider=fips"
22
23=item "fips=yes"
24
25=back
26
27It may be used in a property query string with fetching functions such as
28L<EVP_MD_fetch(3)> or L<EVP_CIPHER_fetch(3)>, as well as with other
29functions that take a property query string, such as
30L<EVP_PKEY_CTX_new_from_name(3)>.
31
32It isn't mandatory to query for any of these properties, except to
33make sure to get implementations of this provider and none other.
34
35The "fips=yes" property can be use to make sure only FIPS approved
36implementations are used for crypto operations.  This may also include
37other non-crypto support operations that are not in the FIPS provider,
38such as asymmetric key encoders,
39see L<OSSL_PROVIDER-default(7)/Asymmetric Key Management>.
40
41=head1 OPERATIONS AND ALGORITHMS
42
43The 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 (TripleDES), 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 TLS13-KDF, see L<EVP_KDF-TLS13_KDF(7)>
90
91=item SSKDF, see L<EVP_KDF-SS(7)>
92
93=item PBKDF2, see L<EVP_KDF-PBKDF2(7)>
94
95=item SSHKDF, see L<EVP_KDF-SSHKDF(7)>
96
97=item TLS1-PRF, see L<EVP_KDF-TLS1_PRF(7)>
98
99=item KBKDF, see L<EVP_KDF-KB(7)>
100
101=item X942KDF-ASN1, see L<EVP_KDF-X942-ASN1(7)>
102
103=item X942KDF-CONCAT, see L<EVP_KDF-X942-CONCAT(7)>
104
105=item X963KDF, see L<EVP_KDF-X963(7)>
106
107=back
108
109=head2 Key Exchange
110
111=over 4
112
113=item DH, see L<EVP_KEYEXCH-DH(7)>
114
115=item ECDH, see L<EVP_KEYEXCH-ECDH(7)>
116
117=item X25519, see L<EVP_KEYEXCH-X25519(7)>
118
119=item X448, see L<EVP_KEYEXCH-X448(7)>
120
121=back
122
123=head2 Asymmetric Signature
124
125=over 4
126
127=item RSA, see L<EVP_SIGNATURE-RSA(7)>
128
129=item X25519, see L<EVP_SIGNATURE-ED25519(7)>
130
131=item X448, see L<EVP_SIGNATURE-ED448(7)>
132
133=item HMAC, see L<EVP_SIGNATURE-HMAC(7)>
134
135=item CMAC, see L<EVP_SIGNATURE-CMAC(7)>
136
137=back
138
139=head2 Asymmetric Cipher
140
141=over 4
142
143=item RSA, see L<EVP_ASYM_CIPHER-RSA(7)>
144
145=back
146
147=head2 Asymmetric Key Encapsulation
148
149=over 4
150
151=item RSA, see L<EVP_KEM-RSA(7)>
152
153=back
154
155=head2 Asymmetric Key Management
156
157=over 4
158
159=item DH, see L<EVP_KEYMGMT-DH(7)>
160
161=item DHX, see L<EVP_KEYMGMT-DHX(7)>
162
163=item DSA, see L<EVP_KEYMGMT-DSA(7)>
164
165=item RSA, see L<EVP_KEYMGMT-RSA(7)>
166
167=item EC, see L<EVP_KEYMGMT-EC(7)>
168
169=item X25519, see L<EVP_KEYMGMT-X25519(7)>
170
171=item X448, see L<EVP_KEYMGMT-X448(7)>
172
173=back
174
175=head2 Random Number Generation
176
177=over 4
178
179=item CTR-DRBG, see L<EVP_RAND-CTR-DRBG(7)>
180
181=item HASH-DRBG, see L<EVP_RAND-HASH-DRBG(7)>
182
183=item HMAC-DRBG, see L<EVP_RAND-HMAC-DRBG(7)>
184
185=item TEST-RAND, see L<EVP_RAND-TEST-RAND(7)>
186
187TEST-RAND is an unapproved algorithm.
188
189=back
190
191=head1 SELF TESTING
192
193One of the requirements for the FIPS module is self testing. An optional callback
194mechanism is available to return information to the user using
195L<OSSL_SELF_TEST_set_callback(3)>.
196
197The parameters passed to the callback are described in L<OSSL_SELF_TEST_new(3)>
198
199The OpenSSL FIPS module uses the following mechanism to provide information
200about the self tests as they run.
201This is useful for debugging if a self test is failing.
202The callback also allows forcing any self test to fail, in order to check that
203it operates correctly on failure.
204Note that all self tests run even if a self test failure occurs.
205
206The FIPS module passes the following type(s) to OSSL_SELF_TEST_onbegin().
207
208=over 4
209
210=item "Module_Integrity" (B<OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY>)
211
212Uses HMAC SHA256 on the module file to validate that the module has not been
213modified. The integrity value is compared to a value written to a configuration
214file during installation.
215
216=item "Install_Integrity" (B<OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY>)
217
218Uses HMAC SHA256 on a fixed string to validate that the installation process
219has already been performed and the self test KATS have already been tested,
220The integrity value is compared to a value written to a configuration
221file after successfully running the self tests during installation.
222
223=item "KAT_Cipher" (B<OSSL_SELF_TEST_TYPE_KAT_CIPHER>)
224
225Known answer test for a symmetric cipher.
226
227=item "KAT_AsymmetricCipher" (B<OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER>)
228
229Known answer test for a asymmetric cipher.
230
231=item "KAT_Digest" (B<OSSL_SELF_TEST_TYPE_KAT_DIGEST>)
232
233Known answer test for a digest.
234
235=item "KAT_Signature" (B<OSSL_SELF_TEST_TYPE_KAT_SIGNATURE>)
236
237Known answer test for a signature.
238
239=item "PCT_Signature" (B<OSSL_SELF_TEST_TYPE_PCT_SIGNATURE>)
240
241Pairwise Consistency check for a signature.
242
243=item "KAT_KDF" (B<OSSL_SELF_TEST_TYPE_KAT_KDF>)
244
245Known answer test for a key derivation function.
246
247=item "KAT_KA" (B<OSSL_SELF_TEST_TYPE_KAT_KA>)
248
249Known answer test for key agreement.
250
251=item "DRBG" (B<OSSL_SELF_TEST_TYPE_DRBG>)
252
253Known answer test for a Deterministic Random Bit Generator.
254
255=item "Conditional_PCT" (B<OSSL_SELF_TEST_TYPE_PCT>)
256
257Conditional test that is run during the generation of key pairs.
258
259=item "Continuous_RNG_Test" (B<OSSL_SELF_TEST_TYPE_CRNG>)
260
261Continuous random number generator test.
262
263=back
264
265The "Module_Integrity" self test is always run at startup.
266The "Install_Integrity" self test is used to check if the self tests have
267already been run at installation time. If they have already run then the
268self tests are not run on subsequent startups.
269All other self test categories are run once at installation time, except for the
270"Pairwise_Consistency_Test".
271
272There is only one instance of the "Module_Integrity" and "Install_Integrity"
273self tests. All other self tests may have multiple instances.
274
275
276The FIPS module passes the following descriptions(s) to OSSL_SELF_TEST_onbegin().
277
278=over 4
279
280=item "HMAC" (B<OSSL_SELF_TEST_DESC_INTEGRITY_HMAC>)
281
282"Module_Integrity" and "Install_Integrity" use this.
283
284=item "RSA" (B<OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1>)
285
286=item "ECDSA" (B<OSSL_SELF_TEST_DESC_PCT_ECDSA>)
287
288=item "DSA" (B<OSSL_SELF_TEST_DESC_PCT_DSA>)
289
290Key generation tests used with the "Pairwise_Consistency_Test" type.
291
292=item "RSA_Encrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_ENC>)
293
294=item "RSA_Decrypt" (B<OSSL_SELF_TEST_DESC_ASYM_RSA_DEC>)
295
296"KAT_AsymmetricCipher" uses this to indicate an encrypt or decrypt KAT.
297
298=item "AES_GCM" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_GCM>)
299
300=item "AES_ECB_Decrypt" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_ECB>)
301
302=item "TDES" (B<OSSL_SELF_TEST_DESC_CIPHER_TDES>)
303
304Symmetric cipher tests used with the "KAT_Cipher" type.
305
306=item "SHA1" (B<OSSL_SELF_TEST_DESC_MD_SHA1>)
307
308=item "SHA2" (B<OSSL_SELF_TEST_DESC_MD_SHA2>)
309
310=item "SHA3" (B<OSSL_SELF_TEST_DESC_MD_SHA3>)
311
312Digest tests used with the "KAT_Digest" type.
313
314=item "DSA" (B<OSSL_SELF_TEST_DESC_SIGN_DSA>)
315
316=item "RSA" (B<OSSL_SELF_TEST_DESC_SIGN_RSA>)
317
318=item "ECDSA" (B<OSSL_SELF_TEST_DESC_SIGN_ECDSA>)
319
320Signature tests used with the "KAT_Signature" type.
321
322=item "ECDH" (B<OSSL_SELF_TEST_DESC_KA_ECDH>)
323
324=item "DH" (B<OSSL_SELF_TEST_DESC_KA_DH>)
325
326Key agreement tests used with the "KAT_KA" type.
327
328=item "HKDF" (B<OSSL_SELF_TEST_DESC_KDF_HKDF>)
329
330=item "TLS13_KDF_EXTRACT" (B<OSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT>)
331
332=item "TLS13_KDF_EXPAND" (B<OSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND>)
333
334=item "SSKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSKDF>)
335
336=item "X963KDF" (B<OSSL_SELF_TEST_DESC_KDF_X963KDF>)
337
338=item "X942KDF" (B<OSSL_SELF_TEST_DESC_KDF_X942KDF>)
339
340=item "PBKDF2" (B<OSSL_SELF_TEST_DESC_KDF_PBKDF2>)
341
342=item "SSHKDF" (B<OSSL_SELF_TEST_DESC_KDF_SSHKDF>)
343
344=item "TLS12_PRF" (B<OSSL_SELF_TEST_DESC_KDF_TLS12_PRF>)
345
346=item "KBKDF" (B<OSSL_SELF_TEST_DESC_KDF_KBKDF>)
347
348Key Derivation Function tests used with the "KAT_KDF" type.
349
350=item "CTR" (B<OSSL_SELF_TEST_DESC_DRBG_CTR>)
351
352=item "HASH" (B<OSSL_SELF_TEST_DESC_DRBG_HASH>)
353
354=item "HMAC" (B<OSSL_SELF_TEST_DESC_DRBG_HMAC>)
355
356DRBG tests used with the "DRBG" type.
357
358= item "RNG" (B<OSSL_SELF_TEST_DESC_RNG>)
359
360"Continuous_RNG_Test" uses this.
361
362=back
363
364=head1 EXAMPLES
365
366A simple self test callback is shown below for illustrative purposes.
367
368  #include <openssl/self_test.h>
369
370  static OSSL_CALLBACK self_test_cb;
371
372  static int self_test_cb(const OSSL_PARAM params[], void *arg)
373  {
374    int ret = 0;
375    const OSSL_PARAM *p = NULL;
376    const char *phase = NULL, *type = NULL, *desc = NULL;
377
378    p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE);
379    if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
380        goto err;
381    phase = (const char *)p->data;
382
383    p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC);
384    if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
385        goto err;
386    desc = (const char *)p->data;
387
388    p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE);
389    if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
390        goto err;
391    type = (const char *)p->data;
392
393    /* Do some logging */
394    if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0)
395        BIO_printf(bio_out, "%s : (%s) : ", desc, type);
396    if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0
397            || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0)
398        BIO_printf(bio_out, "%s\n", phase);
399
400    /* Corrupt the SHA1 self test during the 'corrupt' phase by returning 0 */
401    if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0
402            && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) {
403        BIO_printf(bio_out, "%s %s", phase, desc);
404        return 0;
405    }
406    ret = 1;
407  err:
408    return ret;
409  }
410
411=head1 NOTES
412
413Some released versions of OpenSSL do not include a validated
414FIPS provider.  To determine which versions have undergone
415the validation process, please refer to the
416L<OpenSSL Downloads page|https://www.openssl.org/source/>.  If you
417require FIPS-approved functionality, it is essential to build your FIPS
418provider using one of the validated versions listed there.  Normally,
419it is possible to utilize a FIPS provider constructed from one of the
420validated versions alongside F<libcrypto> and F<libssl> compiled from any
421release within the same major release series.  This flexibility enables
422you to address bug fixes and CVEs that fall outside the FIPS boundary.
423
424=head1 SEE ALSO
425
426L<openssl-fipsinstall(1)>,
427L<fips_config(5)>,
428L<OSSL_SELF_TEST_set_callback(3)>,
429L<OSSL_SELF_TEST_new(3)>,
430L<OSSL_PARAM(3)>,
431L<openssl-core.h(7)>,
432L<openssl-core_dispatch.h(7)>,
433L<provider(7)>,
434L<https://www.openssl.org/source/>
435
436=head1 HISTORY
437
438This functionality was added in OpenSSL 3.0.
439
440=head1 COPYRIGHT
441
442Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
443
444Licensed under the Apache License 2.0 (the "License").  You may not use
445this file except in compliance with the License.  You can obtain a copy
446in the file LICENSE in the source distribution or at
447L<https://www.openssl.org/source/license.html>.
448
449=cut
450