1OSSL_PROVIDER-FIPS(7ossl)           OpenSSL          OSSL_PROVIDER-FIPS(7ossl)
2
3
4

NAME

6       OSSL_PROVIDER-FIPS - OpenSSL FIPS provider
7

DESCRIPTION

9       The OpenSSL FIPS provider is a special provider that conforms to the
10       Federal Information Processing Standards (FIPS) specified in FIPS
11       140-2. This 'module' contains an approved set of cryptographic
12       algorithms that is validated by an accredited testing laboratory.
13
14   Properties
15       The implementations in this provider specifically have these properties
16       defined:
17
18       "provider=fips"
19       "fips=yes"
20
21       It may be used in a property query string with fetching functions such
22       as EVP_MD_fetch(3) or EVP_CIPHER_fetch(3), as well as with other
23       functions that take a property query string, such as
24       EVP_PKEY_CTX_new_from_name(3).
25
26       It isn't mandatory to query for any of these properties, except to make
27       sure to get implementations of this provider and none other.
28
29       The "fips=yes" property can be use to make sure only FIPS approved
30       implementations are used for crypto operations.  This may also include
31       other non-crypto support operations that are not in the FIPS provider,
32       such as asymmetric key encoders, see "Asymmetric Key Management" in
33       OSSL_PROVIDER-default(7).
34

OPERATIONS AND ALGORITHMS

36       The OpenSSL FIPS provider supports these operations and algorithms:
37
38   Hashing Algorithms / Message Digests
39       SHA1, see EVP_MD-SHA1(7)
40       SHA2, see EVP_MD-SHA2(7)
41       SHA3, see EVP_MD-SHA3(7)
42       KECCAK-KMAC, see EVP_MD-KECCAK-KMAC(7)
43
44   Symmetric Ciphers
45       AES, see EVP_CIPHER-AES(7)
46       DES-EDE3 (TripleDES), see EVP_CIPHER-DES(7)
47
48   Message Authentication Code (MAC)
49       CMAC, see EVP_MAC-CMAC(7)
50       GMAC, see EVP_MAC-GMAC(7)
51       HMAC, see EVP_MAC-HMAC(7)
52       KMAC, see EVP_MAC-KMAC(7)
53
54   Key Derivation Function (KDF)
55       HKDF, see EVP_KDF-HKDF(7)
56       TLS13-KDF, see EVP_KDF-TLS13_KDF(7)
57       SSKDF, see EVP_KDF-SSKDF(7)
58       PBKDF2, see EVP_KDF-PBKDF2(7)
59       SSHKDF, see EVP_KDF-SSHKDF(7)
60       TLS1-PRF, see EVP_KDF-TLS1_PRF(7)
61       KBKDF, see EVP_KDF-KBKDF(7)
62       X942KDF-ASN1, see EVP_KDF-X942-ASN1(7)
63       X942KDF-CONCAT, see EVP_KDF-X942-CONCAT(7)
64       X963KDF, see EVP_KDF-X963(7)
65
66   Key Exchange
67       DH, see EVP_KEYEXCH-DH(7)
68       ECDH, see EVP_KEYEXCH-ECDH(7)
69       X25519, see EVP_KEYEXCH-X25519(7)
70       X448, see EVP_KEYEXCH-X448(7)
71
72   Asymmetric Signature
73       DSA, see EVP_KEYEXCH-DSA(7)
74       RSA, see EVP_SIGNATURE-RSA(7)
75       X25519, see EVP_SIGNATURE-ED25519(7)
76       X448, see EVP_SIGNATURE-ED448(7)
77       HMAC, see EVP_SIGNATURE-HMAC(7)
78       CMAC, see EVP_SIGNATURE-CMAC(7)
79
80   Asymmetric Cipher
81       RSA, see EVP_KEYEXCH-RSA(7)
82
83   Asymmetric Key Encapsulation
84       RSA, see EVP_KEM-RSA(7)
85
86   Asymmetric Key Management
87       DH, see EVP_KEYMGMT-DH(7)
88       DHX, see EVP_KEYMGMT-DHX(7)
89       DSA, see EVP_KEYMGMT-DSA(7)
90       RSA, see EVP_KEYMGMT-RSA(7)
91       EC, see EVP_KEYMGMT-EC(7)
92       X25519, see EVP_KEYMGMT-X25519(7)
93       X448, see EVP_KEYMGMT-X448(7)
94

SELF TESTING

96       One of the requirements for the FIPS module is self testing. An
97       optional callback mechanism is available to return information to the
98       user using OSSL_SELF_TEST_set_callback(3).
99
100       The parameters passed to the callback are described in
101       OSSL_SELF_TEST_new(3)
102
103       The OpenSSL FIPS module uses the following mechanism to provide
104       information about the self tests as they run.  This is useful for
105       debugging if a self test is failing.  The callback also allows forcing
106       any self test to fail, in order to check that it operates correctly on
107       failure.  Note that all self tests run even if a self test failure
108       occurs.
109
110       The FIPS module passes the following type(s) to
111       OSSL_SELF_TEST_onbegin().
112
113       "Module_Integrity" (OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY)
114           Uses HMAC SHA256 on the module file to validate that the module has
115           not been modified. The integrity value is compared to a value
116           written to a configuration file during installation.
117
118       "Install_Integrity" (OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY)
119           Uses HMAC SHA256 on a fixed string to validate that the
120           installation process has already been performed and the self test
121           KATS have already been tested, The integrity value is compared to a
122           value written to a configuration file after successfully running
123           the self tests during installation.
124
125       "KAT_Cipher" (OSSL_SELF_TEST_TYPE_KAT_CIPHER)
126           Known answer test for a symmetric cipher.
127
128       "KAT_AsymmetricCipher" (OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER)
129           Known answer test for a asymmetric cipher.
130
131       "KAT_Digest" (OSSL_SELF_TEST_TYPE_KAT_DIGEST)
132           Known answer test for a digest.
133
134       "KAT_Signature" (OSSL_SELF_TEST_TYPE_KAT_SIGNATURE)
135           Known answer test for a signature.
136
137       "PCT_Signature" (OSSL_SELF_TEST_TYPE_PCT_SIGNATURE)
138           Pairwise Consistency check for a signature.
139
140       "KAT_KDF" (OSSL_SELF_TEST_TYPE_KAT_KDF)
141           Known answer test for a key derivation function.
142
143       "KAT_KA" (OSSL_SELF_TEST_TYPE_KAT_KA)
144           Known answer test for key agreement.
145
146       "DRBG" (OSSL_SELF_TEST_TYPE_DRBG)
147           Known answer test for a Deterministic Random Bit Generator.
148
149       "Conditional_PCT" (OSSL_SELF_TEST_TYPE_PCT)
150           Conditional test that is run during the generation of key pairs.
151
152       "Continuous_RNG_Test" (OSSL_SELF_TEST_TYPE_CRNG)
153           Continuous random number generator test.
154
155       The "Module_Integrity" self test is always run at startup.  The
156       "Install_Integrity" self test is used to check if the self tests have
157       already been run at installation time. If they have already run then
158       the self tests are not run on subsequent startups.  All other self test
159       categories are run once at installation time, except for the
160       "Pairwise_Consistency_Test".
161
162       There is only one instance of the "Module_Integrity" and
163       "Install_Integrity" self tests. All other self tests may have multiple
164       instances.
165
166       The FIPS module passes the following descriptions(s) to
167       OSSL_SELF_TEST_onbegin().
168
169       "HMAC" (OSSL_SELF_TEST_DESC_INTEGRITY_HMAC)
170           "Module_Integrity" and "Install_Integrity" use this.
171
172       "RSA" (OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1)
173       "ECDSA" (OSSL_SELF_TEST_DESC_PCT_ECDSA)
174       "DSA" (OSSL_SELF_TEST_DESC_PCT_DSA)
175           Key generation tests used with the "Pairwise_Consistency_Test"
176           type.
177
178       "RSA_Encrypt" (OSSL_SELF_TEST_DESC_ASYM_RSA_ENC)
179       "RSA_Decrypt" (OSSL_SELF_TEST_DESC_ASYM_RSA_DEC)
180           "KAT_AsymmetricCipher" uses this to indicate an encrypt or decrypt
181           KAT.
182
183       "AES_GCM" (OSSL_SELF_TEST_DESC_CIPHER_AES_GCM)
184       "AES_ECB_Decrypt" (OSSL_SELF_TEST_DESC_CIPHER_AES_ECB)
185       "TDES" (OSSL_SELF_TEST_DESC_CIPHER_TDES)
186           Symmetric cipher tests used with the "KAT_Cipher" type.
187
188       "SHA1" (OSSL_SELF_TEST_DESC_MD_SHA1)
189       "SHA2" (OSSL_SELF_TEST_DESC_MD_SHA2)
190       "SHA3" (OSSL_SELF_TEST_DESC_MD_SHA3)
191           Digest tests used with the "KAT_Digest" type.
192
193       "DSA" (OSSL_SELF_TEST_DESC_SIGN_DSA)
194       "RSA" (OSSL_SELF_TEST_DESC_SIGN_RSA)
195       "ECDSA" (OSSL_SELF_TEST_DESC_SIGN_ECDSA)
196           Signature tests used with the "KAT_Signature" type.
197
198       "ECDH" (OSSL_SELF_TEST_DESC_KA_ECDH)
199       "DH" (OSSL_SELF_TEST_DESC_KA_DH)
200           Key agreement tests used with the "KAT_KA" type.
201
202       "HKDF" (OSSL_SELF_TEST_DESC_KDF_HKDF)
203       "TLS13_KDF_EXTRACT" (OSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT)
204       "TLS13_KDF_EXPAND" (OSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND)
205       "SSKDF" (OSSL_SELF_TEST_DESC_KDF_SSKDF)
206       "X963KDF" (OSSL_SELF_TEST_DESC_KDF_X963KDF)
207       "X942KDF" (OSSL_SELF_TEST_DESC_KDF_X942KDF)
208       "PBKDF2" (OSSL_SELF_TEST_DESC_KDF_PBKDF2)
209       "SSHKDF" (OSSL_SELF_TEST_DESC_KDF_SSHKDF)
210       "TLS12_PRF" (OSSL_SELF_TEST_DESC_KDF_TLS12_PRF)
211       "KBKDF" (OSSL_SELF_TEST_DESC_KDF_KBKDF)
212           Key Derivation Function tests used with the "KAT_KDF" type.
213
214       "CTR" (OSSL_SELF_TEST_DESC_DRBG_CTR)
215       "HASH" (OSSL_SELF_TEST_DESC_DRBG_HASH)
216       "HMAC" (OSSL_SELF_TEST_DESC_DRBG_HMAC)
217           DRBG tests used with the "DRBG" type.
218
219           = item "RNG" (OSSL_SELF_TEST_DESC_RNG)
220
221           "Continuous_RNG_Test" uses this.
222

EXAMPLES

224       A simple self test callback is shown below for illustrative purposes.
225
226         #include <openssl/self_test.h>
227
228         static OSSL_CALLBACK self_test_cb;
229
230         static int self_test_cb(const OSSL_PARAM params[], void *arg)
231         {
232           int ret = 0;
233           const OSSL_PARAM *p = NULL;
234           const char *phase = NULL, *type = NULL, *desc = NULL;
235
236           p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE);
237           if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
238               goto err;
239           phase = (const char *)p->data;
240
241           p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC);
242           if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
243               goto err;
244           desc = (const char *)p->data;
245
246           p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE);
247           if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
248               goto err;
249           type = (const char *)p->data;
250
251           /* Do some logging */
252           if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0)
253               BIO_printf(bio_out, "%s : (%s) : ", desc, type);
254           if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0
255                   || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0)
256               BIO_printf(bio_out, "%s\n", phase);
257
258           /* Corrupt the SHA1 self test during the 'corrupt' phase by returning 0 */
259           if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0
260                   && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) {
261               BIO_printf(bio_out, "%s %s", phase, desc);
262               return 0;
263           }
264           ret = 1;
265         err:
266           return ret;
267         }
268

SEE ALSO

270       openssl-fipsinstall(1), fips_config(5), OSSL_SELF_TEST_set_callback(3),
271       OSSL_SELF_TEST_new(3), OSSL_PARAM(3), openssl-core.h(7),
272       openssl-core_dispatch.h(7), provider(7)
273

HISTORY

275       The type and functions described here were added in OpenSSL 3.0.
276
278       Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
279
280       Licensed under the Apache License 2.0 (the "License").  You may not use
281       this file except in compliance with the License.  You can obtain a copy
282       in the file LICENSE in the source distribution or at
283       <https://www.openssl.org/source/license.html>.
284
285
286
2873.0.5                             2022-07-05         OSSL_PROVIDER-FIPS(7ossl)
Impressum