]>
Commit | Line | Data |
---|---|---|
ece9304c RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | OSSL_DECODER_CTX, | |
6 | OSSL_DECODER_CTX_new, | |
7 | OSSL_DECODER_settable_ctx_params, | |
8 | OSSL_DECODER_CTX_set_params, | |
48b62fb3 | 9 | OSSL_DECODER_CTX_free, |
df65c06b | 10 | OSSL_DECODER_CTX_set_selection, |
48b62fb3 | 11 | OSSL_DECODER_CTX_set_input_type, |
df65c06b | 12 | OSSL_DECODER_CTX_set_input_structure, |
48b62fb3 RL |
13 | OSSL_DECODER_CTX_add_decoder, |
14 | OSSL_DECODER_CTX_add_extra, | |
15 | OSSL_DECODER_CTX_get_num_decoders, | |
16 | OSSL_DECODER_INSTANCE, | |
17 | OSSL_DECODER_CONSTRUCT, | |
18 | OSSL_DECODER_CLEANUP, | |
19 | OSSL_DECODER_CTX_set_construct, | |
20 | OSSL_DECODER_CTX_set_construct_data, | |
21 | OSSL_DECODER_CTX_set_cleanup, | |
22 | OSSL_DECODER_CTX_get_construct, | |
23 | OSSL_DECODER_CTX_get_construct_data, | |
24 | OSSL_DECODER_CTX_get_cleanup, | |
25 | OSSL_DECODER_export, | |
26 | OSSL_DECODER_INSTANCE_get_decoder, | |
27 | OSSL_DECODER_INSTANCE_get_decoder_ctx, | |
df65c06b RL |
28 | OSSL_DECODER_INSTANCE_get_input_type, |
29 | OSSL_DECODER_INSTANCE_get_input_structure | |
48b62fb3 | 30 | - Decoder context routines |
ece9304c RL |
31 | |
32 | =head1 SYNOPSIS | |
33 | ||
34 | #include <openssl/decoder.h> | |
35 | ||
36 | typedef struct ossl_decoder_ctx_st OSSL_DECODER_CTX; | |
37 | ||
11b93a1c | 38 | OSSL_DECODER_CTX *OSSL_DECODER_CTX_new(void); |
ece9304c RL |
39 | const OSSL_PARAM *OSSL_DECODER_settable_ctx_params(OSSL_DECODER *decoder); |
40 | int OSSL_DECODER_CTX_set_params(OSSL_DECODER_CTX *ctx, | |
41 | const OSSL_PARAM params[]); | |
42 | void OSSL_DECODER_CTX_free(OSSL_DECODER_CTX *ctx); | |
43 | ||
df65c06b | 44 | int OSSL_DECODER_CTX_set_selection(OSSL_DECODER_CTX *ctx, int selection); |
48b62fb3 RL |
45 | int OSSL_DECODER_CTX_set_input_type(OSSL_DECODER_CTX *ctx, |
46 | const char *input_type); | |
df65c06b RL |
47 | int OSSL_DECODER_CTX_set_input_structure(OSSL_DECODER_CTX *ctx, |
48 | const char *input_structure); | |
48b62fb3 RL |
49 | int OSSL_DECODER_CTX_add_decoder(OSSL_DECODER_CTX *ctx, OSSL_DECODER *decoder); |
50 | int OSSL_DECODER_CTX_add_extra(OSSL_DECODER_CTX *ctx); | |
51 | int OSSL_DECODER_CTX_get_num_decoders(OSSL_DECODER_CTX *ctx); | |
52 | ||
53 | typedef struct ossl_decoder_instance_st OSSL_DECODER_INSTANCE; | |
54 | OSSL_DECODER * | |
55 | OSSL_DECODER_INSTANCE_get_decoder(OSSL_DECODER_INSTANCE *decoder_inst); | |
56 | void * | |
57 | OSSL_DECODER_INSTANCE_get_decoder_ctx(OSSL_DECODER_INSTANCE *decoder_inst); | |
58 | const char * | |
59 | OSSL_DECODER_INSTANCE_get_input_type(OSSL_DECODER_INSTANCE *decoder_inst); | |
df65c06b RL |
60 | OSSL_DECODER_INSTANCE_get_input_structure(OSSL_DECODER_INSTANCE *decoder_inst, |
61 | int *was_set); | |
48b62fb3 RL |
62 | |
63 | typedef int OSSL_DECODER_CONSTRUCT(OSSL_DECODER_INSTANCE *decoder_inst, | |
64 | const OSSL_PARAM *object, | |
65 | void *construct_data); | |
66 | typedef void OSSL_DECODER_CLEANUP(void *construct_data); | |
67 | ||
68 | int OSSL_DECODER_CTX_set_construct(OSSL_DECODER_CTX *ctx, | |
69 | OSSL_DECODER_CONSTRUCT *construct); | |
70 | int OSSL_DECODER_CTX_set_construct_data(OSSL_DECODER_CTX *ctx, | |
71 | void *construct_data); | |
72 | int OSSL_DECODER_CTX_set_cleanup(OSSL_DECODER_CTX *ctx, | |
73 | OSSL_DECODER_CLEANUP *cleanup); | |
74 | OSSL_DECODER_CONSTRUCT *OSSL_DECODER_CTX_get_construct(OSSL_DECODER_CTX *ctx); | |
75 | void *OSSL_DECODER_CTX_get_construct_data(OSSL_DECODER_CTX *ctx); | |
76 | OSSL_DECODER_CLEANUP *OSSL_DECODER_CTX_get_cleanup(OSSL_DECODER_CTX *ctx); | |
77 | ||
78 | int OSSL_DECODER_export(OSSL_DECODER_INSTANCE *decoder_inst, | |
79 | void *reference, size_t reference_sz, | |
80 | OSSL_CALLBACK *export_cb, void *export_cbarg); | |
81 | ||
ece9304c RL |
82 | =head1 DESCRIPTION |
83 | ||
48b62fb3 RL |
84 | The B<OSSL_DECODER_CTX> holds data about multiple decoders, as needed to |
85 | figure out what the input data is and to attempt to unpack it into one of | |
86 | several possible related results. This also includes chaining decoders, so | |
87 | the output from one can become the input for another. This allows having | |
88 | generic format decoders such as PEM to DER, as well as more specialized | |
89 | decoders like DER to RSA. | |
90 | ||
91 | The chains may be limited by specifying an input type, which is considered a | |
92 | starting point. This is both considered by OSSL_DECODER_CTX_add_extra(), | |
93 | which will stop adding one more decoder implementations when it has already | |
94 | added those that take the specified input type, and functions like | |
95 | L<OSSL_DECODER_from_bio(3)>, which will only start the decoding process with | |
96 | the decoder implementations that take that input type. For example, if the | |
97 | input type is set to C<DER>, a PEM to DER decoder will be ignored. | |
98 | ||
99 | The input type can also be NULL, which means that the caller doesn't know | |
100 | what type of input they have. In this case, OSSL_DECODER_from_bio() will | |
101 | simply try with one decoder implementation after the other, and thereby | |
102 | discover what kind of input the caller gave it. | |
103 | ||
104 | For every decoding done, even an intermediary one, a constructor provided by | |
105 | the caller is called to attempt to construct an appropriate type / structure | |
106 | that the caller knows how to handle from the current decoding result. | |
107 | The constructor is set with OSSL_DECODER_CTX_set_construct(). | |
108 | ||
109 | B<OSSL_DECODER_INSTANCE> is an opaque structure that contains data about the | |
110 | decoder that was just used, and that may be useful for the constructor. | |
111 | There are some functions to extract data from this type, described further | |
112 | down. | |
113 | ||
114 | =head2 Functions | |
ece9304c RL |
115 | |
116 | OSSL_DECODER_CTX_new() creates a new empty B<OSSL_DECODER_CTX>. | |
117 | ||
48b62fb3 RL |
118 | OSSL_DECODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> array of |
119 | parameter descriptors. | |
ece9304c | 120 | |
48b62fb3 RL |
121 | OSSL_DECODER_CTX_set_params() attempts to set parameters specified with an |
122 | L<OSSL_PARAM(3)> array I<params>. These parameters are passed to all | |
123 | decoders that have been added to the I<ctx> so far. Parameters that an | |
124 | implementation doesn't recognise should be ignored by it. | |
ece9304c RL |
125 | |
126 | OSSL_DECODER_CTX_free() frees the given context I<ctx>. | |
127 | ||
48b62fb3 RL |
128 | OSSL_DECODER_CTX_add_decoder() populates the B<OSSL_DECODER_CTX> I<ctx> with |
129 | a decoder, to be used to attempt to decode some encoded input. | |
130 | ||
131 | OSSL_DECODER_CTX_add_extra() finds decoders that generate input for already | |
132 | added decoders, and adds them as well. This is used to build decoder | |
133 | chains. | |
134 | ||
135 | OSSL_DECODER_CTX_set_input_type() sets the starting input type. This limits | |
136 | the decoder chains to be considered, as explained in the general description | |
137 | above. | |
138 | ||
df65c06b RL |
139 | OSSL_DECODER_CTX_set_input_structure() sets the name of the structure that |
140 | the input is expected to have. This may be used to determines what decoder | |
141 | implementations may be used. NULL is a valid input structure, when it's not | |
142 | relevant, or when the decoder implementations are expected to figure it out. | |
143 | ||
48b62fb3 RL |
144 | OSSL_DECODER_CTX_get_num_decoders() gets the number of decoders currently |
145 | added to the context I<ctx>. | |
146 | ||
147 | OSSL_DECODER_CTX_set_construct() sets the constructor I<construct>. | |
148 | ||
149 | OSSL_DECODER_CTX_set_construct_data() sets the constructor data that is | |
150 | passed to the constructor every time it's called. | |
151 | ||
152 | OSSL_DECODER_CTX_set_cleanup() sets the constructor data I<cleanup> | |
153 | function. This is called by L<OSSL_DECODER_CTX_free(3)>. | |
154 | ||
155 | OSSL_DECODER_CTX_get_construct(), OSSL_DECODER_CTX_get_construct_data() and | |
156 | OSSL_DECODER_CTX_get_cleanup() return the values that have been set by | |
157 | OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data() and | |
158 | OSSL_DECODER_CTX_set_cleanup() respectively. | |
159 | ||
160 | OSSL_DECODER_export() is a fallback function for constructors that cannot | |
161 | use the data they get directly for diverse reasons. It takes the same | |
57cd10dd | 162 | decode instance I<decoder_inst> that the constructor got and an object |
48b62fb3 RL |
163 | I<reference>, unpacks the object which it refers to, and exports it by |
164 | creating an L<OSSL_PARAM(3)> array that it then passes to I<export_cb>, | |
165 | along with I<export_arg>. | |
166 | ||
167 | =head2 Constructor | |
168 | ||
169 | A B<OSSL_DECODER_CONSTRUCT> gets the following arguments: | |
170 | ||
171 | =over 4 | |
172 | ||
173 | =item I<decoder_inst> | |
174 | ||
175 | The B<OSSL_DECODER_INSTANCE> for the decoder from which the constructor gets | |
176 | its data. | |
177 | ||
178 | =item I<object> | |
179 | ||
180 | A provider-native object abstraction produced by the decoder. Further | |
181 | information on the provider-native object abstraction can be found in | |
182 | L<provider-object(7)>. | |
183 | ||
184 | =item I<construct_data> | |
185 | ||
186 | The pointer that was set with OSSL_DECODE_CTX_set_construct_data(). | |
187 | ||
188 | =back | |
189 | ||
190 | The constructor is expected to return 1 when the data it receives can be | |
191 | constructed, otherwise 0. | |
192 | ||
193 | These utility functions may be used by a constructor: | |
194 | ||
df65c06b RL |
195 | OSSL_DECODER_INSTANCE_get_decoder() can be used to get the decoder |
196 | implementation from a decoder instance I<decoder_inst>. | |
48b62fb3 RL |
197 | |
198 | OSSL_DECODER_INSTANCE_get_decoder_ctx() can be used to get the decoder | |
df65c06b | 199 | implementation's provider context from a decoder instance I<decoder_inst>. |
48b62fb3 RL |
200 | |
201 | OSSL_DECODER_INSTANCE_get_input_type() can be used to get the decoder | |
df65c06b RL |
202 | implementation's input type from a decoder instance I<decoder_inst>. |
203 | ||
204 | OSSL_DECODER_INSTANCE_get_input_structure() can be used to get the input | |
205 | structure for the decoder implementation from a decoder instance | |
206 | I<decoder_inst>. | |
207 | This may be NULL. | |
48b62fb3 | 208 | |
ece9304c RL |
209 | =head1 RETURN VALUES |
210 | ||
48b62fb3 RL |
211 | OSSL_DECODER_CTX_new() returns a pointer to a B<OSSL_DECODER_CTX>, or NULL |
212 | if the context structure couldn't be allocated. | |
213 | ||
214 | OSSL_DECODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> array, or | |
215 | NULL if none is available. | |
216 | ||
217 | OSSL_DECODER_CTX_set_params() returns 1 if all recognised parameters were | |
218 | valid, or 0 if one of them was invalid or caused some other failure in the | |
219 | implementation. | |
220 | ||
221 | OSSL_DECODER_CTX_add_decoder(), OSSL_DECODER_CTX_add_extra(), | |
222 | OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data() and | |
223 | OSSL_DECODER_CTX_set_cleanup() return 1 on success, or 0 on failure. | |
224 | ||
225 | OSSL_DECODER_CTX_get_construct(), OSSL_DECODER_CTX_get_construct_data() and | |
226 | OSSL_DECODER_CTX_get_cleanup() return the current pointers to the | |
227 | constructor, the constructor data and the cleanup functions, respectively. | |
228 | ||
229 | OSSL_DECODER_CTX_num_decoders() returns the current number of decoders. It | |
230 | returns 0 if I<ctx> is NULL. | |
231 | ||
232 | OSSL_DECODER_export() returns 1 on success, or 0 on failure. | |
ece9304c | 233 | |
48b62fb3 RL |
234 | OSSL_DECODER_INSTANCE_decoder() returns an B<OSSL_DECODER> pointer on |
235 | success, or NULL on failure. | |
ece9304c | 236 | |
48b62fb3 RL |
237 | OSSL_DECODER_INSTANCE_decoder_ctx() returns a provider context pointer on |
238 | success, or NULL on failure. | |
ece9304c RL |
239 | |
240 | =head1 SEE ALSO | |
241 | ||
242 | L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_from_bio(3)> | |
243 | ||
244 | =head1 HISTORY | |
245 | ||
246 | The functions described here were added in OpenSSL 3.0. | |
247 | ||
248 | =head1 COPYRIGHT | |
249 | ||
250 | Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. | |
251 | ||
252 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
253 | this file except in compliance with the License. You can obtain a copy | |
254 | in the file LICENSE in the source distribution or at | |
255 | L<https://www.openssl.org/source/license.html>. | |
256 | ||
257 | =cut |