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