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