1OSSL_STORE_LOADER(3) OpenSSL OSSL_STORE_LOADER(3)
2
6 OSSL_STORE_LOADER, OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new,
7 OSSL_STORE_LOADER_get0_engine, OSSL_STORE_LOADER_get0_scheme,
8 OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_ctrl,
9 OSSL_STORE_LOADER_set_expect, OSSL_STORE_LOADER_set_find,
10 OSSL_STORE_LOADER_set_load, OSSL_STORE_LOADER_set_eof,
11 OSSL_STORE_LOADER_set_error, OSSL_STORE_LOADER_set_close,
12 OSSL_STORE_LOADER_free, OSSL_STORE_register_loader,
13 OSSL_STORE_unregister_loader, OSSL_STORE_open_fn, OSSL_STORE_ctrl_fn,
14 OSSL_STORE_expect_fn, OSSL_STORE_find_fn, OSSL_STORE_load_fn,
15 OSSL_STORE_eof_fn, OSSL_STORE_error_fn, OSSL_STORE_close_fn - Types and
16 functions to manipulate, register and unregister STORE loaders for
17 different URI schemes
18
20 #include <openssl/store.h>
21 typedef struct ossl_store_loader_st OSSL_STORE_LOADER;
23 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 /* 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 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 int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader);
66 OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme);
67
69 These functions help applications and engines to create loaders for
70 schemes they support.
71 Types
73 OSSL_STORE_LOADER is the type to hold a loader. It contains a scheme
74 and the functions needed to implement OSSL_STORE_open(),
75 OSSL_STORE_load(), OSSL_STORE_eof(), OSSL_STORE_error() and
76 OSSL_STORE_close() for this scheme.
77 OSSL_STORE_LOADER_CTX is a type template, to be defined by each loader
79 using struct ossl_store_loader_ctx_st { ... }.
80 OSSL_STORE_open_fn, OSSL_STORE_ctrl_fn, OSSL_STORE_expect_fn,
82 OSSL_STORE_find_fn, OSSL_STORE_load_fn, OSSL_STORE_eof_fn, and
83 OSSL_STORE_close_fn are the function pointer types used within a STORE
84 loader. The functions pointed at define the functionality of the given
85 loader.
86 OSSL_STORE_open_fn
88 This function takes a URI and is expected to interpret it in the
89 best manner possible according to the scheme the loader implements,
90 it also takes a UI_METHOD and associated data, to be used any time
91 something needs to be prompted for. Furthermore, this function is
92 expected to initialize what needs to be initialized, to create a
93 private data store (OSSL_STORE_LOADER_CTX, see above), and to
94 return it. If something goes wrong, this function is expected to
95 return NULL.
96 OSSL_STORE_ctrl_fn
98 This function takes a OSSL_STORE_LOADER_CTX pointer, a command
99 number cmd and a va_list args and is used to manipulate loader
100 specific parameters.
101 Loader specific command numbers must begin at
103 OSSL_STORE_C_CUSTOM_START. Any number below that is reserved for
104 future globally known command numbers.
105 This function is expected to return 1 on success, 0 on error.
107 OSSL_STORE_expect_fn
109 This function takes a OSSL_STORE_LOADER_CTX pointer and a
110 OSSL_STORE_INFO identity expected, and is used to tell the loader
111 what object type is expected. expected may be zero to signify that
112 no specific object type is expected.
113 This function is expected to return 1 on success, 0 on error.
115 OSSL_STORE_find_fn
117 This function takes a OSSL_STORE_LOADER_CTX pointer and a
118 OSSL_STORE_SEARCH search criterion, and is used to tell the loader
119 what to search for.
120 When called with the loader context being NULL, this function is
122 expected to return 1 if the loader supports the criterion,
123 otherwise 0.
124 When called with the loader context being something other than
126 NULL, this function is expected to return 1 on success, 0 on error.
127 OSSL_STORE_load_fn
129 This function takes a OSSL_STORE_LOADER_CTX pointer and a UI_METHOD
130 with associated data. It's expected to load the next available
131 data, mold it into a data structure that can be wrapped in a
132 OSSL_STORE_INFO using one of the OSSL_STORE_INFO(3) functions. If
133 no more data is available or an error occurs, this function is
134 expected to return NULL. The OSSL_STORE_eof_fn and
135 OSSL_STORE_error_fn functions must indicate if it was in fact the
136 end of data or if an error occurred.
137 Note that this function retrieves one data item only.
139 OSSL_STORE_eof_fn
141 This function takes a OSSL_STORE_LOADER_CTX pointer and is expected
142 to return 1 to indicate that the end of available data has been
143 reached. It is otherwise expected to return 0.
144 OSSL_STORE_error_fn
146 This function takes a OSSL_STORE_LOADER_CTX pointer and is expected
147 to return 1 to indicate that an error occurred in a previous call
148 to the OSSL_STORE_load_fn function. It is otherwise expected to
149 return 0.
150 OSSL_STORE_close_fn
152 This function takes a OSSL_STORE_LOADER_CTX pointer and is expected
153 to close or shut down what needs to be closed, and finally free the
154 contents of the OSSL_STORE_LOADER_CTX pointer. It returns 1 on
155 success and 0 on error.
156 Functions
158 OSSL_STORE_LOADER_new() creates a new OSSL_STORE_LOADER. It takes an
159 ENGINE e and a string scheme. scheme must always be set. Both e and
160 scheme are used as is and must therefore be alive as long as the
161 created loader is.
162 OSSL_STORE_LOADER_get0_engine() returns the engine of the store_loader.
164 OSSL_STORE_LOADER_get0_scheme() returns the scheme of the store_loader.
165 OSSL_STORE_LOADER_set_open() sets the opener function for the
167 store_loader.
168 OSSL_STORE_LOADER_set_ctrl() sets the control function for the
170 store_loader.
171 OSSL_STORE_LOADER_set_expect() sets the expect function for the
173 store_loader.
174 OSSL_STORE_LOADER_set_load() sets the loader function for the
176 store_loader.
177 OSSL_STORE_LOADER_set_eof() sets the end of file checker function for
179 the store_loader.
180 OSSL_STORE_LOADER_set_close() sets the closing function for the
182 store_loader.
183 OSSL_STORE_LOADER_free() frees the given store_loader.
185 OSSL_STORE_register_loader() register the given store_loader and
187 thereby makes it available for use with OSSL_STORE_open(),
188 OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close().
189 OSSL_STORE_unregister_loader() unregister the store loader for the
191 given scheme.
192
194 The file: scheme has built in support.
195
197 The functions with the types OSSL_STORE_open_fn, OSSL_STORE_ctrl_fn,
198 OSSL_STORE_expect_fn, OSSL_STORE_load_fn, OSSL_STORE_eof_fn and
199 OSSL_STORE_close_fn have the same return values as OSSL_STORE_open(),
200 OSSL_STORE_ctrl(), OSSL_STORE_expect(), OSSL_STORE_load(),
201 OSSL_STORE_eof() and OSSL_STORE_close(), respectively.
202 OSSL_STORE_LOADER_new() returns a pointer to a OSSL_STORE_LOADER on
204 success, or NULL on failure.
205 OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_ctrl(),
207 OSSL_STORE_LOADER_set_load(), OSSL_STORE_LOADER_set_eof() and
208 OSSL_STORE_LOADER_set_close() return 1 on success, or 0 on failure.
209 OSSL_STORE_register_loader() returns 1 on success, or 0 on failure.
211 OSSL_STORE_unregister_loader() returns the unregistered loader on
213 success, or NULL on failure.
214
216 ossl_store(7), OSSL_STORE_open(3)
217
219 OSSL_STORE_LOADER(), OSSL_STORE_LOADER_CTX(), OSSL_STORE_LOADER_new(),
220 OSSL_STORE_LOADER_set0_scheme(), OSSL_STORE_LOADER_set_open(),
221 OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_load(),
222 OSSL_STORE_LOADER_set_eof(), OSSL_STORE_LOADER_set_close(),
223 OSSL_STORE_LOADER_free(), OSSL_STORE_register_loader(),
224 OSSL_STORE_unregister_loader(), OSSL_STORE_open_fn(),
225 OSSL_STORE_ctrl_fn(), OSSL_STORE_load_fn(), OSSL_STORE_eof_fn() and
226 OSSL_STORE_close_fn() were added in OpenSSL 1.1.1.
227
229 Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved.
230 Licensed under the OpenSSL license (the "License"). You may not use
232 this file except in compliance with the License. You can obtain a copy
233 in the file LICENSE in the source distribution or at
234 <https://www.openssl.org/source/license.html>.
2351.1.1l 2021-09-15 OSSL_STORE_LOADER(3)