1OSSL_PROVIDER-FIPS(7ossl) OpenSSL OSSL_PROVIDER-FIPS(7ossl)
2
6 OSSL_PROVIDER-FIPS - OpenSSL FIPS provider
7
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 Properties
15 The implementations in this provider specifically have these properties
16 defined:
17 "provider=fips"
19 "fips=yes"
20 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 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 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
36 The OpenSSL FIPS provider supports these operations and algorithms:
37 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 Symmetric Ciphers
45 AES, see EVP_CIPHER-AES(7)
46 DES-EDE3 (TripleDES), see EVP_CIPHER-DES(7)
47 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 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 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 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 Asymmetric Cipher
81 RSA, see EVP_KEYEXCH-RSA(7)
82 Asymmetric Key Encapsulation
84 RSA, see EVP_KEM-RSA(7)
85 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
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 The parameters passed to the callback are described in
101 OSSL_SELF_TEST_new(3)
102 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 The FIPS module passes the following type(s) to
111 OSSL_SELF_TEST_onbegin().
112 "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 "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 "KAT_Cipher" (OSSL_SELF_TEST_TYPE_KAT_CIPHER)
126 Known answer test for a symmetric cipher.
127 "KAT_AsymmetricCipher" (OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER)
129 Known answer test for a asymmetric cipher.
130 "KAT_Digest" (OSSL_SELF_TEST_TYPE_KAT_DIGEST)
132 Known answer test for a digest.
133 "KAT_Signature" (OSSL_SELF_TEST_TYPE_KAT_SIGNATURE)
135 Known answer test for a signature.
136 "PCT_Signature" (OSSL_SELF_TEST_TYPE_PCT_SIGNATURE)
138 Pairwise Consistency check for a signature.
139 "KAT_KDF" (OSSL_SELF_TEST_TYPE_KAT_KDF)
141 Known answer test for a key derivation function.
142 "KAT_KA" (OSSL_SELF_TEST_TYPE_KAT_KA)
144 Known answer test for key agreement.
145 "DRBG" (OSSL_SELF_TEST_TYPE_DRBG)
147 Known answer test for a Deterministic Random Bit Generator.
148 "Conditional_PCT" (OSSL_SELF_TEST_TYPE_PCT)
150 Conditional test that is run during the generation of key pairs.
151 "Continuous_RNG_Test" (OSSL_SELF_TEST_TYPE_CRNG)
153 Continuous random number generator test.
154 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 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 The FIPS module passes the following descriptions(s) to
167 OSSL_SELF_TEST_onbegin().
168 "HMAC" (OSSL_SELF_TEST_DESC_INTEGRITY_HMAC)
170 "Module_Integrity" and "Install_Integrity" use this.
171 "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 "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 "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 "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 "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 "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 "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 "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 = item "RNG" (OSSL_SELF_TEST_DESC_RNG)
220 "Continuous_RNG_Test" uses this.
222
224 A simple self test callback is shown below for illustrative purposes.
225 #include <openssl/self_test.h>
227 static OSSL_CALLBACK self_test_cb;
229 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 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 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 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 /* 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 /* 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
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
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 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>.
2843.0.5 2022-07-05 OSSL_PROVIDER-FIPS(7ossl)