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