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