Documentation: Add provider(7), for general description of providers
[openssl.git] / doc / man7 / provider.pod
1 =pod
2
3 =head1 NAME
4
5 provider - OpenSSL operation implementation providers
6
7 =head1 SYNOPSIS
8
9 =for comment generic
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
87 non-zero, signifies that the OpenSSL libraries will not store a
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
126 =begin comment NOT AVAILABLE YET
127
128 =item Message Authentication Code (MAC)
129
130 In the OpenSSL libraries, the corresponding method object is
131 B<EVP_MAC>.
132 The number for this operation is B<OSSL_OP_MAC>.
133 The functions the provider can offer are described in
134 L<provider-mac(7)>
135
136 =end comment
137
138 =begin comment NOT AVAILABLE YET
139
140 =item Key Derivation Function (KDF)
141
142 In the OpenSSL libraries, the corresponding method object is
143 B<EVP_KDF>.
144 The number for this operation is B<OSSL_OP_KDF>.
145 The functions the provider can offer are described in
146 L<provider-kdf(7)>
147
148 =end comment
149
150 =item Key Exchange
151
152 In the OpenSSL libraries, the corresponding method object is
153 B<EVP_KEYEXCh>.
154 The number for this operation is B<OSSL_OP_KEYEXCH>.
155 The functions the provider can offer are described in
156 L<provider-keyexch(7)>
157
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
207 =head2 Implicit fetch
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
220 Implicit fetching can also occur with functions such as
221 L<EVP_PKEY_CTX_derive_init_ex(3)> where a NULL algorithm parameter is
222 supplied.
223 In this case an algorithm implementation is implicitly fetched using
224 default search criteria and an algorithm name that is consistent with
225 the type of EVP_PKEY being used.
226
227 =head1 OPENSSL PROVIDERS
228
229 OpenSSL comes with a set of providers.
230 All the algorithm names mentioned can be used as an algorithm
231 identifier to the appropriate fetching function.
232
233 =head2 Default provider
234
235 The default provider is built in as part of the F<libcrypto> library.
236 Should it be needed (if other providers are loaded and offer
237 implementations of the same algorithms), the property "default=yes"
238 can be used as a search criterion for these implementations.
239
240 It currently offers the following named algorithms:
241
242 =over 4
243
244 =item Digests
245
246 SHA1, SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256,
247 SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128, SHAKE256, SM3,
248 BLAKE2b512, BLAKE2s256, KMAC128, KMAC256, MD5, MD5-SHA1
249
250 =item Symmetric ciphers
251
252 AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC,
253 AES-128-CBC, AES-256-OFB, AES-192-OFB, AES-128-OFB, AES-256-CFB,
254 AES-192-CFB, AES-128-CFB, AES-256-CFB1, AES-192-CFB1, AES-128-CFB1,
255 AES-256-CFB8, AES-192-CFB8, AES-128-CFB8, AES-256-CTR, AES-192-CTR,
256 AES-128-CTR, id-aes256-GCM, id-aes192-GCM, id-aes128-GCM
257
258 =item Key Exchange
259
260 dhKeyAgreement
261
262 =back
263
264 =head2 FIPS provider
265
266 The FIPS provider is a dynamically loadable module, and must therefore
267 be loaded explicitly, either in code or through OpenSSL configuration
268 (see L<config(5)>).
269 Should it be needed (if other providers are loaded and offer
270 implementations of the same algorithms), the property "fips=yes" can
271 be used as a search criterion for these implementations.
272
273 It currently offers the following FIPS approved named algorithms:
274
275 =over 4
276
277 =item Digests
278
279 SHA1, SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256,
280 SHA3-224, SHA3-256, SHA3-384, SHA3-512, KMAC128, KMAC256
281
282 =item Symmetric ciphers
283
284 AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC,
285 AES-128-CBC, AES-256-CTR, AES-192-CTR, AES-128-CTR
286
287 =back
288
289 =head2 Legacy provider
290
291 The legacy provider is a dynamically loadable module, and must therefore
292 be loaded explicitly, either in code or through OpenSSL configuration
293 (see L<config(5)>).
294 Should it be needed (if other providers are loaded and offer
295 implementations of the same algorithms), the property "legacy=yes" can be
296 used as a search criterion for these implementations.
297
298 It currently offers the following named algorithms:
299
300 =over 4
301
302 =item Digest algorithms:
303
304 RIPEMD160, MD2, MD4, MDC2, whirlpool.
305
306 =back
307
308 =head1 EXAMPLES
309
310 =head2 Fetching
311
312 Fetch any available implementation of SHA256 in the default context:
313
314  EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", NULL);
315  ...
316  EVP_MD_meth_free(md);
317
318 Fetch any available implementation of AES-128-CBC in the default context:
319
320  EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
321  ...
322  EVP_CIPHER_meth_free(cipher);
323
324 Fetch an implementation of SHA256 from the default provider in the default
325 context:
326
327  EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=yes");
328  ...
329  EVP_MD_meth_free(md);
330
331 Fetch an implementation of SHA256 that is not from the default provider in the
332 default context:
333
334  EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=no");
335  ...
336  EVP_MD_meth_free(md);
337
338 Fetch an implementation of SHA256 from the default provider in the specified
339 context:
340
341  EVP_MD *md = EVP_MD_fetch(ctx, "SHA256", "default=yes");
342  ...
343  EVP_MD_meth_free(md);
344
345 Load the legacy provider into the default context and then fetch an
346 implementation of whirlpool from it:
347
348  /* This only needs to be done once - usually at application start up */
349  OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
350
351  EVP_MD *md = EVP_MD_fetch(NULL, "whirlpool", "legacy=yes");
352  ...
353  EVP_MD_meth_free(md);
354
355 Note that in the above example the property string "legacy=yes" is optional
356 since, assuming no other providers have been loaded, the only implementation of
357 the "whirlpool" algorithm is in the "legacy" provider. Also note that the
358 default provider should be explicitly loaded if it is required in addition to
359 other providers:
360
361  /* This only needs to be done once - usually at application start up */
362  OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
363  OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
364
365  EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
366  EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
367  ...
368  EVP_MD_meth_free(md_whirlpool);
369  EVP_MD_meth_free(md_sha256);
370
371
372 =head1 SEE ALSO
373
374 L<EVP_DigestInit_ex(3)>, L<EVP_EncryptInit_ex(3)>,
375 L<EVP_PKEY_derive_init_ex(3)>, 
376 L<OPENSSL_CTX(3)>,
377 L<EVP_set_default_properties(3)>,
378 L<EVP_MD_fetch(3)>,
379 L<EVP_CIPHER_fetch(3)>,
380 L<EVP_KEYMGMT_fetch(3)>,
381 L<openssl-core.h(7)>,
382 L<provider-base(7)>,
383 L<provider-digest(7)>,
384 L<provider-cipher(7)>,
385 L<provider-keyexch(7)>
386
387 =head1 HISTORY
388
389 The concept of providers and everything surrounding them was
390 introduced in OpenSSL 3.0.
391
392 =head1 COPYRIGHT
393
394 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
395
396 Licensed under the Apache License 2.0 (the "License").  You may not use
397 this file except in compliance with the License.  You can obtain a copy
398 in the file LICENSE in the source distribution or at
399 L<https://www.openssl.org/source/license.html>.
400
401 =cut