diff options
Diffstat (limited to 'doc/man3/OSSL_STORE_open.pod')
| -rw-r--r-- | doc/man3/OSSL_STORE_open.pod | 72 |
1 files changed, 46 insertions, 26 deletions
diff --git a/doc/man3/OSSL_STORE_open.pod b/doc/man3/OSSL_STORE_open.pod index 71fdd6932f82..fe51912e84c0 100644 --- a/doc/man3/OSSL_STORE_open.pod +++ b/doc/man3/OSSL_STORE_open.pod @@ -2,9 +2,11 @@ =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 +OSSL_STORE_CTX, OSSL_STORE_post_process_info_fn, +OSSL_STORE_open, OSSL_STORE_open_ex, +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 @@ -19,18 +21,29 @@ OSSL_STORE_close - Types and functions to read objects from a URI 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_CTX * + OSSL_STORE_open_ex(const char *uri, OSSL_LIB_CTX *libctx, const char *propq, + const UI_METHOD *ui_method, void *ui_data, + const OSSL_PARAM params[], + OSSL_STORE_post_process_info_fn post_process, + void *post_process_data); + 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); +The following function has been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, +see L<openssl_user_macros(7)>: + + int OSSL_STORE_ctrl(OSSL_STORE_CTX *ctx, int cmd, ... /* args */); + =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). +from a given URI. 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(). @@ -41,19 +54,23 @@ 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. +information for OSSL_STORE_open(), OSSL_STORE_open_ex(), +OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close() to work +together. =head2 Functions -OSSL_STORE_open() takes a uri or path I<uri>, password UI method +OSSL_STORE_open_ex() takes a uri or path I<uri>, password UI method I<ui_method> with associated data I<ui_data>, and post processing callback I<post_process> with associated data I<post_process_data>, -opens a channel to the data located at that URI and returns a +a library context I<libctx> with an associated property query I<propq>, +and opens a channel to the data located at the URI and returns a B<OSSL_STORE_CTX> with all necessary internal information. The given I<ui_method> and I<ui_data> will be reused by all functions that use B<OSSL_STORE_CTX> when interaction is needed, for instance to provide a password. +The auxiliary L<OSSL_PARAM(3)> parameters in I<params> can be set to further +modify the store operation. The given I<post_process> and I<post_process_data> will be reused by OSSL_STORE_load() to manipulate or drop the value to be returned. The I<post_process> function drops values by returning NULL, which @@ -61,6 +78,9 @@ will cause OSSL_STORE_load() to start its process over with loading the next object, until I<post_process> returns something other than NULL, or the end of data is reached as indicated by OSSL_STORE_eof(). +OSSL_STORE_open() is similar to OSSL_STORE_open_ex() but uses NULL for +the I<params>, the library context I<libctx> and property query I<propq>. + OSSL_STORE_ctrl() takes a B<OSSL_STORE_CTX>, and command number I<cmd> and more arguments not specified here. The available loader specific command numbers and arguments they each @@ -75,14 +95,14 @@ There are also global controls available: 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 +This control expects one argument, a pointer to an I<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_load() takes a B<OSSL_STORE_CTX> and 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. @@ -97,12 +117,6 @@ 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. If I<ctx> is NULL it does nothing. -=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 @@ -127,13 +141,13 @@ See L<passphrase-encoding(7)> for further information. OSSL_STORE_open() returns a pointer to a B<OSSL_STORE_CTX> on success, or NULL on failure. -OSSL_STORE_load() returns a pointer to a B<OSSL_STORE_INFO> on success, or -NULL on error or when end of data is reached. +OSSL_STORE_load() returns a pointer to a B<OSSL_STORE_INFO> on success, or 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 NULL. -OSSL_STORE_eof() returns 1 if the end of data has been reached, otherwise -0. +OSSL_STORE_eof() returns 1 if the end of data has been reached +or an error occurred, 0 otherwise. OSSL_STORE_error() returns 1 if an error occurred in an OSSL_STORE_load() call, otherwise 0. @@ -147,18 +161,24 @@ L<passphrase-encoding(7)> =head1 HISTORY -OSSL_STORE_CTX(), OSSL_STORE_post_process_info_fn(), OSSL_STORE_open(), +OSSL_STORE_open_ex() was added in OpenSSL 3.0. + +B<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 in OpenSSL 1.1.1. Handling of NULL I<ctx> argument for OSSL_STORE_close() was introduced in OpenSSL 1.1.1h. +OSSL_STORE_open_ex() was added in OpenSSL 3.0. + +OSSL_STORE_ctrl() and OSSL_STORE_vctrl() were deprecated in OpenSSL 3.0. + =head1 COPYRIGHT -Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved. -Licensed under the OpenSSL license (the "License"). You may not use +Licensed under the Apache License 2.0 (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>. |