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