1OSSL_STORE_LOADER(3ossl)            OpenSSL           OSSL_STORE_LOADER(3ossl)
2
3
4

NAME

6       OSSL_STORE_LOADER, OSSL_STORE_LOADER_fetch, OSSL_STORE_LOADER_up_ref,
7       OSSL_STORE_LOADER_free, OSSL_STORE_LOADER_get0_provider,
8       OSSL_STORE_LOADER_get0_properties, OSSL_STORE_LOADER_is_a,
9       OSSL_STORE_LOADER_get0_description, OSSL_STORE_LOADER_do_all_provided,
10       OSSL_STORE_LOADER_names_do_all, OSSL_STORE_LOADER_CTX,
11       OSSL_STORE_LOADER_new, OSSL_STORE_LOADER_get0_engine,
12       OSSL_STORE_LOADER_get0_scheme, OSSL_STORE_LOADER_set_open,
13       OSSL_STORE_LOADER_set_open_ex, OSSL_STORE_LOADER_set_attach,
14       OSSL_STORE_LOADER_set_ctrl, OSSL_STORE_LOADER_set_expect,
15       OSSL_STORE_LOADER_set_find, OSSL_STORE_LOADER_set_load,
16       OSSL_STORE_LOADER_set_eof, OSSL_STORE_LOADER_set_error,
17       OSSL_STORE_LOADER_set_close, OSSL_STORE_register_loader,
18       OSSL_STORE_unregister_loader, OSSL_STORE_open_fn,
19       OSSL_STORE_open_ex_fn, OSSL_STORE_attach_fn, OSSL_STORE_ctrl_fn,
20       OSSL_STORE_expect_fn, OSSL_STORE_find_fn, OSSL_STORE_load_fn,
21       OSSL_STORE_eof_fn, OSSL_STORE_error_fn, OSSL_STORE_close_fn - Types and
22       functions to manipulate, register and unregister STORE loaders for
23       different URI schemes
24

SYNOPSIS

26        #include <openssl/store.h>
27
28        typedef struct ossl_store_loader_st OSSL_STORE_LOADER;
29
30        OSSL_STORE_LOADER *OSSL_STORE_LOADER_fetch(OSSL_LIB_CTX *libctx,
31                                                   const char *scheme,
32                                                   const char *properties);
33        int OSSL_STORE_LOADER_up_ref(OSSL_STORE_LOADER *loader);
34        void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *loader);
35        const OSSL_PROVIDER *OSSL_STORE_LOADER_get0_provider(const OSSL_STORE_LOADER *
36                                                        loader);
37        const char *OSSL_STORE_LOADER_get0_properties(const OSSL_STORE_LOADER *loader);
38        const char *OSSL_STORE_LOADER_get0_description(const OSSL_STORE_LOADER *loader);
39        int OSSL_STORE_LOADER_is_a(const OSSL_STORE_LOADER *loader,
40                                   const char *scheme);
41        void OSSL_STORE_LOADER_do_all_provided(OSSL_LIB_CTX *libctx,
42                                               void (*user_fn)(OSSL_STORE_LOADER *loader,
43                                                          void *arg),
44                                               void *user_arg);
45        int OSSL_STORE_LOADER_names_do_all(const OSSL_STORE_LOADER *loader,
46                                           void (*fn)(const char *name, void *data),
47                                           void *data);
48
49       The following functions have been deprecated since OpenSSL 3.0, and can
50       be hidden entirely by defining OPENSSL_API_COMPAT with a suitable
51       version value, see openssl_user_macros(7):
52
53        OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme);
54        const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER
55                                                    *store_loader);
56        const char *OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER
57                                                  *store_loader);
58
59        /* struct ossl_store_loader_ctx_st is defined differently by each loader */
60        typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX;
61
62        typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn)(
63            const char *uri, const UI_METHOD *ui_method, void *ui_data);
64        int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *store_loader,
65                                       OSSL_STORE_open_fn store_open_function);
66        typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_ex_fn)(
67            const char *uri, const UI_METHOD *ui_method, void *ui_data);
68        int OSSL_STORE_LOADER_set_open_ex
69            (OSSL_STORE_LOADER *store_loader,
70             OSSL_STORE_open_ex_fn store_open_ex_function);
71        typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_attach_fn)
72            (const OSSL_STORE_LOADER *loader, BIO *bio,
73             OSSL_LIB_CTX *libctx, const char *propq,
74             const UI_METHOD *ui_method, void *ui_data);
75        int OSSL_STORE_LOADER_set_attach(OSSL_STORE_LOADER *loader,
76                                         OSSL_STORE_attach_fn attach_function);
77        typedef int (*OSSL_STORE_ctrl_fn)(OSSL_STORE_LOADER_CTX *ctx, int cmd,
78                                          va_list args);
79        int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader,
80                                       OSSL_STORE_ctrl_fn store_ctrl_function);
81        typedef int (*OSSL_STORE_expect_fn)(OSSL_STORE_LOADER_CTX *ctx, int expected);
82        int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader,
83                                         OSSL_STORE_expect_fn expect_function);
84        typedef int (*OSSL_STORE_find_fn)(OSSL_STORE_LOADER_CTX *ctx,
85                                          OSSL_STORE_SEARCH *criteria);
86        int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader,
87                                       OSSL_STORE_find_fn find_function);
88        typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx,
89                                                       UI_METHOD *ui_method,
90                                                       void *ui_data);
91        int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *store_loader,
92                                       OSSL_STORE_load_fn store_load_function);
93        typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx);
94        int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER *store_loader,
95                                      OSSL_STORE_eof_fn store_eof_function);
96        typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx);
97        int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *store_loader,
98                                        OSSL_STORE_error_fn store_error_function);
99        typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx);
100        int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *store_loader,
101                                        OSSL_STORE_close_fn store_close_function);
102        void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *store_loader);
103
104        int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader);
105        OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme);
106

DESCRIPTION

108       OSSL_STORE_LOADER is a method for OSSL_STORE loaders, which implement
109       OSSL_STORE_open(), OSSL_STORE_open_ex(), OSSL_STORE_load(),
110       OSSL_STORE_eof(), OSSL_STORE_error() and OSSL_STORE_close() for
111       specific storage schemes.
112
113       OSSL_STORE_LOADER_fetch() looks for an implementation for a storage
114       scheme within the providers that has been loaded into the OSSL_LIB_CTX
115       given by libctx, and with the properties given by properties.
116
117       OSSL_STORE_LOADER_up_ref() increments the reference count for the given
118       loader.
119
120       OSSL_STORE_LOADER_free() decrements the reference count for the given
121       loader, and when the count reaches zero, frees it.
122
123       OSSL_STORE_LOADER_get0_provider() returns the provider of the given
124       loader.
125
126       OSSL_STORE_LOADER_get0_properties() returns the property definition
127       associated with the given loader.
128
129       OSSL_STORE_LOADER_is_a() checks if loader is an implementation of an
130       algorithm that's identifiable with scheme.
131
132       OSSL_STORE_LOADER_get0_description() returns a description of the
133       loader, meant for display and human consumption.  The description is at
134       the discretion of the loader implementation.
135
136       OSSL_STORE_LOADER_do_all_provided() traverses all store implementations
137       by all activated providers in the library context libctx, and for each
138       of the implementations, calls user_fn with the implementation method
139       and user_arg as arguments.
140
141       OSSL_STORE_LOADER_names_do_all() traverses all names for the given
142       loader, and calls fn with each name and data.
143
144   Legacy Types and Functions (deprecated)
145       These functions help applications and engines to create loaders for
146       schemes they support.  These are all deprecated and discouraged in
147       favour of provider implementations, see provider-storemgmt(7).
148
149       OSSL_STORE_LOADER_CTX is a type template, to be defined by each loader
150       using "struct ossl_store_loader_ctx_st { ... }".
151
152       OSSL_STORE_open_fn, OSSL_STORE_open_ex_fn, OSSL_STORE_ctrl_fn,
153       OSSL_STORE_expect_fn, OSSL_STORE_find_fn, OSSL_STORE_load_fn,
154       OSSL_STORE_eof_fn, and OSSL_STORE_close_fn are the function pointer
155       types used within a STORE loader.  The functions pointed at define the
156       functionality of the given loader.
157
158       OSSL_STORE_open_fn and OSSL_STORE_open_ex_fn
159           OSSL_STORE_open_ex_fn takes a URI and is expected to interpret it
160           in the best manner possible according to the scheme the loader
161           implements.  It also takes a UI_METHOD and associated data, to be
162           used any time something needs to be prompted for, as well as a
163           library context libctx with an associated property query propq, to
164           be used when fetching necessary algorithms to perform the loads.
165           Furthermore, this function is expected to initialize what needs to
166           be initialized, to create a private data store
167           (OSSL_STORE_LOADER_CTX, see above), and to return it.  If something
168           goes wrong, this function is expected to return NULL.
169
170           OSSL_STORE_open_fn does the same thing as OSSL_STORE_open_ex_fn but
171           uses NULL for the library context libctx and property query propq.
172
173       OSSL_STORE_attach_fn
174           This function takes a BIO, otherwise works like
175           OSSL_STORE_open_ex_fn.
176
177       OSSL_STORE_ctrl_fn
178           This function takes a OSSL_STORE_LOADER_CTX pointer, a command
179           number cmd and a va_list args and is used to manipulate loader
180           specific parameters.
181
182           Loader specific command numbers must begin at
183           OSSL_STORE_C_CUSTOM_START.  Any number below that is reserved for
184           future globally known command numbers.
185
186           This function is expected to return 1 on success, 0 on error.
187
188       OSSL_STORE_expect_fn
189           This function takes a OSSL_STORE_LOADER_CTX pointer and a
190           OSSL_STORE_INFO identity expected, and is used to tell the loader
191           what object type is expected.  expected may be zero to signify that
192           no specific object type is expected.
193
194           This function is expected to return 1 on success, 0 on error.
195
196       OSSL_STORE_find_fn
197           This function takes a OSSL_STORE_LOADER_CTX pointer and a
198           OSSL_STORE_SEARCH search criterion, and is used to tell the loader
199           what to search for.
200
201           When called with the loader context being NULL, this function is
202           expected to return 1 if the loader supports the criterion,
203           otherwise 0.
204
205           When called with the loader context being something other than
206           NULL, this function is expected to return 1 on success, 0 on error.
207
208       OSSL_STORE_load_fn
209           This function takes a OSSL_STORE_LOADER_CTX pointer and a UI_METHOD
210           with associated data.  It's expected to load the next available
211           data, mold it into a data structure that can be wrapped in a
212           OSSL_STORE_INFO using one of the OSSL_STORE_INFO(3) functions.  If
213           no more data is available or an error occurs, this function is
214           expected to return NULL.  The OSSL_STORE_eof_fn and
215           OSSL_STORE_error_fn functions must indicate if it was in fact the
216           end of data or if an error occurred.
217
218           Note that this function retrieves one data item only.
219
220       OSSL_STORE_eof_fn
221           This function takes a OSSL_STORE_LOADER_CTX pointer and is expected
222           to return 1 to indicate that the end of available data has been
223           reached.  It is otherwise expected to return 0.
224
225       OSSL_STORE_error_fn
226           This function takes a OSSL_STORE_LOADER_CTX pointer and is expected
227           to return 1 to indicate that an error occurred in a previous call
228           to the OSSL_STORE_load_fn function.  It is otherwise expected to
229           return 0.
230
231       OSSL_STORE_close_fn
232           This function takes a OSSL_STORE_LOADER_CTX pointer and is expected
233           to close or shut down what needs to be closed, and finally free the
234           contents of the OSSL_STORE_LOADER_CTX pointer.  It returns 1 on
235           success and 0 on error.
236
237       OSSL_STORE_LOADER_new() creates a new OSSL_STORE_LOADER.  It takes an
238       ENGINE e and a string scheme.  scheme must always be set.  Both e and
239       scheme are used as is and must therefore be alive as long as the
240       created loader is.
241
242       OSSL_STORE_LOADER_get0_engine() returns the engine of the store_loader.
243       OSSL_STORE_LOADER_get0_scheme() returns the scheme of the store_loader.
244
245       OSSL_STORE_LOADER_set_open() sets the opener function for the
246       store_loader.
247
248       OSSL_STORE_LOADER_set_open_ex() sets the opener with library context
249       function for the store_loader.
250
251       OSSL_STORE_LOADER_set_attach() sets the attacher function for the
252       store_loader.
253
254       OSSL_STORE_LOADER_set_ctrl() sets the control function for the
255       store_loader.
256
257       OSSL_STORE_LOADER_set_expect() sets the expect function for the
258       store_loader.
259
260       OSSL_STORE_LOADER_set_load() sets the loader function for the
261       store_loader.
262
263       OSSL_STORE_LOADER_set_eof() sets the end of file checker function for
264       the store_loader.
265
266       OSSL_STORE_LOADER_set_close() sets the closing function for the
267       store_loader.
268
269       OSSL_STORE_LOADER_free() frees the given store_loader.
270
271       OSSL_STORE_register_loader() register the given store_loader and
272       thereby makes it available for use with OSSL_STORE_open(),
273       OSSL_STORE_open_ex(), OSSL_STORE_load(), OSSL_STORE_eof() and
274       OSSL_STORE_close().
275
276       OSSL_STORE_unregister_loader() unregister the store loader for the
277       given scheme.
278

RETURN VALUES

280       OSSL_STORE_LOADER_fetch() returns a pointer to an OSSL_STORE_LOADER
281       object, or NULL on error.
282
283       OSSL_STORE_LOADER_up_ref() returns 1 on success, or 0 on error.
284
285       OSSL_STORE_LOADER_names_do_all() returns 1 if the callback was called
286       for all names. A return value of 0 means that the callback was not
287       called for any names.
288
289       OSSL_STORE_LOADER_free() doesn't return any value.
290
291       OSSL_STORE_LOADER_get0_provider() returns a pointer to a provider
292       object, or NULL on error.
293
294       OSSL_STORE_LOADER_get0_properties() returns a pointer to a property
295       definition string, or NULL on error.
296
297       OSSL_STORE_LOADER_is_a() returns 1 if loader was identifiable,
298       otherwise 0.
299
300       OSSL_STORE_LOADER_get0_description() returns a pointer to a decription,
301       or NULL if there isn't one.
302
303       The functions with the types OSSL_STORE_open_fn, OSSL_STORE_open_ex_fn,
304       OSSL_STORE_ctrl_fn, OSSL_STORE_expect_fn, OSSL_STORE_load_fn,
305       OSSL_STORE_eof_fn and OSSL_STORE_close_fn have the same return values
306       as OSSL_STORE_open(), OSSL_STORE_open_ex(), OSSL_STORE_ctrl(),
307       OSSL_STORE_expect(), OSSL_STORE_load(), OSSL_STORE_eof() and
308       OSSL_STORE_close(), respectively.
309
310       OSSL_STORE_LOADER_new() returns a pointer to a OSSL_STORE_LOADER on
311       success, or NULL on failure.
312
313       OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_open_ex(),
314       OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_load(),
315       OSSL_STORE_LOADER_set_eof() and OSSL_STORE_LOADER_set_close() return 1
316       on success, or 0 on failure.
317
318       OSSL_STORE_register_loader() returns 1 on success, or 0 on failure.
319
320       OSSL_STORE_unregister_loader() returns the unregistered loader on
321       success, or NULL on failure.
322

SEE ALSO

324       ossl_store(7), OSSL_STORE_open(3), OSSL_LIB_CTX(3),
325       provider-storemgmt(7)
326

HISTORY

328       OSSL_STORE_LOADER_fetch(), OSSL_STORE_LOADER_up_ref(),
329       OSSL_STORE_LOADER_free(), OSSL_STORE_LOADER_get0_provider(),
330       OSSL_STORE_LOADER_get0_properties(), OSSL_STORE_LOADER_is_a(),
331       OSSL_STORE_LOADER_do_all_provided() and
332       OSSL_STORE_LOADER_names_do_all() were added in OpenSSL 3.0.
333
334       OSSL_STORE_open_ex_fn() was added in OpenSSL 3.0.
335
336       OSSL_STORE_LOADER, OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new(),
337       OSSL_STORE_LOADER_set0_scheme(), OSSL_STORE_LOADER_get0_scheme(),
338       OSSL_STORE_LOADER_get0_engine(), OSSL_STORE_LOADER_set_expect(),
339       OSSL_STORE_LOADER_set_find(), OSSL_STORE_LOADER_set_attach(),
340       OSSL_STORE_LOADER_set_open_ex(), OSSL_STORE_LOADER_set_open(),
341       OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_load(),
342       OSSL_STORE_LOADER_set_eof(), OSSL_STORE_LOADER_set_close(),
343       OSSL_STORE_LOADER_free(), OSSL_STORE_register_loader(),
344       OSSL_STORE_LOADER_set_error(), OSSL_STORE_unregister_loader(),
345       OSSL_STORE_open_fn(), OSSL_STORE_ctrl_fn(), OSSL_STORE_load_fn(),
346       OSSL_STORE_eof_fn() and OSSL_STORE_close_fn() were added in OpenSSL
347       1.1.1, and became deprecated in OpenSSL 3.0.
348
350       Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved.
351
352       Licensed under the Apache License 2.0 (the "License").  You may not use
353       this file except in compliance with the License.  You can obtain a copy
354       in the file LICENSE in the source distribution or at
355       <https://www.openssl.org/source/license.html>.
356
357
358
3593.0.9                             2023-07-27          OSSL_STORE_LOADER(3ossl)
Impressum