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