[thirdparty/openssl.git] / doc / man3 / OSSL_PROVIDER.pod

=pod

=head1 NAME

OSSL_PROVIDER_set_default_search_path,
OSSL_PROVIDER, OSSL_PROVIDER_load, OSSL_PROVIDER_unload,
OSSL_PROVIDER_available, OSSL_PROVIDER_do_all,
OSSL_PROVIDER_gettable_params, OSSL_PROVIDER_get_params,
OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_name - provider routines

=head1 SYNOPSIS

 #include <openssl/provider.h>

 typedef struct ossl_provider_st OSSL_PROVIDER;

 void OSSL_PROVIDER_set_default_search_path(OPENSSL_CTX *libctx,
                                            const char *path);

 OSSL_PROVIDER *OSSL_PROVIDER_load(OPENSSL_CTX *libctx, const char *name);
 int OSSL_PROVIDER_unload(OSSL_PROVIDER *prov);
 int OSSL_PROVIDER_available(OPENSSL_CTX *libctx, const char *name);
 int OSSL_PROVIDER_do_all(OPENSSL_CTX *ctx,
                          int (*cb)(OSSL_PROVIDER *provider, void *cbdata),
                          void *cbdata);

 const OSSL_PARAM *OSSL_PROVIDER_gettable_params(OSSL_PROVIDER *prov);
 int OSSL_PROVIDER_get_params(OSSL_PROVIDER *prov, OSSL_PARAM params[]);

 int OSSL_PROVIDER_add_builtin(OPENSSL_CTX *libctx, const char *name,
                               ossl_provider_init_fn *init_fn);

 const char *OSSL_PROVIDER_name(const OSSL_PROVIDER *prov);

=head1 DESCRIPTION

B<OSSL_PROVIDER> is a type that holds internal information about
implementation providers (see L<provider(7)> for information on what a
provider is).
A provider can be built in to the application or the OpenSSL
libraries, or can be a loadable module.
The functions described here handle both forms.

Some of these functions operate within a library context, please see
L<OPENSSL_CTX(3)> for further details.

=head2 Functions

OSSL_PROVIDER_set_default_search_path() specifies the default search B<path>
that is to be used for looking for providers in the specified B<libctx>.
If left unspecified, an environment variable and a fall back default value will
be used instead.

OSSL_PROVIDER_add_builtin() is used to add a built in provider to
B<OSSL_PROVIDER> store in the given library context, by associating a
provider name with a provider initialization function.
This name can then be used with OSSL_PROVIDER_load().

OSSL_PROVIDER_load() loads and initializes a provider.
This may simply initialize a provider that was previously added with
OSSL_PROVIDER_add_builtin() and run its given initialization function,
or load a provider module with the given name and run its provider
entry point, C<OSSL_provider_init>.

OSSL_PROVIDER_unload() unloads the given provider.
For a provider added with OSSL_PROVIDER_add_builtin(), this simply
runs its teardown function.

OSSL_PROVIDER_available() checks if a named provider is available
for use.

OSSL_PROVIDER_do_all() iterates over all loaded providers, calling
I<cb> for each one, with the current provider in I<provider> and the
I<cbdata> that comes from the caller.

OSSL_PROVIDER_gettable_params() is used to get a provider parameter
descriptor set as a constant B<OSSL_PARAM> array.
See L<OSSL_PARAM(3)> for more information.

OSSL_PROVIDER_get_params() is used to get provider parameter values.
The caller must prepare the B<OSSL_PARAM> array before calling this
function, and the variables acting as buffers for this parameter array
should be filled with data when it returns successfully.

OSSL_PROVIDER_name() returns the name of the given provider.

=head1 RETURN VALUES

OSSL_PROVIDER_add() returns 1 on success, or 0 on error.

OSSL_PROVIDER_load() returns a pointer to a provider object on
success, or B<NULL> on error.

OSSL_PROVIDER_unload() returns 1 on success, or 0 on error.

OSSL_PROVIDER_available() returns 1 if the named provider is available,
otherwise 0.

OSSL_PROVIDER_gettable_params() returns a pointer to an array
of constant B<OSSL_PARAM>, or NULL if none is provided.

OSSL_PROVIDER_get_params() returns 1 on success, or 0 on error.

=head1 EXAMPLES

This demonstrates how to load the provider module "foo" and ask for
its build number.

 OSSL_PROVIDER *prov = NULL;
 const char *build = NULL;
 size_t built_l = 0;
 OSSL_PARAM request[] = {
     { "build", OSSL_PARAM_UTF8_STRING_PTR, &build, 0, &build_l },
     { NULL, 0, NULL, 0, NULL }
 };

 if ((prov = OSSL_PROVIDER_load(NULL, "foo")) != NULL
     && OSSL_PROVIDER_get_params(prov, request))
     printf("Provider 'foo' build %s\n", build);
 else
     ERR_print_errors_fp(stderr);

=head1 SEE ALSO

L<openssl-core.h(7)>, L<OPENSSL_CTX(3)>, L<provider(7)>

=head1 HISTORY

The type and functions described here were added in OpenSSL 3.0.

=head1 COPYRIGHT

Copyright 2019-2020 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
6bd4e3f2	5	OSSL_PROVIDER_set_default_search_path,
c4532834	6	OSSL_PROVIDER, OSSL_PROVIDER_load, OSSL_PROVIDER_unload,
a7ad40c5	7	OSSL_PROVIDER_available, OSSL_PROVIDER_do_all,
dca97d00	8	OSSL_PROVIDER_gettable_params, OSSL_PROVIDER_get_params,
b37066fd	9	OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_name - provider routines
c4532834 RL	10
	11	=head1 SYNOPSIS
	12
	13	#include <openssl/provider.h>
	14
	15	typedef struct ossl_provider_st OSSL_PROVIDER;
	16
6bd4e3f2 P	17	void OSSL_PROVIDER_set_default_search_path(OPENSSL_CTX *libctx,
	18	const char *path);
	19
36f5ec55	20	OSSL_PROVIDER OSSL_PROVIDER_load(OPENSSL_CTX libctx, const char *name);
c4532834	21	int OSSL_PROVIDER_unload(OSSL_PROVIDER *prov);
36f5ec55	22	int OSSL_PROVIDER_available(OPENSSL_CTX libctx, const char name);
a7ad40c5 RL	23	int OSSL_PROVIDER_do_all(OPENSSL_CTX *ctx,
	24	int (cb)(OSSL_PROVIDER provider, void *cbdata),
	25	void *cbdata);
c4532834	26
dca97d00	27	const OSSL_PARAM OSSL_PROVIDER_gettable_params(OSSL_PROVIDER prov);
4e7991b4	28	int OSSL_PROVIDER_get_params(OSSL_PROVIDER *prov, OSSL_PARAM params[]);
c4532834	29
36f5ec55	30	int OSSL_PROVIDER_add_builtin(OPENSSL_CTX libctx, const char name,
c4532834 RL	31	ossl_provider_init_fn *init_fn);
c4532834 RL	32
b37066fd RL	33	const char OSSL_PROVIDER_name(const OSSL_PROVIDER prov);
b37066fd RL	34
c4532834 RL	35	=head1 DESCRIPTION
	36
	37	B<OSSL_PROVIDER> is a type that holds internal information about
	38	implementation providers (see L<provider(7)> for information on what a
	39	provider is).
	40	A provider can be built in to the application or the OpenSSL
	41	libraries, or can be a loadable module.
	42	The functions described here handle both forms.
	43
36f5ec55 RL	44	Some of these functions operate within a library context, please see
	45	L<OPENSSL_CTX(3)> for further details.
	46
c4532834 RL	47	=head2 Functions
c4532834 RL	48
6bd4e3f2 P	49	OSSL_PROVIDER_set_default_search_path() specifies the default search B<path>
	50	that is to be used for looking for providers in the specified B<libctx>.
	51	If left unspecified, an environment variable and a fall back default value will
	52	be used instead.
	53
c4532834 RL	54	OSSL_PROVIDER_add_builtin() is used to add a built in provider to
	55	B<OSSL_PROVIDER> store in the given library context, by associating a
	56	provider name with a provider initialization function.
	57	This name can then be used with OSSL_PROVIDER_load().
	58
	59	OSSL_PROVIDER_load() loads and initializes a provider.
	60	This may simply initialize a provider that was previously added with
	61	OSSL_PROVIDER_add_builtin() and run its given initialization function,
	62	or load a provider module with the given name and run its provider
	63	entry point, C<OSSL_provider_init>.
	64
	65	OSSL_PROVIDER_unload() unloads the given provider.
	66	For a provider added with OSSL_PROVIDER_add_builtin(), this simply
	67	runs its teardown function.
	68
36f5ec55 RL	69	OSSL_PROVIDER_available() checks if a named provider is available
	70	for use.
	71
a7ad40c5 RL	72	OSSL_PROVIDER_do_all() iterates over all loaded providers, calling
	73	I<cb> for each one, with the current provider in I<provider> and the
	74	I<cbdata> that comes from the caller.
	75
dca97d00	76	OSSL_PROVIDER_gettable_params() is used to get a provider parameter
26175013 RL	77	descriptor set as a constant B<OSSL_PARAM> array.
26175013 RL	78	See L<OSSL_PARAM(3)> for more information.
c4532834 RL	79
	80	OSSL_PROVIDER_get_params() is used to get provider parameter values.
	81	The caller must prepare the B<OSSL_PARAM> array before calling this
	82	function, and the variables acting as buffers for this parameter array
	83	should be filled with data when it returns successfully.
	84
b37066fd RL	85	OSSL_PROVIDER_name() returns the name of the given provider.
b37066fd RL	86
c4532834 RL	87	=head1 RETURN VALUES
	88
	89	OSSL_PROVIDER_add() returns 1 on success, or 0 on error.
	90
	91	OSSL_PROVIDER_load() returns a pointer to a provider object on
	92	success, or B<NULL> on error.
	93
	94	OSSL_PROVIDER_unload() returns 1 on success, or 0 on error.
	95
36f5ec55 RL	96	OSSL_PROVIDER_available() returns 1 if the named provider is available,
	97	otherwise 0.
	98
dca97d00	99	OSSL_PROVIDER_gettable_params() returns a pointer to an array
26175013	100	of constant B<OSSL_PARAM>, or NULL if none is provided.
c4532834 RL	101
	102	OSSL_PROVIDER_get_params() returns 1 on success, or 0 on error.
	103
	104	=head1 EXAMPLES
	105
	106	This demonstrates how to load the provider module "foo" and ask for
	107	its build number.
	108
	109	OSSL_PROVIDER *prov = NULL;
	110	const char *build = NULL;
	111	size_t built_l = 0;
4e7991b4	112	OSSL_PARAM request[] = {
c4532834 RL	113	{ "build", OSSL_PARAM_UTF8_STRING_PTR, &build, 0, &build_l },
	114	{ NULL, 0, NULL, 0, NULL }
	115	};
	116
	117	if ((prov = OSSL_PROVIDER_load(NULL, "foo")) != NULL
	118	&& OSSL_PROVIDER_get_params(prov, request))
	119	printf("Provider 'foo' build %s\n", build);
	120	else
	121	ERR_print_errors_fp(stderr);
	122
	123	=head1 SEE ALSO
	124
36f5ec55	125	L<openssl-core.h(7)>, L<OPENSSL_CTX(3)>, L<provider(7)>
c4532834 RL	126
	127	=head1 HISTORY
	128
	129	The type and functions described here were added in OpenSSL 3.0.
	130
	131	=head1 COPYRIGHT
	132
33388b44	133	Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
c4532834 RL	134
	135	Licensed under the Apache License 2.0 (the "License"). You may not use
	136	this file except in compliance with the License. You can obtain a copy
	137	in the file LICENSE in the source distribution or at
	138	L<https://www.openssl.org/source/license.html>.
	139
	140	=cut