[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_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);

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