doc/man3/OSSL_STORE_LOADER.pod

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