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