Add documentation for STORE functions

=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

=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

=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