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