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