[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_available,
ossl_provider_ctx,
ossl_provider_forall_loaded,
ossl_provider_name, ossl_provider_dso,
ossl_provider_module_name, ossl_provider_module_path,
ossl_provider_library_context,
ossl_provider_teardown, ossl_provider_gettable_params,
ossl_provider_get_params, ossl_provider_query_operation,
ossl_provider_set_operation_bit, ossl_provider_test_operation_bit
- internal provider routines

=head1 SYNOPSIS

 #include "internal/provider.h"

 OSSL_PROVIDER *ossl_provider_find(OPENSSL_CTX *libctx, const char *name,
                                   int noconfig);
 OSSL_PROVIDER *ossl_provider_new(OPENSSL_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);

 /* Load and initialize the Provider */
 int ossl_provider_activate(OSSL_PROVIDER *prov);
 /* Check if provider is available */
 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_forall_loaded(OPENSSL_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);
 OPENSSL_CTX *ossl_provider_library_context(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[]);
 const OSSL_ALGORITHM *ossl_provider_query_operation(const OSSL_PROVIDER *prov,
                                                     int operation_id,
                                                     int *no_cache);

 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 inactivated when ossl_provider_free() has been called as many
times as ossl_provider_activate() has.

=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; if it drops below 2, the provider object is assumed
to have fallen out of use and will be deactivated (its I<teardown>
function is called); if it drops down to zero, I<prov> is assumed to
have been taken out of the store, 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_library_context() 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>.
What "activates" means depends on what type of provider object it
is:

=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

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_forall_loaded() 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 and tries another iteration.

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_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_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_set_module_path(), ossl_provider_set_fallback() and
ossl_provider_activate() 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_library_context() 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.

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