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

=pod

=head1 NAME

OSSL_METHOD_CONSTRUCT_METHOD, ossl_method_construct
- generic method constructor

=head1 SYNOPSIS

 #include "internal/core.h"

 struct ossl_method_construct_method_st {
     /* Get a temporary store */
     void *(*get_tmp_store)(void *data);
     /* Get an already existing method from a store */
     void *(*get)(void *store, const OSSL_PROVIDER *prov, void *data);
     /* Store a method in a store */
     int (*put)(void *store, void *method, const OSSL_PROVIDER *prov,
                const char *name, const char *propdef, void *data);
     /* Construct a new method */
     void *(*construct)(const OSSL_ALGORITHM *algodef, OSSL_PROVIDER *prov,
                        void *data);
     /* Destruct a method */
     void (*destruct)(void *method, void *data);
 };
 typedef struct ossl_method_construct_method OSSL_METHOD_CONSTRUCT_METHOD;

 void *ossl_method_construct(OSSL_LIB_CTX *ctx, int operation_id,
                             OSSL_PROVIDER *prov, int force_cache,
                             OSSL_METHOD_CONSTRUCT_METHOD *mcm, void *mcm_data);


=head1 DESCRIPTION

All libcrypto subsystems that want to create their own methods based
on provider dispatch tables need to do so in exactly the same way.
ossl_method_construct() does this while leaving it to the subsystems
to define more precisely how the methods are created, stored, etc.

It's important to keep in mind that a method is identified by three things:

=over 4

=item The operation identity

=item The name of the algorithm

=item The properties associated with the algorithm implementation

=back

=head2 Functions

ossl_method_construct() creates a method by asking all available
providers for a dispatch table given an I<operation_id>, and then
calling the appropriate functions given by the subsystem specific
method creator through I<mcm> and the data in I<mcm_data> (which is
passed by ossl_method_construct()).
If I<prov> is not NULL, only that provider is considered, which is
useful in the case a method must be found in that particular
provider.

This function assumes that the subsystem method creator implements
reference counting and acts accordingly (i.e. it will call the
subsystem destruct() method to decrement the reference count when
appropriate).

=head2 Structures

A central part of constructing a subsystem specific method is to give
ossl_method_construct a set of functions, all in the
B<OSSL_METHOD_CONSTRUCT_METHOD> structure, which holds the following
function pointers:

=over 4

=item get_tmp_store()

Create a temporary method store in the scope of the library context I<ctx>.
This store is used to temporarily store methods for easier lookup, for
when the provider doesn't want its dispatch table stored in a longer
term cache.

=item get()

Look up an already existing method from a store by name.

The store may be given with I<store>.
NULL is a valid value and means that a subsystem default store
must be used.
This default store should be stored in the library context I<libctx>.

The method to be looked up should be identified with data found in I<data>
(which is the I<mcm_data> that was passed to ossl_construct_method()).
In other words, the ossl_method_construct() caller is entirely responsible
for ensuring the necessary data is made available.

Optionally, I<prov> may be given as a search criterion, to narrow down the
search of a method belonging to just one provider.

This function is expected to increment the resulting method's reference count.

=item put()

Places the I<method> created by the construct() function (see below)
in a store.

The store may be given with I<store>.
NULL is a valid value and means that a subsystem default store
must be used.
This default store should be stored in the library context I<libctx>.

The method should be associated with the given provider I<prov>,
I<name> and property definition I<propdef> as well as any
identification data given through I<data> (which is the I<mcm_data>
that was passed to ossl_construct_method()).

This function is expected to increment the I<method>'s reference count.

=item construct()

Constructs a subsystem method for the given I<name> and the given
dispatch table I<fns>.

The associated provider object I<prov> is passed as well, to make
it possible for the subsystem constructor to keep a reference, which
is recommended.
If such a reference is kept, the I<provider object> reference counter
must be incremented, using ossl_provider_up_ref().

This function is expected to set the method's reference count to 1.

=item destruct()

Decrement the I<method>'s reference count, and destruct it when
the reference count reaches zero.

=back

=head1 RETURN VALUES

ossl_method_construct() returns a constructed method on success, or
NULL on error.

=head1 HISTORY

This functionality was added to 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
9e11fe0d RL	1	=pod
	2
	3	=head1 NAME
	4
	5	OSSL_METHOD_CONSTRUCT_METHOD, ossl_method_construct
	6	- generic method constructor
	7
	8	=head1 SYNOPSIS
	9
	10	#include "internal/core.h"
	11
	12	struct ossl_method_construct_method_st {
48b3ad05 PH	13	/* Get a temporary store */
48b3ad05 PH	14	void (get_tmp_store)(void *data);
9e11fe0d	15	/* Get an already existing method from a store */
dc010ca6	16	void (get)(void store, const OSSL_PROVIDER prov, void *data);
9e11fe0d	17	/* Store a method in a store */
dc010ca6 RL	18	int (put)(void store, void method, const OSSL_PROVIDER prov,
dc010ca6 RL	19	const char name, const char propdef, void *data);
9e11fe0d	20	/* Construct a new method */
dc010ca6 RL	21	void (construct)(const OSSL_ALGORITHM algodef, OSSL_PROVIDER prov,
dc010ca6 RL	22	void *data);
9e11fe0d	23	/* Destruct a method */
dc010ca6	24	void (destruct)(void method, void *data);
9e11fe0d RL	25	};
	26	typedef struct ossl_method_construct_method OSSL_METHOD_CONSTRUCT_METHOD;
	27
b4250010	28	void ossl_method_construct(OSSL_LIB_CTX ctx, int operation_id,
cfce50f7	29	OSSL_PROVIDER *prov, int force_cache,
9e11fe0d RL	30	OSSL_METHOD_CONSTRUCT_METHOD mcm, void mcm_data);
9e11fe0d RL	31
25b25b0f	32
9e11fe0d RL	33	=head1 DESCRIPTION
9e11fe0d RL	34
490c8711	35	All libcrypto subsystems that want to create their own methods based
9e11fe0d	36	on provider dispatch tables need to do so in exactly the same way.
490c8711	37	ossl_method_construct() does this while leaving it to the subsystems
9e11fe0d RL	38	to define more precisely how the methods are created, stored, etc.
9e11fe0d RL	39
2ccb1b4e RL	40	It's important to keep in mind that a method is identified by three things:
	41
	42	=over 4
	43
	44	=item The operation identity
	45
	46	=item The name of the algorithm
	47
	48	=item The properties associated with the algorithm implementation
	49
	50	=back
	51
9e11fe0d RL	52	=head2 Functions
	53
	54	ossl_method_construct() creates a method by asking all available
f7c16d48	55	providers for a dispatch table given an I<operation_id>, and then
490c8711	56	calling the appropriate functions given by the subsystem specific
f7c16d48 RL	57	method creator through I<mcm> and the data in I<mcm_data> (which is
f7c16d48 RL	58	passed by ossl_method_construct()).
cfce50f7 RL	59	If I<prov> is not NULL, only that provider is considered, which is
	60	useful in the case a method must be found in that particular
	61	provider.
9e11fe0d	62
490c8711	63	This function assumes that the subsystem method creator implements
a3830831	64	reference counting and acts accordingly (i.e. it will call the
490c8711	65	subsystem destruct() method to decrement the reference count when
a3830831 RL	66	appropriate).
a3830831 RL	67
9e11fe0d RL	68	=head2 Structures
9e11fe0d RL	69
490c8711	70	A central part of constructing a subsystem specific method is to give
9e11fe0d	71	ossl_method_construct a set of functions, all in the
b4d3f203	72	B<OSSL_METHOD_CONSTRUCT_METHOD> structure, which holds the following
9e11fe0d RL	73	function pointers:
	74
	75	=over 4
	76
dc010ca6	77	=item get_tmp_store()
9e11fe0d	78
b4d3f203	79	Create a temporary method store in the scope of the library context I<ctx>.
9e11fe0d RL	80	This store is used to temporarily store methods for easier lookup, for
	81	when the provider doesn't want its dispatch table stored in a longer
	82	term cache.
	83
9e11fe0d RL	84	=item get()
9e11fe0d RL	85
2e49c054	86	Look up an already existing method from a store by name.
9e11fe0d	87
b4d3f203	88	The store may be given with I<store>.
490c8711	89	NULL is a valid value and means that a subsystem default store
9e11fe0d	90	must be used.
b4d3f203	91	This default store should be stored in the library context I<libctx>.
9e11fe0d	92
f7c16d48 RL	93	The method to be looked up should be identified with data found in I<data>
	94	(which is the I<mcm_data> that was passed to ossl_construct_method()).
	95	In other words, the ossl_method_construct() caller is entirely responsible
164a541b	96	for ensuring the necessary data is made available.
9e11fe0d	97
dc010ca6 RL	98	Optionally, I<prov> may be given as a search criterion, to narrow down the
	99	search of a method belonging to just one provider.
	100
	101	This function is expected to increment the resulting method's reference count.
a3830831	102
9e11fe0d RL	103	=item put()
9e11fe0d RL	104
b4d3f203	105	Places the I<method> created by the construct() function (see below)
9e11fe0d RL	106	in a store.
9e11fe0d RL	107
b4d3f203	108	The store may be given with I<store>.
490c8711	109	NULL is a valid value and means that a subsystem default store
9e11fe0d	110	must be used.
b4d3f203	111	This default store should be stored in the library context I<libctx>.
9e11fe0d	112
dc010ca6	113	The method should be associated with the given provider I<prov>,
b4d3f203 RL	114	I<name> and property definition I<propdef> as well as any
b4d3f203 RL	115	identification data given through I<data> (which is the I<mcm_data>
2ccb1b4e	116	that was passed to ossl_construct_method()).
9e11fe0d	117
b4d3f203	118	This function is expected to increment the I<method>'s reference count.
a3830831	119
9e11fe0d RL	120	=item construct()
9e11fe0d RL	121
490c8711	122	Constructs a subsystem method for the given I<name> and the given
b4d3f203	123	dispatch table I<fns>.
9e11fe0d	124
b4d3f203	125	The associated provider object I<prov> is passed as well, to make
490c8711	126	it possible for the subsystem constructor to keep a reference, which
9e11fe0d RL	127	is recommended.
9e11fe0d RL	128	If such a reference is kept, the I<provider object> reference counter
7c95390e	129	must be incremented, using ossl_provider_up_ref().
9e11fe0d	130
a3830831 RL	131	This function is expected to set the method's reference count to 1.
a3830831 RL	132
c2969ff6	133	=item destruct()
9e11fe0d	134
b4d3f203	135	Decrement the I<method>'s reference count, and destruct it when
a3830831	136	the reference count reaches zero.
9e11fe0d RL	137
	138	=back
	139
	140	=head1 RETURN VALUES
	141
	142	ossl_method_construct() returns a constructed method on success, or
dfabee82	143	NULL on error.
9e11fe0d RL	144
	145	=head1 HISTORY
	146
2e49c054	147	This functionality was added to OpenSSL 3.0.
9e11fe0d RL	148
	149	=head1 COPYRIGHT
	150
a8d9bd81	151	Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
9e11fe0d RL	152
	153	Licensed under the Apache License 2.0 (the "License"). You may not use this
	154	file except in compliance with the License. You can obtain a copy in the file
	155	LICENSE in the source distribution or at
	156	L<https://www.openssl.org/source/license.html>.
	157
	158	=cut