Add documentation for STORE functions

Reviewed-by: NMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3542)

doc/man3/OSSL_STORE_INFO.pod

+=pod
+
+=head1 NAME
+
+OSSL_STORE_INFO, OSSL_STORE_INFO_get_type, OSSL_STORE_INFO_get0_NAME,
+OSSL_STORE_INFO_get0_NAME_description, OSSL_STORE_INFO_get0_PARAMS,
+OSSL_STORE_INFO_get0_PKEY, OSSL_STORE_INFO_get0_CERT, OSSL_STORE_INFO_get0_CRL,
+OSSL_STORE_INFO_get1_NAME, OSSL_STORE_INFO_get1_NAME_description,
+OSSL_STORE_INFO_get1_PARAMS, OSSL_STORE_INFO_get1_PKEY,
+OSSL_STORE_INFO_get1_CERT,
+OSSL_STORE_INFO_get1_CRL, OSSL_STORE_INFO_type_string, OSSL_STORE_INFO_free, 
+OSSL_STORE_INFO_new_NAME, OSSL_STORE_INFO_set0_NAME_description,
+OSSL_STORE_INFO_new_PARAMS, OSSL_STORE_INFO_new_PKEY, OSSL_STORE_INFO_new_CERT,
+OSSL_STORE_INFO_new_CRL - Functions to manipulate OSSL_STORE_INFO objects 
+
+=head1 SYNOPSIS
+
+ #include <openssl/store.h>
+ 
+ typedef struct ossl_store_info_st OSSL_STORE_INFO;
+
+ int OSSL_STORE_INFO_get_type(const OSSL_STORE_INFO *store_info);
+ const char *OSSL_STORE_INFO_get0_NAME(const OSSL_STORE_INFO *store_info);
+ char *OSSL_STORE_INFO_get1_NAME(const OSSL_STORE_INFO *store_info);
+ const char *OSSL_STORE_INFO_get0_NAME_description(const OSSL_STORE_INFO
+                                                   *store_info);
+ char *OSSL_STORE_INFO_get1_NAME_description(const OSSL_STORE_INFO *store_info);
+ EVP_PKEY *OSSL_STORE_INFO_get0_PARAMS(const OSSL_STORE_INFO *store_info);
+ EVP_PKEY *OSSL_STORE_INFO_get1_PARAMS(const OSSL_STORE_INFO *store_info);
+ EVP_PKEY *OSSL_STORE_INFO_get0_PKEY(const OSSL_STORE_INFO *store_info);
+ EVP_PKEY *OSSL_STORE_INFO_get1_PKEY(const OSSL_STORE_INFO *store_info);
+ X509 *OSSL_STORE_INFO_get0_CERT(const OSSL_STORE_INFO *store_info);
+ X509 *OSSL_STORE_INFO_get1_CERT(const OSSL_STORE_INFO *store_info);
+ X509_CRL *OSSL_STORE_INFO_get0_CRL(const OSSL_STORE_INFO *store_info);
+ X509_CRL *OSSL_STORE_INFO_get1_CRL(const OSSL_STORE_INFO *store_info);
+
+ const char *OSSL_STORE_INFO_type_string(int type);
+
+ void OSSL_STORE_INFO_free(OSSL_STORE_INFO *store_info);
+
+ OSSL_STORE_INFO *OSSL_STORE_INFO_new_NAME(char *name);
+ int OSSL_STORE_INFO_set0_NAME_description(OSSL_STORE_INFO *info, char *desc);
+ OSSL_STORE_INFO *OSSL_STORE_INFO_new_PARAMS(DSA *dsa_params);
+ OSSL_STORE_INFO *OSSL_STORE_INFO_new_PKEY(EVP_PKEY *pkey);
+ OSSL_STORE_INFO *OSSL_STORE_INFO_new_CERT(X509 *x509);
+ OSSL_STORE_INFO *OSSL_STORE_INFO_new_CRL(X509_CRL *crl);
+
+=head1 DESCRIPTION
+
+These functions are primarly useful for applications to retrieve
+supported objects from B<OSSL_STORE_INFO> objects and for scheme specific
+loaders to create B<OSSL_STORE_INFO> holders.
+
+=head2 Types
+
+B<OSSL_STORE_INFO> is an opaque type that's just an intermediary holder for
+the objects that have been retrieved by OSSL_STORE_load() and similar
+functions.
+Supported OpenSSL type object can be extracted using one of
+STORE_INFO_get0_TYPE().
+The life time of this extracted object is as long as the life time of
+the B<OSSL_STORE_INFO> it was extracted from, so care should be taken not
+to free the latter too early.
+As an alternative, STORE_INFO_get1_TYPE() extracts a duplicate (or the
+same object with its reference count increased), which can be used
+after the containing B<OSSL_STORE_INFO> has been freed.
+The object returned by STORE_INFO_get1_TYPE() must be freed separately
+by the caller.
+See L</SUPPORTED OBJECTS> for more information on the types that are
+supported.
+
+=head2 Functions
+
+OSSL_STORE_INFO_get_type() takes a B<OSSL_STORE_INFO> and returns the STORE
+type number for the object inside.
+STORE_INFO_get_type_string() takes a STORE type number and returns a
+short string describing it.
+
+OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(),
+OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
+OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all take a
+B<OSSL_STORE_INFO> and return the held object of the appropriate OpenSSL
+type provided that's what's held.
+
+OSSL_STORE_INFO_get1_NAME(), OSSL_STORE_INFO_get1_NAME_description(),
+OSSL_STORE_INFO_get1_PARAMS(), OSSL_STORE_INFO_get1_PKEY(),
+OSSL_STORE_INFO_get1_CERT() and OSSL_STORE_INFO_get1_CRL() all take a
+B<OSSL_STORE_INFO> and return a duplicate of the held object of the
+appropriate OpenSSL type provided that's what's held.
+
+OSSL_STORE_INFO_free() frees a B<OSSL_STORE_INFO> and its contained type.
+
+OSSL_STORE_INFO_new_NAME() , OSSL_STORE_INFO_new_PARAMS(),
+OSSL_STORE_INFO_new_PKEY(), OSSL_STORE_INFO_new_CERT() and
+OSSL_STORE_INFO_new_CRL() create a B<OSSL_STORE_INFO>
+object to hold the given input object.
+Additionally, for B<OSSL_STORE_INFO_NAME>` objects,
+OSSL_STORE_INFO_set0_NAME_description() can be used to add an extra
+description.
+This description is meant to be human readable and should be used for
+information printout.
+
+=head1 SUPPORTED OBJECTS
+
+Currently supported object types are:
+
+=over 4
+
+=item OSSL_STORE_INFO_NAME
+
+A name is exactly that, a name.
+It's like a name in a directory, but formatted as a complete URI.
+For example, the path in URI C<file:/foo/bar/> could include a file
+named C<cookie.pem>, and in that case, the returned B<OSSL_STORE_INFO_NAME>
+object would have the URI C<file:/foo/bar/cookie.pem>, which can be
+used by the application to get the objects in that file.
+This can be applied to all schemes that can somehow support a listing
+of object URIs.
+
+For C<file:> URIs that are used without the explicit scheme, or paths
+given to L<OSSL_STORE_open_file(3)>, the returned name will be the path of
+each object, so if C</foo/bar> was given and that path has the file
+C<cookie.pem>, the name C</foo/bar/cookie.pem> will be returned.
+
+At the discretion of the loader that was used to get these names, an
+extra description may be attached as well.
+
+=item OSSL_STORE_INFO_PARAMS
+
+Key parameters.
+
+=item OSSL_STORE_INFO_PKEY
+
+A private/public key of some sort.
+
+=item OSSL_STORE_INFO_CERT
+
+An X.509 certificate.
+
+=item OSSL_STORE_INFO_CRL
+
+A X.509 certificate reocation list.
+
+=back
+
+=head1 RETURN VALUES
+
+OSSL_STORE_INFO_get_type() returns the STORE type number of the given
+B<OSSL_STORE_INFO>.
+There is no error value.
+
+OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(),
+OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
+OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all return
+a pointer to the OpenSSL object on success, NULL otherwise.
+
+OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(),
+OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
+OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all return
+a pointer to a duplicate of the OpenSSL object on success, NULL otherwise.
+
+OSSL_STORE_INFO_type_string() returns a string on success, or B<NULL> on
+failure.
+
+OSSL_STORE_INFO_new_NAME(), OSSL_STORE_INFO_new_PARAMS(),
+OSSL_STORE_INFO_new_PKEY(), OSSL_STORE_INFO_new_CERT() and
+OSSL_STORE_INFO_new_CRL() return a B<OSSL_STORE_INFO>
+pointer on success, or B<NULL> on failure.
+
+OSSL_STORE_INFO_set0_NAME_description() returns 1 on success, or 0 on
+failure.
+
+=head1 SEE ALSO
+
+L<ossl_store(7)>, L<OSSL_STORE_open(3)>, L<OSSL_STORE_register_loader(3)>
+
+=head1 HISTORY
+
+OSSL_STORE_INFO(), OSSL_STORE_INFO_get_type(), OSSL_STORE_INFO_get0_NAME(),
+OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
+OSSL_STORE_INFO_get0_CERT(), OSSL_STORE_INFO_get0_CRL(),
+OSSL_STORE_INFO_type_string(), OSSL_STORE_INFO_free(), OSSL_STORE_INFO_new_NAME(),
+OSSL_STORE_INFO_new_PARAMS(), OSSL_STORE_INFO_new_PKEY(),
+OSSL_STORE_INFO_new_CERT() and OSSL_STORE_INFO_new_CRL()
+were added to OpenSSL 1.1.1.
+
+=head1 COPYRIGHT
+
+Copyright 2016-2017 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

doc/man3/OSSL_STORE_LOADER.pod

+=pod
+
+=head1 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_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_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
+
+=head1 SYNOPSIS
+
+ #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 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);
+
+=head1 DESCRIPTION
+
+These functions help applications and engines to create loaders for
+schemes they support.
+
+=head2 Types
+
+B<OSSL_STORE_LOADER> is the type to hold a loader.
+It contains a scheme and the functions needed to implement
+OSSL_STORE_open(), OSSL_STORE_load(), OSSL_STORE_eof(), OSSL_STORE_error() and
+OSSL_STORE_close() for this scheme.
+
+B<OSSL_STORE_LOADER_CTX> is a type template, to be defined by each loader
+using B<struct ossl_store_loader_ctx_st { ... }>.
+
+B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>, B<OSSL_STORE_load_fn>,
+B<OSSL_STORE_eof_fn> and B<OSSL_STORE_close_fn> are the function pointer
+types used within a STORE loader.
+The functions pointed at define the functionality of the given loader.
+
+=over 4
+
+=item B<OSSL_STORE_open_fn>
+
+This function takes a URI and is expected to interpret it in the best
+manner possible according to the scheme the loader implements, it also
+takes a B<UI_METHOD> 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 privata data store (B<OSSL_STORE_LOADER_CTX>, see
+above), and to return it.
+If something goes wrong, this function is expected to return NULL.
+
+=item B<OSSL_STORE_ctrl_fn>
+
+This function takes a B<OSSL_STORE_LOADER_CTX> pointer, a command number
+B<cmd> and a B<va_list> B<args> and is used to manipulate loader
+specific parameters.
+
+=begin comment
+
+Globally known command numbers are documented in L<OSSL_STORE_ctrl(3)>,
+along with what B<args> are expected with each of them.
+
+=end comment
+
+Loader specific command numbers must begin at B<OSSL_STORE_C_CUSTOM_START>.
+Any number below that is reserved for future globally known command
+numbers.
+
+This function is expected to return 1 on success, 0 on error.
+
+=item B<OSSL_STORE_load_fn>
+
+This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<UI_METHOD>
+with associated data.
+It's expected to load the next available data, mold it into a data
+structure that can be wrapped in a B<OSSL_STORE_INFO> using one of the
+L<OSSL_STORE_INFO(3)> functions.
+If no more data is available or an error occurs, this function is
+expected to return NULL.
+The B<OSSL_STORE_eof_fn> and B<OSSL_STORE_error_fn> functions must indicate if
+it was in fact the end of data or if an error occured.
+
+Note that this function retrives I<one> data item only.
+
+=item B<OSSL_STORE_eof_fn>
+
+This function takes a B<OSSL_STORE_LOADER_CTX> 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.
+
+=item B<OSSL_STORE_error_fn>
+
+This function takes a B<OSSL_STORE_LOADER_CTX> pointer and is expected to
+return 1 to indicate that an error occured in a previous call to the
+B<OSSL_STORE_load_fn> function.
+It is otherwise expected to return 0.
+
+=item B<OSSL_STORE_close_fn>
+
+This function takes a B<OSSL_STORE_LOADER_CTX> pointer and is expected to
+close or shut down what needs to be closed, and finally free the
+contents of the B<OSSL_STORE_LOADER_CTX> pointer.
+It returns 1 on success and 0 on error.
+
+=back
+
+=head2 Functions
+
+OSSL_STORE_LOADER_new() creates a new B<OSSL_STORE_LOADER>.
+It takes an B<ENGINE> B<e> and a string B<scheme>.
+B<scheme> must I<always> be set.
+Both B<e> and B<scheme> are used as is and must therefore be alive as
+long as the created loader is.
+
+OSSL_STORE_LOADER_get0_engine() returns the engine of the B<store_loader>.
+OSSL_STORE_LOADER_get0_scheme() returns the scheme of the B<store_loader>.
+
+OSSL_STORE_LOADER_set_open() sets the opener function for the
+B<store_loader>.
+
+OSSL_STORE_LOADER_set_ctrl() sets the control function for the
+B<store_loader>.
+
+OSSL_STORE_LOADER_set_load() sets the loader function for the
+B<store_loader>.
+
+OSSL_STORE_LOADER_set_eof() sets the end of file checker function for the
+B<store_loader>.
+
+OSSL_STORE_LOADER_set_close() sets the closing function for the
+B<store_loader>.
+
+OSSL_STORE_LOADER_free() frees the given B<store_loader>.
+
+OSSL_STORE_register_loader() register the given B<store_loader> and thereby
+makes it available for use with OSSL_STORE_open(), OSSL_STORE_load(),
+OSSL_STORE_eof() and OSSL_STORE_close().
+
+OSSL_STORE_unregister_loader() unregister the store loader for the given
+B<scheme>.
+
+=head1 NOTES
+
+The B<file:> scheme has built in support.
+
+=head1 RETURN VALUES
+
+The functions with the types B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>,
+B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn> and B<OSSL_STORE_close_fn> have the
+same return values as OSSL_STORE_open(), OSSL_STORE_load(), OSSL_STORE_eof() and
+OSSL_STORE_close(), respectively.
+
+OSSL_STORE_LOADER_new() returns a pointer to a B<OSSL_STORE_LOADER> on success,
+or B<NULL> on failure.
+
+OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_ctrl(),
+OSSL_STORE_LOADER_set_load(), OSSL_STORE_LOADER_set_eof() and
+OSSL_STORE_LOADER_set_close() return 1 on success, or 0 on failure.
+
+OSSL_STORE_register_loader() returns 1 on success, or 0 on failure.
+
+OSSL_STORE_unregister_loader() returns the unregistered loader on success,
+or B<NULL> on failure.
+
+=head1 SEE ALSO
+
+L<ossl_store(7)>, L<OSSL_STORE_open(3)>
+
+=head1 HISTORY
+
+OSSL_STORE_LOADER(), OSSL_STORE_LOADER_CTX(), OSSL_STORE_LOADER_new(),
+OSSL_STORE_LOADER_set0_scheme(), OSSL_STORE_LOADER_set_open(),
+OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_load(),
+OSSL_STORE_LOADER_set_eof(), 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_load_fn(), OSSL_STORE_eof_fn() and OSSL_STORE_close_fn()
+were added to OpenSSL 1.1.1.
+
+=head1 COPYRIGHT
+
+Copyright 2016-2017 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

doc/man3/OSSL_STORE_open.pod

+=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.
+
+OSSL_STORE_ctrl() takes a B<OSSL_STORE_CTX>, and command number B<cmd> 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.
+
+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 occured in
+the last OSSL_STORE_load() call.
+
+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
+
+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<file:/foo/bar/cookie.txt> 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
+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>.
+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.
+
+=head1 RETURN VALUES
+
+OSSL_STORE_open() and OSSL_STORE_load() return a pointer to a B<OSSL_STORE_CTX>
+on success, or B<NULL> on failure.
+
+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,
+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)>
+
+=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-2017 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

doc/man7/ossl_store.pod

+=pod
+
+=head1 NAME
+
+ossl_store - Store retrieval functions
+
+=head1 SYNOPSIS
+
+=for comment generic
+
+#include <openssl/store.h>
+
+=head1 DESCRIPTION
+
+=head2 General
+
+A STORE is a layer of functionality to retrieve a number of supported
+objects from a repository of any kind, addressable as a file name or
+as a URI.
+
+The functionality supports the pattern "open a channel to the
+repository", "loop and retrieve one object at a time", and "finish up
+by closing the channel".
+
+The retrieved objects are returned as a wrapper type B<OSSL_STORE_INFO>,
+from which an OpenSSL type can be retrieved.
+
+=head2 URI schemes and loaders
+
+Support for a URI scheme is called a STORE "loader", and can be added
+dynamically from the calling application or from a loadable engine.
+
+=head2 The 'file' scheme
+
+Support for the 'file' scheme is already built into C<libcrypto>.
+Since files come in all kinds of formats and content types, the 'file'
+scheme has its own layer of functionality called "file handlers",
+which are used to try to decode diverse types of file contents.
+
+In case a file is formatted as PEM, each called file handler receives
+the PEM name (everything following any 'C<-----BEGIN >') as well as
+possible PEM headers, together with the decoded PEM body.  Since PEM
+formatted files can contain more than one object, the file handlers
+are called upon for each such object.
+
+If the file isn't determined to be formatted as PEM, the content is
+loaded in raw form in its entirety and passed to the available file
+handlers as is, with no PEM name or headers.
+
+Each file handler is expected to handle PEM and non-PEM content as
+appropriate.  Some may refuse non-PEM content for the sake of
+determinism (for example, there are keys out in the wild that are
+represented as an ASN.1 OCTET STRING.  In raw form, it's not easily
+possible to distinguish those from any other data coming as an ASN.1
+OCTET STRING, so such keys would naturally be accepted as PEM files
+only).
+
+=head1 EXAMPLES
+
+=head2 A generic call
+
+ /*
+  * There is also a OSSL_STORE_open_file() that can be used for file paths
+  * that can't be represented as URIs, such as Windows backslashes
+  */
+ OSSL_STORE_CTX *ctx = OSSL_STORE_open("file:/foo/bar/data.pem");
+
+ /*
+  * OSSL_STORE_eof() simulates file semantics for any repository to signal
+  * that no more data can be expected
+  */ 
+ while (!OSSL_STORE_eof(ctx)) {
+     OSSL_STORE_INFO *info = OSSL_STORE_load(ctx);
+
+     /*
+      * Do whatever is necessary with the OSSL_STORE_INFO,
+      * here just one example
+      */
+     switch (OSSL_STORE_INFO_get_type(info)) {
+     case OSSL_STORE_INFO_X509:
+         /* Print the X.509 certificate text */
+         X509_print_fp(stdout, OSSL_STORE_INFO_get0_CERT(info));
+         /* Print the X.509 certificate PEM output */
+         PEM_write_X509(stdout, OSSL_STORE_INFO_get0_CERT(info));
+         break;
+     }
+ }
+
+ OSSL_STORE_close(ctx);
+
+=head1 SEE ALSO
+L<OSSL_STORE_open(3)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016-2017 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