secure/lib/libcrypto/man/man3/OSSL_STORE_LOADER.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
   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 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "OSSL_STORE_LOADER 3"
 136 .TH OSSL_STORE_LOADER 3 "2020-03-17" "1.1.1e" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 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
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/store.h>
 147 \&
 148 \& typedef struct ossl_store_loader_st OSSL_STORE_LOADER;
 149 \&
 150 \& OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme);
 151 \& const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER
 152 \&                                             *store_loader);
 153 \& const char *OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER
 154 \&                                           *store_loader);
 155 \&
 156 \& /* struct ossl_store_loader_ctx_st is defined differently by each loader */
 157 \& typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX;
 158 \&
 159 \& typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn)(const char *uri,
 160 \&                                                      const UI_METHOD *ui_method,
 161 \&                                                      void *ui_data);
 162 \& int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *store_loader,
 163 \&                                OSSL_STORE_open_fn store_open_function);
 164 \& typedef int (*OSSL_STORE_ctrl_fn)(OSSL_STORE_LOADER_CTX *ctx, int cmd,
 165 \&                                   va_list args);
 166 \& int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader,
 167 \&                                OSSL_STORE_ctrl_fn store_ctrl_function);
 168 \& typedef int (*OSSL_STORE_expect_fn)(OSSL_STORE_LOADER_CTX *ctx, int expected);
 169 \& int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader,
 170 \&                                  OSSL_STORE_expect_fn expect_function);
 171 \& typedef int (*OSSL_STORE_find_fn)(OSSL_STORE_LOADER_CTX *ctx,
 172 \&                                   OSSL_STORE_SEARCH *criteria);
 173 \& int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader,
 174 \&                                OSSL_STORE_find_fn find_function);
 175 \& typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx,
 176 \&                                                UI_METHOD *ui_method,
 177 \&                                                void *ui_data);
 178 \& int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *store_loader,
 179 \&                                OSSL_STORE_load_fn store_load_function);
 180 \& typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx);
 181 \& int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER *store_loader,
 182 \&                               OSSL_STORE_eof_fn store_eof_function);
 183 \& typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx);
 184 \& int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *store_loader,
 185 \&                                 OSSL_STORE_error_fn store_error_function);
 186 \& typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx);
 187 \& int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *store_loader,
 188 \&                                 OSSL_STORE_close_fn store_close_function);
 189 \& void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *store_loader);
 190 \&
 191 \& int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader);
 192 \& OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme);
 193 .Ve
 194 .SH "DESCRIPTION"
 195 .IX Header "DESCRIPTION"
 196 These functions help applications and engines to create loaders for
 197 schemes they support.
 198 .SS "Types"
 199 .IX Subsection "Types"
 200 \&\fB\s-1OSSL_STORE_LOADER\s0\fR is the type to hold a loader.
 201 It contains a scheme and the functions needed to implement
 202 \&\fBOSSL_STORE_open()\fR, \fBOSSL_STORE_load()\fR, \fBOSSL_STORE_eof()\fR, \fBOSSL_STORE_error()\fR and
 203 \&\fBOSSL_STORE_close()\fR for this scheme.
 204 .PP
 205 \&\fB\s-1OSSL_STORE_LOADER_CTX\s0\fR is a type template, to be defined by each loader
 206 using \fBstruct ossl_store_loader_ctx_st { ... }\fR.
 207 .PP
 208 \&\fBOSSL_STORE_open_fn\fR, \fBOSSL_STORE_ctrl_fn\fR, \fBOSSL_STORE_expect_fn\fR,
 209 \&\fBOSSL_STORE_find_fn\fR, \fBOSSL_STORE_load_fn\fR, \fBOSSL_STORE_eof_fn\fR,
 210 and \fBOSSL_STORE_close_fn\fR
 211 are the function pointer types used within a \s-1STORE\s0 loader.
 212 The functions pointed at define the functionality of the given loader.
 213 .IP "\fBOSSL_STORE_open_fn\fR" 4
 214 .IX Item "OSSL_STORE_open_fn"
 215 This function takes a \s-1URI\s0 and is expected to interpret it in the best
 216 manner possible according to the scheme the loader implements, it also
 217 takes a \fB\s-1UI_METHOD\s0\fR and associated data, to be used any time
 218 something needs to be prompted for.
 219 Furthermore, this function is expected to initialize what needs to be
 220 initialized, to create a private data store (\fB\s-1OSSL_STORE_LOADER_CTX\s0\fR, see
 221 above), and to return it.
 222 If something goes wrong, this function is expected to return \s-1NULL.\s0
 223 .IP "\fBOSSL_STORE_ctrl_fn\fR" 4
 224 .IX Item "OSSL_STORE_ctrl_fn"
 225 This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer, a command number
 226 \&\fBcmd\fR and a \fBva_list\fR \fBargs\fR and is used to manipulate loader
 227 specific parameters.
 228 .Sp
 229 Loader specific command numbers must begin at \fB\s-1OSSL_STORE_C_CUSTOM_START\s0\fR.
 230 Any number below that is reserved for future globally known command
 231 numbers.
 232 .Sp
 233 This function is expected to return 1 on success, 0 on error.
 234 .IP "\fBOSSL_STORE_expect_fn\fR" 4
 235 .IX Item "OSSL_STORE_expect_fn"
 236 This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and a \fB\s-1OSSL_STORE_INFO\s0\fR
 237 identity \fBexpected\fR, and is used to tell the loader what object type is
 238 expected.
 239 \&\fBexpected\fR may be zero to signify that no specific object type is expected.
 240 .Sp
 241 This function is expected to return 1 on success, 0 on error.
 242 .IP "\fBOSSL_STORE_find_fn\fR" 4
 243 .IX Item "OSSL_STORE_find_fn"
 244 This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and a
 245 \&\fB\s-1OSSL_STORE_SEARCH\s0\fR search criterion, and is used to tell the loader what
 246 to search for.
 247 .Sp
 248 When called with the loader context being \fB\s-1NULL\s0\fR, this function is expected
 249 to return 1 if the loader supports the criterion, otherwise 0.
 250 .Sp
 251 When called with the loader context being something other than \fB\s-1NULL\s0\fR, this
 252 function is expected to return 1 on success, 0 on error.
 253 .IP "\fBOSSL_STORE_load_fn\fR" 4
 254 .IX Item "OSSL_STORE_load_fn"
 255 This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and a \fB\s-1UI_METHOD\s0\fR
 256 with associated data.
 257 It's expected to load the next available data, mold it into a data
 258 structure that can be wrapped in a \fB\s-1OSSL_STORE_INFO\s0\fR using one of the
 259 \&\s-1\fBOSSL_STORE_INFO\s0\fR\|(3) functions.
 260 If no more data is available or an error occurs, this function is
 261 expected to return \s-1NULL.\s0
 262 The \fBOSSL_STORE_eof_fn\fR and \fBOSSL_STORE_error_fn\fR functions must indicate if
 263 it was in fact the end of data or if an error occurred.
 264 .Sp
 265 Note that this function retrieves \fIone\fR data item only.
 266 .IP "\fBOSSL_STORE_eof_fn\fR" 4
 267 .IX Item "OSSL_STORE_eof_fn"
 268 This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and is expected to
 269 return 1 to indicate that the end of available data has been reached.
 270 It is otherwise expected to return 0.
 271 .IP "\fBOSSL_STORE_error_fn\fR" 4
 272 .IX Item "OSSL_STORE_error_fn"
 273 This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and is expected to
 274 return 1 to indicate that an error occurred in a previous call to the
 275 \&\fBOSSL_STORE_load_fn\fR function.
 276 It is otherwise expected to return 0.
 277 .IP "\fBOSSL_STORE_close_fn\fR" 4
 278 .IX Item "OSSL_STORE_close_fn"
 279 This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and is expected to
 280 close or shut down what needs to be closed, and finally free the
 281 contents of the \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer.
 282 It returns 1 on success and 0 on error.
 283 .SS "Functions"
 284 .IX Subsection "Functions"
 285 \&\fBOSSL_STORE_LOADER_new()\fR creates a new \fB\s-1OSSL_STORE_LOADER\s0\fR.
 286 It takes an \fB\s-1ENGINE\s0\fR \fBe\fR and a string \fBscheme\fR.
 287 \&\fBscheme\fR must \fIalways\fR be set.
 288 Both \fBe\fR and \fBscheme\fR are used as is and must therefore be alive as
 289 long as the created loader is.
 290 .PP
 291 \&\fBOSSL_STORE_LOADER_get0_engine()\fR returns the engine of the \fBstore_loader\fR.
 292 \&\fBOSSL_STORE_LOADER_get0_scheme()\fR returns the scheme of the \fBstore_loader\fR.
 293 .PP
 294 \&\fBOSSL_STORE_LOADER_set_open()\fR sets the opener function for the
 295 \&\fBstore_loader\fR.
 296 .PP
 297 \&\fBOSSL_STORE_LOADER_set_ctrl()\fR sets the control function for the
 298 \&\fBstore_loader\fR.
 299 .PP
 300 \&\fBOSSL_STORE_LOADER_set_expect()\fR sets the expect function for the
 301 \&\fBstore_loader\fR.
 302 .PP
 303 \&\fBOSSL_STORE_LOADER_set_load()\fR sets the loader function for the
 304 \&\fBstore_loader\fR.
 305 .PP
 306 \&\fBOSSL_STORE_LOADER_set_eof()\fR sets the end of file checker function for the
 307 \&\fBstore_loader\fR.
 308 .PP
 309 \&\fBOSSL_STORE_LOADER_set_close()\fR sets the closing function for the
 310 \&\fBstore_loader\fR.
 311 .PP
 312 \&\fBOSSL_STORE_LOADER_free()\fR frees the given \fBstore_loader\fR.
 313 .PP
 314 \&\fBOSSL_STORE_register_loader()\fR register the given \fBstore_loader\fR and thereby
 315 makes it available for use with \fBOSSL_STORE_open()\fR, \fBOSSL_STORE_load()\fR,
 316 \&\fBOSSL_STORE_eof()\fR and \fBOSSL_STORE_close()\fR.
 317 .PP
 318 \&\fBOSSL_STORE_unregister_loader()\fR unregister the store loader for the given
 319 \&\fBscheme\fR.
 320 .SH "NOTES"
 321 .IX Header "NOTES"
 322 The \fBfile:\fR scheme has built in support.
 323 .SH "RETURN VALUES"
 324 .IX Header "RETURN VALUES"
 325 The functions with the types \fBOSSL_STORE_open_fn\fR, \fBOSSL_STORE_ctrl_fn\fR,
 326 \&\fBOSSL_STORE_expect_fn\fR,
 327 \&\fBOSSL_STORE_load_fn\fR, \fBOSSL_STORE_eof_fn\fR and \fBOSSL_STORE_close_fn\fR have the
 328 same return values as \fBOSSL_STORE_open()\fR, \fBOSSL_STORE_ctrl()\fR, \fBOSSL_STORE_expect()\fR,
 329 \&\fBOSSL_STORE_load()\fR, \fBOSSL_STORE_eof()\fR and \fBOSSL_STORE_close()\fR, respectively.
 330 .PP
 331 \&\fBOSSL_STORE_LOADER_new()\fR returns a pointer to a \fB\s-1OSSL_STORE_LOADER\s0\fR on success,
 332 or \fB\s-1NULL\s0\fR on failure.
 333 .PP
 334 \&\fBOSSL_STORE_LOADER_set_open()\fR, \fBOSSL_STORE_LOADER_set_ctrl()\fR,
 335 \&\fBOSSL_STORE_LOADER_set_load()\fR, \fBOSSL_STORE_LOADER_set_eof()\fR and
 336 \&\fBOSSL_STORE_LOADER_set_close()\fR return 1 on success, or 0 on failure.
 337 .PP
 338 \&\fBOSSL_STORE_register_loader()\fR returns 1 on success, or 0 on failure.
 339 .PP
 340 \&\fBOSSL_STORE_unregister_loader()\fR returns the unregistered loader on success,
 341 or \fB\s-1NULL\s0\fR on failure.
 342 .SH "SEE ALSO"
 343 .IX Header "SEE ALSO"
 344 \&\fBossl_store\fR\|(7), \fBOSSL_STORE_open\fR\|(3)
 345 .SH "HISTORY"
 346 .IX Header "HISTORY"
 347 \&\s-1\fBOSSL_STORE_LOADER\s0()\fR, \s-1\fBOSSL_STORE_LOADER_CTX\s0()\fR, \fBOSSL_STORE_LOADER_new()\fR,
 348 \&\fBOSSL_STORE_LOADER_set0_scheme()\fR, \fBOSSL_STORE_LOADER_set_open()\fR,
 349 \&\fBOSSL_STORE_LOADER_set_ctrl()\fR, \fBOSSL_STORE_LOADER_set_load()\fR,
 350 \&\fBOSSL_STORE_LOADER_set_eof()\fR, \fBOSSL_STORE_LOADER_set_close()\fR,
 351 \&\fBOSSL_STORE_LOADER_free()\fR, \fBOSSL_STORE_register_loader()\fR,
 352 \&\fBOSSL_STORE_unregister_loader()\fR, \fBOSSL_STORE_open_fn()\fR, \fBOSSL_STORE_ctrl_fn()\fR,
 353 \&\fBOSSL_STORE_load_fn()\fR, \fBOSSL_STORE_eof_fn()\fR and \fBOSSL_STORE_close_fn()\fR
 354 were added in OpenSSL 1.1.1.
 355 .SH "COPYRIGHT"
 356 .IX Header "COPYRIGHT"
 357 Copyright 2016\-2019 The OpenSSL Project Authors. All Rights Reserved.
 358 .PP
 359 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 360 this file except in compliance with the License.  You can obtain a copy
 361 in the file \s-1LICENSE\s0 in the source distribution or at
 362 <https://www.openssl.org/source/license.html>.