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