1=pod 2 3=head1 NAME 4 5OSSL_STORE_LOADER, 6OSSL_STORE_LOADER_fetch, 7OSSL_STORE_LOADER_up_ref, 8OSSL_STORE_LOADER_free, 9OSSL_STORE_LOADER_get0_provider, 10OSSL_STORE_LOADER_get0_properties, 11OSSL_STORE_LOADER_is_a, 12OSSL_STORE_LOADER_get0_description, 13OSSL_STORE_LOADER_do_all_provided, 14OSSL_STORE_LOADER_names_do_all, 15OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new, 16OSSL_STORE_LOADER_get0_engine, OSSL_STORE_LOADER_get0_scheme, 17OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_open_ex, 18OSSL_STORE_LOADER_set_attach, OSSL_STORE_LOADER_set_ctrl, 19OSSL_STORE_LOADER_set_expect, OSSL_STORE_LOADER_set_find, 20OSSL_STORE_LOADER_set_load, OSSL_STORE_LOADER_set_eof, 21OSSL_STORE_LOADER_set_error, OSSL_STORE_LOADER_set_close, 22OSSL_STORE_register_loader, OSSL_STORE_unregister_loader, 23OSSL_STORE_open_fn, OSSL_STORE_open_ex_fn, 24OSSL_STORE_attach_fn, OSSL_STORE_ctrl_fn, 25OSSL_STORE_expect_fn, OSSL_STORE_find_fn, 26OSSL_STORE_load_fn, OSSL_STORE_eof_fn, OSSL_STORE_error_fn, 27OSSL_STORE_close_fn - Types and functions to manipulate, register and 28unregister STORE loaders for different URI schemes 29 30=head1 SYNOPSIS 31 32 #include <openssl/store.h> 33 34 typedef struct ossl_store_loader_st OSSL_STORE_LOADER; 35 36 OSSL_STORE_LOADER *OSSL_STORE_LOADER_fetch(OSSL_LIB_CTX *libctx, 37 const char *scheme, 38 const char *properties); 39 int OSSL_STORE_LOADER_up_ref(OSSL_STORE_LOADER *loader); 40 void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *loader); 41 const OSSL_PROVIDER *OSSL_STORE_LOADER_get0_provider(const OSSL_STORE_LOADER * 42 loader); 43 const char *OSSL_STORE_LOADER_get0_properties(const OSSL_STORE_LOADER *loader); 44 const char *OSSL_STORE_LOADER_get0_description(const OSSL_STORE_LOADER *loader); 45 int OSSL_STORE_LOADER_is_a(const OSSL_STORE_LOADER *loader, 46 const char *scheme); 47 void OSSL_STORE_LOADER_do_all_provided(OSSL_LIB_CTX *libctx, 48 void (*user_fn)(OSSL_STORE_LOADER *loader, 49 void *arg), 50 void *user_arg); 51 int OSSL_STORE_LOADER_names_do_all(const OSSL_STORE_LOADER *loader, 52 void (*fn)(const char *name, void *data), 53 void *data); 54 55The following functions have been deprecated since OpenSSL 3.0, and can be 56hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 57see L<openssl_user_macros(7)>: 58 59 OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme); 60 const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER 61 *store_loader); 62 const char *OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER 63 *store_loader); 64 65 /* struct ossl_store_loader_ctx_st is defined differently by each loader */ 66 typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX; 67 68 typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn)( 69 const char *uri, const UI_METHOD *ui_method, void *ui_data); 70 int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *store_loader, 71 OSSL_STORE_open_fn store_open_function); 72 typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_ex_fn)( 73 const char *uri, const UI_METHOD *ui_method, void *ui_data); 74 int OSSL_STORE_LOADER_set_open_ex 75 (OSSL_STORE_LOADER *store_loader, 76 OSSL_STORE_open_ex_fn store_open_ex_function); 77 typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_attach_fn) 78 (const OSSL_STORE_LOADER *loader, BIO *bio, 79 OSSL_LIB_CTX *libctx, const char *propq, 80 const UI_METHOD *ui_method, void *ui_data); 81 int OSSL_STORE_LOADER_set_attach(OSSL_STORE_LOADER *loader, 82 OSSL_STORE_attach_fn attach_function); 83 typedef int (*OSSL_STORE_ctrl_fn)(OSSL_STORE_LOADER_CTX *ctx, int cmd, 84 va_list args); 85 int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader, 86 OSSL_STORE_ctrl_fn store_ctrl_function); 87 typedef int (*OSSL_STORE_expect_fn)(OSSL_STORE_LOADER_CTX *ctx, int expected); 88 int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader, 89 OSSL_STORE_expect_fn expect_function); 90 typedef int (*OSSL_STORE_find_fn)(OSSL_STORE_LOADER_CTX *ctx, 91 OSSL_STORE_SEARCH *criteria); 92 int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader, 93 OSSL_STORE_find_fn find_function); 94 typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx, 95 UI_METHOD *ui_method, 96 void *ui_data); 97 int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *store_loader, 98 OSSL_STORE_load_fn store_load_function); 99 typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx); 100 int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER *store_loader, 101 OSSL_STORE_eof_fn store_eof_function); 102 typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx); 103 int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *store_loader, 104 OSSL_STORE_error_fn store_error_function); 105 typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx); 106 int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *store_loader, 107 OSSL_STORE_close_fn store_close_function); 108 void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *store_loader); 109 110 int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader); 111 OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme); 112 113=head1 DESCRIPTION 114 115B<OSSL_STORE_LOADER> is a method for OSSL_STORE loaders, which implement 116OSSL_STORE_open(), OSSL_STORE_open_ex(), OSSL_STORE_load(), 117OSSL_STORE_eof(), OSSL_STORE_error() and OSSL_STORE_close() for specific 118storage schemes. 119 120OSSL_STORE_LOADER_fetch() looks for an implementation for a storage 121I<scheme> within the providers that has been loaded into the B<OSSL_LIB_CTX> 122given by I<libctx>, and with the properties given by I<properties>. 123 124OSSL_STORE_LOADER_up_ref() increments the reference count for the given 125I<loader>. 126 127OSSL_STORE_LOADER_free() decrements the reference count for the given 128I<loader>, and when the count reaches zero, frees it. 129 130OSSL_STORE_LOADER_get0_provider() returns the provider of the given 131I<loader>. 132 133OSSL_STORE_LOADER_get0_properties() returns the property definition associated 134with the given I<loader>. 135 136OSSL_STORE_LOADER_is_a() checks if I<loader> is an implementation 137of an algorithm that's identifiable with I<scheme>. 138 139OSSL_STORE_LOADER_get0_description() returns a description of the I<loader>, meant 140for display and human consumption. The description is at the discretion of the 141I<loader> implementation. 142 143OSSL_STORE_LOADER_do_all_provided() traverses all store implementations 144by all activated providers in the library context I<libctx>, and for each 145of the implementations, calls I<user_fn> with the implementation method and 146I<user_arg> as arguments. 147 148OSSL_STORE_LOADER_names_do_all() traverses all names for the given 149I<loader>, and calls I<fn> with each name and I<data>. 150 151=head2 Legacy Types and Functions (deprecated) 152 153These functions help applications and engines to create loaders for 154schemes they support. These are all deprecated and discouraged in favour of 155provider implementations, see L<provider-storemgmt(7)>. 156 157B<OSSL_STORE_LOADER_CTX> is a type template, to be defined by each loader 158using C<struct ossl_store_loader_ctx_st { ... }>. 159 160B<OSSL_STORE_open_fn>, B<OSSL_STORE_open_ex_fn>, 161B<OSSL_STORE_ctrl_fn>, B<OSSL_STORE_expect_fn>, B<OSSL_STORE_find_fn>, 162B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn>, and B<OSSL_STORE_close_fn> 163are the function pointer types used within a STORE loader. 164The functions pointed at define the functionality of the given loader. 165 166=over 4 167 168=item B<OSSL_STORE_open_fn> and B<OSSL_STORE_open_ex_fn> 169 170B<OSSL_STORE_open_ex_fn> takes a URI and is expected to 171interpret it in the best manner possible according to the scheme the 172loader implements. It also takes a B<UI_METHOD> and associated data, 173to be used any time something needs to be prompted for, as well as a 174library context I<libctx> with an associated property query I<propq>, 175to be used when fetching necessary algorithms to perform the loads. 176Furthermore, this function is expected to initialize what needs to be 177initialized, to create a private data store (B<OSSL_STORE_LOADER_CTX>, 178see above), and to return it. 179If something goes wrong, this function is expected to return NULL. 180 181B<OSSL_STORE_open_fn> does the same thing as 182B<OSSL_STORE_open_ex_fn> but uses NULL for the library 183context I<libctx> and property query I<propq>. 184 185=item B<OSSL_STORE_attach_fn> 186 187This function takes a B<BIO>, otherwise works like 188B<OSSL_STORE_open_ex_fn>. 189 190=item B<OSSL_STORE_ctrl_fn> 191 192This function takes a B<OSSL_STORE_LOADER_CTX> pointer, a command number 193I<cmd> and a B<va_list> I<args> and is used to manipulate loader 194specific parameters. 195 196=begin comment 197 198Globally known command numbers are documented in L<OSSL_STORE_ctrl(3)>, 199along with what I<args> are expected with each of them. 200 201=end comment 202 203Loader specific command numbers must begin at B<OSSL_STORE_C_CUSTOM_START>. 204Any number below that is reserved for future globally known command 205numbers. 206 207This function is expected to return 1 on success, 0 on error. 208 209=item B<OSSL_STORE_expect_fn> 210 211This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<OSSL_STORE_INFO> 212identity I<expected>, and is used to tell the loader what object type is 213expected. 214I<expected> may be zero to signify that no specific object type is expected. 215 216This function is expected to return 1 on success, 0 on error. 217 218=item B<OSSL_STORE_find_fn> 219 220This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a 221B<OSSL_STORE_SEARCH> search criterion, and is used to tell the loader what 222to search for. 223 224When called with the loader context being NULL, this function is expected 225to return 1 if the loader supports the criterion, otherwise 0. 226 227When called with the loader context being something other than NULL, this 228function is expected to return 1 on success, 0 on error. 229 230=item B<OSSL_STORE_load_fn> 231 232This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<UI_METHOD> 233with associated data. 234It's expected to load the next available data, mold it into a data 235structure that can be wrapped in a B<OSSL_STORE_INFO> using one of the 236L<OSSL_STORE_INFO(3)> functions. 237If no more data is available or an error occurs, this function is 238expected to return NULL. 239The B<OSSL_STORE_eof_fn> and B<OSSL_STORE_error_fn> functions must indicate if 240it was in fact the end of data or if an error occurred. 241 242Note that this function retrieves I<one> data item only. 243 244=item B<OSSL_STORE_eof_fn> 245 246This function takes a B<OSSL_STORE_LOADER_CTX> pointer and is expected to 247return 1 to indicate that the end of available data has been reached. 248It is otherwise expected to return 0. 249 250=item B<OSSL_STORE_error_fn> 251 252This function takes a B<OSSL_STORE_LOADER_CTX> pointer and is expected to 253return 1 to indicate that an error occurred in a previous call to the 254B<OSSL_STORE_load_fn> function. 255It is otherwise expected to return 0. 256 257=item B<OSSL_STORE_close_fn> 258 259This function takes a B<OSSL_STORE_LOADER_CTX> pointer and is expected to 260close or shut down what needs to be closed, and finally free the 261contents of the B<OSSL_STORE_LOADER_CTX> pointer. 262It returns 1 on success and 0 on error. 263 264=back 265 266OSSL_STORE_LOADER_new() creates a new B<OSSL_STORE_LOADER>. 267It takes an B<ENGINE> I<e> and a string I<scheme>. 268I<scheme> must I<always> be set. 269Both I<e> and I<scheme> are used as is and must therefore be alive as 270long as the created loader is. 271 272OSSL_STORE_LOADER_get0_engine() returns the engine of the I<store_loader>. 273OSSL_STORE_LOADER_get0_scheme() returns the scheme of the I<store_loader>. 274 275OSSL_STORE_LOADER_set_open() sets the opener function for the 276I<store_loader>. 277 278OSSL_STORE_LOADER_set_open_ex() sets the opener with library context 279function for the I<store_loader>. 280 281OSSL_STORE_LOADER_set_attach() sets the attacher function for the 282I<store_loader>. 283 284OSSL_STORE_LOADER_set_ctrl() sets the control function for the 285I<store_loader>. 286 287OSSL_STORE_LOADER_set_expect() sets the expect function for the 288I<store_loader>. 289 290OSSL_STORE_LOADER_set_load() sets the loader function for the 291I<store_loader>. 292 293OSSL_STORE_LOADER_set_eof() sets the end of file checker function for the 294I<store_loader>. 295 296OSSL_STORE_LOADER_set_close() sets the closing function for the 297I<store_loader>. 298 299OSSL_STORE_LOADER_free() frees the given I<store_loader>. 300 301OSSL_STORE_register_loader() register the given I<store_loader> and 302thereby makes it available for use with OSSL_STORE_open(), 303OSSL_STORE_open_ex(), OSSL_STORE_load(), OSSL_STORE_eof() 304and OSSL_STORE_close(). 305 306OSSL_STORE_unregister_loader() unregister the store loader for the given 307I<scheme>. 308 309=head1 RETURN VALUES 310 311OSSL_STORE_LOADER_fetch() returns a pointer to an OSSL_STORE_LOADER object, 312or NULL on error. 313 314OSSL_STORE_LOADER_up_ref() returns 1 on success, or 0 on error. 315 316OSSL_STORE_LOADER_names_do_all() returns 1 if the callback was called for all 317names. A return value of 0 means that the callback was not called for any names. 318 319OSSL_STORE_LOADER_free() doesn't return any value. 320 321OSSL_STORE_LOADER_get0_provider() returns a pointer to a provider object, or 322NULL on error. 323 324OSSL_STORE_LOADER_get0_properties() returns a pointer to a property 325definition string, or NULL on error. 326 327OSSL_STORE_LOADER_is_a() returns 1 if I<loader> was identifiable, 328otherwise 0. 329 330OSSL_STORE_LOADER_get0_description() returns a pointer to a decription, or NULL if 331there isn't one. 332 333The functions with the types B<OSSL_STORE_open_fn>, 334B<OSSL_STORE_open_ex_fn>, B<OSSL_STORE_ctrl_fn>, 335B<OSSL_STORE_expect_fn>, B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn> 336and B<OSSL_STORE_close_fn> have the same return values as OSSL_STORE_open(), 337OSSL_STORE_open_ex(), OSSL_STORE_ctrl(), OSSL_STORE_expect(), 338OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close(), respectively. 339 340OSSL_STORE_LOADER_new() returns a pointer to a B<OSSL_STORE_LOADER> on success, 341or NULL on failure. 342 343OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_open_ex(), 344OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_load(), 345OSSL_STORE_LOADER_set_eof() and OSSL_STORE_LOADER_set_close() return 1 346on success, or 0 on failure. 347 348OSSL_STORE_register_loader() returns 1 on success, or 0 on failure. 349 350OSSL_STORE_unregister_loader() returns the unregistered loader on success, 351or NULL on failure. 352 353=head1 SEE ALSO 354 355L<ossl_store(7)>, L<OSSL_STORE_open(3)>, L<OSSL_LIB_CTX(3)>, 356L<provider-storemgmt(7)> 357 358=head1 HISTORY 359 360OSSL_STORE_LOADER_fetch(), OSSL_STORE_LOADER_up_ref(), 361OSSL_STORE_LOADER_free(), OSSL_STORE_LOADER_get0_provider(), 362OSSL_STORE_LOADER_get0_properties(), OSSL_STORE_LOADER_is_a(), 363OSSL_STORE_LOADER_do_all_provided() and 364OSSL_STORE_LOADER_names_do_all() were added in OpenSSL 3.0. 365 366OSSL_STORE_open_ex_fn() was added in OpenSSL 3.0. 367 368B<OSSL_STORE_LOADER>, B<OSSL_STORE_LOADER_CTX>, OSSL_STORE_LOADER_new(), 369OSSL_STORE_LOADER_set0_scheme(), OSSL_STORE_LOADER_get0_scheme(), 370OSSL_STORE_LOADER_get0_engine(), OSSL_STORE_LOADER_set_expect(), 371OSSL_STORE_LOADER_set_find(), OSSL_STORE_LOADER_set_attach(), 372OSSL_STORE_LOADER_set_open_ex(), OSSL_STORE_LOADER_set_open(), 373OSSL_STORE_LOADER_set_ctrl(), 374OSSL_STORE_LOADER_set_load(), OSSL_STORE_LOADER_set_eof(), 375OSSL_STORE_LOADER_set_close(), OSSL_STORE_LOADER_free(), 376OSSL_STORE_register_loader(), OSSL_STORE_LOADER_set_error(), 377OSSL_STORE_unregister_loader(), OSSL_STORE_open_fn(), OSSL_STORE_ctrl_fn(), 378OSSL_STORE_load_fn(), OSSL_STORE_eof_fn() and OSSL_STORE_close_fn() 379were added in OpenSSL 1.1.1, and became deprecated in OpenSSL 3.0. 380 381=head1 COPYRIGHT 382 383Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved. 384 385Licensed under the Apache License 2.0 (the "License"). You may not use 386this file except in compliance with the License. You can obtain a copy 387in the file LICENSE in the source distribution or at 388L<https://www.openssl.org/source/license.html>. 389 390=cut 391