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