1cb75e7c87e3ebc7418cf743333c96f9dbb1ad67
[openssl.git] / doc / man7 / OSSL_PROVIDER-FIPS.pod
1 =pod
2
3 =head1 NAME
4
5 OSSL_PROVIDER-FIPS - OPENSSL FIPS provider
6
7 =head1 DESCRIPTION
8
9 The OPENSSL FIPS provider is a special provider that conforms to the Federal 
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
14 =head1 SELF TESTING
15
16 One of the requirements for the FIPS module is self testing. An optional callback
17 mechanism is available to return information to the user using
18 L<OSSL_SELF_TEST_set_callback(3)>.
19
20 The parameters passed to the callback are described in L<OSSL_SELF_TEST_new(3)>
21
22 The OPENSSL FIPS module uses the following mechanism to provide information
23 about the self tests as they run.
24 This is useful for debugging if a self test is failing.
25 The callback also allows forcing any self test to fail, in order to check that
26 it operates correctly on failure.
27 Note that all self tests run even if a self test failure occurs.
28
29 The FIPS module passes the following type(s) to OSSL_SELF_TEST_onbegin().
30
31 =over 4
32
33 =item "Module_Integrity" (B<OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY>)
34
35 Uses HMAC SHA256 on the module file to validate that the module has not been
36 modified. The integrity value is compared to a value written to a configuration
37 file during installation.
38
39 =item "Install_Integrity" (B<OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY>)
40
41 Uses HMAC SHA256 on a fixed string to validate that the installation process
42 has already been performed and the self test KATS have already been tested,
43 The integrity value is compared to a value written to a configuration
44 file after successfully running the self tests during installation.
45
46 =item "KAT_Cipher" (B<OSSL_SELF_TEST_TYPE_KAT_CIPHER>)
47
48 Known answer test for a symmetric cipher.
49
50 =item "KAT_Digest" (B<OSSL_SELF_TEST_TYPE_KAT_DIGEST>)
51
52 Known answer test for a digest.
53
54 =item "KAT_Signature" (B<OSSL_SELF_TEST_TYPE_KAT_SIGNATURE>)
55
56 Known answer test for a signature.
57
58 =item "KAT_KDF" (B<OSSL_SELF_TEST_TYPE_KAT_KDF>)
59
60 Known answer test for a key derivation function.
61
62 =item "KAT_KA" (B<OSSL_SELF_TEST_TYPE_KAT_KA>)
63
64 Known answer test for key agreement.
65
66 =item "DRBG" (B<OSSL_SELF_TEST_TYPE_DRBG>)
67
68 Known answer test for a Deterministic Random Bit Generator.
69
70 =item "Pairwise_Consistency_Test" (B<OSSL_SELF_TEST_TYPE_PCT>)
71
72 Conditional test that is run during the generation of key pairs.
73
74 =back
75
76 The "Module_Integrity" self test is always run at startup.
77 The "Install_Integrity" self test is used to check if the self tests have
78 already been run at installation time. If they have already run then the
79 self tests are not run on subsequent startups.
80 All other self test categories are run once at installation time, except for the
81 "Pairwise_Consistency_Test".
82
83 There is only one instance of the "Module_Integrity" and "Install_Integrity"
84 self tests. All other self tests may have multiple instances.
85
86
87 The FIPS module passes the following descriptions(s) to OSSL_SELF_TEST_onbegin().
88
89 =over 4
90
91 =item "HMAC" (B<OSSL_SELF_TEST_DESC_INTEGRITY_HMAC>)
92
93 "Module_Integrity" and "Install_Integrity" use this.
94
95 =item "RSA" (B<OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1>)
96
97 =item "ECDSA" (B<OSSL_SELF_TEST_DESC_PCT_ECDSA>)
98
99 =item "DSA" (B<OSSL_SELF_TEST_DESC_PCT_DSA>)
100
101 Key generation tests used with the "Pairwise_Consistency_Test" type.
102
103 =item "AES_GCM" (B<OSSL_SELF_TEST_DESC_CIPHER_AES_GCM>)
104
105 =item "TDES" (B<OSSL_SELF_TEST_DESC_CIPHER_TDES>)
106
107 Symmetric cipher tests used with the "KAT_Cipher" type.
108
109 =item "SHA1" (B<OSSL_SELF_TEST_DESC_MD_SHA1>)
110
111 =item "SHA2" (B<OSSL_SELF_TEST_DESC_MD_SHA2>)
112
113 =item "SHA3" (B<OSSL_SELF_TEST_DESC_MD_SHA3>)
114
115 Digest tests used with the "KAT_Digest" type.
116
117 =item "DSA" (B<OSSL_SELF_TEST_DESC_SIGN_DSA>)
118
119 =item "RSA" (B<OSSL_SELF_TEST_DESC_SIGN_RSA>)
120
121 =item "ECDSA" (B<OSSL_SELF_TEST_DESC_SIGN_ECDSA>)
122
123 Signature tests used with the "KAT_Signature" type.
124
125 =item "ECDH" (B<OSSL_SELF_TEST_DESC_KA_ECDH>)
126
127 =item "ECDSA" (B<OSSL_SELF_TEST_DESC_KA_ECDSA>)
128
129 Key agreement tests used with the "KAT_KA" type.
130
131 =item "HKDF" (B<OSSL_SELF_TEST_DESC_KDF_HKDF>)
132
133 Key Derivation Function tests used with the "KAT_KDF" type.
134
135 =item "CTR" (B<OSSL_SELF_TEST_DESC_DRBG_CTR>)
136
137 =item "HASH" (B<OSSL_SELF_TEST_DESC_DRBG_HASH>)
138
139 =item "HMAC" (B<OSSL_SELF_TEST_DESC_DRBG_HMAC>)
140
141 DRBG tests used with the "DRBG" type.
142
143 =back
144
145 =head1 EXAMPLES
146
147 A simple self test callback is shown below for illustrative purposes.
148
149   #include <openssl/self_test.h>
150
151   static OSSL_CALLBACK self_test_cb;
152
153   static int self_test_cb(const OSSL_PARAM params[], void *arg)
154   {
155     int ret = 0;
156     const OSSL_PARAM *p = NULL;
157     const char *phase = NULL, *type = NULL, *desc = NULL;
158
159     p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE);
160     if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
161         goto err;
162     phase = (const char *)p->data;
163
164     p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC);
165     if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
166         goto err;
167     desc = (const char *)p->data;
168
169     p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE);
170     if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
171         goto err;
172     type = (const char *)p->data;
173
174     /* Do some logging */
175     if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0)
176         BIO_printf(bio_out, "%s : (%s) : ", desc, type);
177     if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0
178             || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0)
179         BIO_printf(bio_out, "%s\n", phase);
180
181     /* Corrupt the SHA1 self test during the 'corrupt' phase by returning 0 */
182     if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0
183             && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) {
184         BIO_printf(bio_out, "%s %s", phase, desc);
185         return 0;
186     }
187     ret = 1;
188   err:
189     return ret;
190   }
191
192 =head1 SEE ALSO
193
194 L<openssl-fipsinstall(1)>,
195 L<fips_config(5)>,
196 L<OSSL_SELF_TEST_set_callback(3)>,
197 L<OSSL_SELF_TEST_new(3)>,
198 L<OSSL_PARAM(3)>,
199 L<openssl-core.h(7)>
200
201 =head1 HISTORY
202
203 The type and functions described here were added in OpenSSL 3.0.
204
205 =head1 COPYRIGHT
206
207 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
208
209 Licensed under the Apache License 2.0 (the "License").  You may not use
210 this file except in compliance with the License.  You can obtain a copy
211 in the file LICENSE in the source distribution or at
212 L<https://www.openssl.org/source/license.html>.
213
214 =cut