diff options
Diffstat (limited to 'doc/man3/OSSL_STORE_open.pod')
| -rw-r--r-- | doc/man3/OSSL_STORE_open.pod | 161 |
1 files changed, 161 insertions, 0 deletions
diff --git a/doc/man3/OSSL_STORE_open.pod b/doc/man3/OSSL_STORE_open.pod new file mode 100644 index 000000000000..b1467f4100a7 --- /dev/null +++ b/doc/man3/OSSL_STORE_open.pod @@ -0,0 +1,161 @@ +=pod + +=head1 NAME + +OSSL_STORE_CTX, OSSL_STORE_post_process_info_fn, OSSL_STORE_open, +OSSL_STORE_ctrl, OSSL_STORE_load, OSSL_STORE_eof, OSSL_STORE_error, +OSSL_STORE_close - Types and functions to read objects from a URI + +=head1 SYNOPSIS + + #include <openssl/store.h> + + typedef struct ossl_store_ctx_st OSSL_STORE_CTX; + + typedef OSSL_STORE_INFO *(*OSSL_STORE_post_process_info_fn)(OSSL_STORE_INFO *, + void *); + + OSSL_STORE_CTX *OSSL_STORE_open(const char *uri, const UI_METHOD *ui_method, + void *ui_data, + OSSL_STORE_post_process_info_fn post_process, + void *post_process_data); + int OSSL_STORE_ctrl(OSSL_STORE_CTX *ctx, int cmd, ... /* args */); + OSSL_STORE_INFO *OSSL_STORE_load(OSSL_STORE_CTX *ctx); + int OSSL_STORE_eof(OSSL_STORE_CTX *ctx); + int OSSL_STORE_error(OSSL_STORE_CTX *ctx); + int OSSL_STORE_close(OSSL_STORE_CTX *ctx); + +=head1 DESCRIPTION + +These functions help the application to fetch supported objects (see +L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS> for information on which those are) +from a given URI (see L</SUPPORTED SCHEMES> for more information on +the supported URI schemes). +The general method to do so is to "open" the URI using OSSL_STORE_open(), +read each available and supported object using OSSL_STORE_load() as long as +OSSL_STORE_eof() hasn't been reached, and finish it off with OSSL_STORE_close(). + +The retrieved information is stored in a B<OSSL_STORE_INFO>, which is further +described in L<OSSL_STORE_INFO(3)>. + +=head2 Types + +B<OSSL_STORE_CTX> is a context variable that holds all the internal +information for OSSL_STORE_open(), OSSL_STORE_load(), OSSL_STORE_eof() and +OSSL_STORE_close() to work together. + +=head2 Functions + +OSSL_STORE_open() takes a uri or path B<uri>, password UI method +B<ui_method> with associated data B<ui_data>, and post processing +callback B<post_process> with associated data B<post_process_data>, +opens a channel to the data located at that URI and returns a +B<OSSL_STORE_CTX> with all necessary internal information. +The given B<ui_method> and B<ui_data_data> will be reused by all +functions that use B<OSSL_STORE_CTX> when interaction is needed. +The given B<post_process> and B<post_process_data> will be reused by +OSSL_STORE_load() to manipulate or drop the value to be returned. +The B<post_process> function drops values by returning B<NULL>, which +will cause OSSL_STORE_load() to start its process over with loading +the next object, until B<post_process> returns something other than +B<NULL>, or the end of data is reached as indicated by OSSL_STORE_eof(). + +OSSL_STORE_ctrl() takes a B<OSSL_STORE_CTX>, and command number B<cmd> and +more arguments not specified here. +The available loader specific command numbers and arguments they each +take depends on the loader that's used and is documented together with +that loader. + +There are also global controls available: + +=over 4 + +=item B<OSSL_STORE_C_USE_SECMEM> + +Controls if the loader should attempt to use secure memory for any +allocated B<OSSL_STORE_INFO> and its contents. +This control expects one argument, a pointer to an B<int> that is expected to +have the value 1 (yes) or 0 (no). +Any other value is an error. + +=back + +OSSL_STORE_load() takes a B<OSSL_STORE_CTX>, tries to load the next available +object and return it wrapped with B<OSSL_STORE_INFO>. + +OSSL_STORE_eof() takes a B<OSSL_STORE_CTX> and checks if we've reached the end +of data. + +OSSL_STORE_error() takes a B<OSSL_STORE_CTX> and checks if an error occurred in +the last OSSL_STORE_load() call. +Note that it may still be meaningful to try and load more objects, unless +OSSL_STORE_eof() shows that the end of data has been reached. + +OSSL_STORE_close() takes a B<OSSL_STORE_CTX>, closes the channel that was opened +by OSSL_STORE_open() and frees all other information that was stored in the +B<OSSL_STORE_CTX>, as well as the B<OSSL_STORE_CTX> itself. + +=head1 SUPPORTED SCHEMES + +The basic supported scheme is B<file:>. +Any other scheme can be added dynamically, using +OSSL_STORE_register_loader(). + +=head1 NOTES + +A string without a scheme prefix (that is, a non-URI string) is +implicitly interpreted as using the F<file:> scheme. + +There are some tools that can be used together with +OSSL_STORE_open() to determine if any failure is caused by an unparsable +URI, or if it's a different error (such as memory allocation +failures); if the URI was parsable but the scheme unregistered, the +top error will have the reason C<OSSL_STORE_R_UNREGISTERED_SCHEME>. + +These functions make no direct assumption regarding the pass phrase received +from the password callback. +The loaders may make assumptions, however. +For example, the B<file:> scheme loader inherits the assumptions made by +OpenSSL functionality that handles the different file types; this is mostly +relevant for PKCS#12 objects. +See L<passphrase-encoding(7)> for further information. + +=head1 RETURN VALUES + +OSSL_STORE_open() returns a pointer to a B<OSSL_STORE_CTX> on success, or +B<NULL> on failure. + +OSSL_STORE_load() returns a pointer to a B<OSSL_STORE_INFO> on success, or +B<NULL> on error or when end of data is reached. +Use OSSL_STORE_error() and OSSL_STORE_eof() to determine the meaning of a +returned B<NULL>. + +OSSL_STORE_eof() returns 1 if the end of data has been reached, otherwise +0. + +OSSL_STORE_error() returns 1 if an error occurred in an OSSL_STORE_load() call, +otherwise 0. + +OSSL_STORE_ctrl() and OSSL_STORE_close() returns 1 on success, or 0 on failure. + +=head1 SEE ALSO + +L<ossl_store(7)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_register_loader(3)>, +L<passphrase-encoding(7)> + +=head1 HISTORY + +OSSL_STORE_CTX(), OSSL_STORE_post_process_info_fn(), OSSL_STORE_open(), +OSSL_STORE_ctrl(), OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close() +were added to OpenSSL 1.1.1. + +=head1 COPYRIGHT + +Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut |