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