xref: /freebsd/crypto/openssl/doc/man3/OSSL_STORE_LOADER.pod (revision 535af610a4fdace6d50960c0ad9be0597eea7a1b)
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 void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *store_loader);
109
110 int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader);
111 OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme);
112
113=head1 DESCRIPTION
114
115B<OSSL_STORE_LOADER> is a method for OSSL_STORE loaders, which implement
116OSSL_STORE_open(), OSSL_STORE_open_ex(), OSSL_STORE_load(),
117OSSL_STORE_eof(), OSSL_STORE_error() and OSSL_STORE_close() for specific
118storage schemes.
119
120OSSL_STORE_LOADER_fetch() looks for an implementation for a storage
121I<scheme> within the providers that has been loaded into the B<OSSL_LIB_CTX>
122given by I<libctx>, and with the properties given by I<properties>.
123
124OSSL_STORE_LOADER_up_ref() increments the reference count for the given
125I<loader>.
126
127OSSL_STORE_LOADER_free() decrements the reference count for the given
128I<loader>, and when the count reaches zero, frees it.
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>.
300
301OSSL_STORE_register_loader() register the given I<store_loader> and
302thereby makes it available for use with OSSL_STORE_open(),
303OSSL_STORE_open_ex(), OSSL_STORE_load(), OSSL_STORE_eof()
304and OSSL_STORE_close().
305
306OSSL_STORE_unregister_loader() unregister the store loader for the given
307I<scheme>.
308
309=head1 RETURN VALUES
310
311OSSL_STORE_LOADER_fetch() returns a pointer to an OSSL_STORE_LOADER object,
312or NULL on error.
313
314OSSL_STORE_LOADER_up_ref() returns 1 on success, or 0 on error.
315
316OSSL_STORE_LOADER_names_do_all() returns 1 if the callback was called for all
317names. A return value of 0 means that the callback was not called for any names.
318
319OSSL_STORE_LOADER_free() doesn't return any value.
320
321OSSL_STORE_LOADER_get0_provider() returns a pointer to a provider object, or
322NULL on error.
323
324OSSL_STORE_LOADER_get0_properties() returns a pointer to a property
325definition string, or NULL on error.
326
327OSSL_STORE_LOADER_is_a() returns 1 if I<loader> was identifiable,
328otherwise 0.
329
330OSSL_STORE_LOADER_get0_description() returns a pointer to a description, or NULL if
331there isn't one.
332
333The functions with the types B<OSSL_STORE_open_fn>,
334B<OSSL_STORE_open_ex_fn>, B<OSSL_STORE_ctrl_fn>,
335B<OSSL_STORE_expect_fn>, B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn>
336and B<OSSL_STORE_close_fn> have the same return values as OSSL_STORE_open(),
337OSSL_STORE_open_ex(), OSSL_STORE_ctrl(), OSSL_STORE_expect(),
338OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close(), respectively.
339
340OSSL_STORE_LOADER_new() returns a pointer to a B<OSSL_STORE_LOADER> on success,
341or NULL on failure.
342
343OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_open_ex(),
344OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_load(),
345OSSL_STORE_LOADER_set_eof() and OSSL_STORE_LOADER_set_close() return 1
346on success, or 0 on failure.
347
348OSSL_STORE_register_loader() returns 1 on success, or 0 on failure.
349
350OSSL_STORE_unregister_loader() returns the unregistered loader on success,
351or NULL on failure.
352
353=head1 SEE ALSO
354
355L<ossl_store(7)>, L<OSSL_STORE_open(3)>, L<OSSL_LIB_CTX(3)>,
356L<provider-storemgmt(7)>
357
358=head1 HISTORY
359
360OSSL_STORE_LOADER_fetch(), OSSL_STORE_LOADER_up_ref(),
361OSSL_STORE_LOADER_free(), OSSL_STORE_LOADER_get0_provider(),
362OSSL_STORE_LOADER_get0_properties(), OSSL_STORE_LOADER_is_a(),
363OSSL_STORE_LOADER_do_all_provided() and
364OSSL_STORE_LOADER_names_do_all() were added in OpenSSL 3.0.
365
366OSSL_STORE_open_ex_fn() was added in OpenSSL 3.0.
367
368B<OSSL_STORE_LOADER>, B<OSSL_STORE_LOADER_CTX>, OSSL_STORE_LOADER_new(),
369OSSL_STORE_LOADER_set0_scheme(), OSSL_STORE_LOADER_get0_scheme(),
370OSSL_STORE_LOADER_get0_engine(), OSSL_STORE_LOADER_set_expect(),
371OSSL_STORE_LOADER_set_find(), OSSL_STORE_LOADER_set_attach(),
372OSSL_STORE_LOADER_set_open_ex(), OSSL_STORE_LOADER_set_open(),
373OSSL_STORE_LOADER_set_ctrl(),
374OSSL_STORE_LOADER_set_load(), OSSL_STORE_LOADER_set_eof(),
375OSSL_STORE_LOADER_set_close(), OSSL_STORE_LOADER_free(),
376OSSL_STORE_register_loader(), OSSL_STORE_LOADER_set_error(),
377OSSL_STORE_unregister_loader(), OSSL_STORE_open_fn(), OSSL_STORE_ctrl_fn(),
378OSSL_STORE_load_fn(), OSSL_STORE_eof_fn() and OSSL_STORE_close_fn()
379were added in OpenSSL 1.1.1, and became deprecated in OpenSSL 3.0.
380
381=head1 COPYRIGHT
382
383Copyright 2016-2023 The OpenSSL Project Authors. All Rights Reserved.
384
385Licensed under the Apache License 2.0 (the "License").  You may not use
386this file except in compliance with the License.  You can obtain a copy
387in the file LICENSE in the source distribution or at
388L<https://www.openssl.org/source/license.html>.
389
390=cut
391