xref: /openssl/doc/man3/OSSL_STORE_LOADER.pod (revision 7ed6de99) 
1=pod
2
3=head1 NAME
4
5OSSL_STORE_LOADER,
6OSSL_STORE_LOADER_fetch,
7OSSL_STORE_LOADER_up_ref,
8OSSL_STORE_LOADER_free,
9OSSL_STORE_LOADER_get0_provider,
10OSSL_STORE_LOADER_get0_properties,
11OSSL_STORE_LOADER_is_a,
12OSSL_STORE_LOADER_get0_description,
13OSSL_STORE_LOADER_do_all_provided,
14OSSL_STORE_LOADER_names_do_all,
15OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new,
16OSSL_STORE_LOADER_get0_engine, OSSL_STORE_LOADER_get0_scheme,
17OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_open_ex,
18OSSL_STORE_LOADER_set_attach, OSSL_STORE_LOADER_set_ctrl,
19OSSL_STORE_LOADER_set_expect, OSSL_STORE_LOADER_set_find,
20OSSL_STORE_LOADER_set_load, OSSL_STORE_LOADER_set_eof,
21OSSL_STORE_LOADER_set_error, OSSL_STORE_LOADER_set_close,
22OSSL_STORE_register_loader, OSSL_STORE_unregister_loader,
23OSSL_STORE_open_fn, OSSL_STORE_open_ex_fn,
24OSSL_STORE_attach_fn, OSSL_STORE_ctrl_fn,
25OSSL_STORE_expect_fn, OSSL_STORE_find_fn,
26OSSL_STORE_load_fn, OSSL_STORE_eof_fn, OSSL_STORE_error_fn,
27OSSL_STORE_close_fn - Types and functions to manipulate, register and
28unregister STORE loaders for different URI schemes
29
30=head1 SYNOPSIS
31
32 #include <openssl/store.h>
33
34 typedef struct ossl_store_loader_st OSSL_STORE_LOADER;
35
36 OSSL_STORE_LOADER *OSSL_STORE_LOADER_fetch(OSSL_LIB_CTX *libctx,
37                                            const char *scheme,
38                                            const char *properties);
39 int OSSL_STORE_LOADER_up_ref(OSSL_STORE_LOADER *loader);
40 void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *loader);
41 const OSSL_PROVIDER *OSSL_STORE_LOADER_get0_provider(const OSSL_STORE_LOADER *
42                                                 loader);
43 const char *OSSL_STORE_LOADER_get0_properties(const OSSL_STORE_LOADER *loader);
44 const char *OSSL_STORE_LOADER_get0_description(const OSSL_STORE_LOADER *loader);
45 int OSSL_STORE_LOADER_is_a(const OSSL_STORE_LOADER *loader,
46                            const char *scheme);
47 void OSSL_STORE_LOADER_do_all_provided(OSSL_LIB_CTX *libctx,
48                                        void (*user_fn)(OSSL_STORE_LOADER *loader,
49                                                   void *arg),
50                                        void *user_arg);
51 int OSSL_STORE_LOADER_names_do_all(const OSSL_STORE_LOADER *loader,
52                                    void (*fn)(const char *name, void *data),
53                                    void *data);
54
55The following functions have been deprecated since OpenSSL 3.0, and can be
56hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
57see L<openssl_user_macros(7)>:
58
59 OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme);
60 const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER
61                                             *store_loader);
62 const char *OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER
63                                           *store_loader);
64
65 /* struct ossl_store_loader_ctx_st is defined differently by each loader */
66 typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX;
67
68 typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn)(
69     const char *uri, const UI_METHOD *ui_method, void *ui_data);
70 int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *store_loader,
71                                OSSL_STORE_open_fn store_open_function);
72 typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_ex_fn)(
73     const char *uri, const UI_METHOD *ui_method, void *ui_data);
74 int OSSL_STORE_LOADER_set_open_ex
75     (OSSL_STORE_LOADER *store_loader,
76      OSSL_STORE_open_ex_fn store_open_ex_function);
77 typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_attach_fn)
78     (const OSSL_STORE_LOADER *loader, BIO *bio,
79      OSSL_LIB_CTX *libctx, const char *propq,
80      const UI_METHOD *ui_method, void *ui_data);
81 int OSSL_STORE_LOADER_set_attach(OSSL_STORE_LOADER *loader,
82                                  OSSL_STORE_attach_fn attach_function);
83 typedef int (*OSSL_STORE_ctrl_fn)(OSSL_STORE_LOADER_CTX *ctx, int cmd,
84                                   va_list args);
85 int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader,
86                                OSSL_STORE_ctrl_fn store_ctrl_function);
87 typedef int (*OSSL_STORE_expect_fn)(OSSL_STORE_LOADER_CTX *ctx, int expected);
88 int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader,
89                                  OSSL_STORE_expect_fn expect_function);
90 typedef int (*OSSL_STORE_find_fn)(OSSL_STORE_LOADER_CTX *ctx,
91                                   OSSL_STORE_SEARCH *criteria);
92 int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader,
93                                OSSL_STORE_find_fn find_function);
94 typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx,
95                                                UI_METHOD *ui_method,
96                                                void *ui_data);
97 int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *store_loader,
98                                OSSL_STORE_load_fn store_load_function);
99 typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx);
100 int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER *store_loader,
101                               OSSL_STORE_eof_fn store_eof_function);
102 typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx);
103 int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *store_loader,
104                                 OSSL_STORE_error_fn store_error_function);
105 typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx);
106 int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *store_loader,
107                                 OSSL_STORE_close_fn store_close_function);
108
109 int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader);
110 OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme);
111
112=head1 DESCRIPTION
113
114B<OSSL_STORE_LOADER> is a method for OSSL_STORE loaders, which implement
115OSSL_STORE_open(), OSSL_STORE_open_ex(), OSSL_STORE_load(),
116OSSL_STORE_eof(), OSSL_STORE_error() and OSSL_STORE_close() for specific
117storage schemes.
118
119OSSL_STORE_LOADER_fetch() looks for an implementation for a storage
120I<scheme> within the providers that has been loaded into the B<OSSL_LIB_CTX>
121given by I<libctx>, and with the properties given by I<properties>.
122
123OSSL_STORE_LOADER_up_ref() increments the reference count for the given
124I<loader>.
125
126OSSL_STORE_LOADER_free() decrements the reference count for the given
127I<loader>, and when the count reaches zero, frees it.
128If the argument is NULL, nothing is done.
129
130OSSL_STORE_LOADER_get0_provider() returns the provider of the given
131I<loader>.
132
133OSSL_STORE_LOADER_get0_properties() returns the property definition associated
134with the given I<loader>.
135
136OSSL_STORE_LOADER_is_a() checks if I<loader> is an implementation
137of an algorithm that's identifiable with I<scheme>.
138
139OSSL_STORE_LOADER_get0_description() returns a description of the I<loader>, meant
140for display and human consumption.  The description is at the discretion of the
141I<loader> implementation.
142
143OSSL_STORE_LOADER_do_all_provided() traverses all store implementations
144by all activated providers in the library context I<libctx>, and for each
145of the implementations, calls I<user_fn> with the implementation method and
146I<user_arg> as arguments.
147
148OSSL_STORE_LOADER_names_do_all() traverses all names for the given
149I<loader>, and calls I<fn> with each name and I<data>.
150
151=head2 Legacy Types and Functions (deprecated)
152
153These functions help applications and engines to create loaders for
154schemes they support.  These are all deprecated and discouraged in favour of
155provider implementations, see L<provider-storemgmt(7)>.
156
157B<OSSL_STORE_LOADER_CTX> is a type template, to be defined by each loader
158using C<struct ossl_store_loader_ctx_st { ... }>.
159
160B<OSSL_STORE_open_fn>, B<OSSL_STORE_open_ex_fn>,
161B<OSSL_STORE_ctrl_fn>, B<OSSL_STORE_expect_fn>, B<OSSL_STORE_find_fn>,
162B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn>, and B<OSSL_STORE_close_fn>
163are the function pointer types used within a STORE loader.
164The functions pointed at define the functionality of the given loader.
165
166=over 4
167
168=item B<OSSL_STORE_open_fn> and B<OSSL_STORE_open_ex_fn>
169
170B<OSSL_STORE_open_ex_fn> takes a URI and is expected to
171interpret it in the best manner possible according to the scheme the
172loader implements.  It also takes a B<UI_METHOD> and associated data,
173to be used any time something needs to be prompted for, as well as a
174library context I<libctx> with an associated property query I<propq>,
175to be used when fetching necessary algorithms to perform the loads.
176Furthermore, this function is expected to initialize what needs to be
177initialized, to create a private data store (B<OSSL_STORE_LOADER_CTX>,
178see above), and to return it.
179If something goes wrong, this function is expected to return NULL.
180
181B<OSSL_STORE_open_fn> does the same thing as
182B<OSSL_STORE_open_ex_fn> but uses NULL for the library
183context I<libctx> and property query I<propq>.
184
185=item B<OSSL_STORE_attach_fn>
186
187This function takes a B<BIO>, otherwise works like
188B<OSSL_STORE_open_ex_fn>.
189
190=item B<OSSL_STORE_ctrl_fn>
191
192This function takes a B<OSSL_STORE_LOADER_CTX> pointer, a command number
193I<cmd> and a B<va_list> I<args> and is used to manipulate loader
194specific parameters.
195
196=begin comment
197
198Globally known command numbers are documented in L<OSSL_STORE_ctrl(3)>,
199along with what I<args> are expected with each of them.
200
201=end comment
202
203Loader specific command numbers must begin at B<OSSL_STORE_C_CUSTOM_START>.
204Any number below that is reserved for future globally known command
205numbers.
206
207This function is expected to return 1 on success, 0 on error.
208
209=item B<OSSL_STORE_expect_fn>
210
211This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<OSSL_STORE_INFO>
212identity I<expected>, and is used to tell the loader what object type is
213expected.
214I<expected> may be zero to signify that no specific object type is expected.
215
216This function is expected to return 1 on success, 0 on error.
217
218=item B<OSSL_STORE_find_fn>
219
220This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a
221B<OSSL_STORE_SEARCH> search criterion, and is used to tell the loader what
222to search for.
223
224When called with the loader context being NULL, this function is expected
225to return 1 if the loader supports the criterion, otherwise 0.
226
227When called with the loader context being something other than NULL, this
228function is expected to return 1 on success, 0 on error.
229
230=item B<OSSL_STORE_load_fn>
231
232This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<UI_METHOD>
233with associated data.
234It's expected to load the next available data, mold it into a data
235structure that can be wrapped in a B<OSSL_STORE_INFO> using one of the
236L<OSSL_STORE_INFO(3)> functions.
237If no more data is available or an error occurs, this function is
238expected to return NULL.
239The B<OSSL_STORE_eof_fn> and B<OSSL_STORE_error_fn> functions must indicate if
240it was in fact the end of data or if an error occurred.
241
242Note that this function retrieves I<one> data item only.
243
244=item B<OSSL_STORE_eof_fn>
245
246This function takes a B<OSSL_STORE_LOADER_CTX> pointer and is expected to
247return 1 to indicate that the end of available data has been reached.
248It is otherwise expected to return 0.
249
250=item B<OSSL_STORE_error_fn>
251
252This function takes a B<OSSL_STORE_LOADER_CTX> pointer and is expected to
253return 1 to indicate that an error occurred in a previous call to the
254B<OSSL_STORE_load_fn> function.
255It is otherwise expected to return 0.
256
257=item B<OSSL_STORE_close_fn>
258
259This function takes a B<OSSL_STORE_LOADER_CTX> pointer and is expected to
260close or shut down what needs to be closed, and finally free the
261contents of the B<OSSL_STORE_LOADER_CTX> pointer.
262It returns 1 on success and 0 on error.
263
264=back
265
266OSSL_STORE_LOADER_new() creates a new B<OSSL_STORE_LOADER>.
267It takes an B<ENGINE> I<e> and a string I<scheme>.
268I<scheme> must I<always> be set.
269Both I<e> and I<scheme> are used as is and must therefore be alive as
270long as the created loader is.
271
272OSSL_STORE_LOADER_get0_engine() returns the engine of the I<store_loader>.
273OSSL_STORE_LOADER_get0_scheme() returns the scheme of the I<store_loader>.
274
275OSSL_STORE_LOADER_set_open() sets the opener function for the
276I<store_loader>.
277
278OSSL_STORE_LOADER_set_open_ex() sets the opener with library context
279function for the I<store_loader>.
280
281OSSL_STORE_LOADER_set_attach() sets the attacher function for the
282I<store_loader>.
283
284OSSL_STORE_LOADER_set_ctrl() sets the control function for the
285I<store_loader>.
286
287OSSL_STORE_LOADER_set_expect() sets the expect function for the
288I<store_loader>.
289
290OSSL_STORE_LOADER_set_load() sets the loader function for the
291I<store_loader>.
292
293OSSL_STORE_LOADER_set_eof() sets the end of file checker function for the
294I<store_loader>.
295
296OSSL_STORE_LOADER_set_close() sets the closing function for the
297I<store_loader>.
298
299OSSL_STORE_LOADER_free() frees the given I<store_loader>.
300If the argument is NULL, nothing is done.
301
302OSSL_STORE_register_loader() register the given I<store_loader> and
303thereby makes it available for use with OSSL_STORE_open(),
304OSSL_STORE_open_ex(), OSSL_STORE_load(), OSSL_STORE_eof()
305and OSSL_STORE_close().
306
307OSSL_STORE_unregister_loader() unregister the store loader for the given
308I<scheme>.
309
310=head1 RETURN VALUES
311
312OSSL_STORE_LOADER_fetch() returns a pointer to an OSSL_STORE_LOADER object,
313or NULL on error.
314
315OSSL_STORE_LOADER_up_ref() returns 1 on success, or 0 on error.
316
317OSSL_STORE_LOADER_names_do_all() returns 1 if the callback was called for all
318names. A return value of 0 means that the callback was not called for any names.
319
320OSSL_STORE_LOADER_free() doesn't return any value.
321
322OSSL_STORE_LOADER_get0_provider() returns a pointer to a provider object, or
323NULL on error.
324
325OSSL_STORE_LOADER_get0_properties() returns a pointer to a property
326definition string, or NULL on error.
327
328OSSL_STORE_LOADER_is_a() returns 1 if I<loader> was identifiable,
329otherwise 0.
330
331OSSL_STORE_LOADER_get0_description() returns a pointer to a description, or NULL if
332there isn't one.
333
334The functions with the types B<OSSL_STORE_open_fn>,
335B<OSSL_STORE_open_ex_fn>, B<OSSL_STORE_ctrl_fn>,
336B<OSSL_STORE_expect_fn>, B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn>
337and B<OSSL_STORE_close_fn> have the same return values as OSSL_STORE_open(),
338OSSL_STORE_open_ex(), OSSL_STORE_ctrl(), OSSL_STORE_expect(),
339OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close(), respectively.
340
341OSSL_STORE_LOADER_new() returns a pointer to a B<OSSL_STORE_LOADER> on success,
342or NULL on failure.
343
344OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_open_ex(),
345OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_load(),
346OSSL_STORE_LOADER_set_eof() and OSSL_STORE_LOADER_set_close() return 1
347on success, or 0 on failure.
348
349OSSL_STORE_register_loader() returns 1 on success, or 0 on failure.
350
351OSSL_STORE_unregister_loader() returns the unregistered loader on success,
352or NULL on failure.
353
354=head1 SEE ALSO
355
356L<ossl_store(7)>, L<OSSL_STORE_open(3)>, L<OSSL_LIB_CTX(3)>,
357L<provider-storemgmt(7)>
358
359=head1 HISTORY
360
361OSSL_STORE_LOADER_fetch(), OSSL_STORE_LOADER_up_ref(),
362OSSL_STORE_LOADER_get0_provider(), OSSL_STORE_LOADER_get0_properties(),
363OSSL_STORE_LOADER_get0_description(), OSSL_STORE_LOADER_is_a(),
364OSSL_STORE_LOADER_do_all_provided() and OSSL_STORE_LOADER_names_do_all()
365were added in OpenSSL 3.0.
366
367B<OSSL_STORE_LOADER> and OSSL_STORE_LOADER_free() were added in OpenSSL
3681.1.1.
369
370OSSL_STORE_LOADER_set_open_ex() and OSSL_STORE_open_ex_fn() were added in
371OpenSSL 3.0, and are deprecated.
372
373B<OSSL_STORE_LOADER_CTX>, OSSL_STORE_LOADER_new(),
374OSSL_STORE_LOADER_set0_scheme(), OSSL_STORE_LOADER_get0_scheme(),
375OSSL_STORE_LOADER_get0_engine(), OSSL_STORE_LOADER_set_expect(),
376OSSL_STORE_LOADER_set_find(), OSSL_STORE_LOADER_set_attach(),
377OSSL_STORE_LOADER_set_open_ex(), OSSL_STORE_LOADER_set_open(),
378OSSL_STORE_LOADER_set_ctrl(),
379OSSL_STORE_LOADER_set_load(), OSSL_STORE_LOADER_set_eof(),
380OSSL_STORE_LOADER_set_close(),
381OSSL_STORE_register_loader(), OSSL_STORE_LOADER_set_error(),
382OSSL_STORE_unregister_loader(), OSSL_STORE_open_fn(), OSSL_STORE_ctrl_fn(),
383OSSL_STORE_load_fn(), OSSL_STORE_eof_fn() and OSSL_STORE_close_fn()
384were added in OpenSSL 1.1.1, and became deprecated in OpenSSL 3.0.
385
386=head1 COPYRIGHT
387
388Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved.
389
390Licensed under the Apache License 2.0 (the "License").  You may not use
391this file except in compliance with the License.  You can obtain a copy
392in the file LICENSE in the source distribution or at
393L<https://www.openssl.org/source/license.html>.
394
395=cut
396