xref: /freebsd/secure/lib/libcrypto/man/man3/OSSL_STORE_LOADER.3 (revision e32fecd0c2c3ee37c47ee100f169e7eb0282a873)
Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)

Standard preamble:
========================================================================
..
..
.. 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 -- \(*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\} . 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.

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'.
.. .nr rF 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 . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . 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 . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . 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 .\} ========================================================================

Title "OSSL_STORE_LOADER 3"
OSSL_STORE_LOADER 3 "2023-02-07" "1.1.1t" "OpenSSL"
For nroff, turn off justification. Always turn off hyphenation; it makes
way too many mistakes in technical documents.
"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
"SYNOPSIS"
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
"DESCRIPTION"
Header "DESCRIPTION" These functions help applications and engines to create loaders for schemes they support.
"Types"
Subsection "Types" \fB\s-1OSSL_STORE_LOADER\s0 is the type to hold a loader. It contains a scheme and the functions needed to implement \fBOSSL_STORE_open(), OSSL_STORE_load(), OSSL_STORE_eof(), OSSL_STORE_error() and \fBOSSL_STORE_close() for this scheme.

\fB\s-1OSSL_STORE_LOADER_CTX\s0 is a type template, to be defined by each loader using struct ossl_store_loader_ctx_st { ... }.

\fBOSSL_STORE_open_fn, OSSL_STORE_ctrl_fn, OSSL_STORE_expect_fn, \fBOSSL_STORE_find_fn, OSSL_STORE_load_fn, OSSL_STORE_eof_fn, and OSSL_STORE_close_fn are the function pointer types used within a \s-1STORE\s0 loader. The functions pointed at define the functionality of the given loader.

"OSSL_STORE_open_fn" 4
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 \s-1UI_METHOD\s0 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 (\s-1OSSL_STORE_LOADER_CTX\s0, see above), and to return it. If something goes wrong, this function is expected to return \s-1NULL.\s0
"OSSL_STORE_ctrl_fn" 4
Item "OSSL_STORE_ctrl_fn" This function takes a \s-1OSSL_STORE_LOADER_CTX\s0 pointer, a command number \fBcmd and a va_list args and is used to manipulate loader specific parameters. .Sp Loader specific command numbers must begin at \s-1OSSL_STORE_C_CUSTOM_START\s0. 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.
"OSSL_STORE_expect_fn" 4
Item "OSSL_STORE_expect_fn" This function takes a \s-1OSSL_STORE_LOADER_CTX\s0 pointer and a \s-1OSSL_STORE_INFO\s0 identity expected, and is used to tell the loader what object type is expected. \fBexpected 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.
"OSSL_STORE_find_fn" 4
Item "OSSL_STORE_find_fn" This function takes a \s-1OSSL_STORE_LOADER_CTX\s0 pointer and a \fB\s-1OSSL_STORE_SEARCH\s0 search criterion, and is used to tell the loader what to search for. .Sp When called with the loader context being \s-1NULL\s0, 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 \s-1NULL\s0, this function is expected to return 1 on success, 0 on error.
"OSSL_STORE_load_fn" 4
Item "OSSL_STORE_load_fn" This function takes a \s-1OSSL_STORE_LOADER_CTX\s0 pointer and a \s-1UI_METHOD\s0 with associated data. It's expected to load the next available data, mold it into a data structure that can be wrapped in a \s-1OSSL_STORE_INFO\s0 using one of the \s-1OSSL_STORE_INFO\s0\|(3) functions. If no more data is available or an error occurs, this function is expected to return \s-1NULL.\s0 The OSSL_STORE_eof_fn and OSSL_STORE_error_fn functions must indicate if it was in fact the end of data or if an error occurred. .Sp Note that this function retrieves one data item only.
"OSSL_STORE_eof_fn" 4
Item "OSSL_STORE_eof_fn" This function takes a \s-1OSSL_STORE_LOADER_CTX\s0 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.
"OSSL_STORE_error_fn" 4
Item "OSSL_STORE_error_fn" This function takes a \s-1OSSL_STORE_LOADER_CTX\s0 pointer and is expected to return 1 to indicate that an error occurred in a previous call to the \fBOSSL_STORE_load_fn function. It is otherwise expected to return 0.
"OSSL_STORE_close_fn" 4
Item "OSSL_STORE_close_fn" This function takes a \s-1OSSL_STORE_LOADER_CTX\s0 pointer and is expected to close or shut down what needs to be closed, and finally free the contents of the \s-1OSSL_STORE_LOADER_CTX\s0 pointer. It returns 1 on success and 0 on error.
"Functions"
Subsection "Functions" \fBOSSL_STORE_LOADER_new() creates a new \s-1OSSL_STORE_LOADER\s0. It takes an \s-1ENGINE\s0 e and a string scheme. \fBscheme must always be set. Both e and scheme are used as is and must therefore be alive as long as the created loader is.

\fBOSSL_STORE_LOADER_get0_engine() returns the engine of the store_loader. \fBOSSL_STORE_LOADER_get0_scheme() returns the scheme of the store_loader.

\fBOSSL_STORE_LOADER_set_open() sets the opener function for the \fBstore_loader.

\fBOSSL_STORE_LOADER_set_ctrl() sets the control function for the \fBstore_loader.

\fBOSSL_STORE_LOADER_set_expect() sets the expect function for the \fBstore_loader.

\fBOSSL_STORE_LOADER_set_load() sets the loader function for the \fBstore_loader.

\fBOSSL_STORE_LOADER_set_eof() sets the end of file checker function for the \fBstore_loader.

\fBOSSL_STORE_LOADER_set_close() sets the closing function for the \fBstore_loader.

\fBOSSL_STORE_LOADER_free() frees the given store_loader.

\fBOSSL_STORE_register_loader() register the given store_loader and thereby makes it available for use with OSSL_STORE_open(), OSSL_STORE_load(), \fBOSSL_STORE_eof() and OSSL_STORE_close().

\fBOSSL_STORE_unregister_loader() unregister the store loader for the given \fBscheme.

"NOTES"
Header "NOTES" The file: scheme has built in support.
"RETURN VALUES"
Header "RETURN VALUES" The functions with the types OSSL_STORE_open_fn, OSSL_STORE_ctrl_fn, \fBOSSL_STORE_expect_fn, \fBOSSL_STORE_load_fn, OSSL_STORE_eof_fn and OSSL_STORE_close_fn have the same return values as OSSL_STORE_open(), OSSL_STORE_ctrl(), OSSL_STORE_expect(), \fBOSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close(), respectively.

\fBOSSL_STORE_LOADER_new() returns a pointer to a \s-1OSSL_STORE_LOADER\s0 on success, or \s-1NULL\s0 on failure.

\fBOSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_ctrl(), \fBOSSL_STORE_LOADER_set_load(), OSSL_STORE_LOADER_set_eof() and \fBOSSL_STORE_LOADER_set_close() return 1 on success, or 0 on failure.

\fBOSSL_STORE_register_loader() returns 1 on success, or 0 on failure.

\fBOSSL_STORE_unregister_loader() returns the unregistered loader on success, or \s-1NULL\s0 on failure.

"SEE ALSO"
Header "SEE ALSO" \fBossl_store\|(7), OSSL_STORE_open\|(3)
"HISTORY"
Header "HISTORY" \s-1OSSL_STORE_LOADER\s0(), \s-1OSSL_STORE_LOADER_CTX\s0(), OSSL_STORE_LOADER_new(), \fBOSSL_STORE_LOADER_set0_scheme(), OSSL_STORE_LOADER_set_open(), \fBOSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_load(), \fBOSSL_STORE_LOADER_set_eof(), OSSL_STORE_LOADER_set_close(), \fBOSSL_STORE_LOADER_free(), OSSL_STORE_register_loader(), \fBOSSL_STORE_unregister_loader(), OSSL_STORE_open_fn(), OSSL_STORE_ctrl_fn(), \fBOSSL_STORE_load_fn(), OSSL_STORE_eof_fn() and OSSL_STORE_close_fn() were added in OpenSSL 1.1.1.
"COPYRIGHT"
Header "COPYRIGHT" Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved.

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>.