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