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

=pod

=head1 NAME

OSSL_PROVIDER, OSSL_PROVIDER_load, OSSL_PROVIDER_unload,
OSSL_PROVIDER_available,
OSSL_PROVIDER_get_param_types, 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;

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