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