xref: /freebsd/crypto/openssl/doc/man3/OSSL_STORE_LOADER.pod (revision 19261079b74319502c6ffa1249920079f0f69a72) 
1=pod
2
3=head1 NAME
4
5OSSL_STORE_LOADER, OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new,
6OSSL_STORE_LOADER_get0_engine, OSSL_STORE_LOADER_get0_scheme,
7OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_ctrl,
8OSSL_STORE_LOADER_set_expect, OSSL_STORE_LOADER_set_find,
9OSSL_STORE_LOADER_set_load, OSSL_STORE_LOADER_set_eof,
10OSSL_STORE_LOADER_set_error, OSSL_STORE_LOADER_set_close,
11OSSL_STORE_LOADER_free, OSSL_STORE_register_loader,
12OSSL_STORE_unregister_loader, OSSL_STORE_open_fn, OSSL_STORE_ctrl_fn,
13OSSL_STORE_expect_fn, OSSL_STORE_find_fn,
14OSSL_STORE_load_fn, OSSL_STORE_eof_fn, OSSL_STORE_error_fn,
15OSSL_STORE_close_fn - Types and functions to manipulate, register and
16unregister STORE loaders for different URI schemes
17
18=head1 SYNOPSIS
19
20 #include <openssl/store.h>
21
22 typedef struct ossl_store_loader_st OSSL_STORE_LOADER;
23
24 OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme);
25 const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER
26                                             *store_loader);
27 const char *OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER
28                                           *store_loader);
29
30 /* struct ossl_store_loader_ctx_st is defined differently by each loader */
31 typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX;
32
33 typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn)(const char *uri,
34                                                      const UI_METHOD *ui_method,
35                                                      void *ui_data);
36 int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *store_loader,
37                                OSSL_STORE_open_fn store_open_function);
38 typedef int (*OSSL_STORE_ctrl_fn)(OSSL_STORE_LOADER_CTX *ctx, int cmd,
39                                   va_list args);
40 int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader,
41                                OSSL_STORE_ctrl_fn store_ctrl_function);
42 typedef int (*OSSL_STORE_expect_fn)(OSSL_STORE_LOADER_CTX *ctx, int expected);
43 int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader,
44                                  OSSL_STORE_expect_fn expect_function);
45 typedef int (*OSSL_STORE_find_fn)(OSSL_STORE_LOADER_CTX *ctx,
46                                   OSSL_STORE_SEARCH *criteria);
47 int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader,
48                                OSSL_STORE_find_fn find_function);
49 typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx,
50                                                UI_METHOD *ui_method,
51                                                void *ui_data);
52 int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *store_loader,
53                                OSSL_STORE_load_fn store_load_function);
54 typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx);
55 int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER *store_loader,
56                               OSSL_STORE_eof_fn store_eof_function);
57 typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx);
58 int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *store_loader,
59                                 OSSL_STORE_error_fn store_error_function);
60 typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx);
61 int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *store_loader,
62                                 OSSL_STORE_close_fn store_close_function);
63 void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *store_loader);
64
65 int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader);
66 OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme);
67
68=head1 DESCRIPTION
69
70These functions help applications and engines to create loaders for
71schemes they support.
72
73=head2 Types
74
75B<OSSL_STORE_LOADER> is the type to hold a loader.
76It contains a scheme and the functions needed to implement
77OSSL_STORE_open(), OSSL_STORE_load(), OSSL_STORE_eof(), OSSL_STORE_error() and
78OSSL_STORE_close() for this scheme.
79
80B<OSSL_STORE_LOADER_CTX> is a type template, to be defined by each loader
81using B<struct ossl_store_loader_ctx_st { ... }>.
82
83B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>, B<OSSL_STORE_expect_fn>,
84B<OSSL_STORE_find_fn>, B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn>,
85and B<OSSL_STORE_close_fn>
86are the function pointer types used within a STORE loader.
87The functions pointed at define the functionality of the given loader.
88
89=over 4
90
91=item B<OSSL_STORE_open_fn>
92
93This function takes a URI and is expected to interpret it in the best
94manner possible according to the scheme the loader implements, it also
95takes a B<UI_METHOD> and associated data, to be used any time
96something needs to be prompted for.
97Furthermore, this function is expected to initialize what needs to be
98initialized, to create a private data store (B<OSSL_STORE_LOADER_CTX>, see
99above), and to return it.
100If something goes wrong, this function is expected to return NULL.
101
102=item B<OSSL_STORE_ctrl_fn>
103
104This function takes a B<OSSL_STORE_LOADER_CTX> pointer, a command number
105B<cmd> and a B<va_list> B<args> and is used to manipulate loader
106specific parameters.
107
108=begin comment
109
110Globally known command numbers are documented in L<OSSL_STORE_ctrl(3)>,
111along with what B<args> are expected with each of them.
112
113=end comment
114
115Loader specific command numbers must begin at B<OSSL_STORE_C_CUSTOM_START>.
116Any number below that is reserved for future globally known command
117numbers.
118
119This function is expected to return 1 on success, 0 on error.
120
121=item B<OSSL_STORE_expect_fn>
122
123This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<OSSL_STORE_INFO>
124identity B<expected>, and is used to tell the loader what object type is
125expected.
126B<expected> may be zero to signify that no specific object type is expected.
127
128This function is expected to return 1 on success, 0 on error.
129
130=item B<OSSL_STORE_find_fn>
131
132This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a
133B<OSSL_STORE_SEARCH> search criterion, and is used to tell the loader what
134to search for.
135
136When called with the loader context being B<NULL>, this function is expected
137to return 1 if the loader supports the criterion, otherwise 0.
138
139When called with the loader context being something other than B<NULL>, this
140function is expected to return 1 on success, 0 on error.
141
142=item B<OSSL_STORE_load_fn>
143
144This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<UI_METHOD>
145with associated data.
146It's expected to load the next available data, mold it into a data
147structure that can be wrapped in a B<OSSL_STORE_INFO> using one of the
148L<OSSL_STORE_INFO(3)> functions.
149If no more data is available or an error occurs, this function is
150expected to return NULL.
151The B<OSSL_STORE_eof_fn> and B<OSSL_STORE_error_fn> functions must indicate if
152it was in fact the end of data or if an error occurred.
153
154Note that this function retrieves I<one> data item only.
155
156=item B<OSSL_STORE_eof_fn>
157
158This function takes a B<OSSL_STORE_LOADER_CTX> pointer and is expected to
159return 1 to indicate that the end of available data has been reached.
160It is otherwise expected to return 0.
161
162=item B<OSSL_STORE_error_fn>
163
164This function takes a B<OSSL_STORE_LOADER_CTX> pointer and is expected to
165return 1 to indicate that an error occurred in a previous call to the
166B<OSSL_STORE_load_fn> function.
167It is otherwise expected to return 0.
168
169=item B<OSSL_STORE_close_fn>
170
171This function takes a B<OSSL_STORE_LOADER_CTX> pointer and is expected to
172close or shut down what needs to be closed, and finally free the
173contents of the B<OSSL_STORE_LOADER_CTX> pointer.
174It returns 1 on success and 0 on error.
175
176=back
177
178=head2 Functions
179
180OSSL_STORE_LOADER_new() creates a new B<OSSL_STORE_LOADER>.
181It takes an B<ENGINE> B<e> and a string B<scheme>.
182B<scheme> must I<always> be set.
183Both B<e> and B<scheme> are used as is and must therefore be alive as
184long as the created loader is.
185
186OSSL_STORE_LOADER_get0_engine() returns the engine of the B<store_loader>.
187OSSL_STORE_LOADER_get0_scheme() returns the scheme of the B<store_loader>.
188
189OSSL_STORE_LOADER_set_open() sets the opener function for the
190B<store_loader>.
191
192OSSL_STORE_LOADER_set_ctrl() sets the control function for the
193B<store_loader>.
194
195OSSL_STORE_LOADER_set_expect() sets the expect function for the
196B<store_loader>.
197
198OSSL_STORE_LOADER_set_load() sets the loader function for the
199B<store_loader>.
200
201OSSL_STORE_LOADER_set_eof() sets the end of file checker function for the
202B<store_loader>.
203
204OSSL_STORE_LOADER_set_close() sets the closing function for the
205B<store_loader>.
206
207OSSL_STORE_LOADER_free() frees the given B<store_loader>.
208
209OSSL_STORE_register_loader() register the given B<store_loader> and thereby
210makes it available for use with OSSL_STORE_open(), OSSL_STORE_load(),
211OSSL_STORE_eof() and OSSL_STORE_close().
212
213OSSL_STORE_unregister_loader() unregister the store loader for the given
214B<scheme>.
215
216=head1 NOTES
217
218The B<file:> scheme has built in support.
219
220=head1 RETURN VALUES
221
222The functions with the types B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>,
223B<OSSL_STORE_expect_fn>,
224B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn> and B<OSSL_STORE_close_fn> have the
225same return values as OSSL_STORE_open(), OSSL_STORE_ctrl(), OSSL_STORE_expect(),
226OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close(), respectively.
227
228OSSL_STORE_LOADER_new() returns a pointer to a B<OSSL_STORE_LOADER> on success,
229or B<NULL> on failure.
230
231OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_ctrl(),
232OSSL_STORE_LOADER_set_load(), OSSL_STORE_LOADER_set_eof() and
233OSSL_STORE_LOADER_set_close() return 1 on success, or 0 on failure.
234
235OSSL_STORE_register_loader() returns 1 on success, or 0 on failure.
236
237OSSL_STORE_unregister_loader() returns the unregistered loader on success,
238or B<NULL> on failure.
239
240=head1 SEE ALSO
241
242L<ossl_store(7)>, L<OSSL_STORE_open(3)>
243
244=head1 HISTORY
245
246OSSL_STORE_LOADER(), OSSL_STORE_LOADER_CTX(), OSSL_STORE_LOADER_new(),
247OSSL_STORE_LOADER_set0_scheme(), OSSL_STORE_LOADER_set_open(),
248OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_load(),
249OSSL_STORE_LOADER_set_eof(), OSSL_STORE_LOADER_set_close(),
250OSSL_STORE_LOADER_free(), OSSL_STORE_register_loader(),
251OSSL_STORE_unregister_loader(), OSSL_STORE_open_fn(), OSSL_STORE_ctrl_fn(),
252OSSL_STORE_load_fn(), OSSL_STORE_eof_fn() and OSSL_STORE_close_fn()
253were added in OpenSSL 1.1.1.
254
255=head1 COPYRIGHT
256
257Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved.
258
259Licensed under the OpenSSL license (the "License").  You may not use
260this file except in compliance with the License.  You can obtain a copy
261in the file LICENSE in the source distribution or at
262L<https://www.openssl.org/source/license.html>.
263
264=cut
265