]>
Commit | Line | Data |
---|---|---|
c4532834 RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
7c95390e | 5 | ossl_provider_find, ossl_provider_new, ossl_provider_up_ref, |
3bbec1af RL |
6 | ossl_provider_free, |
7 | ossl_provider_set_fallback, ossl_provider_set_module_path, | |
878be71c MC |
8 | ossl_provider_add_parameter, ossl_provider_set_child, ossl_provider_get_parent, |
9 | ossl_provider_up_ref_parent, ossl_provider_free_parent, | |
b1956770 | 10 | ossl_provider_default_props_update, ossl_provider_get0_dispatch, |
878be71c | 11 | ossl_provider_init_as_child, |
29d46e09 | 12 | ossl_provider_activate, ossl_provider_deactivate, ossl_provider_add_to_store, |
3bbec1af | 13 | ossl_provider_ctx, |
8f089576 | 14 | ossl_provider_doall_activated, |
85e2417c | 15 | ossl_provider_name, ossl_provider_dso, |
c4532834 | 16 | ossl_provider_module_name, ossl_provider_module_path, |
a829b735 | 17 | ossl_provider_libctx, |
dca97d00 | 18 | ossl_provider_teardown, ossl_provider_gettable_params, |
2876528d | 19 | ossl_provider_get_params, ossl_provider_clear_all_operation_bits, |
b0001d0c | 20 | ossl_provider_query_operation, ossl_provider_unquery_operation, |
82ec09ec MC |
21 | ossl_provider_set_operation_bit, ossl_provider_test_operation_bit, |
22 | ossl_provider_get_capabilities | |
099bd339 | 23 | - internal provider routines |
c4532834 RL |
24 | |
25 | =head1 SYNOPSIS | |
26 | ||
27 | #include "internal/provider.h" | |
28 | ||
b4250010 | 29 | OSSL_PROVIDER *ossl_provider_find(OSSL_LIB_CTX *libctx, const char *name, |
29dc6e00 | 30 | int noconfig); |
b4250010 | 31 | OSSL_PROVIDER *ossl_provider_new(OSSL_LIB_CTX *libctx, const char *name, |
29dc6e00 MC |
32 | ossl_provider_init_fn *init_function |
33 | int noconfig); | |
7c95390e | 34 | int ossl_provider_up_ref(OSSL_PROVIDER *prov); |
c4532834 RL |
35 | void ossl_provider_free(OSSL_PROVIDER *prov); |
36 | ||
37 | /* Setters */ | |
e55008a9 | 38 | int ossl_provider_set_fallback(OSSL_PROVIDER *prov); |
3bbec1af RL |
39 | int ossl_provider_set_module_path(OSSL_PROVIDER *prov, const char *path); |
40 | int ossl_provider_add_parameter(OSSL_PROVIDER *prov, const char *name, | |
41 | const char *value); | |
c4532834 | 42 | |
878be71c MC |
43 | /* Child Providers */ |
44 | int ossl_provider_set_child(OSSL_PROVIDER *prov, | |
45 | const OSSL_CORE_HANDLE *handle); | |
46 | const OSSL_CORE_HANDLE *ossl_provider_get_parent(OSSL_PROVIDER *prov); | |
47 | int ossl_provider_up_ref_parent(OSSL_PROVIDER *prov, int activate); | |
48 | int ossl_provider_free_parent(OSSL_PROVIDER *prov, int deactivate); | |
b1956770 MC |
49 | int ossl_provider_default_props_update(OSSL_LIB_CTX *libctx, |
50 | const char *props); | |
878be71c | 51 | |
390f9bad RL |
52 | /* |
53 | * Activate the Provider | |
54 | * If the Provider is a module, the module will be loaded | |
55 | */ | |
29d46e09 | 56 | int ossl_provider_activate(OSSL_PROVIDER *prov, int upcalls, int aschild); |
390f9bad | 57 | int ossl_provider_deactivate(OSSL_PROVIDER *prov); |
59a783d0 MC |
58 | int ossl_provider_add_to_store(OSSL_PROVIDER *prov, OSSL_PROVIDER **actualprov, |
59 | int retain_fallbacks); | |
c4532834 | 60 | |
a39eb840 RL |
61 | /* Return pointer to the provider's context */ |
62 | void *ossl_provider_ctx(const OSSL_PROVIDER *prov); | |
63 | ||
878be71c MC |
64 | const OSSL_DISPATCH *ossl_provider_get0_dispatch(const OSSL_PROVIDER *prov); |
65 | ||
85e2417c | 66 | /* Iterate over all loaded providers */ |
8f089576 P |
67 | int ossl_provider_doall_activated(OSSL_LIB_CTX *, |
68 | int (*cb)(OSSL_PROVIDER *provider, | |
69 | void *cbdata), | |
70 | void *cbdata); | |
85e2417c | 71 | |
c4532834 RL |
72 | /* Getters for other library functions */ |
73 | const char *ossl_provider_name(OSSL_PROVIDER *prov); | |
74 | const DSO *ossl_provider_dso(OSSL_PROVIDER *prov); | |
75 | const char *ossl_provider_module_name(OSSL_PROVIDER *prov); | |
76 | const char *ossl_provider_module_path(OSSL_PROVIDER *prov); | |
a829b735 | 77 | OSSL_LIB_CTX *ossl_provider_libctx(const OSSL_PROVIDER *prov); |
c4532834 RL |
78 | |
79 | /* Thin wrappers around calls to the provider */ | |
80 | void ossl_provider_teardown(const OSSL_PROVIDER *prov); | |
dca97d00 | 81 | const OSSL_PARAM *ossl_provider_gettable_params(const OSSL_PROVIDER *prov); |
4e7991b4 | 82 | int ossl_provider_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]); |
82ec09ec MC |
83 | int ossl_provider_get_capabilities(const OSSL_PROVIDER *prov, |
84 | const char *capability, | |
85 | OSSL_CALLBACK *cb, | |
86 | void *arg); | |
099bd339 RL |
87 | const OSSL_ALGORITHM *ossl_provider_query_operation(const OSSL_PROVIDER *prov, |
88 | int operation_id, | |
89 | int *no_cache); | |
b0001d0c P |
90 | void ossl_provider_unquery_operation(const OSSL_PROVIDER *prov, |
91 | int operation_id, | |
92 | const OSSL_ALGORITHM *algs); | |
c4532834 | 93 | |
5a29b628 RL |
94 | int ossl_provider_set_operation_bit(OSSL_PROVIDER *provider, size_t bitnum); |
95 | int ossl_provider_test_operation_bit(OSSL_PROVIDER *provider, size_t bitnum, | |
96 | int *result); | |
2876528d | 97 | int ossl_provider_clear_all_operation_bits(OSSL_LIB_CTX *libctx); |
5a29b628 | 98 | |
878be71c MC |
99 | int ossl_provider_init_as_child(OSSL_LIB_CTX *ctx, |
100 | const OSSL_CORE_HANDLE *handle, | |
101 | const OSSL_DISPATCH *in); | |
102 | ||
103 | ||
c4532834 RL |
104 | =head1 DESCRIPTION |
105 | ||
3bbec1af | 106 | I<OSSL_PROVIDER> is a type that holds all the necessary information |
c4532834 RL |
107 | to handle a provider, regardless of if it's built in to the |
108 | application or the OpenSSL libraries, or if it's a loadable provider | |
109 | module. | |
3bbec1af | 110 | Instances of this type are commonly referred to as "provider objects". |
c4532834 | 111 | |
3bbec1af | 112 | A provider object is always stored in a set of provider objects |
c4532834 RL |
113 | in the library context. |
114 | ||
3bbec1af | 115 | Provider objects are reference counted. |
c4532834 | 116 | |
3bbec1af RL |
117 | Provider objects are initially inactive, i.e. they are only recorded |
118 | in the store, but are not used. | |
c4532834 | 119 | They are activated with the first call to ossl_provider_activate(), |
390f9bad RL |
120 | and are deactivated with the last call to ossl_provider_deactivate(). |
121 | Activation affects a separate counter. | |
c4532834 RL |
122 | |
123 | =head2 Functions | |
124 | ||
3bbec1af | 125 | ossl_provider_find() finds an existing provider object in the provider |
29dc6e00 MC |
126 | object store by I<name>. |
127 | The config file will be automatically loaded unless I<noconfig> is set. | |
128 | Typically I<noconfig> should be 0. | |
129 | We set I<noconfig> to 1 only when calling these functions while processing a | |
130 | config file in order to avoid recursively attempting to load the file. | |
3bbec1af RL |
131 | The provider object it finds has its reference count incremented. |
132 | ||
133 | ossl_provider_new() creates a new provider object named I<name> and | |
134 | stores it in the provider object store, unless there already is one | |
135 | there with the same name. | |
136 | If there already is one with the same name, it's returned with its | |
137 | reference count incremented. | |
29dc6e00 MC |
138 | The config file will be automatically loaded unless I<noconfig> is set. |
139 | Typically I<noconfig> should be 0. | |
140 | We set I<noconfig> to 1 only when calling these functions while processing a | |
141 | config file in order to avoid recursively attempting to load the file. | |
3bbec1af RL |
142 | The reference count of a newly created provider object will always |
143 | be 2; one for being added to the store, and one for the returned | |
144 | reference. | |
145 | If I<init_function> is NULL, the provider is assumed to be a | |
146 | dynamically loadable module, with the symbol B<OSSL_provider_init> as | |
147 | its initialisation function. | |
148 | If I<init_function> isn't NULL, the provider is assumed to be built | |
149 | in, with I<init_function> being the pointer to its initialisation | |
150 | function. | |
151 | For further description of the initialisation function, see the | |
152 | description of ossl_provider_activate() below. | |
153 | ||
7c95390e | 154 | ossl_provider_up_ref() increments the provider object I<prov>'s |
3bbec1af RL |
155 | reference count. |
156 | ||
157 | ossl_provider_free() decrements the provider object I<prov>'s | |
390f9bad RL |
158 | reference count; when it drops to zero, the provider object is assumed |
159 | to have fallen out of use and will be deinitialized (its I<teardown> | |
160 | function is called), and the associated module will be unloaded if one | |
161 | was loaded, and I<prov> itself will be freed. | |
3bbec1af RL |
162 | |
163 | ossl_provider_set_fallback() marks an available provider I<prov> as | |
164 | fallback. | |
165 | Note that after this call, the provider object pointer that was | |
e55008a9 RL |
166 | used can simply be dropped, but not freed. |
167 | ||
3bbec1af RL |
168 | ossl_provider_set_module_path() sets the module path to load the |
169 | provider module given the provider object I<prov>. | |
170 | This will be used in preference to automatically trying to figure out | |
171 | the path from the provider name and the default module directory (more | |
172 | on this in L</NOTES>). | |
173 | ||
a829b735 | 174 | ossl_provider_libctx() returns the library context the given |
e74bd290 RL |
175 | provider I<prov> is registered in. |
176 | ||
3bbec1af RL |
177 | ossl_provider_add_parameter() adds a global parameter for the provider |
178 | to retrieve as it sees fit. | |
179 | The parameters are a combination of I<name> and I<value>, and the | |
180 | provider will use the name to find the value it wants. | |
181 | Only text parameters can be given, and it's up to the provider to | |
182 | interpret them. | |
183 | ||
878be71c MC |
184 | ossl_provider_set_child() marks this provider as a child of a provider in the |
185 | parent library context. I<handle> is the B<OSSL_CORE_HANDLE> object passed to | |
186 | the provider's B<OSSL_provider_init> function. | |
187 | ||
188 | ossl_provider_get_parent() obtains the handle on the parent provider. | |
189 | ||
190 | ossl_provider_up_ref_parent() increases the reference count on the parent | |
191 | provider. If I<activate> is nonzero then the parent provider is also activated. | |
192 | ||
193 | ossl_provider_free_parent() decreases the reference count on the parent | |
194 | provider. If I<deactivate> is nonzero then the parent provider is also | |
195 | deactivated. | |
196 | ||
b1956770 MC |
197 | ossl_provider_default_props_update() is responsible for informing any child |
198 | providers of an update to the default properties. The new properties are | |
199 | supplied in the I<props> string. | |
200 | ||
c4532834 | 201 | ossl_provider_activate() "activates" the provider for the given |
390f9bad RL |
202 | provider object I<prov> by incrementing its activation count, flagging |
203 | it as activated, and initializing it if it isn't already initialized. | |
204 | Initializing means one of the following: | |
c4532834 RL |
205 | |
206 | =over 4 | |
207 | ||
208 | =item * | |
209 | ||
210 | If an initialization function was given with ossl_provider_new(), that | |
211 | function will get called. | |
212 | ||
213 | =item * | |
214 | ||
c2969ff6 | 215 | If no initialization function was given with ossl_provider_new(), a |
3bbec1af RL |
216 | loadable module with the I<name> that was given to ossl_provider_new() |
217 | will be located and loaded, then the symbol B<OSSL_provider_init> will | |
c4532834 RL |
218 | be located in that module, and called. |
219 | ||
220 | =back | |
221 | ||
eb2263da | 222 | If I<upcalls> is nonzero then, if this is a child provider, upcalls to the |
29d46e09 MC |
223 | parent libctx will be made to inform it of an up-ref. If I<aschild> is nonzero |
224 | then the provider will only be activated if it is a child provider. Otherwise | |
225 | no action is taken and ossl_provider_activate() returns success. | |
299f5ff3 | 226 | |
390f9bad RL |
227 | ossl_provider_deactivate() "deactivates" the provider for the given |
228 | provider object I<prov> by decrementing its activation count. When | |
229 | that count reaches zero, the activation flag is cleared. | |
230 | ||
29d46e09 MC |
231 | ossl_provider_add_to_store() adds the provider I<prov> to the provider store and |
232 | makes it available to other threads. This will prevent future automatic loading | |
59a783d0 MC |
233 | of fallback providers, unless I<retain_fallbacks> is true. If a provider of the |
234 | same name already exists in the store then it is not added but this function | |
235 | still returns success. On success the I<actualprov> value is populated with a | |
236 | pointer to the provider of the given name that is now in the store. The | |
237 | reference passed in the I<prov> argument is consumed by this function. A | |
238 | reference to the provider that should be used is passed back in the | |
239 | I<actualprov> argument. | |
29d46e09 | 240 | |
a39eb840 RL |
241 | ossl_provider_ctx() returns a context created by the provider. |
242 | Outside of the provider, it's completely opaque, but it needs to be | |
243 | passed back to some of the provider functions. | |
244 | ||
878be71c MC |
245 | ossl_provider_get0_dispatch() returns the dispatch table that the provider |
246 | initially returned in the I<out> parameter of its B<OSSL_provider_init> | |
247 | function. | |
248 | ||
8f089576 | 249 | ossl_provider_doall_activated() iterates over all the currently |
3bbec1af | 250 | "activated" providers, and calls I<cb> for each of them. |
e55008a9 | 251 | If no providers have been "activated" yet, it tries to activate all |
3c5ce1ce | 252 | available fallback providers before iterating over them. |
85e2417c | 253 | |
c4532834 RL |
254 | ossl_provider_name() returns the name that was given with |
255 | ossl_provider_new(). | |
256 | ||
257 | ossl_provider_dso() returns a reference to the module, for providers | |
258 | that come in the form of loadable modules. | |
259 | ||
9c0586d5 | 260 | ossl_provider_module_name() returns the filename of the module, for |
c4532834 RL |
261 | providers that come in the form of loadable modules. |
262 | ||
263 | ossl_provider_module_path() returns the full path of the module file, | |
264 | for providers that come in the form of loadable modules. | |
265 | ||
3bbec1af | 266 | ossl_provider_teardown() calls the provider's I<teardown> function, if |
c4532834 RL |
267 | the provider has one. |
268 | ||
dca97d00 | 269 | ossl_provider_gettable_params() calls the provider's I<gettable_params> |
c4532834 | 270 | function, if the provider has one. |
26175013 | 271 | It should return an array of I<OSSL_PARAM> to describe all the |
3bbec1af | 272 | parameters that the provider has for the provider object. |
c4532834 RL |
273 | |
274 | ossl_provider_get_params() calls the provider's parameter request | |
275 | responder. | |
3bbec1af | 276 | It should treat the given I<OSSL_PARAM> array as described in |
c4532834 RL |
277 | L<OSSL_PARAM(3)>. |
278 | ||
82ec09ec MC |
279 | ossl_provider_get_capabilities() calls the provider's I<get_capabilities> function, |
280 | if the provider has one. It provides the name of the I<capability> and a | |
281 | callback I<cb> parameter to call for each capability that has a matching name in | |
282 | the provider. The callback gets passed OSSL_PARAM details about the capability as | |
283 | well as the caller supplied argument I<arg>. | |
284 | ||
099bd339 | 285 | ossl_provider_query_operation() calls the provider's |
3bbec1af RL |
286 | I<query_operation> function, if the provider has one. |
287 | It should return an array of I<OSSL_ALGORITHM> for the given | |
288 | I<operation_id>. | |
b0001d0c P |
289 | |
290 | ossl_provider_unquery_operation() informs the provider that the result of | |
291 | ossl_provider_query_operation() is no longer going to be directly accessed and | |
292 | that all relevant information has been copied. | |
099bd339 | 293 | |
5a29b628 RL |
294 | ossl_provider_set_operation_bit() registers a 1 for operation I<bitnum> |
295 | in a bitstring that's internal to I<provider>. | |
296 | ||
2876528d | 297 | ossl_provider_test_operation_bit() checks if the bit operation I<bitnum> |
5a29b628 | 298 | is set (1) or not (0) in the internal I<provider> bitstring, and sets |
57cd10dd | 299 | I<*result> to 1 or 0 accorddingly. |
5a29b628 | 300 | |
2876528d P |
301 | ossl_provider_clear_all_operation_bits() clears all of the operation bits |
302 | to (0) for all providers in the library context I<libctx>. | |
303 | ||
878be71c MC |
304 | ossl_provider_init_as_child() stores in the library context I<ctx> references to |
305 | the necessary upcalls for managing child providers. The I<handle> and I<in> | |
306 | parameters are the B<OSSL_CORE_HANDLE> and B<OSSL_DISPATCH> pointers that were | |
307 | passed to the provider's B<OSSL_provider_init> function. | |
308 | ||
c4532834 RL |
309 | =head1 NOTES |
310 | ||
311 | Locating a provider module happens as follows: | |
312 | ||
313 | =over 4 | |
314 | ||
315 | =item 1. | |
316 | ||
3bbec1af RL |
317 | If a path was given with ossl_provider_set_module_path(), use that as |
318 | module path. | |
319 | Otherwise, use the provider object's name as module path, with | |
320 | platform specific standard extensions added. | |
c4532834 RL |
321 | |
322 | =item 2. | |
323 | ||
3bbec1af RL |
324 | If the environment variable B<OPENSSL_MODULES> is defined, assume its |
325 | value is a directory specification and merge it with the module path. | |
326 | Otherwise, merge the value of the OpenSSL built in macro B<MODULESDIR> | |
327 | with the module path. | |
c4532834 | 328 | |
3bbec1af | 329 | =back |
c4532834 | 330 | |
3bbec1af RL |
331 | When this process is done, the result is used when trying to load the |
332 | provider module. | |
c4532834 | 333 | |
3bbec1af RL |
334 | The command C<openssl version -m> can be used to find out the value |
335 | of the built in macro B<MODULESDIR>. | |
c4532834 RL |
336 | |
337 | =head1 RETURN VALUES | |
338 | ||
339 | ossl_provider_find() and ossl_provider_new() return a pointer to a | |
3bbec1af | 340 | provider object (I<OSSL_PROVIDER>) on success, or NULL on error. |
c4532834 | 341 | |
7c95390e | 342 | ossl_provider_up_ref() returns the value of the reference count after |
c4532834 RL |
343 | it has been incremented. |
344 | ||
345 | ossl_provider_free() doesn't return any value. | |
346 | ||
8f089576 | 347 | ossl_provider_doall_activated() returns 1 if the callback was called for all |
3c5ce1ce P |
348 | activated providers. A return value of 0 means that the callback was not |
349 | called for any activated providers. | |
350 | ||
390f9bad | 351 | ossl_provider_set_module_path(), ossl_provider_set_fallback(), |
299f5ff3 | 352 | ossl_provider_activate(), ossl_provider_activate_leave_fallbacks() and |
29d46e09 MC |
353 | ossl_provider_deactivate(), ossl_provider_add_to_store(), |
354 | ossl_provider_default_props_update() return 1 on success, or 0 on error. | |
c4532834 RL |
355 | |
356 | ossl_provider_name(), ossl_provider_dso(), | |
357 | ossl_provider_module_name(), and ossl_provider_module_path() return a | |
3bbec1af | 358 | pointer to their respective data if it's available, otherwise NULL |
c4532834 RL |
359 | is returned. |
360 | ||
a829b735 | 361 | ossl_provider_libctx() return a pointer to the library context. |
e74bd290 RL |
362 | This may be NULL, and is perfectly valid, as it denotes the default |
363 | global library context. | |
364 | ||
79c44b4e | 365 | ossl_provider_teardown() doesn't return any value. |
c4532834 | 366 | |
dca97d00 | 367 | ossl_provider_gettable_params() returns a pointer to a constant |
26175013 RL |
368 | I<OSSL_PARAM> array if this function is available in the provider, |
369 | otherwise NULL. | |
c4532834 RL |
370 | |
371 | ossl_provider_get_params() returns 1 on success, or 0 on error. | |
372 | If this function isn't available in the provider, 0 is returned. | |
373 | ||
5a29b628 RL |
374 | ossl_provider_set_operation_bit() and ossl_provider_test_operation_bit() |
375 | return 1 on success, or 0 on error. | |
376 | ||
2876528d P |
377 | ossl_provider_clear_all_operation_bits() returns 1 on success, or 0 on error. |
378 | ||
82ec09ec MC |
379 | ossl_provider_get_capabilities() returns 1 on success, or 0 on error. |
380 | If this function isn't available in the provider or the provider does not | |
381 | support the requested capability then 0 is returned. | |
382 | ||
c4532834 RL |
383 | =head1 SEE ALSO |
384 | ||
3bbec1af | 385 | L<OSSL_PROVIDER(3)>, L<provider(7)>, L<openssl(1)> |
c4532834 RL |
386 | |
387 | =head1 HISTORY | |
388 | ||
389 | The functions described here were all added in OpenSSL 3.0. | |
390 | ||
391 | =head1 COPYRIGHT | |
392 | ||
8020d79b | 393 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. |
c4532834 RL |
394 | |
395 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
396 | this file except in compliance with the License. You can obtain a copy | |
397 | in the file LICENSE in the source distribution or at | |
398 | L<https://www.openssl.org/source/license.html>. | |
399 | ||
400 | =cut |