1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
=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
|
