1OSSL_STORE_LOADER(3)                OpenSSL               OSSL_STORE_LOADER(3)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

69       These functions help applications and engines to create loaders for
70       schemes they support.
71
72   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
78       OSSL_STORE_LOADER_CTX is a type template, to be defined by each loader
79       using struct ossl_store_loader_ctx_st { ... }.
80
81       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
87       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
97       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
102           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
106           This function is expected to return 1 on success, 0 on error.
107
108       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
114           This function is expected to return 1 on success, 0 on error.
115
116       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
121           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
125           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
128       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
138           Note that this function retrieves one data item only.
139
140       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
145       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
151       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
157   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
163       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
166       OSSL_STORE_LOADER_set_open() sets the opener function for the
167       store_loader.
168
169       OSSL_STORE_LOADER_set_ctrl() sets the control function for the
170       store_loader.
171
172       OSSL_STORE_LOADER_set_expect() sets the expect function for the
173       store_loader.
174
175       OSSL_STORE_LOADER_set_load() sets the loader function for the
176       store_loader.
177
178       OSSL_STORE_LOADER_set_eof() sets the end of file checker function for
179       the store_loader.
180
181       OSSL_STORE_LOADER_set_close() sets the closing function for the
182       store_loader.
183
184       OSSL_STORE_LOADER_free() frees the given store_loader.
185
186       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
190       OSSL_STORE_unregister_loader() unregister the store loader for the
191       given scheme.
192

NOTES

194       The file: scheme has built in support.
195

RETURN VALUES

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
203       OSSL_STORE_LOADER_new() returns a pointer to a OSSL_STORE_LOADER on
204       success, or NULL on failure.
205
206       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
210       OSSL_STORE_register_loader() returns 1 on success, or 0 on failure.
211
212       OSSL_STORE_unregister_loader() returns the unregistered loader on
213       success, or NULL on failure.
214

SEE ALSO

216       ossl_store(7), OSSL_STORE_open(3)
217

HISTORY

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
231       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>.
235
236
237
2381.1.1q                            2022-07-07              OSSL_STORE_LOADER(3)
Impressum