=head1 NAME
-OSSL_STORE_LOADER, OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new,
+OSSL_STORE_LOADER,
+OSSL_STORE_LOADER_fetch,
+OSSL_STORE_LOADER_up_ref,
+OSSL_STORE_LOADER_free,
+OSSL_STORE_LOADER_get0_provider,
+OSSL_STORE_LOADER_get0_properties,
+OSSL_STORE_LOADER_is_a,
+OSSL_STORE_LOADER_get_number,
+OSSL_STORE_LOADER_get0_description,
+OSSL_STORE_LOADER_do_all_provided,
+OSSL_STORE_LOADER_names_do_all,
+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_open, OSSL_STORE_LOADER_set_open_ex,
+OSSL_STORE_LOADER_set_attach, OSSL_STORE_LOADER_set_ctrl,
OSSL_STORE_LOADER_set_expect, OSSL_STORE_LOADER_set_find,
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_register_loader, OSSL_STORE_unregister_loader,
+OSSL_STORE_open_fn, OSSL_STORE_open_ex_fn,
+OSSL_STORE_attach_fn, OSSL_STORE_ctrl_fn,
OSSL_STORE_expect_fn, OSSL_STORE_find_fn,
OSSL_STORE_load_fn, OSSL_STORE_eof_fn, OSSL_STORE_error_fn,
OSSL_STORE_close_fn - Types and functions to manipulate, register and
typedef struct ossl_store_loader_st OSSL_STORE_LOADER;
+ OSSL_STORE_LOADER *OSSL_STORE_LOADER_fetch(const char *scheme,
+ OSSL_LIB_CTX *libctx,
+ const char *properties);
+ int OSSL_STORE_LOADER_up_ref(OSSL_STORE_LOADER *loader);
+ void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *loader);
+ const OSSL_PROVIDER *OSSL_STORE_LOADER_get0_provider(const OSSL_STORE_LOADER *
+ loader);
+ const char *OSSL_STORE_LOADER_get0_properties(const OSSL_STORE_LOADER *loader);
+ int OSSL_STORE_LOADER_get_number(const OSSL_STORE_LOADER *loader);
+ const char *OSSL_STORE_LOADER_get0_description(const OSSL_STORE_LOADER *loader);
+ int OSSL_STORE_LOADER_is_a(const OSSL_STORE_LOADER *loader,
+ const char *scheme);
+ void OSSL_STORE_LOADER_do_all_provided(OSSL_LIB_CTX *libctx,
+ void (*fn)(OSSL_STORE_LOADER *loader,
+ void *arg),
+ void *arg);
+ int OSSL_STORE_LOADER_names_do_all(const OSSL_STORE_LOADER *loader,
+ void (*fn)(const char *name, void *data),
+ void *data);
+
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
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);
/* 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);
+ 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 OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_ex_fn)(
+ const char *uri, const UI_METHOD *ui_method, void *ui_data);
+ int OSSL_STORE_LOADER_set_open_ex
+ (OSSL_STORE_LOADER *store_loader,
+ OSSL_STORE_open_ex_fn store_open_ex_function);
+ typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_attach_fn)
+ (const OSSL_STORE_LOADER *loader, BIO *bio,
+ OSSL_LIB_CTX *libctx, const char *propq,
+ const UI_METHOD *ui_method, void *ui_data);
+ int OSSL_STORE_LOADER_set_attach(OSSL_STORE_LOADER *loader,
+ OSSL_STORE_attach_fn attach_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,
=head1 DESCRIPTION
-These functions help applications and engines to create loaders for
-schemes they support.
+B<OSSL_STORE_LOADER> is a method for OSSL_STORE loaders, which implement
+OSSL_STORE_open(), OSSL_STORE_open_ex(), OSSL_STORE_load(),
+OSSL_STORE_eof(), OSSL_STORE_error() and OSSL_STORE_close() for specific
+storage schemes.
+
+OSSL_STORE_LOADER_fetch() looks for an implementation for a storage
+I<scheme> within the providers that has been loaded into the B<OSSL_LIB_CTX>
+given by I<ctx>, and with the properties given by I<properties>.
+
+OSSL_STORE_LOADER_up_ref() increments the reference count for the given
+I<loader>.
+
+OSSL_STORE_LOADER_free() decrements the reference count for the given
+I<loader>, and when the count reaches zero, frees it.
+
+OSSL_STORE_LOADER_get0_provider() returns the provider of the given
+I<loader>.
+
+OSSL_STORE_LOADER_get0_properties() returns the property definition associated
+with the given I<loader>.
+
+OSSL_STORE_LOADER_is_a() checks if I<loader> is an implementation
+of an algorithm that's identifiable with I<scheme>.
-=head2 Types
+OSSL_STORE_LOADER_get_number() returns the internal dynamic number assigned
+to the given I<loader>.
-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.
+OSSL_STORE_LOADER_get0_description() returns a description of the I<loader>, meant
+for display and human consumption. The description is at the discretion of the
+I<loader> implementation.
+
+OSSL_STORE_LOADER_do_all_provided() traverses all store implementations
+by all activated providers in the library context I<libctx>, and for each
+of the implementations, calls I<fn> with the implementation method and
+I<data> as arguments.
+
+OSSL_STORE_LOADER_names_do_all() traverses all names for the given
+I<loader>, and calls I<fn> with each name and I<data>.
+
+=head2 Legacy Types and Functions (deprecated)
+
+These functions help applications and engines to create loaders for
+schemes they support. These are all deprecated and discouraged in favour of
+provider implementations, see L<provider-storemgmt(7)>.
B<OSSL_STORE_LOADER_CTX> is a type template, to be defined by each loader
-using B<struct ossl_store_loader_ctx_st { ... }>.
+using C<struct ossl_store_loader_ctx_st { ... }>.
-B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>, B<OSSL_STORE_expect_fn>,
-B<OSSL_STORE_find_fn>, B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn>,
-and B<OSSL_STORE_close_fn>
+B<OSSL_STORE_open_fn>, B<OSSL_STORE_open_ex_fn>,
+B<OSSL_STORE_ctrl_fn>, B<OSSL_STORE_expect_fn>, B<OSSL_STORE_find_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>
+=item B<OSSL_STORE_open_fn> and B<OSSL_STORE_open_ex_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.
+B<OSSL_STORE_open_ex_fn> 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, as well as a
+library context I<libctx> with an associated property query I<propq>,
+to be used when fetching necessary algorithms to perform the loads.
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.
+initialized, to create a private data store (B<OSSL_STORE_LOADER_CTX>,
+see above), and to return it.
If something goes wrong, this function is expected to return NULL.
+B<OSSL_STORE_open_fn> does the same thing as
+B<OSSL_STORE_open_ex_fn> but uses NULL for the library
+context I<libctx> and property query I<propq>.
+
+=item B<OSSL_STORE_attach_fn>
+
+This function takes a B<BIO>, otherwise works like
+B<OSSL_STORE_open_ex_fn>.
+
=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
+
I<cmd> and a B<va_list> I<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.
+along with what
I<args> are expected with each of them.
=end comment
=item B<OSSL_STORE_expect_fn>
This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<OSSL_STORE_INFO>
-identity B<expected>, and is used to tell the loader what object type is
+identity I<expected>, and is used to tell the loader what object type is
expected.
-B<expected> may be zero to signify that no specific object type is expected.
+I<expected> may be zero to signify that no specific object type is expected.
This function is expected to return 1 on success, 0 on error.
B<OSSL_STORE_SEARCH> search criterion, and is used to tell the loader what
to search for.
-When called with the loader context being B<NULL>, this function is expected
+When called with the loader context being NULL, this function is expected
to return 1 if the loader supports the criterion, otherwise 0.
-When called with the loader context being something other than B<NULL>, this
+When called with the loader context being something other than NULL, this
function is expected to return 1 on success, 0 on error.
=item B<OSSL_STORE_load_fn>
=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
+return 1 to indicate that an error occurred in a previous call to the
B<OSSL_STORE_load_fn> function.
It is otherwise expected to return 0.
=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
+It takes an B<ENGINE> I<e> and a string I<scheme>.
+
I<scheme> must I<always> be set.
+Both I<e> and I<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_get0_engine() returns the engine of the I<store_loader>.
+OSSL_STORE_LOADER_get0_scheme() returns the scheme of the I<store_loader>.
OSSL_STORE_LOADER_set_open() sets the opener function for the
-B<store_loader>.
+I<store_loader>.
+
+OSSL_STORE_LOADER_set_open_ex() sets the opener with library context
+function for the I<store_loader>.
+
+OSSL_STORE_LOADER_set_attach() sets the attacher function for the
+I<store_loader>.
OSSL_STORE_LOADER_set_ctrl() sets the control function for the
-B<store_loader>.
+I<store_loader>.
OSSL_STORE_LOADER_set_expect() sets the expect function for the
-B<store_loader>.
+I<store_loader>.
OSSL_STORE_LOADER_set_load() sets the loader function for the
-B<store_loader>.
+I<store_loader>.
OSSL_STORE_LOADER_set_eof() sets the end of file checker function for the
-B<store_loader>.
+I<store_loader>.
OSSL_STORE_LOADER_set_close() sets the closing function for the
-B<store_loader>.
+I<store_loader>.
-OSSL_STORE_LOADER_free() frees the given B<store_loader>.
+OSSL_STORE_LOADER_free() frees the given I<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_register_loader() register the given I<store_loader> and
+thereby makes it available for use with OSSL_STORE_open(),
+OSSL_STORE_open_ex(), OSSL_STORE_load(), OSSL_STORE_eof()
+and OSSL_STORE_close().
OSSL_STORE_unregister_loader() unregister the store loader for the given
-B<scheme>.
+I<scheme>.
-=head1 NOTES
+=head1 RETURN VALUES
-The B<file:> scheme has built in support.
+OSSL_STORE_LOADER_fetch() returns a pointer to an OSSL_STORE_LOADER object,
+or NULL on error.
-=head1 RETURN VALUES
+OSSL_STORE_LOADER_up_ref() returns 1 on success, or 0 on error.
+
+OSSL_STORE_LOADER_names_do_all() returns 1 if the callback was called for all
+names. A return value of 0 means that the callback was not called for any names.
+
+OSSL_STORE_LOADER_free() doesn't return any value.
-The functions with the types B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>,
-B<OSSL_STORE_expect_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_ctrl(), OSSL_STORE_expect(),
+OSSL_STORE_LOADER_get0_provider() returns a pointer to a provider object, or
+NULL on error.
+
+OSSL_STORE_LOADER_get0_properties() returns a pointer to a property
+definition string, or NULL on error.
+
+OSSL_STORE_LOADER_is_a() returns 1 if I<loader> was identifiable,
+otherwise 0.
+
+OSSL_STORE_LOADER_get_number() returns an integer.
+
+OSSL_STORE_LOADER_get0_description() returns a pointer to a decription, or NULL if
+there isn't one.
+
+The functions with the types B<OSSL_STORE_open_fn>,
+B<OSSL_STORE_open_ex_fn>, B<OSSL_STORE_ctrl_fn>,
+B<OSSL_STORE_expect_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_open_ex(), OSSL_STORE_ctrl(), OSSL_STORE_expect(),
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.
+or 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_LOADER_set_open(), OSSL_STORE_LOADER_set_open_ex(),
+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.
+or NULL on failure.
=head1 SEE ALSO
-L<ossl_store(7)>, L<OSSL_STORE_open(3)>
+L<ossl_store(7)>, L<OSSL_STORE_open(3)>, L<OSSL_LIB_CTX(3)>,
+L<provider-storemgmt(7)>
=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_LOADER_fetch(), OSSL_STORE_LOADER_up_ref(),
+OSSL_STORE_LOADER_free(), OSSL_STORE_LOADER_get0_provider(),
+OSSL_STORE_LOADER_get0_properties(), OSSL_STORE_LOADER_is_a(),
+OSSL_STORE_LOADER_get_number(), OSSL_STORE_LOADER_do_all_provided() and
+OSSL_STORE_LOADER_names_do_all() were added in OpenSSL 3.0.
+
+OSSL_STORE_open_ex_fn() was added in OpenSSL 3.0.
+
+B<OSSL_STORE_LOADER>, B<OSSL_STORE_LOADER_CTX>, OSSL_STORE_LOADER_new(),
+OSSL_STORE_LOADER_set0_scheme(), OSSL_STORE_LOADER_get0_scheme(),
+OSSL_STORE_LOADER_get0_engine(), OSSL_STORE_LOADER_set_expect(),
+OSSL_STORE_LOADER_set_find(), OSSL_STORE_LOADER_set_attach(),
+OSSL_STORE_LOADER_set_open_ex(), 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_LOADER_set_error(),
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.
+were added in OpenSSL 1.1.1, and became deprecated in OpenSSL 3.0.
=head1 COPYRIGHT
-Copyright 2016-2017 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>.
projects / thirdparty / openssl.git / blobdiff