[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 {
     /* Create store */
     void *(*alloc_tmp_store)(OPENSSL_CTX *ctx);
     /* Remove a store */
     void (*dealloc_tmp_store)(void *store);
     /* Get an already existing method from a store */
     void *(*get)(OPENSSL_CTX *libctx, void *store,
                  int operation_id, const char *name, const char *propquery,
                  void *data);
     /* Store a method in a store */
     int (*put)(OPENSSL_CTX *libctx, void *store, void *method,
                int operation_id, const char *name, const char *propdef,
                void *data);
     /* Construct a new method */
     void *(*construct)(const char *name, const OSSL_DISPATCH *fns,
                        OSSL_PROVIDER *prov, void *data);
     /* Destruct a method */
     void (*destruct)(void *method);
 };
 typedef struct ossl_method_construct_method OSSL_METHOD_CONSTRUCT_METHOD;

 void *ossl_method_construct(OPENSSL_CTX *ctx, int operation_id,
                             const char *name, const char *properties,
                             int force_cache,
                             OSSL_METHOD_CONSTRUCT_METHOD *mcm, void *mcm_data);


=head1 DESCRIPTION

All libcrypto sub-systems 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 sub-systems
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 C<operation_id>, an algorithm
C<name> and a set of C<properties>, and then calling the appropriate
functions given by the sub-system specific method creator through
C<mcm> and the data in C<mcm_data> (which is passed by
ossl_method_construct()).

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

=head2 Structures

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

=over 4

=item alloc_tmp_store()

Create a temporary method store in the scope of the library context C<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 dealloc_tmp_store()

Remove a temporary store.

=item get()

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

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

The method to be looked up should be identified with the given
C<operation_id>, C<name>, the provided property query C<propquery>
and data from C<data> (which is the C<mcm_data> that was passed to
ossl_construct_method()).

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

=item put()

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

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

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

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

=item construct()

Constructs a sub-system method for the given C<name> and the given
dispatch table C<fns>.

The associated I<provider object> C<prov> is passed as well, to make
it possible for the sub-system 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_upref().

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

=item desctruct()

Decrement the C<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
B<NULL> on error.

=head1 HISTORY

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