diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/OSSL_STORE_LOADER.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/OSSL_STORE_LOADER.3 | 362 |
1 files changed, 362 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/man3/OSSL_STORE_LOADER.3 b/secure/lib/libcrypto/man/man3/OSSL_STORE_LOADER.3 new file mode 100644 index 000000000000..45b15c3a644a --- /dev/null +++ b/secure/lib/libcrypto/man/man3/OSSL_STORE_LOADER.3 @@ -0,0 +1,362 @@ +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.39) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "OSSL_STORE_LOADER 3" +.TH OSSL_STORE_LOADER 3 "2019-09-10" "1.1.1d" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +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 +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/store.h> +\& +\& typedef struct ossl_store_loader_st OSSL_STORE_LOADER; +\& +\& OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme); +\& const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER +\& *store_loader); +\& const char *OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER +\& *store_loader); +\& +\& /* struct ossl_store_loader_ctx_st is defined differently by each loader */ +\& typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX; +\& +\& typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn)(const char *uri, +\& const UI_METHOD *ui_method, +\& void *ui_data); +\& int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *store_loader, +\& OSSL_STORE_open_fn store_open_function); +\& typedef int (*OSSL_STORE_ctrl_fn)(OSSL_STORE_LOADER_CTX *ctx, int cmd, +\& va_list args); +\& int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader, +\& OSSL_STORE_ctrl_fn store_ctrl_function); +\& typedef int (*OSSL_STORE_expect_fn)(OSSL_STORE_LOADER_CTX *ctx, int expected); +\& int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader, +\& OSSL_STORE_expect_fn expect_function); +\& typedef int (*OSSL_STORE_find_fn)(OSSL_STORE_LOADER_CTX *ctx, +\& OSSL_STORE_SEARCH *criteria); +\& int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader, +\& OSSL_STORE_find_fn find_function); +\& typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx, +\& UI_METHOD *ui_method, +\& void *ui_data); +\& int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *store_loader, +\& OSSL_STORE_load_fn store_load_function); +\& typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx); +\& int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER *store_loader, +\& OSSL_STORE_eof_fn store_eof_function); +\& typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx); +\& int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *store_loader, +\& OSSL_STORE_error_fn store_error_function); +\& typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx); +\& int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *store_loader, +\& OSSL_STORE_close_fn store_close_function); +\& void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *store_loader); +\& +\& int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader); +\& OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions help applications and engines to create loaders for +schemes they support. +.SS "Types" +.IX Subsection "Types" +\&\fB\s-1OSSL_STORE_LOADER\s0\fR is the type to hold a loader. +It contains a scheme and the functions needed to implement +\&\fBOSSL_STORE_open()\fR, \fBOSSL_STORE_load()\fR, \fBOSSL_STORE_eof()\fR, \fBOSSL_STORE_error()\fR and +\&\fBOSSL_STORE_close()\fR for this scheme. +.PP +\&\fB\s-1OSSL_STORE_LOADER_CTX\s0\fR is a type template, to be defined by each loader +using \fBstruct ossl_store_loader_ctx_st { ... }\fR. +.PP +\&\fBOSSL_STORE_open_fn\fR, \fBOSSL_STORE_ctrl_fn\fR, \fBOSSL_STORE_expect_fn\fR, +\&\fBOSSL_STORE_find_fn\fR, \fBOSSL_STORE_load_fn\fR, \fBOSSL_STORE_eof_fn\fR, +and \fBOSSL_STORE_close_fn\fR +are the function pointer types used within a \s-1STORE\s0 loader. +The functions pointed at define the functionality of the given loader. +.IP "\fBOSSL_STORE_open_fn\fR" 4 +.IX Item "OSSL_STORE_open_fn" +This function takes a \s-1URI\s0 and is expected to interpret it in the best +manner possible according to the scheme the loader implements, it also +takes a \fB\s-1UI_METHOD\s0\fR and associated data, to be used any time +something needs to be prompted for. +Furthermore, this function is expected to initialize what needs to be +initialized, to create a private data store (\fB\s-1OSSL_STORE_LOADER_CTX\s0\fR, see +above), and to return it. +If something goes wrong, this function is expected to return \s-1NULL.\s0 +.IP "\fBOSSL_STORE_ctrl_fn\fR" 4 +.IX Item "OSSL_STORE_ctrl_fn" +This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer, a command number +\&\fBcmd\fR and a \fBva_list\fR \fBargs\fR and is used to manipulate loader +specific parameters. +.Sp +Loader specific command numbers must begin at \fB\s-1OSSL_STORE_C_CUSTOM_START\s0\fR. +Any number below that is reserved for future globally known command +numbers. +.Sp +This function is expected to return 1 on success, 0 on error. +.IP "\fBOSSL_STORE_expect_fn\fR" 4 +.IX Item "OSSL_STORE_expect_fn" +This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and a \fB\s-1OSSL_STORE_INFO\s0\fR +identity \fBexpected\fR, and is used to tell the loader what object type is +expected. +\&\fBexpected\fR may be zero to signify that no specific object type is expected. +.Sp +This function is expected to return 1 on success, 0 on error. +.IP "\fBOSSL_STORE_find_fn\fR" 4 +.IX Item "OSSL_STORE_find_fn" +This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and a +\&\fB\s-1OSSL_STORE_SEARCH\s0\fR search criterion, and is used to tell the loader what +to search for. +.Sp +When called with the loader context being \fB\s-1NULL\s0\fR, this function is expected +to return 1 if the loader supports the criterion, otherwise 0. +.Sp +When called with the loader context being something other than \fB\s-1NULL\s0\fR, this +function is expected to return 1 on success, 0 on error. +.IP "\fBOSSL_STORE_load_fn\fR" 4 +.IX Item "OSSL_STORE_load_fn" +This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and a \fB\s-1UI_METHOD\s0\fR +with associated data. +It's expected to load the next available data, mold it into a data +structure that can be wrapped in a \fB\s-1OSSL_STORE_INFO\s0\fR using one of the +\&\s-1\fBOSSL_STORE_INFO\s0\fR\|(3) functions. +If no more data is available or an error occurs, this function is +expected to return \s-1NULL.\s0 +The \fBOSSL_STORE_eof_fn\fR and \fBOSSL_STORE_error_fn\fR functions must indicate if +it was in fact the end of data or if an error occurred. +.Sp +Note that this function retrieves \fIone\fR data item only. +.IP "\fBOSSL_STORE_eof_fn\fR" 4 +.IX Item "OSSL_STORE_eof_fn" +This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and is expected to +return 1 to indicate that the end of available data has been reached. +It is otherwise expected to return 0. +.IP "\fBOSSL_STORE_error_fn\fR" 4 +.IX Item "OSSL_STORE_error_fn" +This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and is expected to +return 1 to indicate that an error occurred in a previous call to the +\&\fBOSSL_STORE_load_fn\fR function. +It is otherwise expected to return 0. +.IP "\fBOSSL_STORE_close_fn\fR" 4 +.IX Item "OSSL_STORE_close_fn" +This function takes a \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer and is expected to +close or shut down what needs to be closed, and finally free the +contents of the \fB\s-1OSSL_STORE_LOADER_CTX\s0\fR pointer. +It returns 1 on success and 0 on error. +.SS "Functions" +.IX Subsection "Functions" +\&\fBOSSL_STORE_LOADER_new()\fR creates a new \fB\s-1OSSL_STORE_LOADER\s0\fR. +It takes an \fB\s-1ENGINE\s0\fR \fBe\fR and a string \fBscheme\fR. +\&\fBscheme\fR must \fIalways\fR be set. +Both \fBe\fR and \fBscheme\fR are used as is and must therefore be alive as +long as the created loader is. +.PP +\&\fBOSSL_STORE_LOADER_get0_engine()\fR returns the engine of the \fBstore_loader\fR. +\&\fBOSSL_STORE_LOADER_get0_scheme()\fR returns the scheme of the \fBstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_set_open()\fR sets the opener function for the +\&\fBstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_set_ctrl()\fR sets the control function for the +\&\fBstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_set_expect()\fR sets the expect function for the +\&\fBstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_set_load()\fR sets the loader function for the +\&\fBstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_set_eof()\fR sets the end of file checker function for the +\&\fBstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_set_close()\fR sets the closing function for the +\&\fBstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_free()\fR frees the given \fBstore_loader\fR. +.PP +\&\fBOSSL_STORE_register_loader()\fR register the given \fBstore_loader\fR and thereby +makes it available for use with \fBOSSL_STORE_open()\fR, \fBOSSL_STORE_load()\fR, +\&\fBOSSL_STORE_eof()\fR and \fBOSSL_STORE_close()\fR. +.PP +\&\fBOSSL_STORE_unregister_loader()\fR unregister the store loader for the given +\&\fBscheme\fR. +.SH "NOTES" +.IX Header "NOTES" +The \fBfile:\fR scheme has built in support. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The functions with the types \fBOSSL_STORE_open_fn\fR, \fBOSSL_STORE_ctrl_fn\fR, +\&\fBOSSL_STORE_expect_fn\fR, +\&\fBOSSL_STORE_load_fn\fR, \fBOSSL_STORE_eof_fn\fR and \fBOSSL_STORE_close_fn\fR have the +same return values as \fBOSSL_STORE_open()\fR, \fBOSSL_STORE_ctrl()\fR, \fBOSSL_STORE_expect()\fR, +\&\fBOSSL_STORE_load()\fR, \fBOSSL_STORE_eof()\fR and \fBOSSL_STORE_close()\fR, respectively. +.PP +\&\fBOSSL_STORE_LOADER_new()\fR returns a pointer to a \fB\s-1OSSL_STORE_LOADER\s0\fR on success, +or \fB\s-1NULL\s0\fR on failure. +.PP +\&\fBOSSL_STORE_LOADER_set_open()\fR, \fBOSSL_STORE_LOADER_set_ctrl()\fR, +\&\fBOSSL_STORE_LOADER_set_load()\fR, \fBOSSL_STORE_LOADER_set_eof()\fR and +\&\fBOSSL_STORE_LOADER_set_close()\fR return 1 on success, or 0 on failure. +.PP +\&\fBOSSL_STORE_register_loader()\fR returns 1 on success, or 0 on failure. +.PP +\&\fBOSSL_STORE_unregister_loader()\fR returns the unregistered loader on success, +or \fB\s-1NULL\s0\fR on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl_store\fR\|(7), \fBOSSL_STORE_open\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\s-1\fBOSSL_STORE_LOADER\s0()\fR, \s-1\fBOSSL_STORE_LOADER_CTX\s0()\fR, \fBOSSL_STORE_LOADER_new()\fR, +\&\fBOSSL_STORE_LOADER_set0_scheme()\fR, \fBOSSL_STORE_LOADER_set_open()\fR, +\&\fBOSSL_STORE_LOADER_set_ctrl()\fR, \fBOSSL_STORE_LOADER_set_load()\fR, +\&\fBOSSL_STORE_LOADER_set_eof()\fR, \fBOSSL_STORE_LOADER_set_close()\fR, +\&\fBOSSL_STORE_LOADER_free()\fR, \fBOSSL_STORE_register_loader()\fR, +\&\fBOSSL_STORE_unregister_loader()\fR, \fBOSSL_STORE_open_fn()\fR, \fBOSSL_STORE_ctrl_fn()\fR, +\&\fBOSSL_STORE_load_fn()\fR, \fBOSSL_STORE_eof_fn()\fR and \fBOSSL_STORE_close_fn()\fR +were added in OpenSSL 1.1.1. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2016\-2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +<https://www.openssl.org/source/license.html>. |