7 OSSL_DECODER_settable_ctx_params,
8 OSSL_DECODER_CTX_set_params,
10 OSSL_DECODER_CTX_set_selection,
11 OSSL_DECODER_CTX_set_input_type,
12 OSSL_DECODER_CTX_set_input_structure,
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,
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,
26 OSSL_DECODER_INSTANCE_get_decoder,
27 OSSL_DECODER_INSTANCE_get_decoder_ctx,
28 OSSL_DECODER_INSTANCE_get_input_type,
29 OSSL_DECODER_INSTANCE_get_input_structure
30 - Decoder context routines
34 #include <openssl/decoder.h>
36 typedef struct ossl_decoder_ctx_st OSSL_DECODER_CTX;
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);
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 int OSSL_DECODER_CTX_get_num_decoders(OSSL_DECODER_CTX *ctx);
53 typedef struct ossl_decoder_instance_st OSSL_DECODER_INSTANCE;
55 OSSL_DECODER_INSTANCE_get_decoder(OSSL_DECODER_INSTANCE *decoder_inst);
57 OSSL_DECODER_INSTANCE_get_decoder_ctx(OSSL_DECODER_INSTANCE *decoder_inst);
59 OSSL_DECODER_INSTANCE_get_input_type(OSSL_DECODER_INSTANCE *decoder_inst);
60 OSSL_DECODER_INSTANCE_get_input_structure(OSSL_DECODER_INSTANCE *decoder_inst,
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);
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);
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);
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.
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.
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.
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().
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
116 OSSL_DECODER_CTX_new() creates a new empty B<OSSL_DECODER_CTX>.
118 OSSL_DECODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> array of
119 parameter descriptors.
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.
126 OSSL_DECODER_CTX_free() frees the given context I<ctx>.
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.
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
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
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.
144 OSSL_DECODER_CTX_get_num_decoders() gets the number of decoders currently
145 added to the context I<ctx>.
147 OSSL_DECODER_CTX_set_construct() sets the constructor I<construct>.
149 OSSL_DECODER_CTX_set_construct_data() sets the constructor data that is
150 passed to the constructor every time it's called.
152 OSSL_DECODER_CTX_set_cleanup() sets the constructor data I<cleanup>
153 function. This is called by L<OSSL_DECODER_CTX_free(3)>.
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.
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
162 decode instance I<decoder_inst> that the constructor got and an object
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>.
169 A B<OSSL_DECODER_CONSTRUCT> gets the following arguments:
173 =item I<decoder_inst>
175 The B<OSSL_DECODER_INSTANCE> for the decoder from which the constructor gets
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)>.
184 =item I<construct_data>
186 The pointer that was set with OSSL_DECODE_CTX_set_construct_data().
190 The constructor is expected to return 1 when the data it receives can be
191 constructed, otherwise 0.
193 These utility functions may be used by a constructor:
195 OSSL_DECODER_INSTANCE_get_decoder() can be used to get the decoder
196 implementation from a decoder instance I<decoder_inst>.
198 OSSL_DECODER_INSTANCE_get_decoder_ctx() can be used to get the decoder
199 implementation's provider context from a decoder instance I<decoder_inst>.
201 OSSL_DECODER_INSTANCE_get_input_type() can be used to get the decoder
202 implementation's input type from a decoder instance I<decoder_inst>.
204 OSSL_DECODER_INSTANCE_get_input_structure() can be used to get the input
205 structure for the decoder implementation from a decoder instance
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.
214 OSSL_DECODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> array, or
215 NULL if none is available.
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
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.
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.
229 OSSL_DECODER_CTX_num_decoders() returns the current number of decoders. It
230 returns 0 if I<ctx> is NULL.
232 OSSL_DECODER_export() returns 1 on success, or 0 on failure.
234 OSSL_DECODER_INSTANCE_decoder() returns an B<OSSL_DECODER> pointer on
235 success, or NULL on failure.
237 OSSL_DECODER_INSTANCE_decoder_ctx() returns a provider context pointer on
238 success, or NULL on failure.
242 L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_from_bio(3)>
246 The functions described here were added in OpenSSL 3.0.
250 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
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>.