1OSSL_DECODER_CTX(3ossl)             OpenSSL            OSSL_DECODER_CTX(3ossl)
2
3
4

NAME

6       OSSL_DECODER_CTX, OSSL_DECODER_CTX_new,
7       OSSL_DECODER_settable_ctx_params, OSSL_DECODER_CTX_set_params,
8       OSSL_DECODER_CTX_free, OSSL_DECODER_CTX_set_selection,
9       OSSL_DECODER_CTX_set_input_type, OSSL_DECODER_CTX_set_input_structure,
10       OSSL_DECODER_CTX_add_decoder, OSSL_DECODER_CTX_add_extra,
11       OSSL_DECODER_CTX_get_num_decoders, OSSL_DECODER_INSTANCE,
12       OSSL_DECODER_CONSTRUCT, OSSL_DECODER_CLEANUP,
13       OSSL_DECODER_CTX_set_construct, OSSL_DECODER_CTX_set_construct_data,
14       OSSL_DECODER_CTX_set_cleanup, OSSL_DECODER_CTX_get_construct,
15       OSSL_DECODER_CTX_get_construct_data, OSSL_DECODER_CTX_get_cleanup,
16       OSSL_DECODER_export, OSSL_DECODER_INSTANCE_get_decoder,
17       OSSL_DECODER_INSTANCE_get_decoder_ctx,
18       OSSL_DECODER_INSTANCE_get_input_type,
19       OSSL_DECODER_INSTANCE_get_input_structure - Decoder context routines
20

SYNOPSIS

22        #include <openssl/decoder.h>
23
24        typedef struct ossl_decoder_ctx_st OSSL_DECODER_CTX;
25
26        OSSL_DECODER_CTX *OSSL_DECODER_CTX_new(void);
27        const OSSL_PARAM *OSSL_DECODER_settable_ctx_params(OSSL_DECODER *decoder);
28        int OSSL_DECODER_CTX_set_params(OSSL_DECODER_CTX *ctx,
29                                        const OSSL_PARAM params[]);
30        void OSSL_DECODER_CTX_free(OSSL_DECODER_CTX *ctx);
31
32        int OSSL_DECODER_CTX_set_selection(OSSL_DECODER_CTX *ctx, int selection);
33        int OSSL_DECODER_CTX_set_input_type(OSSL_DECODER_CTX *ctx,
34                                            const char *input_type);
35        int OSSL_DECODER_CTX_set_input_structure(OSSL_DECODER_CTX *ctx,
36                                                 const char *input_structure);
37        int OSSL_DECODER_CTX_add_decoder(OSSL_DECODER_CTX *ctx, OSSL_DECODER *decoder);
38        int OSSL_DECODER_CTX_add_extra(OSSL_DECODER_CTX *ctx,
39                                       OSSL_LIB_CTX *libctx,
40                                       const char *propq);
41        int OSSL_DECODER_CTX_get_num_decoders(OSSL_DECODER_CTX *ctx);
42
43        typedef struct ossl_decoder_instance_st OSSL_DECODER_INSTANCE;
44        OSSL_DECODER *
45        OSSL_DECODER_INSTANCE_get_decoder(OSSL_DECODER_INSTANCE *decoder_inst);
46        void *
47        OSSL_DECODER_INSTANCE_get_decoder_ctx(OSSL_DECODER_INSTANCE *decoder_inst);
48        const char *
49        OSSL_DECODER_INSTANCE_get_input_type(OSSL_DECODER_INSTANCE *decoder_inst);
50        OSSL_DECODER_INSTANCE_get_input_structure(OSSL_DECODER_INSTANCE *decoder_inst,
51                                                  int *was_set);
52
53        typedef int OSSL_DECODER_CONSTRUCT(OSSL_DECODER_INSTANCE *decoder_inst,
54                                           const OSSL_PARAM *object,
55                                           void *construct_data);
56        typedef void OSSL_DECODER_CLEANUP(void *construct_data);
57
58        int OSSL_DECODER_CTX_set_construct(OSSL_DECODER_CTX *ctx,
59                                           OSSL_DECODER_CONSTRUCT *construct);
60        int OSSL_DECODER_CTX_set_construct_data(OSSL_DECODER_CTX *ctx,
61                                                void *construct_data);
62        int OSSL_DECODER_CTX_set_cleanup(OSSL_DECODER_CTX *ctx,
63                                         OSSL_DECODER_CLEANUP *cleanup);
64        OSSL_DECODER_CONSTRUCT *OSSL_DECODER_CTX_get_construct(OSSL_DECODER_CTX *ctx);
65        void *OSSL_DECODER_CTX_get_construct_data(OSSL_DECODER_CTX *ctx);
66        OSSL_DECODER_CLEANUP *OSSL_DECODER_CTX_get_cleanup(OSSL_DECODER_CTX *ctx);
67
68        int OSSL_DECODER_export(OSSL_DECODER_INSTANCE *decoder_inst,
69                                void *reference, size_t reference_sz,
70                                OSSL_CALLBACK *export_cb, void *export_cbarg);
71

DESCRIPTION

73       The OSSL_DECODER_CTX holds data about multiple decoders, as needed to
74       figure out what the input data is and to attempt to unpack it into one
75       of several possible related results.  This also includes chaining
76       decoders, so the output from one can become the input for another.
77       This allows having generic format decoders such as PEM to DER, as well
78       as more specialized decoders like DER to RSA.
79
80       The chains may be limited by specifying an input type, which is
81       considered a starting point.  This is both considered by
82       OSSL_DECODER_CTX_add_extra(), which will stop adding one more decoder
83       implementations when it has already added those that take the specified
84       input type, and functions like OSSL_DECODER_from_bio(3), which will
85       only start the decoding process with the decoder implementations that
86       take that input type.  For example, if the input type is set to "DER",
87       a PEM to DER decoder will be ignored.
88
89       The input type can also be NULL, which means that the caller doesn't
90       know what type of input they have.  In this case,
91       OSSL_DECODER_from_bio() will simply try with one decoder implementation
92       after the other, and thereby discover what kind of input the caller
93       gave it.
94
95       For every decoding done, even an intermediary one, a constructor
96       provided by the caller is called to attempt to construct an appropriate
97       type / structure that the caller knows how to handle from the current
98       decoding result.  The constructor is set with
99       OSSL_DECODER_CTX_set_construct().
100
101       OSSL_DECODER_INSTANCE is an opaque structure that contains data about
102       the decoder that was just used, and that may be useful for the
103       constructor.  There are some functions to extract data from this type,
104       described further down.
105
106   Functions
107       OSSL_DECODER_CTX_new() creates a new empty OSSL_DECODER_CTX.
108
109       OSSL_DECODER_settable_ctx_params() returns an OSSL_PARAM(3) array of
110       parameter descriptors.
111
112       OSSL_DECODER_CTX_set_params() attempts to set parameters specified with
113       an OSSL_PARAM(3) array params.  These parameters are passed to all
114       decoders that have been added to the ctx so far.  Parameters that an
115       implementation doesn't recognise should be ignored by it.
116
117       OSSL_DECODER_CTX_free() frees the given context ctx.
118
119       OSSL_DECODER_CTX_add_decoder() populates the OSSL_DECODER_CTX ctx with
120       a decoder, to be used to attempt to decode some encoded input.
121
122       OSSL_DECODER_CTX_add_extra() finds decoders that generate input for
123       already added decoders, and adds them as well.  This is used to build
124       decoder chains.
125
126       OSSL_DECODER_CTX_set_input_type() sets the starting input type.  This
127       limits the decoder chains to be considered, as explained in the general
128       description above.
129
130       OSSL_DECODER_CTX_set_input_structure() sets the name of the structure
131       that the input is expected to have.  This may be used to determines
132       what decoder implementations may be used.  NULL is a valid input
133       structure, when it's not relevant, or when the decoder implementations
134       are expected to figure it out.
135
136       OSSL_DECODER_CTX_get_num_decoders() gets the number of decoders
137       currently added to the context ctx.
138
139       OSSL_DECODER_CTX_set_construct() sets the constructor construct.
140
141       OSSL_DECODER_CTX_set_construct_data() sets the constructor data that is
142       passed to the constructor every time it's called.
143
144       OSSL_DECODER_CTX_set_cleanup() sets the constructor data cleanup
145       function.  This is called by OSSL_DECODER_CTX_free(3).
146
147       OSSL_DECODER_CTX_get_construct(), OSSL_DECODER_CTX_get_construct_data()
148       and OSSL_DECODER_CTX_get_cleanup() return the values that have been set
149       by OSSL_DECODER_CTX_set_construct(),
150       OSSL_DECODER_CTX_set_construct_data() and
151       OSSL_DECODER_CTX_set_cleanup() respectively.
152
153       OSSL_DECODER_export() is a fallback function for constructors that
154       cannot use the data they get directly for diverse reasons.  It takes
155       the same decode instance decoder_inst that the constructor got and an
156       object reference, unpacks the object which it refers to, and exports it
157       by creating an OSSL_PARAM(3) array that it then passes to export_cb,
158       along with export_arg.
159
160   Constructor
161       A OSSL_DECODER_CONSTRUCT gets the following arguments:
162
163       decoder_inst
164           The OSSL_DECODER_INSTANCE for the decoder from which the
165           constructor gets its data.
166
167       object
168           A provider-native object abstraction produced by the decoder.
169           Further information on the provider-native object abstraction can
170           be found in provider-object(7).
171
172       construct_data
173           The pointer that was set with OSSL_DECODE_CTX_set_construct_data().
174
175       The constructor is expected to return 1 when the data it receives can
176       be constructed, otherwise 0.
177
178       These utility functions may be used by a constructor:
179
180       OSSL_DECODER_INSTANCE_get_decoder() can be used to get the decoder
181       implementation from a decoder instance decoder_inst.
182
183       OSSL_DECODER_INSTANCE_get_decoder_ctx() can be used to get the decoder
184       implementation's provider context from a decoder instance decoder_inst.
185
186       OSSL_DECODER_INSTANCE_get_input_type() can be used to get the decoder
187       implementation's input type from a decoder instance decoder_inst.
188
189       OSSL_DECODER_INSTANCE_get_input_structure() can be used to get the
190       input structure for the decoder implementation from a decoder instance
191       decoder_inst.  This may be NULL.
192

RETURN VALUES

194       OSSL_DECODER_CTX_new() returns a pointer to a OSSL_DECODER_CTX, or NULL
195       if the context structure couldn't be allocated.
196
197       OSSL_DECODER_settable_ctx_params() returns an OSSL_PARAM(3) array, or
198       NULL if none is available.
199
200       OSSL_DECODER_CTX_set_params() returns 1 if all recognised parameters
201       were valid, or 0 if one of them was invalid or caused some other
202       failure in the implementation.
203
204       OSSL_DECODER_CTX_add_decoder(), OSSL_DECODER_CTX_add_extra(),
205       OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data()
206       and OSSL_DECODER_CTX_set_cleanup() return 1 on success, or 0 on
207       failure.
208
209       OSSL_DECODER_CTX_get_construct(), OSSL_DECODER_CTX_get_construct_data()
210       and OSSL_DECODER_CTX_get_cleanup() return the current pointers to the
211       constructor, the constructor data and the cleanup functions,
212       respectively.
213
214       OSSL_DECODER_CTX_num_decoders() returns the current number of decoders.
215       It returns 0 if ctx is NULL.
216
217       OSSL_DECODER_export() returns 1 on success, or 0 on failure.
218
219       OSSL_DECODER_INSTANCE_decoder() returns an OSSL_DECODER pointer on
220       success, or NULL on failure.
221
222       OSSL_DECODER_INSTANCE_decoder_ctx() returns a provider context pointer
223       on success, or NULL on failure.
224

SEE ALSO

226       provider(7), OSSL_DECODER(3), OSSL_DECODER_from_bio(3)
227

HISTORY

229       The functions described here were added in OpenSSL 3.0.
230
232       Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
233
234       Licensed under the Apache License 2.0 (the "License").  You may not use
235       this file except in compliance with the License.  You can obtain a copy
236       in the file LICENSE in the source distribution or at
237       <https://www.openssl.org/source/license.html>.
238
239
240
2413.0.5                             2022-07-05           OSSL_DECODER_CTX(3ossl)
Impressum