secure/lib/libcrypto/man/OSSL_STORE_LOADER.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "OSSL_STORE_LOADER 3"
 132 .TH OSSL_STORE_LOADER 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 OSSL_STORE_LOADER, OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new, OSSL_STORE_LOADER_get0_engine, OSSL_STORE_LOADER_get0_scheme, OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_ctrl, OSSL_STORE_LOADER_set_expect, OSSL_STORE_LOADER_set_find, OSSL_STORE_LOADER_set_load, OSSL_STORE_LOADER_set_eof, OSSL_STORE_LOADER_set_error, OSSL_STORE_LOADER_set_close, OSSL_STORE_LOADER_free, OSSL_STORE_register_loader, OSSL_STORE_unregister_loader, OSSL_STORE_open_fn, OSSL_STORE_ctrl_fn, OSSL_STORE_expect_fn, OSSL_STORE_find_fn, OSSL_STORE_load_fn, OSSL_STORE_eof_fn, OSSL_STORE_error_fn, OSSL_STORE_close_fn \- Types and functions to manipulate, register and unregister STORE loaders for different URI schemes
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/store.h>
 143 \&
 144 \& typedef struct ossl_store_loader_st OSSL_STORE_LOADER;
 145 \&
 146 \& OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme);
 147 \& const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER
 148 \&                                             *store_loader);
 149 \& const char *OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER
 150 \&                                           *store_loader);
 151 \&
 152 \& /* struct ossl_store_loader_ctx_st is defined differently by each loader */
 153 \& typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX;
 154 \&
 155 \& typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn)(const char *uri,
 156 \&                                                      const UI_METHOD *ui_method,
 157 \&                                                      void *ui_data);
 158 \& int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *store_loader,
 159 \&                                OSSL_STORE_open_fn store_open_function);
 160 \& typedef int (*OSSL_STORE_ctrl_fn)(OSSL_STORE_LOADER_CTX *ctx, int cmd,
 161 \&                                   va_list args);
 162 \& int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader,
 163 \&                                OSSL_STORE_ctrl_fn store_ctrl_function);
 164 \& typedef int (*OSSL_STORE_expect_fn)(OSSL_STORE_LOADER_CTX *ctx, int expected);
 165 \& int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader,
 166 \&                                  OSSL_STORE_expect_fn expect_function);
 167 \& typedef int (*OSSL_STORE_find_fn)(OSSL_STORE_LOADER_CTX *ctx,
 168 \&                                   OSSL_STORE_SEARCH *criteria);
 169 \& int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader,
 170 \&                                OSSL_STORE_find_fn find_function);
 171 \& typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx,
 172 \&                                                UI_METHOD *ui_method,
 173 \&                                                void *ui_data);
 174 \& int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *store_loader,
 175 \&                                OSSL_STORE_load_fn store_load_function);
 176 \& typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx);
 177 \& int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER *store_loader,
 178 \&                               OSSL_STORE_eof_fn store_eof_function);
 179 \& typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx);
 180 \& int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *store_loader,
 181 \&                                 OSSL_STORE_error_fn store_error_function);
 182 \& typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx);
 183 \& int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *store_loader,
 184 \&                                 OSSL_STORE_close_fn store_close_function);
 185 \& void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *store_loader);
 186 \&
 187 \& int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader);
 188 \& OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme);
 189 .Ve
 190 .SH "DESCRIPTION"
 191 .IX Header "DESCRIPTION"
 192 These functions help applications and engines to create loaders for
 193 schemes they support.
 194 .SS "Types"
 195 .IX Subsection "Types"
 196 \&\fB\s-1OSSL_STORE_LOADER\s0\fR is the type to hold a loader.
 197 It contains a scheme and the functions needed to implement
 198 \&\fIOSSL_STORE_open()\fR, \fIOSSL_STORE_load()\fR, \fIOSSL_STORE_eof()\fR, \fIOSSL_STORE_error()\fR and
 199 \&\fIOSSL_STORE_close()\fR for this scheme.
 200 .PP
 201 \&\fB\s-1OSSL_STORE_LOADER_CTX\s0\fR is a type template, to be defined by each loader
 202 using \fBstruct ossl_store_loader_ctx_st { ... }\fR.
 203 .PP
 204 \&\fBOSSL_STORE_open_fn\fR, \fBOSSL_STORE_ctrl_fn\fR, \fBOSSL_STORE_expect_fn\fR,
 205 \&\fBOSSL_STORE_find_fn\fR, \fBOSSL_STORE_load_fn\fR, \fBOSSL_STORE_eof_fn\fR,
 206 and \fBOSSL_STORE_close_fn\fR
 207 are the function pointer types used within a \s-1STORE\s0 loader.
 208 The functions pointed at define the functionality of the given loader.
 209 .IP "\fBOSSL_STORE_open_fn\fR" 4
 210 .IX Item "OSSL_STORE_open_fn"
 211 This function takes a \s-1URI\s0 and is expected to interpret it in the best
 212 manner possible according to the scheme the loader implements, it also
 213 takes a \fB\s-1UI_METHOD\s0\fR and associated data, to be used any time
 214 something needs to be prompted for.
 215 Furthermore, this function is expected to initialize what needs to be
 216 initialized, to create a privata data store (\fB\s-1OSSL_STORE_LOADER_CTX\s0\fR, see
 217 above), and to return it.
 218 If something goes wrong, this function is expected to return \s-1NULL.\s0
 219 .IP "\fBOSSL_STORE_ctrl_fn\fR" 4
 220 .IX Item "OSSL_STORE_ctrl_fn"
 221 This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer, a command number
 222 \&\fBcmd\fR and a \fBva_list\fR \fBargs\fR and is used to manipulate loader
 223 specific parameters.
 224 .Sp
 225 Loader specific command numbers must begin at \fB\s-1OSSL_STORE_C_CUSTOM_START\s0\fR.
 226 Any number below that is reserved for future globally known command
 227 numbers.
 228 .Sp
 229 This function is expected to return 1 on success, 0 on error.
 230 .IP "\fBOSSL_STORE_expect_fn\fR" 4
 231 .IX Item "OSSL_STORE_expect_fn"
 232 This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and a \fB\s-1OSSL_STORE_INFO\s0\fR
 233 identity \fBexpected\fR, and is used to tell the loader what object type is
 234 expected.
 235 \&\fBexpected\fR may be zero to signify that no specific object type is expected.
 236 .Sp
 237 This function is expected to return 1 on success, 0 on error.
 238 .IP "\fBOSSL_STORE_find_fn\fR" 4
 239 .IX Item "OSSL_STORE_find_fn"
 240 This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and a
 241 \&\fB\s-1OSSL_STORE_SEARCH\s0\fR search criterion, and is used to tell the loader what
 242 to search for.
 243 .Sp
 244 When called with the loader context being \fB\s-1NULL\s0\fR, this function is expected
 245 to return 1 if the loader supports the criterion, otherwise 0.
 246 .Sp
 247 When called with the loader context being something other than \fB\s-1NULL\s0\fR, this
 248 function is expected to return 1 on success, 0 on error.
 249 .IP "\fBOSSL_STORE_load_fn\fR" 4
 250 .IX Item "OSSL_STORE_load_fn"
 251 This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and a \fB\s-1UI_METHOD\s0\fR
 252 with associated data.
 253 It's expected to load the next available data, mold it into a data
 254 structure that can be wrapped in a \fB\s-1OSSL_STORE_INFO\s0\fR using one of the
 255 \&\s-1\fIOSSL_STORE_INFO\s0\fR\|(3) functions.
 256 If no more data is available or an error occurs, this function is
 257 expected to return \s-1NULL.\s0
 258 The \fBOSSL_STORE_eof_fn\fR and \fBOSSL_STORE_error_fn\fR functions must indicate if
 259 it was in fact the end of data or if an error occurred.
 260 .Sp
 261 Note that this function retrieves \fIone\fR data item only.
 262 .IP "\fBOSSL_STORE_eof_fn\fR" 4
 263 .IX Item "OSSL_STORE_eof_fn"
 264 This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and is expected to
 265 return 1 to indicate that the end of available data has been reached.
 266 It is otherwise expected to return 0.
 267 .IP "\fBOSSL_STORE_error_fn\fR" 4
 268 .IX Item "OSSL_STORE_error_fn"
 269 This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and is expected to
 270 return 1 to indicate that an error occurred in a previous call to the
 271 \&\fBOSSL_STORE_load_fn\fR function.
 272 It is otherwise expected to return 0.
 273 .IP "\fBOSSL_STORE_close_fn\fR" 4
 274 .IX Item "OSSL_STORE_close_fn"
 275 This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and is expected to
 276 close or shut down what needs to be closed, and finally free the
 277 contents of the \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer.
 278 It returns 1 on success and 0 on error.
 279 .SS "Functions"
 280 .IX Subsection "Functions"
 281 \&\fIOSSL_STORE_LOADER_new()\fR creates a new \fB\s-1OSSL_STORE_LOADER\s0\fR.
 282 It takes an \fB\s-1ENGINE\s0\fR \fBe\fR and a string \fBscheme\fR.
 283 \&\fBscheme\fR must \fIalways\fR be set.
 284 Both \fBe\fR and \fBscheme\fR are used as is and must therefore be alive as
 285 long as the created loader is.
 286 .PP
 287 \&\fIOSSL_STORE_LOADER_get0_engine()\fR returns the engine of the \fBstore_loader\fR.
 288 \&\fIOSSL_STORE_LOADER_get0_scheme()\fR returns the scheme of the \fBstore_loader\fR.
 289 .PP
 290 \&\fIOSSL_STORE_LOADER_set_open()\fR sets the opener function for the
 291 \&\fBstore_loader\fR.
 292 .PP
 293 \&\fIOSSL_STORE_LOADER_set_ctrl()\fR sets the control function for the
 294 \&\fBstore_loader\fR.
 295 .PP
 296 \&\fIOSSL_STORE_LOADER_set_expect()\fR sets the expect function for the
 297 \&\fBstore_loader\fR.
 298 .PP
 299 \&\fIOSSL_STORE_LOADER_set_load()\fR sets the loader function for the
 300 \&\fBstore_loader\fR.
 301 .PP
 302 \&\fIOSSL_STORE_LOADER_set_eof()\fR sets the end of file checker function for the
 303 \&\fBstore_loader\fR.
 304 .PP
 305 \&\fIOSSL_STORE_LOADER_set_close()\fR sets the closing function for the
 306 \&\fBstore_loader\fR.
 307 .PP
 308 \&\fIOSSL_STORE_LOADER_free()\fR frees the given \fBstore_loader\fR.
 309 .PP
 310 \&\fIOSSL_STORE_register_loader()\fR register the given \fBstore_loader\fR and thereby
 311 makes it available for use with \fIOSSL_STORE_open()\fR, \fIOSSL_STORE_load()\fR,
 312 \&\fIOSSL_STORE_eof()\fR and \fIOSSL_STORE_close()\fR.
 313 .PP
 314 \&\fIOSSL_STORE_unregister_loader()\fR unregister the store loader for the given
 315 \&\fBscheme\fR.
 316 .SH "NOTES"
 317 .IX Header "NOTES"
 318 The \fBfile:\fR scheme has built in support.
 319 .SH "RETURN VALUES"
 320 .IX Header "RETURN VALUES"
 321 The functions with the types \fBOSSL_STORE_open_fn\fR, \fBOSSL_STORE_ctrl_fn\fR,
 322 \&\fBOSSL_STORE_expect_fn\fR,
 323 \&\fBOSSL_STORE_load_fn\fR, \fBOSSL_STORE_eof_fn\fR and \fBOSSL_STORE_close_fn\fR have the
 324 same return values as \fIOSSL_STORE_open()\fR, \fIOSSL_STORE_ctrl()\fR, \fIOSSL_STORE_expect()\fR,
 325 \&\fIOSSL_STORE_load()\fR, \fIOSSL_STORE_eof()\fR and \fIOSSL_STORE_close()\fR, respectively.
 326 .PP
 327 \&\fIOSSL_STORE_LOADER_new()\fR returns a pointer to a \fB\s-1OSSL_STORE_LOADER\s0\fR on success,
 328 or \fB\s-1NULL\s0\fR on failure.
 329 .PP
 330 \&\fIOSSL_STORE_LOADER_set_open()\fR, \fIOSSL_STORE_LOADER_set_ctrl()\fR,
 331 \&\fIOSSL_STORE_LOADER_set_load()\fR, \fIOSSL_STORE_LOADER_set_eof()\fR and
 332 \&\fIOSSL_STORE_LOADER_set_close()\fR return 1 on success, or 0 on failure.
 333 .PP
 334 \&\fIOSSL_STORE_register_loader()\fR returns 1 on success, or 0 on failure.
 335 .PP
 336 \&\fIOSSL_STORE_unregister_loader()\fR returns the unregistered loader on success,
 337 or \fB\s-1NULL\s0\fR on failure.
 338 .SH "SEE ALSO"
 339 .IX Header "SEE ALSO"
 340 \&\fIossl_store\fR\|(7), \fIOSSL_STORE_open\fR\|(3)
 341 .SH "HISTORY"
 342 .IX Header "HISTORY"
 343 \&\s-1\fIOSSL_STORE_LOADER\s0()\fR, \s-1\fIOSSL_STORE_LOADER_CTX\s0()\fR, \fIOSSL_STORE_LOADER_new()\fR,
 344 \&\fIOSSL_STORE_LOADER_set0_scheme()\fR, \fIOSSL_STORE_LOADER_set_open()\fR,
 345 \&\fIOSSL_STORE_LOADER_set_ctrl()\fR, \fIOSSL_STORE_LOADER_set_load()\fR,
 346 \&\fIOSSL_STORE_LOADER_set_eof()\fR, \fIOSSL_STORE_LOADER_set_close()\fR,
 347 \&\fIOSSL_STORE_LOADER_free()\fR, \fIOSSL_STORE_register_loader()\fR,
 348 \&\fIOSSL_STORE_unregister_loader()\fR, \fIOSSL_STORE_open_fn()\fR, \fIOSSL_STORE_ctrl_fn()\fR,
 349 \&\fIOSSL_STORE_load_fn()\fR, \fIOSSL_STORE_eof_fn()\fR and \fIOSSL_STORE_close_fn()\fR
 350 were added to OpenSSL 1.1.1.
 351 .SH "COPYRIGHT"
 352 .IX Header "COPYRIGHT"
 353 Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
 354 .PP
 355 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 356 this file except in compliance with the License.  You can obtain a copy
 357 in the file \s-1LICENSE\s0 in the source distribution or at
 358 <https://www.openssl.org/source/license.html>.