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-SS(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-KB(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 RSA, see EVP_SIGNATURE-RSA(7)
74 X25519, see EVP_SIGNATURE-ED25519(7)
75 X448, see EVP_SIGNATURE-ED448(7)
76 HMAC, see EVP_SIGNATURE-HMAC(7)
77 CMAC, see EVP_SIGNATURE-CMAC(7)
78 Asymmetric Cipher
80 RSA, see EVP_ASYM_CIPHER-RSA(7)
81 Asymmetric Key Encapsulation
83 RSA, see EVP_KEM-RSA(7)
84 Asymmetric Key Management
86 DH, see EVP_KEYMGMT-DH(7)
87 DHX, see EVP_KEYMGMT-DHX(7)
88 DSA, see EVP_KEYMGMT-DSA(7)
89 RSA, see EVP_KEYMGMT-RSA(7)
90 EC, see EVP_KEYMGMT-EC(7)
91 X25519, see EVP_KEYMGMT-X25519(7)
92 X448, see EVP_KEYMGMT-X448(7)
93 Random Number Generation
95 CTR-DRBG, see EVP_RAND-CTR-DRBG(7)
96 HASH-DRBG, see EVP_RAND-HASH-DRBG(7)
97 HMAC-DRBG, see EVP_RAND-HMAC-DRBG(7)
98 TEST-RAND, see EVP_RAND-TEST-RAND(7)
99 TEST-RAND is an unapproved algorithm.
100
102 One of the requirements for the FIPS module is self testing. An
103 optional callback mechanism is available to return information to the
104 user using OSSL_SELF_TEST_set_callback(3).
105 The parameters passed to the callback are described in
107 OSSL_SELF_TEST_new(3)
108 The OpenSSL FIPS module uses the following mechanism to provide
110 information about the self tests as they run. This is useful for
111 debugging if a self test is failing. The callback also allows forcing
112 any self test to fail, in order to check that it operates correctly on
113 failure. Note that all self tests run even if a self test failure
114 occurs.
115 The FIPS module passes the following type(s) to
117 OSSL_SELF_TEST_onbegin().
118 "Module_Integrity" (OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY)
120 Uses HMAC SHA256 on the module file to validate that the module has
121 not been modified. The integrity value is compared to a value
122 written to a configuration file during installation.
123 "Install_Integrity" (OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY)
125 Uses HMAC SHA256 on a fixed string to validate that the
126 installation process has already been performed and the self test
127 KATS have already been tested, The integrity value is compared to a
128 value written to a configuration file after successfully running
129 the self tests during installation.
130 "KAT_Cipher" (OSSL_SELF_TEST_TYPE_KAT_CIPHER)
132 Known answer test for a symmetric cipher.
133 "KAT_AsymmetricCipher" (OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER)
135 Known answer test for a asymmetric cipher.
136 "KAT_Digest" (OSSL_SELF_TEST_TYPE_KAT_DIGEST)
138 Known answer test for a digest.
139 "KAT_Signature" (OSSL_SELF_TEST_TYPE_KAT_SIGNATURE)
141 Known answer test for a signature.
142 "PCT_Signature" (OSSL_SELF_TEST_TYPE_PCT_SIGNATURE)
144 Pairwise Consistency check for a signature.
145 "KAT_KDF" (OSSL_SELF_TEST_TYPE_KAT_KDF)
147 Known answer test for a key derivation function.
148 "KAT_KA" (OSSL_SELF_TEST_TYPE_KAT_KA)
150 Known answer test for key agreement.
151 "DRBG" (OSSL_SELF_TEST_TYPE_DRBG)
153 Known answer test for a Deterministic Random Bit Generator.
154 "Conditional_PCT" (OSSL_SELF_TEST_TYPE_PCT)
156 Conditional test that is run during the generation of key pairs.
157 "Continuous_RNG_Test" (OSSL_SELF_TEST_TYPE_CRNG)
159 Continuous random number generator test.
160 The "Module_Integrity" self test is always run at startup. The
162 "Install_Integrity" self test is used to check if the self tests have
163 already been run at installation time. If they have already run then
164 the self tests are not run on subsequent startups. All other self test
165 categories are run once at installation time, except for the
166 "Pairwise_Consistency_Test".
167 There is only one instance of the "Module_Integrity" and
169 "Install_Integrity" self tests. All other self tests may have multiple
170 instances.
171 The FIPS module passes the following descriptions(s) to
173 OSSL_SELF_TEST_onbegin().
174 "HMAC" (OSSL_SELF_TEST_DESC_INTEGRITY_HMAC)
176 "Module_Integrity" and "Install_Integrity" use this.
177 "RSA" (OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1)
179 "ECDSA" (OSSL_SELF_TEST_DESC_PCT_ECDSA)
180 "DSA" (OSSL_SELF_TEST_DESC_PCT_DSA)
181 Key generation tests used with the "Pairwise_Consistency_Test"
182 type.
183 "RSA_Encrypt" (OSSL_SELF_TEST_DESC_ASYM_RSA_ENC)
185 "RSA_Decrypt" (OSSL_SELF_TEST_DESC_ASYM_RSA_DEC)
186 "KAT_AsymmetricCipher" uses this to indicate an encrypt or decrypt
187 KAT.
188 "AES_GCM" (OSSL_SELF_TEST_DESC_CIPHER_AES_GCM)
190 "AES_ECB_Decrypt" (OSSL_SELF_TEST_DESC_CIPHER_AES_ECB)
191 "TDES" (OSSL_SELF_TEST_DESC_CIPHER_TDES)
192 Symmetric cipher tests used with the "KAT_Cipher" type.
193 "SHA1" (OSSL_SELF_TEST_DESC_MD_SHA1)
195 "SHA2" (OSSL_SELF_TEST_DESC_MD_SHA2)
196 "SHA3" (OSSL_SELF_TEST_DESC_MD_SHA3)
197 Digest tests used with the "KAT_Digest" type.
198 "DSA" (OSSL_SELF_TEST_DESC_SIGN_DSA)
200 "RSA" (OSSL_SELF_TEST_DESC_SIGN_RSA)
201 "ECDSA" (OSSL_SELF_TEST_DESC_SIGN_ECDSA)
202 Signature tests used with the "KAT_Signature" type.
203 "ECDH" (OSSL_SELF_TEST_DESC_KA_ECDH)
205 "DH" (OSSL_SELF_TEST_DESC_KA_DH)
206 Key agreement tests used with the "KAT_KA" type.
207 "HKDF" (OSSL_SELF_TEST_DESC_KDF_HKDF)
209 "TLS13_KDF_EXTRACT" (OSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT)
210 "TLS13_KDF_EXPAND" (OSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND)
211 "SSKDF" (OSSL_SELF_TEST_DESC_KDF_SSKDF)
212 "X963KDF" (OSSL_SELF_TEST_DESC_KDF_X963KDF)
213 "X942KDF" (OSSL_SELF_TEST_DESC_KDF_X942KDF)
214 "PBKDF2" (OSSL_SELF_TEST_DESC_KDF_PBKDF2)
215 "SSHKDF" (OSSL_SELF_TEST_DESC_KDF_SSHKDF)
216 "TLS12_PRF" (OSSL_SELF_TEST_DESC_KDF_TLS12_PRF)
217 "KBKDF" (OSSL_SELF_TEST_DESC_KDF_KBKDF)
218 Key Derivation Function tests used with the "KAT_KDF" type.
219 "CTR" (OSSL_SELF_TEST_DESC_DRBG_CTR)
221 "HASH" (OSSL_SELF_TEST_DESC_DRBG_HASH)
222 "HMAC" (OSSL_SELF_TEST_DESC_DRBG_HMAC)
223 DRBG tests used with the "DRBG" type.
224 = item "RNG" (OSSL_SELF_TEST_DESC_RNG)
226 "Continuous_RNG_Test" uses this.
228
230 A simple self test callback is shown below for illustrative purposes.
231 #include <openssl/self_test.h>
233 static OSSL_CALLBACK self_test_cb;
235 static int self_test_cb(const OSSL_PARAM params[], void *arg)
237 {
238 int ret = 0;
239 const OSSL_PARAM *p = NULL;
240 const char *phase = NULL, *type = NULL, *desc = NULL;
241 p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE);
243 if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
244 goto err;
245 phase = (const char *)p->data;
246 p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC);
248 if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
249 goto err;
250 desc = (const char *)p->data;
251 p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE);
253 if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
254 goto err;
255 type = (const char *)p->data;
256 /* Do some logging */
258 if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0)
259 BIO_printf(bio_out, "%s : (%s) : ", desc, type);
260 if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0
261 || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0)
262 BIO_printf(bio_out, "%s\n", phase);
263 /* Corrupt the SHA1 self test during the 'corrupt' phase by returning 0 */
265 if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0
266 && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) {
267 BIO_printf(bio_out, "%s %s", phase, desc);
268 return 0;
269 }
270 ret = 1;
271 err:
272 return ret;
273 }
274
276 fips_config(5), OSSL_SELF_TEST_set_callback(3), OSSL_SELF_TEST_new(3),
277 OSSL_PARAM(3), openssl-core.h(7), openssl-core_dispatch.h(7),
278 provider(7)
279
281 This functionality was added in OpenSSL 3.0.
282
284 Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
285 Licensed under the Apache License 2.0 (the "License"). You may not use
287 this file except in compliance with the License. You can obtain a copy
288 in the file LICENSE in the source distribution or at
289 <https://www.openssl.org/source/license.html>.
2903.0.9 2023-07-27 OSSL_PROVIDER-FIPS(7ossl)