]>
Commit | Line | Data |
---|---|---|
e4c0ec62 RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | provider - OpenSSL operation implementation providers | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
bb82531f | 9 | =for openssl generic |
e4c0ec62 RL |
10 | |
11 | #include <openssl/provider.h> | |
12 | ||
13 | =head1 DESCRIPTION | |
14 | ||
15 | =head2 General | |
16 | ||
17 | A I<provider>, in OpenSSL terms, is a unit of code that provides one | |
18 | or more implementations for various operations for diverse algorithms | |
19 | that one might want to perform. | |
20 | ||
21 | An I<operation> is something one wants to do, such as encryption and | |
22 | decryption, key derivation, MAC calculation, signing and verification, | |
23 | etc. | |
24 | ||
25 | An I<algorithm> is a named method to perform an operation. | |
26 | Very often, the algorithms revolve around cryptographic operations, | |
27 | but may also revolve around other types of operation, such as managing | |
28 | certain types of objects. | |
29 | ||
30 | =head2 Provider | |
31 | ||
32 | I<NOTE: This section is mostly interesting for provider authors.> | |
33 | ||
34 | A I<provider> offers an initialization function, as a set of base | |
35 | functions in the form of an B<OSSL_DISPATCH> array, and by extension, | |
36 | a set of B<OSSL_ALGORITHM>s (see L<openssl-core.h(7)>). | |
37 | It may be a dynamically loadable module, or may be built-in, in | |
38 | OpenSSL libraries or in the application. | |
39 | If it's a dynamically loadable module, the initialization function | |
40 | must be named C<OSSL_provider_init> and must be exported. | |
41 | If it's built-in, the initialization function may have any name. | |
42 | ||
43 | The initialization function must have the following signature: | |
44 | ||
45 | int NAME(const OSSL_PROVIDER *provider, | |
46 | const OSSL_DISPATCH *in, const OSSL_DISPATCH **out, | |
47 | void **provctx); | |
48 | ||
49 | I<provider> is the OpenSSL library object for the provider, and works | |
50 | as a handle for everything the OpenSSL libraries need to know about | |
51 | the provider. | |
52 | For the provider itself, it may hold some interesting information, | |
53 | and is also passed to some of the functions given in the dispatch | |
54 | array I<in>. | |
55 | ||
56 | I<in> is a dispatch array of base functions offered by the OpenSSL | |
57 | libraries, and the available functions are further described in | |
58 | L<provider-base(7)>. | |
59 | ||
60 | I<*out> must be assigned a dispatch array of base functions that the | |
61 | provider offers to the OpenSSL libraries. | |
62 | The functions that may be offered are further described in | |
63 | L<provider-base(7)>, and they are the central means of communication | |
64 | between the OpenSSL libraries and the provider. | |
65 | ||
66 | I<*provctx> should be assigned a provider specific context to allow | |
67 | the provider multiple simultaneous uses. | |
68 | This pointer will be passed to various operation functions offered by | |
69 | the provider. | |
70 | ||
71 | One of the functions the provider offers to the OpenSSL libraries is | |
72 | the central mechanism for the OpenSSL libraries to get access to | |
73 | operation implementations for diverse algorithms. | |
74 | Its referred to with the number B<OSSL_FUNC_PROVIDER_QUERY_OPERATION> | |
75 | and has the following signature: | |
76 | ||
77 | const OSSL_ALGORITHM *provider_query_operation(void *provctx, | |
78 | int operation_id, | |
79 | const int *no_store); | |
80 | ||
81 | I<provctx> is the provider specific context that was passed back by | |
82 | the initialization function. | |
83 | ||
84 | I<operation_id> is an operation identity (see L</Operations> below). | |
85 | ||
86 | I<no_store> is a flag back to the OpenSSL libraries which, when | |
9c0586d5 | 87 | nonzero, signifies that the OpenSSL libraries will not store a |
e4c0ec62 RL |
88 | reference to the returned data in their internal store of |
89 | implementations. | |
90 | ||
91 | The returned B<OSSL_ALGORITHM> is the foundation of any OpenSSL | |
92 | library API that uses providers for their implementation, most | |
93 | commonly in the I<fetching> type of functions | |
94 | (see L</Fetching algorithms> below). | |
95 | ||
96 | =head2 Operations | |
97 | ||
98 | I<NOTE: This section is mostly interesting for provider authors.> | |
99 | ||
100 | Operations are referred to with numbers, via macros with names | |
101 | starting with C<OSSL_OP_>. | |
102 | ||
103 | With each operation comes a set of defined function types that a | |
104 | provider may or may not offer, depending on its needs. | |
105 | ||
106 | Currently available operations are: | |
107 | ||
108 | =over 4 | |
109 | ||
110 | =item Digests | |
111 | ||
112 | In the OpenSSL libraries, the corresponding method object is | |
113 | B<EVP_MD>. | |
114 | The number for this operation is B<OSSL_OP_DIGEST>. | |
115 | The functions the provider can offer are described in | |
116 | L<provider-digest(7)> | |
117 | ||
118 | =item Symmetric ciphers | |
119 | ||
120 | In the OpenSSL libraries, the corresponding method object is | |
121 | B<EVP_CIPHER>. | |
122 | The number for this operation is B<OSSL_OP_CIPHER>. | |
123 | The functions the provider can offer are described in | |
124 | L<provider-cipher(7)> | |
125 | ||
e4c0ec62 RL |
126 | =item Message Authentication Code (MAC) |
127 | ||
128 | In the OpenSSL libraries, the corresponding method object is | |
129 | B<EVP_MAC>. | |
130 | The number for this operation is B<OSSL_OP_MAC>. | |
131 | The functions the provider can offer are described in | |
132 | L<provider-mac(7)> | |
133 | ||
e4c0ec62 RL |
134 | =item Key Derivation Function (KDF) |
135 | ||
136 | In the OpenSSL libraries, the corresponding method object is | |
137 | B<EVP_KDF>. | |
138 | The number for this operation is B<OSSL_OP_KDF>. | |
139 | The functions the provider can offer are described in | |
140 | L<provider-kdf(7)> | |
141 | ||
e4c0ec62 RL |
142 | =item Key Exchange |
143 | ||
144 | In the OpenSSL libraries, the corresponding method object is | |
dfabee82 | 145 | B<EVP_KEYEXCH>. |
e4c0ec62 RL |
146 | The number for this operation is B<OSSL_OP_KEYEXCH>. |
147 | The functions the provider can offer are described in | |
148 | L<provider-keyexch(7)> | |
149 | ||
0d003c52 RL |
150 | =item Serialization |
151 | ||
152 | In the OpenSSL libraries, the corresponding method object is | |
153 | B<OSSL_SERIALIZER>. | |
154 | The number for this operation is B<OSSL_OP_SERIALIZER>. | |
155 | The functions the provider can offer are described in | |
156 | L<provider-serializer(7)> | |
157 | ||
e4c0ec62 RL |
158 | =back |
159 | ||
160 | =head2 Fetching algorithms | |
161 | ||
162 | =head3 Explicit fetch | |
163 | ||
164 | I<NOTE: This section is mostly interesting to OpenSSL users.> | |
165 | ||
166 | Users of the OpenSSL libraries never query the provider directly for | |
167 | its diverse implementations and dispatch tables. | |
168 | Instead, the diverse OpenSSL APIs often have fetching functions that | |
169 | do the work, and they return an appropriate method object back to the | |
170 | user. | |
171 | These functions usually have the name C<APINAME_fetch>, where | |
172 | C<APINAME> is the name of the API, for example L<EVP_MD_fetch(3)>. | |
173 | ||
174 | These fetching functions follow a fairly common pattern, where three | |
175 | arguments are passed: | |
176 | ||
177 | =over 4 | |
178 | ||
179 | =item The library context | |
180 | ||
181 | See L<OPENSSL_CTX(3)> for a more detailed description. | |
182 | This may be NULL to signify the default (global) library context, or a | |
183 | context created by the user. | |
184 | Only providers loaded in this library context (see | |
185 | L<OSSL_PROVIDER_load(3)>) will be considered by the fetching | |
186 | function. | |
187 | ||
188 | =item An identifier | |
189 | ||
190 | This is most commonly an algorithm name (this is the case for all EVP | |
191 | methods), but may also be called something else. | |
192 | ||
193 | =for comment For example, an OSSL_STORE implementation would use the | |
194 | URI scheme as an identifier. | |
195 | ||
196 | =item A property query string | |
197 | ||
198 | See L<property(7)> for a more detailed description. | |
199 | This is used to select more exactly which providers will get to offer | |
200 | an implementation. | |
201 | ||
202 | =back | |
203 | ||
204 | The method object that is fetched can then be used with diverse other | |
205 | functions that use them, for example L<EVP_DigestInit_ex(3)>. | |
206 | ||
485d3361 | 207 | =head3 Implicit fetch |
e4c0ec62 RL |
208 | |
209 | I<NOTE: This section is mostly interesting to OpenSSL users.> | |
210 | ||
211 | OpenSSL has a number of functions that return a method object with no | |
212 | associated implementation, such as L<EVP_sha256(3)>, | |
213 | L<EVP_blake2b512(3)> or L<EVP_aes_128_cbc(3)>, which are present for | |
214 | compatibility with OpenSSL before version 3.0. | |
215 | ||
216 | When they are used with functions like L<EVP_DigestInit_ex(3)> or | |
217 | L<EVP_CipherInit_ex(3)>, the actual implementation to be used is | |
218 | fetched implicitly using default search criteria. | |
219 | ||
fadb57e5 | 220 | Implicit fetching can also occur when a NULL algorithm parameter is |
e4c0ec62 RL |
221 | supplied. |
222 | In this case an algorithm implementation is implicitly fetched using | |
223 | default search criteria and an algorithm name that is consistent with | |
224 | the type of EVP_PKEY being used. | |
225 | ||
e44192d1 | 226 | =head3 Algorithm naming |
e4c0ec62 | 227 | |
e44192d1 MC |
228 | Algorithm names are case insensitive. Any particular algorithm can have multiple |
229 | aliases associated with it. The canonical OpenSSL naming scheme follows this | |
230 | format: | |
e4c0ec62 | 231 | |
e44192d1 | 232 | ALGNAME[VERSION?][-SUBNAME[VERSION?]?][-SIZE?][-MODE?] |
e4c0ec62 | 233 | |
e44192d1 MC |
234 | VERSION is only present if there are multiple versions of an algorithm (e.g. |
235 | MD2, MD4, MD5). It may be omitted if there is only one version. | |
e4c0ec62 | 236 | |
e44192d1 MC |
237 | SUBNAME may be present where multiple algorithms are combined together, |
238 | e.g. MD5-SHA1. | |
e4c0ec62 | 239 | |
e44192d1 MC |
240 | SIZE is only present if multiple versions of an algorithm exist with different |
241 | sizes (e.g. AES-128-CBC, AES-256-CBC) | |
e4c0ec62 | 242 | |
e44192d1 | 243 | MODE is only present where applicable. |
e4c0ec62 | 244 | |
e44192d1 MC |
245 | Other aliases may exist for example where standards bodies or common practice |
246 | use alternative names or names that OpenSSL has used historically. | |
e4c0ec62 | 247 | |
e44192d1 | 248 | =head1 OPENSSL PROVIDERS |
e4c0ec62 | 249 | |
e44192d1 | 250 | OpenSSL comes with a set of providers. |
e4c0ec62 | 251 | |
e44192d1 MC |
252 | The algorithms available in each of these providers may vary due to build time |
253 | configuration options. The L<openssl-list(1)> command can be used to list the | |
254 | currently available algorithms. | |
e4c0ec62 | 255 | |
e44192d1 MC |
256 | The names of the algorithms shown from L<openssl-list(1)> can be used as an |
257 | algorithm identifier to the appropriate fetching function. | |
e4c0ec62 | 258 | |
e44192d1 MC |
259 | =head2 Default provider |
260 | ||
261 | The default provider is built in as part of the F<libcrypto> library. | |
262 | Should it be needed (if other providers are loaded and offer | |
745fc918 MC |
263 | implementations of the same algorithms), the property "provider=default" |
264 | can be used as a search criterion for these implementations. Some | |
265 | non-cryptographic algorithms (such as serializers for loading keys and | |
266 | parameters from files) are not FIPS algorithm implementations in themselves but | |
267 | support algorithms from the FIPS provider and are allowed for use in "FIPS | |
268 | mode". The property "fips=yes" can be used to select such algorithms. | |
e4c0ec62 RL |
269 | |
270 | =head2 FIPS provider | |
271 | ||
272 | The FIPS provider is a dynamically loadable module, and must therefore | |
273 | be loaded explicitly, either in code or through OpenSSL configuration | |
274 | (see L<config(5)>). | |
275 | Should it be needed (if other providers are loaded and offer | |
745fc918 MC |
276 | implementations of the same algorithms), the property "provider=fips" can |
277 | be used as a search criterion for these implementations. All algorithm | |
278 | implementations in the FIPS provider can also be selected with the property | |
279 | "fips=yes". | |
e4c0ec62 | 280 | |
e4c0ec62 RL |
281 | =head2 Legacy provider |
282 | ||
283 | The legacy provider is a dynamically loadable module, and must therefore | |
284 | be loaded explicitly, either in code or through OpenSSL configuration | |
285 | (see L<config(5)>). | |
286 | Should it be needed (if other providers are loaded and offer | |
745fc918 | 287 | implementations of the same algorithms), the property "provider=legacy" can be |
e4c0ec62 RL |
288 | used as a search criterion for these implementations. |
289 | ||
e4c0ec62 RL |
290 | =head1 EXAMPLES |
291 | ||
292 | =head2 Fetching | |
293 | ||
e44192d1 | 294 | Fetch any available implementation of SHA2-256 in the default context: |
e4c0ec62 | 295 | |
e44192d1 | 296 | EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL); |
e4c0ec62 RL |
297 | ... |
298 | EVP_MD_meth_free(md); | |
299 | ||
300 | Fetch any available implementation of AES-128-CBC in the default context: | |
301 | ||
302 | EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL); | |
303 | ... | |
304 | EVP_CIPHER_meth_free(cipher); | |
305 | ||
e44192d1 | 306 | Fetch an implementation of SHA2-256 from the default provider in the default |
e4c0ec62 RL |
307 | context: |
308 | ||
745fc918 | 309 | EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=default"); |
e4c0ec62 RL |
310 | ... |
311 | EVP_MD_meth_free(md); | |
312 | ||
e44192d1 | 313 | Fetch an implementation of SHA2-256 that is not from the default provider in the |
e4c0ec62 RL |
314 | default context: |
315 | ||
745fc918 | 316 | EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider!=default"); |
e4c0ec62 RL |
317 | ... |
318 | EVP_MD_meth_free(md); | |
319 | ||
e44192d1 | 320 | Fetch an implementation of SHA2-256 from the default provider in the specified |
e4c0ec62 RL |
321 | context: |
322 | ||
745fc918 | 323 | EVP_MD *md = EVP_MD_fetch(ctx, "SHA2-256", "provider=default"); |
e4c0ec62 RL |
324 | ... |
325 | EVP_MD_meth_free(md); | |
326 | ||
327 | Load the legacy provider into the default context and then fetch an | |
e44192d1 | 328 | implementation of WHIRLPOOL from it: |
e4c0ec62 RL |
329 | |
330 | /* This only needs to be done once - usually at application start up */ | |
331 | OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); | |
332 | ||
745fc918 | 333 | EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy"); |
e4c0ec62 RL |
334 | ... |
335 | EVP_MD_meth_free(md); | |
336 | ||
745fc918 | 337 | Note that in the above example the property string "provider=legacy" is optional |
e4c0ec62 RL |
338 | since, assuming no other providers have been loaded, the only implementation of |
339 | the "whirlpool" algorithm is in the "legacy" provider. Also note that the | |
340 | default provider should be explicitly loaded if it is required in addition to | |
341 | other providers: | |
342 | ||
343 | /* This only needs to be done once - usually at application start up */ | |
344 | OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); | |
345 | OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default"); | |
346 | ||
347 | EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL); | |
e44192d1 | 348 | EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL); |
e4c0ec62 RL |
349 | ... |
350 | EVP_MD_meth_free(md_whirlpool); | |
351 | EVP_MD_meth_free(md_sha256); | |
352 | ||
353 | ||
354 | =head1 SEE ALSO | |
355 | ||
356 | L<EVP_DigestInit_ex(3)>, L<EVP_EncryptInit_ex(3)>, | |
e4c0ec62 RL |
357 | L<OPENSSL_CTX(3)>, |
358 | L<EVP_set_default_properties(3)>, | |
359 | L<EVP_MD_fetch(3)>, | |
360 | L<EVP_CIPHER_fetch(3)>, | |
361 | L<EVP_KEYMGMT_fetch(3)>, | |
362 | L<openssl-core.h(7)>, | |
363 | L<provider-base(7)>, | |
364 | L<provider-digest(7)>, | |
365 | L<provider-cipher(7)>, | |
366 | L<provider-keyexch(7)> | |
367 | ||
368 | =head1 HISTORY | |
369 | ||
370 | The concept of providers and everything surrounding them was | |
371 | introduced in OpenSSL 3.0. | |
372 | ||
373 | =head1 COPYRIGHT | |
374 | ||
375 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
376 | ||
377 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
378 | this file except in compliance with the License. You can obtain a copy | |
379 | in the file LICENSE in the source distribution or at | |
380 | L<https://www.openssl.org/source/license.html>. | |
381 | ||
382 | =cut |