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