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