1OSSL_DECODER_CTX(3ossl) OpenSSL OSSL_DECODER_CTX(3ossl)
2
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
22 #include <openssl/decoder.h>
23 typedef struct ossl_decoder_ctx_st OSSL_DECODER_CTX;
25 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 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 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 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 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 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
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 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 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 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 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 Functions
107 OSSL_DECODER_CTX_new() creates a new empty OSSL_DECODER_CTX.
108 OSSL_DECODER_settable_ctx_params() returns an OSSL_PARAM(3) array of
110 parameter descriptors.
111 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 OSSL_DECODER_CTX_free() frees the given context ctx.
118 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 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 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 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 OSSL_DECODER_CTX_get_num_decoders() gets the number of decoders
137 currently added to the context ctx.
138 OSSL_DECODER_CTX_set_construct() sets the constructor construct.
140 OSSL_DECODER_CTX_set_construct_data() sets the constructor data that is
142 passed to the constructor every time it's called.
143 OSSL_DECODER_CTX_set_cleanup() sets the constructor data cleanup
145 function. This is called by OSSL_DECODER_CTX_free(3).
146 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 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 Constructor
161 A OSSL_DECODER_CONSTRUCT gets the following arguments:
162 decoder_inst
164 The OSSL_DECODER_INSTANCE for the decoder from which the
165 constructor gets its data.
166 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 construct_data
173 The pointer that was set with OSSL_DECODE_CTX_set_construct_data().
174 The constructor is expected to return 1 when the data it receives can
176 be constructed, otherwise 0.
177 These utility functions may be used by a constructor:
179 OSSL_DECODER_INSTANCE_get_decoder() can be used to get the decoder
181 implementation from a decoder instance decoder_inst.
182 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 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 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
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 OSSL_DECODER_settable_ctx_params() returns an OSSL_PARAM(3) array, or
198 NULL if none is available.
199 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 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 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 OSSL_DECODER_CTX_num_decoders() returns the current number of decoders.
215 It returns 0 if ctx is NULL.
216 OSSL_DECODER_export() returns 1 on success, or 0 on failure.
218 OSSL_DECODER_INSTANCE_decoder() returns an OSSL_DECODER pointer on
220 success, or NULL on failure.
221 OSSL_DECODER_INSTANCE_decoder_ctx() returns a provider context pointer
223 on success, or NULL on failure.
224
226 provider(7), OSSL_DECODER(3), OSSL_DECODER_from_bio(3)
227
229 The functions described here were added in OpenSSL 3.0.
230
232 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
233 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>.
2383.0.5 2022-11-01 OSSL_DECODER_CTX(3ossl)