doc/man3/OSSL_STORE_LOADER.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_STORE_LOADER, OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new,
   6 OSSL_STORE_LOADER_get0_engine, OSSL_STORE_LOADER_get0_scheme,
   7 OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_attach,
   8 OSSL_STORE_LOADER_set_ctrl, OSSL_STORE_LOADER_set_expect,
   9 OSSL_STORE_LOADER_set_find, OSSL_STORE_LOADER_set_load,
  10 OSSL_STORE_LOADER_set_eof, OSSL_STORE_LOADER_set_error,
  11 OSSL_STORE_LOADER_set_close,
  12 OSSL_STORE_LOADER_free, OSSL_STORE_register_loader,
  13 OSSL_STORE_unregister_loader,
  14 OSSL_STORE_open_fn, OSSL_STORE_attach_fn, OSSL_STORE_ctrl_fn,
  15 OSSL_STORE_expect_fn, OSSL_STORE_find_fn,
  16 OSSL_STORE_load_fn, OSSL_STORE_eof_fn, OSSL_STORE_error_fn,
  17 OSSL_STORE_close_fn - Types and functions to manipulate, register and
  18 unregister STORE loaders for different URI schemes
  19
  20 =head1 SYNOPSIS
  21
  22  #include <openssl/store.h>
  23
  24  typedef struct ossl_store_loader_st OSSL_STORE_LOADER;
  25
  26  OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme);
  27  const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER
  28                                              *store_loader);
  29  const char *OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER
  30                                            *store_loader);
  31
  32  /* struct ossl_store_loader_ctx_st is defined differently by each loader */
  33  typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX;
  34
  35  typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn)(
  36      const char *uri, const UI_METHOD *ui_method, void *ui_data);
  37  int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *store_loader,
  38                                 OSSL_STORE_open_fn store_open_function);
  39  typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_attach_fn)
  40      (const OSSL_STORE_LOADER *loader, BIO *bio,
  41       OPENSSL_CTX *libctx, const char *propq,
  42       const UI_METHOD *ui_method, void *ui_data);
  43  int OSSL_STORE_LOADER_set_attach(OSSL_STORE_LOADER *loader,
  44                                   OSSL_STORE_attach_fn attach_function);
  45  typedef int (*OSSL_STORE_ctrl_fn)(OSSL_STORE_LOADER_CTX *ctx, int cmd,
  46                                    va_list args);
  47  int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader,
  48                                 OSSL_STORE_ctrl_fn store_ctrl_function);
  49  typedef int (*OSSL_STORE_expect_fn)(OSSL_STORE_LOADER_CTX *ctx, int expected);
  50  int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader,
  51                                   OSSL_STORE_expect_fn expect_function);
  52  typedef int (*OSSL_STORE_find_fn)(OSSL_STORE_LOADER_CTX *ctx,
  53                                    OSSL_STORE_SEARCH *criteria);
  54  int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader,
  55                                 OSSL_STORE_find_fn find_function);
  56  typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx,
  57                                                 UI_METHOD *ui_method,
  58                                                 void *ui_data);
  59  int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *store_loader,
  60                                 OSSL_STORE_load_fn store_load_function);
  61  typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx);
  62  int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER *store_loader,
  63                                OSSL_STORE_eof_fn store_eof_function);
  64  typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx);
  65  int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *store_loader,
  66                                  OSSL_STORE_error_fn store_error_function);
  67  typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx);
  68  int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *store_loader,
  69                                  OSSL_STORE_close_fn store_close_function);
  70  void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *store_loader);
  71
  72  int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader);
  73  OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme);
  74
  75 =head1 DESCRIPTION
  76
  77 These functions help applications and engines to create loaders for
  78 schemes they support.
  79
  80 =head2 Types
  81
  82 B<OSSL_STORE_LOADER> is the type to hold a loader.
  83 It contains a scheme and the functions needed to implement
  84 OSSL_STORE_open(), OSSL_STORE_load(), OSSL_STORE_eof(), OSSL_STORE_error() and
  85 OSSL_STORE_close() for this scheme.
  86
  87 B<OSSL_STORE_LOADER_CTX> is a type template, to be defined by each loader
  88 using B<struct ossl_store_loader_ctx_st { ... }>.
  89
  90 B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>, B<OSSL_STORE_expect_fn>,
  91 B<OSSL_STORE_find_fn>, B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn>,
  92 and B<OSSL_STORE_close_fn>
  93 are the function pointer types used within a STORE loader.
  94 The functions pointed at define the functionality of the given loader.
  95
  96 =over 4
  97
  98 =item B<OSSL_STORE_open_fn>
  99
 100 This function takes a URI and is expected to interpret it in the best
 101 manner possible according to the scheme the loader implements, it also
 102 takes a B<UI_METHOD> and associated data, to be used any time
 103 something needs to be prompted for.
 104 Furthermore, this function is expected to initialize what needs to be
 105 initialized, to create a private data store (B<OSSL_STORE_LOADER_CTX>, see
 106 above), and to return it.
 107 If something goes wrong, this function is expected to return NULL.
 108
 109 =item B<OSSL_STORE_open_fn>
 110
 111 This function takes a B<BIO>, otherwise works like B<OSSL_STORE_open_fn>.
 112
 113 =item B<OSSL_STORE_ctrl_fn>
 114
 115 This function takes a B<OSSL_STORE_LOADER_CTX> pointer, a command number
 116 B<cmd> and a B<va_list> B<args> and is used to manipulate loader
 117 specific parameters.
 118
 119 =begin comment
 120
 121 Globally known command numbers are documented in L<OSSL_STORE_ctrl(3)>,
 122 along with what B<args> are expected with each of them.
 123
 124 =end comment
 125
 126 Loader specific command numbers must begin at B<OSSL_STORE_C_CUSTOM_START>.
 127 Any number below that is reserved for future globally known command
 128 numbers.
 129
 130 This function is expected to return 1 on success, 0 on error.
 131
 132 =item B<OSSL_STORE_expect_fn>
 133
 134 This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<OSSL_STORE_INFO>
 135 identity B<expected>, and is used to tell the loader what object type is
 136 expected.
 137 B<expected> may be zero to signify that no specific object type is expected.
 138
 139 This function is expected to return 1 on success, 0 on error.
 140
 141 =item B<OSSL_STORE_find_fn>
 142
 143 This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a
 144 B<OSSL_STORE_SEARCH> search criterion, and is used to tell the loader what
 145 to search for.
 146
 147 When called with the loader context being B<NULL>, this function is expected
 148 to return 1 if the loader supports the criterion, otherwise 0.
 149
 150 When called with the loader context being something other than B<NULL>, this
 151 function is expected to return 1 on success, 0 on error.
 152
 153 =item B<OSSL_STORE_load_fn>
 154
 155 This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<UI_METHOD>
 156 with associated data.
 157 It's expected to load the next available data, mold it into a data
 158 structure that can be wrapped in a B<OSSL_STORE_INFO> using one of the
 159 L<OSSL_STORE_INFO(3)> functions.
 160 If no more data is available or an error occurs, this function is
 161 expected to return NULL.
 162 The B<OSSL_STORE_eof_fn> and B<OSSL_STORE_error_fn> functions must indicate if
 163 it was in fact the end of data or if an error occurred.
 164
 165 Note that this function retrieves I<one> data item only.
 166
 167 =item B<OSSL_STORE_eof_fn>
 168
 169 This function takes a B<OSSL_STORE_LOADER_CTX> pointer and is expected to
 170 return 1 to indicate that the end of available data has been reached.
 171 It is otherwise expected to return 0.
 172
 173 =item B<OSSL_STORE_error_fn>
 174
 175 This function takes a B<OSSL_STORE_LOADER_CTX> pointer and is expected to
 176 return 1 to indicate that an error occurred in a previous call to the
 177 B<OSSL_STORE_load_fn> function.
 178 It is otherwise expected to return 0.
 179
 180 =item B<OSSL_STORE_close_fn>
 181
 182 This function takes a B<OSSL_STORE_LOADER_CTX> pointer and is expected to
 183 close or shut down what needs to be closed, and finally free the
 184 contents of the B<OSSL_STORE_LOADER_CTX> pointer.
 185 It returns 1 on success and 0 on error.
 186
 187 =back
 188
 189 =head2 Functions
 190
 191 OSSL_STORE_LOADER_new() creates a new B<OSSL_STORE_LOADER>.
 192 It takes an B<ENGINE> B<e> and a string B<scheme>.
 193 B<scheme> must I<always> be set.
 194 Both B<e> and B<scheme> are used as is and must therefore be alive as
 195 long as the created loader is.
 196
 197 OSSL_STORE_LOADER_get0_engine() returns the engine of the B<store_loader>.
 198 OSSL_STORE_LOADER_get0_scheme() returns the scheme of the B<store_loader>.
 199
 200 OSSL_STORE_LOADER_set_open() sets the opener function for the
 201 B<store_loader>.
 202
 203 OSSL_STORE_LOADER_set_attach() sets the attacher function for the
 204 B<store_loader>.
 205
 206 OSSL_STORE_LOADER_set_ctrl() sets the control function for the
 207 B<store_loader>.
 208
 209 OSSL_STORE_LOADER_set_expect() sets the expect function for the
 210 B<store_loader>.
 211
 212 OSSL_STORE_LOADER_set_load() sets the loader function for the
 213 B<store_loader>.
 214
 215 OSSL_STORE_LOADER_set_eof() sets the end of file checker function for the
 216 B<store_loader>.
 217
 218 OSSL_STORE_LOADER_set_close() sets the closing function for the
 219 B<store_loader>.
 220
 221 OSSL_STORE_LOADER_free() frees the given B<store_loader>.
 222
 223 OSSL_STORE_register_loader() register the given B<store_loader> and thereby
 224 makes it available for use with OSSL_STORE_open(), OSSL_STORE_load(),
 225 OSSL_STORE_eof() and OSSL_STORE_close().
 226
 227 OSSL_STORE_unregister_loader() unregister the store loader for the given
 228 B<scheme>.
 229
 230 =head1 NOTES
 231
 232 The B<file:> scheme has built in support.
 233
 234 =head1 RETURN VALUES
 235
 236 The functions with the types B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>,
 237 B<OSSL_STORE_expect_fn>,
 238 B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn> and B<OSSL_STORE_close_fn> have the
 239 same return values as OSSL_STORE_open(), OSSL_STORE_ctrl(), OSSL_STORE_expect(),
 240 OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close(), respectively.
 241
 242 OSSL_STORE_LOADER_new() returns a pointer to a B<OSSL_STORE_LOADER> on success,
 243 or B<NULL> on failure.
 244
 245 OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_ctrl(),
 246 OSSL_STORE_LOADER_set_load(), OSSL_STORE_LOADER_set_eof() and
 247 OSSL_STORE_LOADER_set_close() return 1 on success, or 0 on failure.
 248
 249 OSSL_STORE_register_loader() returns 1 on success, or 0 on failure.
 250
 251 OSSL_STORE_unregister_loader() returns the unregistered loader on success,
 252 or B<NULL> on failure.
 253
 254 =head1 SEE ALSO
 255
 256 L<ossl_store(7)>, L<OSSL_STORE_open(3)>
 257
 258 =head1 HISTORY
 259
 260 OSSL_STORE_LOADER(), OSSL_STORE_LOADER_CTX(), OSSL_STORE_LOADER_new(),
 261 OSSL_STORE_LOADER_set0_scheme(), OSSL_STORE_LOADER_set_open(),
 262 OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_load(),
 263 OSSL_STORE_LOADER_set_eof(), OSSL_STORE_LOADER_set_close(),
 264 OSSL_STORE_LOADER_free(), OSSL_STORE_register_loader(),
 265 OSSL_STORE_unregister_loader(), OSSL_STORE_open_fn(), OSSL_STORE_ctrl_fn(),
 266 OSSL_STORE_load_fn(), OSSL_STORE_eof_fn() and OSSL_STORE_close_fn()
 267 were added in OpenSSL 1.1.1.
 268
 269 =head1 COPYRIGHT
 270
 271 Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
 272
 273 Licensed under the Apache License 2.0 (the "License").  You may not use
 274 this file except in compliance with the License.  You can obtain a copy
 275 in the file LICENSE in the source distribution or at
 276 L<https://www.openssl.org/source/license.html>.
 277
 278 =cut