[thirdparty/openssl.git] / doc / internal / man3 / ossl_provider_new.pod

=pod

=head1 NAME

ossl_provider_find, ossl_provider_new, ossl_provider_up_ref,
ossl_provider_free,
ossl_provider_set_fallback, ossl_provider_set_module_path,
ossl_provider_add_parameter,
ossl_provider_activate, ossl_provider_deactivate, ossl_provider_available,
ossl_provider_ctx,
ossl_provider_doall_activated,
ossl_provider_name, ossl_provider_dso,
ossl_provider_module_name, ossl_provider_module_path,
ossl_provider_libctx,
ossl_provider_teardown, ossl_provider_gettable_params,
ossl_provider_get_params,
ossl_provider_query_operation, ossl_provider_unquery_operation,
ossl_provider_set_operation_bit, ossl_provider_test_operation_bit,
ossl_provider_get_capabilities
- internal provider routines

=head1 SYNOPSIS

 #include "internal/provider.h"

 OSSL_PROVIDER *ossl_provider_find(OSSL_LIB_CTX *libctx, const char *name,
                                   int noconfig);
 OSSL_PROVIDER *ossl_provider_new(OSSL_LIB_CTX *libctx, const char *name,
                                  ossl_provider_init_fn *init_function
                                  int noconfig);
 int ossl_provider_up_ref(OSSL_PROVIDER *prov);
 void ossl_provider_free(OSSL_PROVIDER *prov);

 /* Setters */
 int ossl_provider_set_fallback(OSSL_PROVIDER *prov);
 int ossl_provider_set_module_path(OSSL_PROVIDER *prov, const char *path);
 int ossl_provider_add_parameter(OSSL_PROVIDER *prov, const char *name,
                                 const char *value);

 /*
  * Activate the Provider
  * If the Provider is a module, the module will be loaded
  */
 int ossl_provider_activate(OSSL_PROVIDER *prov, int retain_fallbacks);
 int ossl_provider_deactivate(OSSL_PROVIDER *prov);
 /* Check if provider is available (activated) */
 int ossl_provider_available(OSSL_PROVIDER *prov);

 /* Return pointer to the provider's context */
 void *ossl_provider_ctx(const OSSL_PROVIDER *prov);

 /* Iterate over all loaded providers */
 int ossl_provider_doall_activated(OSSL_LIB_CTX *,
                                   int (*cb)(OSSL_PROVIDER *provider,
                                             void *cbdata),
                                   void *cbdata);

 /* Getters for other library functions */
 const char *ossl_provider_name(OSSL_PROVIDER *prov);
 const DSO *ossl_provider_dso(OSSL_PROVIDER *prov);
 const char *ossl_provider_module_name(OSSL_PROVIDER *prov);
 const char *ossl_provider_module_path(OSSL_PROVIDER *prov);
 OSSL_LIB_CTX *ossl_provider_libctx(const OSSL_PROVIDER *prov);

 /* Thin wrappers around calls to the provider */
 void ossl_provider_teardown(const OSSL_PROVIDER *prov);
 const OSSL_PARAM *ossl_provider_gettable_params(const OSSL_PROVIDER *prov);
 int ossl_provider_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]);
 int ossl_provider_get_capabilities(const OSSL_PROVIDER *prov,
                                   const char *capability,
                                   OSSL_CALLBACK *cb,
                                   void *arg);
 const OSSL_ALGORITHM *ossl_provider_query_operation(const OSSL_PROVIDER *prov,
                                                     int operation_id,
                                                     int *no_cache);
 void ossl_provider_unquery_operation(const OSSL_PROVIDER *prov,
                                      int operation_id,
                                      const OSSL_ALGORITHM *algs);

 int ossl_provider_set_operation_bit(OSSL_PROVIDER *provider, size_t bitnum);
 int ossl_provider_test_operation_bit(OSSL_PROVIDER *provider, size_t bitnum,
                                      int *result);

=head1 DESCRIPTION

I<OSSL_PROVIDER> is a type that holds all the necessary information
to handle a provider, regardless of if it's built in to the
application or the OpenSSL libraries, or if it's a loadable provider
module.
Instances of this type are commonly referred to as "provider objects".

A provider object is always stored in a set of provider objects
in the library context.

Provider objects are reference counted.

Provider objects are initially inactive, i.e. they are only recorded
in the store, but are not used.
They are activated with the first call to ossl_provider_activate(),
and are deactivated with the last call to ossl_provider_deactivate().
Activation affects a separate counter.

=head2 Functions

ossl_provider_find() finds an existing provider object in the provider
object store by I<name>.
The config file will be automatically loaded unless I<noconfig> is set.
Typically I<noconfig> should be 0.
We set I<noconfig> to 1 only when calling these functions while processing a
config file in order to avoid recursively attempting to load the file.
The provider object it finds has its reference count incremented.

ossl_provider_new() creates a new provider object named I<name> and
stores it in the provider object store, unless there already is one
there with the same name.
If there already is one with the same name, it's returned with its
reference count incremented.
The config file will be automatically loaded unless I<noconfig> is set.
Typically I<noconfig> should be 0.
We set I<noconfig> to 1 only when calling these functions while processing a
config file in order to avoid recursively attempting to load the file.
The reference count of a newly created provider object will always
be 2; one for being added to the store, and one for the returned
reference.
If I<init_function> is NULL, the provider is assumed to be a
dynamically loadable module, with the symbol B<OSSL_provider_init> as
its initialisation function.
If I<init_function> isn't NULL, the provider is assumed to be built
in, with I<init_function> being the pointer to its initialisation
function.
For further description of the initialisation function, see the
description of ossl_provider_activate() below.

ossl_provider_up_ref() increments the provider object I<prov>'s
reference count.

ossl_provider_free() decrements the provider object I<prov>'s
reference count; when it drops to zero, the provider object is assumed
to have fallen out of use and will be deinitialized (its I<teardown>
function is called), and the associated module will be unloaded if one
was loaded, and I<prov> itself will be freed.

ossl_provider_set_fallback() marks an available provider I<prov> as
fallback.
Note that after this call, the provider object pointer that was
used can simply be dropped, but not freed.

ossl_provider_set_module_path() sets the module path to load the
provider module given the provider object I<prov>.
This will be used in preference to automatically trying to figure out
the path from the provider name and the default module directory (more
on this in L</NOTES>).

ossl_provider_libctx() returns the library context the given
provider I<prov> is registered in.

ossl_provider_add_parameter() adds a global parameter for the provider
to retrieve as it sees fit.
The parameters are a combination of I<name> and I<value>, and the
provider will use the name to find the value it wants.
Only text parameters can be given, and it's up to the provider to
interpret them.

ossl_provider_activate() "activates" the provider for the given
provider object I<prov> by incrementing its activation count, flagging
it as activated, and initializing it if it isn't already initialized.
Initializing means one of the following:

=over 4

=item *

If an initialization function was given with ossl_provider_new(), that
function will get called.

=item *

If no initialization function was given with ossl_provider_new(), a
loadable module with the I<name> that was given to ossl_provider_new()
will be located and loaded, then the symbol B<OSSL_provider_init> will
be located in that module, and called.

=back

If I<retain_fallbacks> is zero, fallbacks are disabled.  If it is nonzero,
fallbacks are left unchanged.

ossl_provider_deactivate() "deactivates" the provider for the given
provider object I<prov> by decrementing its activation count.  When
that count reaches zero, the activation flag is cleared.

ossl_provider_available() activates all fallbacks if no provider is
activated yet, then checks if given provider object I<prov> is
activated.

ossl_provider_ctx() returns a context created by the provider.
Outside of the provider, it's completely opaque, but it needs to be
passed back to some of the provider functions.

ossl_provider_doall_activated() iterates over all the currently
"activated" providers, and calls I<cb> for each of them.
If no providers have been "activated" yet, it tries to activate all
available fallback providers before iterating over them.

ossl_provider_name() returns the name that was given with
ossl_provider_new().

ossl_provider_dso() returns a reference to the module, for providers
that come in the form of loadable modules.

ossl_provider_module_name() returns the filename of the module, for
providers that come in the form of loadable modules.

ossl_provider_module_path() returns the full path of the module file,
for providers that come in the form of loadable modules.

ossl_provider_teardown() calls the provider's I<teardown> function, if
the provider has one.

ossl_provider_gettable_params() calls the provider's I<gettable_params>
function, if the provider has one.
It should return an array of I<OSSL_PARAM> to describe all the
parameters that the provider has for the provider object.

ossl_provider_get_params() calls the provider's parameter request
responder.
It should treat the given I<OSSL_PARAM> array as described in
L<OSSL_PARAM(3)>.

ossl_provider_get_capabilities() calls the provider's I<get_capabilities> function,
if the provider has one. It provides the name of the I<capability> and a
callback I<cb> parameter to call for each capability that has a matching name in
the provider. The callback gets passed OSSL_PARAM details about the capability as
well as the caller supplied argument I<arg>.

ossl_provider_query_operation() calls the provider's
I<query_operation> function, if the provider has one.
It should return an array of I<OSSL_ALGORITHM> for the given
I<operation_id>.

ossl_provider_unquery_operation() informs the provider that the result of
ossl_provider_query_operation() is no longer going to be directly accessed and
that all relevant information has been copied.

ossl_provider_set_operation_bit() registers a 1 for operation I<bitnum>
in a bitstring that's internal to I<provider>.

ossl_provider_tests_operation_bit() checks if the bit operation I<bitnum>
is set (1) or not (0) in the internal I<provider> bitstring, and sets
I<*result> to 1 or 0 accorddingly. 

=head1 NOTES

Locating a provider module happens as follows:

=over 4

=item 1.

If a path was given with ossl_provider_set_module_path(), use that as
module path.
Otherwise, use the provider object's name as module path, with
platform specific standard extensions added.

=item 2.

If the environment variable B<OPENSSL_MODULES> is defined, assume its
value is a directory specification and merge it with the module path.
Otherwise, merge the value of the OpenSSL built in macro B<MODULESDIR>
with the module path.

=back

When this process is done, the result is used when trying to load the
provider module.

The command C<openssl version -m> can be used to find out the value
of the built in macro B<MODULESDIR>.

=head1 RETURN VALUES

ossl_provider_find() and ossl_provider_new() return a pointer to a
provider object (I<OSSL_PROVIDER>) on success, or NULL on error.

ossl_provider_up_ref() returns the value of the reference count after
it has been incremented.

ossl_provider_free() doesn't return any value.

ossl_provider_doall_activated() returns 1 if the callback was called for all
activated providers.  A return value of 0 means that the callback was not
called for any activated providers.

ossl_provider_set_module_path(), ossl_provider_set_fallback(),
ossl_provider_activate(), ossl_provider_activate_leave_fallbacks() and
ossl_provider_deactivate() return 1 on success, or 0 on error.

ossl_provider_available() return 1 if the provider is available,
otherwise 0.

ossl_provider_name(), ossl_provider_dso(),
ossl_provider_module_name(), and ossl_provider_module_path() return a
pointer to their respective data if it's available, otherwise NULL
is returned.

ossl_provider_libctx() return a pointer to the library context.
This may be NULL, and is perfectly valid, as it denotes the default
global library context.

ossl_provider_teardown() doesn't return any value.

ossl_provider_gettable_params() returns a pointer to a constant
I<OSSL_PARAM> array if this function is available in the provider,
otherwise NULL.

ossl_provider_get_params() returns 1 on success, or 0 on error.
If this function isn't available in the provider, 0 is returned.

ossl_provider_set_operation_bit() and ossl_provider_test_operation_bit()
return 1 on success, or 0 on error.

ossl_provider_get_capabilities() returns 1 on success, or 0 on error.
If this function isn't available in the provider or the provider does not
support the requested capability then 0 is returned.

=head1 SEE ALSO

L<OSSL_PROVIDER(3)>, L<provider(7)>, L<openssl(1)>

=head1 HISTORY

The functions described here were all added in OpenSSL 3.0.

=head1 COPYRIGHT

Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.

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>.

=cut
Commit	Line	Data
c4532834 RL	1	=pod
	2
	3	=head1 NAME
	4
7c95390e	5	ossl_provider_find, ossl_provider_new, ossl_provider_up_ref,
3bbec1af RL	6	ossl_provider_free,
	7	ossl_provider_set_fallback, ossl_provider_set_module_path,
	8	ossl_provider_add_parameter,
390f9bad	9	ossl_provider_activate, ossl_provider_deactivate, ossl_provider_available,
3bbec1af	10	ossl_provider_ctx,
8f089576	11	ossl_provider_doall_activated,
85e2417c	12	ossl_provider_name, ossl_provider_dso,
c4532834	13	ossl_provider_module_name, ossl_provider_module_path,
a829b735	14	ossl_provider_libctx,
dca97d00	15	ossl_provider_teardown, ossl_provider_gettable_params,
b0001d0c P	16	ossl_provider_get_params,
b0001d0c P	17	ossl_provider_query_operation, ossl_provider_unquery_operation,
82ec09ec MC	18	ossl_provider_set_operation_bit, ossl_provider_test_operation_bit,
82ec09ec MC	19	ossl_provider_get_capabilities
099bd339	20	- internal provider routines
c4532834 RL	21
	22	=head1 SYNOPSIS
	23
	24	#include "internal/provider.h"
	25
b4250010	26	OSSL_PROVIDER ossl_provider_find(OSSL_LIB_CTX libctx, const char *name,
29dc6e00	27	int noconfig);
b4250010	28	OSSL_PROVIDER ossl_provider_new(OSSL_LIB_CTX libctx, const char *name,
29dc6e00 MC	29	ossl_provider_init_fn *init_function
29dc6e00 MC	30	int noconfig);
7c95390e	31	int ossl_provider_up_ref(OSSL_PROVIDER *prov);
c4532834 RL	32	void ossl_provider_free(OSSL_PROVIDER *prov);
	33
	34	/* Setters */
e55008a9	35	int ossl_provider_set_fallback(OSSL_PROVIDER *prov);
3bbec1af RL	36	int ossl_provider_set_module_path(OSSL_PROVIDER prov, const char path);
	37	int ossl_provider_add_parameter(OSSL_PROVIDER prov, const char name,
	38	const char *value);
c4532834	39
390f9bad RL	40	/*
	41	* Activate the Provider
	42	* If the Provider is a module, the module will be loaded
	43	*/
299f5ff3	44	int ossl_provider_activate(OSSL_PROVIDER *prov, int retain_fallbacks);
390f9bad RL	45	int ossl_provider_deactivate(OSSL_PROVIDER *prov);
390f9bad RL	46	/* Check if provider is available (activated) */
36f5ec55	47	int ossl_provider_available(OSSL_PROVIDER *prov);
c4532834	48
a39eb840 RL	49	/* Return pointer to the provider's context */
	50	void ossl_provider_ctx(const OSSL_PROVIDER prov);
	51
85e2417c	52	/* Iterate over all loaded providers */
8f089576 P	53	int ossl_provider_doall_activated(OSSL_LIB_CTX *,
	54	int (cb)(OSSL_PROVIDER provider,
	55	void *cbdata),
	56	void *cbdata);
85e2417c	57
c4532834 RL	58	/* Getters for other library functions */
	59	const char ossl_provider_name(OSSL_PROVIDER prov);
	60	const DSO ossl_provider_dso(OSSL_PROVIDER prov);
	61	const char ossl_provider_module_name(OSSL_PROVIDER prov);
	62	const char ossl_provider_module_path(OSSL_PROVIDER prov);
a829b735	63	OSSL_LIB_CTX ossl_provider_libctx(const OSSL_PROVIDER prov);
c4532834 RL	64
	65	/* Thin wrappers around calls to the provider */
	66	void ossl_provider_teardown(const OSSL_PROVIDER *prov);
dca97d00	67	const OSSL_PARAM ossl_provider_gettable_params(const OSSL_PROVIDER prov);
4e7991b4	68	int ossl_provider_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]);
82ec09ec MC	69	int ossl_provider_get_capabilities(const OSSL_PROVIDER *prov,
	70	const char *capability,
	71	OSSL_CALLBACK *cb,
	72	void *arg);
099bd339 RL	73	const OSSL_ALGORITHM ossl_provider_query_operation(const OSSL_PROVIDER prov,
	74	int operation_id,
	75	int *no_cache);
b0001d0c P	76	void ossl_provider_unquery_operation(const OSSL_PROVIDER *prov,
	77	int operation_id,
	78	const OSSL_ALGORITHM *algs);
c4532834	79
5a29b628 RL	80	int ossl_provider_set_operation_bit(OSSL_PROVIDER *provider, size_t bitnum);
	81	int ossl_provider_test_operation_bit(OSSL_PROVIDER *provider, size_t bitnum,
	82	int *result);
	83
c4532834 RL	84	=head1 DESCRIPTION
c4532834 RL	85
3bbec1af	86	I<OSSL_PROVIDER> is a type that holds all the necessary information
c4532834 RL	87	to handle a provider, regardless of if it's built in to the
	88	application or the OpenSSL libraries, or if it's a loadable provider
	89	module.
3bbec1af	90	Instances of this type are commonly referred to as "provider objects".
c4532834	91
3bbec1af	92	A provider object is always stored in a set of provider objects
c4532834 RL	93	in the library context.
c4532834 RL	94
3bbec1af	95	Provider objects are reference counted.
c4532834	96
3bbec1af RL	97	Provider objects are initially inactive, i.e. they are only recorded
3bbec1af RL	98	in the store, but are not used.
c4532834	99	They are activated with the first call to ossl_provider_activate(),
390f9bad RL	100	and are deactivated with the last call to ossl_provider_deactivate().
390f9bad RL	101	Activation affects a separate counter.
c4532834 RL	102
	103	=head2 Functions
	104
3bbec1af	105	ossl_provider_find() finds an existing provider object in the provider
29dc6e00 MC	106	object store by I<name>.
	107	The config file will be automatically loaded unless I<noconfig> is set.
	108	Typically I<noconfig> should be 0.
	109	We set I<noconfig> to 1 only when calling these functions while processing a
	110	config file in order to avoid recursively attempting to load the file.
3bbec1af RL	111	The provider object it finds has its reference count incremented.
	112
	113	ossl_provider_new() creates a new provider object named I<name> and
	114	stores it in the provider object store, unless there already is one
	115	there with the same name.
	116	If there already is one with the same name, it's returned with its
	117	reference count incremented.
29dc6e00 MC	118	The config file will be automatically loaded unless I<noconfig> is set.
	119	Typically I<noconfig> should be 0.
	120	We set I<noconfig> to 1 only when calling these functions while processing a
	121	config file in order to avoid recursively attempting to load the file.
3bbec1af RL	122	The reference count of a newly created provider object will always
	123	be 2; one for being added to the store, and one for the returned
	124	reference.
	125	If I<init_function> is NULL, the provider is assumed to be a
	126	dynamically loadable module, with the symbol B<OSSL_provider_init> as
	127	its initialisation function.
	128	If I<init_function> isn't NULL, the provider is assumed to be built
	129	in, with I<init_function> being the pointer to its initialisation
	130	function.
	131	For further description of the initialisation function, see the
	132	description of ossl_provider_activate() below.
	133
7c95390e	134	ossl_provider_up_ref() increments the provider object I<prov>'s
3bbec1af RL	135	reference count.
	136
	137	ossl_provider_free() decrements the provider object I<prov>'s
390f9bad RL	138	reference count; when it drops to zero, the provider object is assumed
	139	to have fallen out of use and will be deinitialized (its I<teardown>
	140	function is called), and the associated module will be unloaded if one
	141	was loaded, and I<prov> itself will be freed.
3bbec1af RL	142
	143	ossl_provider_set_fallback() marks an available provider I<prov> as
	144	fallback.
	145	Note that after this call, the provider object pointer that was
e55008a9 RL	146	used can simply be dropped, but not freed.
e55008a9 RL	147
3bbec1af RL	148	ossl_provider_set_module_path() sets the module path to load the
	149	provider module given the provider object I<prov>.
	150	This will be used in preference to automatically trying to figure out
	151	the path from the provider name and the default module directory (more
	152	on this in L</NOTES>).
	153
a829b735	154	ossl_provider_libctx() returns the library context the given
e74bd290 RL	155	provider I<prov> is registered in.
e74bd290 RL	156
3bbec1af RL	157	ossl_provider_add_parameter() adds a global parameter for the provider
	158	to retrieve as it sees fit.
	159	The parameters are a combination of I<name> and I<value>, and the
	160	provider will use the name to find the value it wants.
	161	Only text parameters can be given, and it's up to the provider to
	162	interpret them.
	163
c4532834	164	ossl_provider_activate() "activates" the provider for the given
390f9bad RL	165	provider object I<prov> by incrementing its activation count, flagging
	166	it as activated, and initializing it if it isn't already initialized.
	167	Initializing means one of the following:
c4532834 RL	168
	169	=over 4
	170
	171	=item *
	172
	173	If an initialization function was given with ossl_provider_new(), that
	174	function will get called.
	175
	176	=item *
	177
c2969ff6	178	If no initialization function was given with ossl_provider_new(), a
3bbec1af RL	179	loadable module with the I<name> that was given to ossl_provider_new()
3bbec1af RL	180	will be located and loaded, then the symbol B<OSSL_provider_init> will
c4532834 RL	181	be located in that module, and called.
	182
	183	=back
	184
299f5ff3 P	185	If I<retain_fallbacks> is zero, fallbacks are disabled. If it is nonzero,
	186	fallbacks are left unchanged.
	187
390f9bad RL	188	ossl_provider_deactivate() "deactivates" the provider for the given
	189	provider object I<prov> by decrementing its activation count. When
	190	that count reaches zero, the activation flag is cleared.
	191
36f5ec55 RL	192	ossl_provider_available() activates all fallbacks if no provider is
	193	activated yet, then checks if given provider object I<prov> is
	194	activated.
	195
a39eb840 RL	196	ossl_provider_ctx() returns a context created by the provider.
	197	Outside of the provider, it's completely opaque, but it needs to be
	198	passed back to some of the provider functions.
	199
8f089576	200	ossl_provider_doall_activated() iterates over all the currently
3bbec1af	201	"activated" providers, and calls I<cb> for each of them.
e55008a9	202	If no providers have been "activated" yet, it tries to activate all
3c5ce1ce	203	available fallback providers before iterating over them.
85e2417c	204
c4532834 RL	205	ossl_provider_name() returns the name that was given with
	206	ossl_provider_new().
	207
	208	ossl_provider_dso() returns a reference to the module, for providers
	209	that come in the form of loadable modules.
	210
9c0586d5	211	ossl_provider_module_name() returns the filename of the module, for
c4532834 RL	212	providers that come in the form of loadable modules.
	213
	214	ossl_provider_module_path() returns the full path of the module file,
	215	for providers that come in the form of loadable modules.
	216
3bbec1af	217	ossl_provider_teardown() calls the provider's I<teardown> function, if
c4532834 RL	218	the provider has one.
c4532834 RL	219
dca97d00	220	ossl_provider_gettable_params() calls the provider's I<gettable_params>
c4532834	221	function, if the provider has one.
26175013	222	It should return an array of I<OSSL_PARAM> to describe all the
3bbec1af	223	parameters that the provider has for the provider object.
c4532834 RL	224
	225	ossl_provider_get_params() calls the provider's parameter request
	226	responder.
3bbec1af	227	It should treat the given I<OSSL_PARAM> array as described in
c4532834 RL	228	L<OSSL_PARAM(3)>.
c4532834 RL	229
82ec09ec MC	230	ossl_provider_get_capabilities() calls the provider's I<get_capabilities> function,
	231	if the provider has one. It provides the name of the I<capability> and a
	232	callback I<cb> parameter to call for each capability that has a matching name in
	233	the provider. The callback gets passed OSSL_PARAM details about the capability as
	234	well as the caller supplied argument I<arg>.
	235
099bd339	236	ossl_provider_query_operation() calls the provider's
3bbec1af RL	237	I<query_operation> function, if the provider has one.
	238	It should return an array of I<OSSL_ALGORITHM> for the given
	239	I<operation_id>.
b0001d0c P	240
	241	ossl_provider_unquery_operation() informs the provider that the result of
	242	ossl_provider_query_operation() is no longer going to be directly accessed and
	243	that all relevant information has been copied.
099bd339	244
5a29b628 RL	245	ossl_provider_set_operation_bit() registers a 1 for operation I<bitnum>
	246	in a bitstring that's internal to I<provider>.
	247
	248	ossl_provider_tests_operation_bit() checks if the bit operation I<bitnum>
	249	is set (1) or not (0) in the internal I<provider> bitstring, and sets
	250	I<*result> to 1 or 0 accorddingly.
	251
c4532834 RL	252	=head1 NOTES
	253
	254	Locating a provider module happens as follows:
	255
	256	=over 4
	257
	258	=item 1.
	259
3bbec1af RL	260	If a path was given with ossl_provider_set_module_path(), use that as
	261	module path.
	262	Otherwise, use the provider object's name as module path, with
	263	platform specific standard extensions added.
c4532834 RL	264
	265	=item 2.
	266
3bbec1af RL	267	If the environment variable B<OPENSSL_MODULES> is defined, assume its
	268	value is a directory specification and merge it with the module path.
	269	Otherwise, merge the value of the OpenSSL built in macro B<MODULESDIR>
	270	with the module path.
c4532834	271
3bbec1af	272	=back
c4532834	273
3bbec1af RL	274	When this process is done, the result is used when trying to load the
3bbec1af RL	275	provider module.
c4532834	276
3bbec1af RL	277	The command C<openssl version -m> can be used to find out the value
3bbec1af RL	278	of the built in macro B<MODULESDIR>.
c4532834 RL	279
	280	=head1 RETURN VALUES
	281
	282	ossl_provider_find() and ossl_provider_new() return a pointer to a
3bbec1af	283	provider object (I<OSSL_PROVIDER>) on success, or NULL on error.
c4532834	284
7c95390e	285	ossl_provider_up_ref() returns the value of the reference count after
c4532834 RL	286	it has been incremented.
	287
	288	ossl_provider_free() doesn't return any value.
	289
8f089576	290	ossl_provider_doall_activated() returns 1 if the callback was called for all
3c5ce1ce P	291	activated providers. A return value of 0 means that the callback was not
	292	called for any activated providers.
	293
390f9bad	294	ossl_provider_set_module_path(), ossl_provider_set_fallback(),
299f5ff3 P	295	ossl_provider_activate(), ossl_provider_activate_leave_fallbacks() and
299f5ff3 P	296	ossl_provider_deactivate() return 1 on success, or 0 on error.
c4532834	297
36f5ec55 RL	298	ossl_provider_available() return 1 if the provider is available,
	299	otherwise 0.
	300
c4532834 RL	301	ossl_provider_name(), ossl_provider_dso(),
c4532834 RL	302	ossl_provider_module_name(), and ossl_provider_module_path() return a
3bbec1af	303	pointer to their respective data if it's available, otherwise NULL
c4532834 RL	304	is returned.
c4532834 RL	305
a829b735	306	ossl_provider_libctx() return a pointer to the library context.
e74bd290 RL	307	This may be NULL, and is perfectly valid, as it denotes the default
	308	global library context.
	309
79c44b4e	310	ossl_provider_teardown() doesn't return any value.
c4532834	311
dca97d00	312	ossl_provider_gettable_params() returns a pointer to a constant
26175013 RL	313	I<OSSL_PARAM> array if this function is available in the provider,
26175013 RL	314	otherwise NULL.
c4532834 RL	315
	316	ossl_provider_get_params() returns 1 on success, or 0 on error.
	317	If this function isn't available in the provider, 0 is returned.
	318
5a29b628 RL	319	ossl_provider_set_operation_bit() and ossl_provider_test_operation_bit()
	320	return 1 on success, or 0 on error.
	321
82ec09ec MC	322	ossl_provider_get_capabilities() returns 1 on success, or 0 on error.
	323	If this function isn't available in the provider or the provider does not
	324	support the requested capability then 0 is returned.
	325
c4532834 RL	326	=head1 SEE ALSO
c4532834 RL	327
3bbec1af	328	L<OSSL_PROVIDER(3)>, L<provider(7)>, L<openssl(1)>
c4532834 RL	329
	330	=head1 HISTORY
	331
	332	The functions described here were all added in OpenSSL 3.0.
	333
	334	=head1 COPYRIGHT
	335
8020d79b	336	Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
c4532834 RL	337
	338	Licensed under the Apache License 2.0 (the "License"). You may not use
	339	this file except in compliance with the License. You can obtain a copy
	340	in the file LICENSE in the source distribution or at
	341	L<https://www.openssl.org/source/license.html>.
	342
	343	=cut