426d95393dd5504da12907e2bfaca4160b0cb32f
[openssl.git] / doc / internal / man3 / ossl_provider_new.pod
1 =pod
2
3 =head1 NAME
4
5 ossl_provider_find, ossl_provider_new, ossl_provider_up_ref,
6 ossl_provider_free,
7 ossl_provider_set_fallback, ossl_provider_set_module_path,
8 ossl_provider_add_parameter,
9 ossl_provider_activate,
10 ossl_provider_ctx,
11 ossl_provider_forall_loaded,
12 ossl_provider_name, ossl_provider_dso,
13 ossl_provider_module_name, ossl_provider_module_path,
14 ossl_provider_teardown, ossl_provider_get_param_types,
15 ossl_provider_get_params, ossl_provider_query_operation
16 - internal provider routines
17
18 =head1 SYNOPSIS
19
20  #include "internal/provider.h"
21
22  OSSL_PROVIDER *ossl_provider_find(OPENSSL_CTX *libctx, const char *name);
23  OSSL_PROVIDER *ossl_provider_new(OPENSSL_CTX *libctx, const char *name,
24                                   ossl_provider_init_fn *init_function);
25  int ossl_provider_up_ref(OSSL_PROVIDER *prov);
26  void ossl_provider_free(OSSL_PROVIDER *prov);
27
28  /* Setters */
29  int ossl_provider_set_fallback(OSSL_PROVIDER *prov);
30  int ossl_provider_set_module_path(OSSL_PROVIDER *prov, const char *path);
31  int ossl_provider_add_parameter(OSSL_PROVIDER *prov, const char *name,
32                                  const char *value);
33
34  /* Load and initialize the Provider */
35  int ossl_provider_activate(OSSL_PROVIDER *prov);
36
37  /* Return pointer to the provider's context */
38  void *ossl_provider_ctx(const OSSL_PROVIDER *prov);
39
40  /* Iterate over all loaded providers */
41  int ossl_provider_forall_loaded(OPENSSL_CTX *,
42                                  int (*cb)(OSSL_PROVIDER *provider,
43                                            void *cbdata),
44                                  void *cbdata);
45
46  /* Getters for other library functions */
47  const char *ossl_provider_name(OSSL_PROVIDER *prov);
48  const DSO *ossl_provider_dso(OSSL_PROVIDER *prov);
49  const char *ossl_provider_module_name(OSSL_PROVIDER *prov);
50  const char *ossl_provider_module_path(OSSL_PROVIDER *prov);
51
52  /* Thin wrappers around calls to the provider */
53  void ossl_provider_teardown(const OSSL_PROVIDER *prov);
54  const OSSL_PARAM *ossl_provider_get_param_types(const OSSL_PROVIDER *prov);
55  int ossl_provider_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]);
56  const OSSL_ALGORITHM *ossl_provider_query_operation(const OSSL_PROVIDER *prov,
57                                                      int operation_id,
58                                                      int *no_cache);
59
60 =head1 DESCRIPTION
61
62 I<OSSL_PROVIDER> is a type that holds all the necessary information
63 to handle a provider, regardless of if it's built in to the
64 application or the OpenSSL libraries, or if it's a loadable provider
65 module.
66 Instances of this type are commonly referred to as "provider objects".
67
68 A provider object is always stored in a set of provider objects
69 in the library context.
70
71 Provider objects are reference counted.
72
73 Provider objects are initially inactive, i.e. they are only recorded
74 in the store, but are not used.
75 They are activated with the first call to ossl_provider_activate(),
76 and are inactivated when ossl_provider_free() has been called as many
77 times as ossl_provider_activate() has.
78
79 =head2 Functions
80
81 ossl_provider_find() finds an existing provider object in the provider
82 object store by I<name>. 
83 The provider object it finds has its reference count incremented.
84
85 ossl_provider_new() creates a new provider object named I<name> and
86 stores it in the provider object store, unless there already is one
87 there with the same name.
88 If there already is one with the same name, it's returned with its
89 reference count incremented.
90 The reference count of a newly created provider object will always
91 be 2; one for being added to the store, and one for the returned
92 reference.
93 If I<init_function> is NULL, the provider is assumed to be a
94 dynamically loadable module, with the symbol B<OSSL_provider_init> as
95 its initialisation function.
96 If I<init_function> isn't NULL, the provider is assumed to be built
97 in, with I<init_function> being the pointer to its initialisation
98 function.
99 For further description of the initialisation function, see the
100 description of ossl_provider_activate() below.
101
102 ossl_provider_up_ref() increments the provider object I<prov>'s
103 reference count.
104
105 ossl_provider_free() decrements the provider object I<prov>'s
106 reference count; if it drops below 2, the provider object is assumed
107 to have fallen out of use and will be deactivated (its I<teardown>
108 function is called); if it drops down to zero, I<prov> is assumed to
109 have been taken out of the store, and the associated module will be
110 unloaded if one was loaded, and I<prov> itself will be freed.
111
112 ossl_provider_set_fallback() marks an available provider I<prov> as
113 fallback.
114 Note that after this call, the provider object pointer that was
115 used can simply be dropped, but not freed.
116
117 ossl_provider_set_module_path() sets the module path to load the
118 provider module given the provider object I<prov>.
119 This will be used in preference to automatically trying to figure out
120 the path from the provider name and the default module directory (more
121 on this in L</NOTES>).
122
123 ossl_provider_add_parameter() adds a global parameter for the provider
124 to retrieve as it sees fit.
125 The parameters are a combination of I<name> and I<value>, and the
126 provider will use the name to find the value it wants.
127 Only text parameters can be given, and it's up to the provider to
128 interpret them.
129
130 ossl_provider_activate() "activates" the provider for the given
131 provider object I<prov>.
132 What "activates" means depends on what type of provider object it
133 is:
134
135 =over 4
136
137 =item *
138
139 If an initialization function was given with ossl_provider_new(), that
140 function will get called.
141
142 =item *
143
144 If no initialization function was given with ossl_provider_new(), a
145 loadable module with the I<name> that was given to ossl_provider_new()
146 will be located and loaded, then the symbol B<OSSL_provider_init> will
147 be located in that module, and called.
148
149 =back
150
151 ossl_provider_ctx() returns a context created by the provider.
152 Outside of the provider, it's completely opaque, but it needs to be
153 passed back to some of the provider functions.
154
155 ossl_provider_forall_loaded() iterates over all the currently
156 "activated" providers, and calls I<cb> for each of them.
157 If no providers have been "activated" yet, it tries to activate all
158 available fallback providers and tries another iteration.
159
160 ossl_provider_name() returns the name that was given with
161 ossl_provider_new().
162
163 ossl_provider_dso() returns a reference to the module, for providers
164 that come in the form of loadable modules.
165
166 ossl_provider_module_name() returns the file name of the module, for
167 providers that come in the form of loadable modules.
168
169 ossl_provider_module_path() returns the full path of the module file,
170 for providers that come in the form of loadable modules.
171
172 ossl_provider_teardown() calls the provider's I<teardown> function, if
173 the provider has one.
174
175 ossl_provider_get_param_types() calls the provider's I<get_param_types>
176 function, if the provider has one.
177 It should return an array of I<OSSL_PARAM> to describe all the
178 parameters that the provider has for the provider object.
179
180 ossl_provider_get_params() calls the provider's parameter request
181 responder.
182 It should treat the given I<OSSL_PARAM> array as described in
183 L<OSSL_PARAM(3)>.
184
185 ossl_provider_query_operation() calls the provider's
186 I<query_operation> function, if the provider has one.
187 It should return an array of I<OSSL_ALGORITHM> for the given
188 I<operation_id>.
189
190 =head1 NOTES
191
192 Locating a provider module happens as follows:
193
194 =over 4
195
196 =item 1.
197
198 If a path was given with ossl_provider_set_module_path(), use that as
199 module path.
200 Otherwise, use the provider object's name as module path, with
201 platform specific standard extensions added.
202
203 =item 2.
204
205 If the environment variable B<OPENSSL_MODULES> is defined, assume its
206 value is a directory specification and merge it with the module path.
207 Otherwise, merge the value of the OpenSSL built in macro B<MODULESDIR>
208 with the module path.
209
210 =back
211
212 When this process is done, the result is used when trying to load the
213 provider module.
214
215 The command C<openssl version -m> can be used to find out the value
216 of the built in macro B<MODULESDIR>.
217
218 =head1 RETURN VALUES
219
220 ossl_provider_find() and ossl_provider_new() return a pointer to a
221 provider object (I<OSSL_PROVIDER>) on success, or NULL on error.
222
223 ossl_provider_up_ref() returns the value of the reference count after
224 it has been incremented.
225
226 ossl_provider_free() doesn't return any value.
227
228 ossl_provider_set_module_path(), ossl_provider_set_fallback() and
229 ossl_provider_activate() return 1 on success, or 0 on error.
230
231 ossl_provider_name(), ossl_provider_dso(),
232 ossl_provider_module_name(), and ossl_provider_module_path() return a
233 pointer to their respective data if it's available, otherwise NULL
234 is returned.
235
236 ossl_provider_teardown() doesnt't return any value.
237
238 ossl_provider_get_param_types() returns a pointer to a constant
239 I<OSSL_PARAM> array if this function is available in the provider,
240 otherwise NULL.
241
242 ossl_provider_get_params() returns 1 on success, or 0 on error.
243 If this function isn't available in the provider, 0 is returned.
244
245 =head1 SEE ALSO
246
247 L<OSSL_PROVIDER(3)>, L<provider(7)>, L<openssl(1)>
248
249 =head1 HISTORY
250
251 The functions described here were all added in OpenSSL 3.0.
252
253 =head1 COPYRIGHT
254
255 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
256
257 Licensed under the Apache License 2.0 (the "License").  You may not use
258 this file except in compliance with the License.  You can obtain a copy
259 in the file LICENSE in the source distribution or at
260 L<https://www.openssl.org/source/license.html>.
261
262 =cut