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