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