1OSSL_STORE_LOADER(3ossl) OpenSSL OSSL_STORE_LOADER(3ossl)
2
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
26 #include <openssl/store.h>
27 typedef struct ossl_store_loader_st OSSL_STORE_LOADER;
29 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 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 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 /* 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 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 int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader);
105 OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme);
106
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 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 OSSL_STORE_LOADER_up_ref() increments the reference count for the given
118 loader.
119 OSSL_STORE_LOADER_free() decrements the reference count for the given
121 loader, and when the count reaches zero, frees it.
122 OSSL_STORE_LOADER_get0_provider() returns the provider of the given
124 loader.
125 OSSL_STORE_LOADER_get0_properties() returns the property definition
127 associated with the given loader.
128 OSSL_STORE_LOADER_is_a() checks if loader is an implementation of an
130 algorithm that's identifiable with scheme.
131 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 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 OSSL_STORE_LOADER_names_do_all() traverses all names for the given
142 loader, and calls fn with each name and data.
143 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 OSSL_STORE_LOADER_CTX is a type template, to be defined by each loader
150 using "struct ossl_store_loader_ctx_st { ... }".
151 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 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 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 OSSL_STORE_attach_fn
174 This function takes a BIO, otherwise works like
175 OSSL_STORE_open_ex_fn.
176 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 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 This function is expected to return 1 on success, 0 on error.
187 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 This function is expected to return 1 on success, 0 on error.
195 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 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 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 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 Note that this function retrieves one data item only.
219 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 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 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 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 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 OSSL_STORE_LOADER_set_open() sets the opener function for the
246 store_loader.
247 OSSL_STORE_LOADER_set_open_ex() sets the opener with library context
249 function for the store_loader.
250 OSSL_STORE_LOADER_set_attach() sets the attacher function for the
252 store_loader.
253 OSSL_STORE_LOADER_set_ctrl() sets the control function for the
255 store_loader.
256 OSSL_STORE_LOADER_set_expect() sets the expect function for the
258 store_loader.
259 OSSL_STORE_LOADER_set_load() sets the loader function for the
261 store_loader.
262 OSSL_STORE_LOADER_set_eof() sets the end of file checker function for
264 the store_loader.
265 OSSL_STORE_LOADER_set_close() sets the closing function for the
267 store_loader.
268 OSSL_STORE_LOADER_free() frees the given store_loader.
270 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 OSSL_STORE_unregister_loader() unregister the store loader for the
277 given scheme.
278
280 OSSL_STORE_LOADER_fetch() returns a pointer to an OSSL_STORE_LOADER
281 object, or NULL on error.
282 OSSL_STORE_LOADER_up_ref() returns 1 on success, or 0 on error.
284 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 OSSL_STORE_LOADER_free() doesn't return any value.
290 OSSL_STORE_LOADER_get0_provider() returns a pointer to a provider
292 object, or NULL on error.
293 OSSL_STORE_LOADER_get0_properties() returns a pointer to a property
295 definition string, or NULL on error.
296 OSSL_STORE_LOADER_is_a() returns 1 if loader was identifiable,
298 otherwise 0.
299 OSSL_STORE_LOADER_get0_description() returns a pointer to a
301 description, or NULL if there isn't one.
302 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 OSSL_STORE_LOADER_new() returns a pointer to a OSSL_STORE_LOADER on
311 success, or NULL on failure.
312 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 OSSL_STORE_register_loader() returns 1 on success, or 0 on failure.
319 OSSL_STORE_unregister_loader() returns the unregistered loader on
321 success, or NULL on failure.
322
324 ossl_store(7), OSSL_STORE_open(3), OSSL_LIB_CTX(3),
325 provider-storemgmt(7)
326
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 OSSL_STORE_open_ex_fn() was added in OpenSSL 3.0.
335 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-2022 The OpenSSL Project Authors. All Rights Reserved.
351 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>.
3563.1.1 2023-08-31 OSSL_STORE_LOADER(3ossl)