X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=doc%2Fman3%2FOSSL_STORE_open.pod;h=61571be490cacf50729f9b6310369a925b4778bb;hb=b425001010044adbdbcd98f8682694b30b73bbf4;hp=b63156a95c5904d02188a5c5fbbc9aa83d08c235;hpb=e2e603fe7c5b35d8dadb1eec4696307d16665731;p=thirdparty%2Fopenssl.git diff --git a/doc/man3/OSSL_STORE_open.pod b/doc/man3/OSSL_STORE_open.pod index b63156a95c..61571be490 100644 --- a/doc/man3/OSSL_STORE_open.pod +++ b/doc/man3/OSSL_STORE_open.pod @@ -2,14 +2,16 @@ =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 #include - + typedef struct ossl_store_ctx_st OSSL_STORE_CTX; typedef OSSL_STORE_INFO *(*OSSL_STORE_post_process_info_fn)(OSSL_STORE_INFO *, @@ -19,18 +21,28 @@ 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, + 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); +Deprecated since OpenSSL 3.0, can be hidden entirely by defining +B with a suitable version value, see +L: + + int OSSL_STORE_ctrl(OSSL_STORE_CTX *ctx, int cmd, ... /* args */); + =head1 DESCRIPTION These functions help the application to fetch supported objects (see L for information on which those are) -from a given URI (see L 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,96 +53,129 @@ described in L. =head2 Types B 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 B, password UI method -B with associated data B, and post processing -callback B with associated data B, -opens a channel to the data located at that URI and returns a +OSSL_STORE_open_ex() takes a uri or path I, password UI method +I with associated data I, and post processing +callback I with associated data I, +a library context I with an associated property query I, +and opens a channel to the data located at the URI and returns a B with all necessary internal information. -The given B and B will be reused by all -functions that use B when interaction is needed. -The given B and B will be reused by +The given I and I will be reused by all +functions that use B when interaction is needed, +for instance to provide a password. +The given I and I will be reused by OSSL_STORE_load() to manipulate or drop the value to be returned. +The I function drops values by returning NULL, which +will cause OSSL_STORE_load() to start its process over with loading +the next object, until I returns something other than +NULL, or the end of data is reached as indicated by OSSL_STORE_eof(). -OSSL_STORE_ctrl() takes a B, and command number B and +OSSL_STORE_open() is similar to OSSL_STORE_open_ex() but uses NULL for +the library context I and property query I. + +OSSL_STORE_ctrl() takes a B, and command number I and more arguments not specified here. -The available command numbers and arguments they each take depends on -the loader that's used and is documented together with that loader. +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 + +Controls if the loader should attempt to use secure memory for any +allocated B and its contents. +This control expects one argument, a pointer to an I that is expected to +have the value 1 (yes) or 0 (no). +Any other value is an error. -OSSL_STORE_load() takes a B, tries to load the next available -object and return it wrapped with B. +=back + +OSSL_STORE_load() takes a B and tries to load the next +available object and return it wrapped with B. OSSL_STORE_eof() takes a B and checks if we've reached the end of data. -OSSL_STORE_error() takes a B and checks if an error occured in +OSSL_STORE_error() takes a B 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, closes the channel that was opened by OSSL_STORE_open() and frees all other information that was stored in the B, as well as the B itself. - -=head1 SUPPORTED SCHEMES - -The basic supported scheme is B. -Any other scheme can be added dynamically, using -OSSL_STORE_register_loader(). +If I is NULL it does nothing. =head1 NOTES -When unsure whether a given string contains a simple file or directory -reference, or if it's a full blown URI, the question is how to figure -that out. -One way is to try OSSL_STORE_open_file() and if that fails, try -OSSL_STORE_open(). -The other way is the other way around. -Either way you choose, there are corner cases, -F might very will be a simple file reference -on a system that supports the notion of volumes. - -This manual won't tell you which way is better, that's up to each -application developer to decide on their own. -However, there are some tools that can be used together with +A string without a scheme prefix (that is, a non-URI string) is +implicitly interpreted as using the F 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. -If you decide to use OSSL_STORE_open() with OSSL_STORE_open_file() as a -fallback, those reasons can be good tools to decide if the fallback -should be taken or not. + +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 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 for further information. =head1 RETURN VALUES -OSSL_STORE_open() and OSSL_STORE_load() return a pointer to a B -on success, or B on failure. +OSSL_STORE_open() returns a pointer to a B on success, or +NULL on failure. + +OSSL_STORE_load() returns a pointer to a B 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_error() returns 1 if an error occured in a OSSL_STORE_load() call, +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, L, L +L, L, L, +L =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_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. +were added in OpenSSL 1.1.1. + +Handling of NULL I 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-2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2020 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.