Replumbing: add fallback provider capability
[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_upref,
6 ossl_provider_free, ossl_provider_add_module_location,
7 ossl_provider_set_fallback, ossl_provider_activate,
8 ossl_provider_forall_loaded,
9 ossl_provider_name, ossl_provider_dso,
10 ossl_provider_module_name, ossl_provider_module_path,
11 ossl_provider_teardown, ossl_provider_get_param_types,
12 ossl_provider_get_params, ossl_provider_query_operation
13 - internal provider routines
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);
27  int ossl_provider_set_fallback(OSSL_PROVIDER *prov);
28
29  /* Load and initialize the Provider */
30  int ossl_provider_activate(OSSL_PROVIDER *prov);
31
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
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[]);
49  const OSSL_ALGORITHM *ossl_provider_query_operation(const OSSL_PROVIDER *prov,
50                                                      int operation_id,
51                                                      int *no_cache);
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>.
76 The I<provider object> it finds gets its reference count
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
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.
95
96 ossl_provider_add_module_location() adds a location to look for a
97 provider module.
98
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
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
124 ossl_provider_forall_loaded() iterates over all the currently
125 "activated" providers, and calls C<cb> for each of them.
126 If no providers have been "activated" yet, it tries to activate all
127 available fallback providers and tries another iteration.
128
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
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
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
191 ossl_provider_add_module_location(), ossl_provider_set_fallback() and
192 ossl_provider_activate() return 1 on success, or 0 on error.
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