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