Debian Codegraph @

upstream/debian-unstable/man3/OSSL_DECODER_CTX.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL_DECODER_CTX 3SSL"
58 .TH OSSL_DECODER_CTX 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 OSSL_DECODER_CTX,
65 OSSL_DECODER_CTX_new,
66 OSSL_DECODER_settable_ctx_params,
67 OSSL_DECODER_CTX_set_params,
68 OSSL_DECODER_CTX_free,
69 OSSL_DECODER_CTX_set_selection,
70 OSSL_DECODER_CTX_set_input_type,
71 OSSL_DECODER_CTX_set_input_structure,
72 OSSL_DECODER_CTX_add_decoder,
73 OSSL_DECODER_CTX_add_extra,
74 OSSL_DECODER_CTX_get_num_decoders,
75 OSSL_DECODER_INSTANCE,
76 OSSL_DECODER_CONSTRUCT,
77 OSSL_DECODER_CLEANUP,
78 OSSL_DECODER_CTX_set_construct,
79 OSSL_DECODER_CTX_set_construct_data,
80 OSSL_DECODER_CTX_set_cleanup,
81 OSSL_DECODER_CTX_get_construct,
82 OSSL_DECODER_CTX_get_construct_data,
83 OSSL_DECODER_CTX_get_cleanup,
84 OSSL_DECODER_export,
85 OSSL_DECODER_INSTANCE_get_decoder,
86 OSSL_DECODER_INSTANCE_get_decoder_ctx,
87 OSSL_DECODER_INSTANCE_get_input_type,
88 OSSL_DECODER_INSTANCE_get_input_structure
89 \&\- Decoder context routines
90 .SH SYNOPSIS
91 .IX Header "SYNOPSIS"
92 .Vb 1
93 \& #include <openssl/decoder.h>
94 \&
95 \& typedef struct ossl_decoder_ctx_st OSSL_DECODER_CTX;
96 \&
97 \& OSSL_DECODER_CTX *OSSL_DECODER_CTX_new(void);
98 \& const OSSL_PARAM *OSSL_DECODER_settable_ctx_params(OSSL_DECODER *decoder);
99 \& int OSSL_DECODER_CTX_set_params(OSSL_DECODER_CTX *ctx,
100 \& const OSSL_PARAM params[]);
101 \& void OSSL_DECODER_CTX_free(OSSL_DECODER_CTX *ctx);
102 \&
103 \& int OSSL_DECODER_CTX_set_selection(OSSL_DECODER_CTX *ctx, int selection);
104 \& int OSSL_DECODER_CTX_set_input_type(OSSL_DECODER_CTX *ctx,
105 \& const char *input_type);
106 \& int OSSL_DECODER_CTX_set_input_structure(OSSL_DECODER_CTX *ctx,
107 \& const char *input_structure);
108 \& int OSSL_DECODER_CTX_add_decoder(OSSL_DECODER_CTX *ctx, OSSL_DECODER *decoder);
109 \& int OSSL_DECODER_CTX_add_extra(OSSL_DECODER_CTX *ctx,
110 \& OSSL_LIB_CTX *libctx,
111 \& const char *propq);
112 \& int OSSL_DECODER_CTX_get_num_decoders(OSSL_DECODER_CTX *ctx);
113 \&
114 \& typedef struct ossl_decoder_instance_st OSSL_DECODER_INSTANCE;
115 \& OSSL_DECODER *
116 \& OSSL_DECODER_INSTANCE_get_decoder(OSSL_DECODER_INSTANCE *decoder_inst);
117 \& void *
118 \& OSSL_DECODER_INSTANCE_get_decoder_ctx(OSSL_DECODER_INSTANCE *decoder_inst);
119 \& const char *
120 \& OSSL_DECODER_INSTANCE_get_input_type(OSSL_DECODER_INSTANCE *decoder_inst);
121 \& OSSL_DECODER_INSTANCE_get_input_structure(OSSL_DECODER_INSTANCE *decoder_inst,
122 \& int *was_set);
123 \&
124 \& typedef int OSSL_DECODER_CONSTRUCT(OSSL_DECODER_INSTANCE *decoder_inst,
125 \& const OSSL_PARAM *object,
126 \& void *construct_data);
127 \& typedef void OSSL_DECODER_CLEANUP(void *construct_data);
128 \&
129 \& int OSSL_DECODER_CTX_set_construct(OSSL_DECODER_CTX *ctx,
130 \& OSSL_DECODER_CONSTRUCT *construct);
131 \& int OSSL_DECODER_CTX_set_construct_data(OSSL_DECODER_CTX *ctx,
132 \& void *construct_data);
133 \& int OSSL_DECODER_CTX_set_cleanup(OSSL_DECODER_CTX *ctx,
134 \& OSSL_DECODER_CLEANUP *cleanup);
135 \& OSSL_DECODER_CONSTRUCT *OSSL_DECODER_CTX_get_construct(OSSL_DECODER_CTX *ctx);
136 \& void *OSSL_DECODER_CTX_get_construct_data(OSSL_DECODER_CTX *ctx);
137 \& OSSL_DECODER_CLEANUP *OSSL_DECODER_CTX_get_cleanup(OSSL_DECODER_CTX *ctx);
138 \&
139 \& int OSSL_DECODER_export(OSSL_DECODER_INSTANCE *decoder_inst,
140 \& void *reference, size_t reference_sz,
141 \& OSSL_CALLBACK *export_cb, void *export_cbarg);
142 .Ve
143 .SH DESCRIPTION
144 .IX Header "DESCRIPTION"
145 The \fBOSSL_DECODER_CTX\fR holds data about multiple decoders, as needed to
146 figure out what the input data is and to attempt to unpack it into one of
147 several possible related results. This also includes chaining decoders, so
148 the output from one can become the input for another. This allows having
149 generic format decoders such as PEM to DER, as well as more specialized
150 decoders like DER to RSA.
151 .PP
152 The chains may be limited by specifying an input type, which is considered a
153 starting point. This is both considered by \fBOSSL_DECODER_CTX_add_extra()\fR,
154 which will stop adding one more decoder implementations when it has already
155 added those that take the specified input type, and functions like
156 \&\fBOSSL_DECODER_from_bio\fR\|(3), which will only start the decoding process with
157 the decoder implementations that take that input type. For example, if the
158 input type is set to \f(CW\*(C`DER\*(C'\fR, a PEM to DER decoder will be ignored.
159 .PP
160 The input type can also be NULL, which means that the caller doesn't know
161 what type of input they have. In this case, \fBOSSL_DECODER_from_bio()\fR will
162 simply try with one decoder implementation after the other, and thereby
163 discover what kind of input the caller gave it.
164 .PP
165 For every decoding done, even an intermediary one, a constructor provided by
166 the caller is called to attempt to construct an appropriate type / structure
167 that the caller knows how to handle from the current decoding result.
168 The constructor is set with \fBOSSL_DECODER_CTX_set_construct()\fR.
169 .PP
170 \&\fBOSSL_DECODER_INSTANCE\fR is an opaque structure that contains data about the
171 decoder that was just used, and that may be useful for the constructor.
172 There are some functions to extract data from this type, described further
173 down.
174 .SS Functions
175 .IX Subsection "Functions"
176 \&\fBOSSL_DECODER_CTX_new()\fR creates a new empty \fBOSSL_DECODER_CTX\fR.
177 .PP
178 \&\fBOSSL_DECODER_settable_ctx_params()\fR returns an \fBOSSL_PARAM\fR\|(3) array of
179 parameter descriptors.
180 .PP
181 \&\fBOSSL_DECODER_CTX_set_params()\fR attempts to set parameters specified with an
182 \&\fBOSSL_PARAM\fR\|(3) array \fIparams\fR. These parameters are passed to all
183 decoders that have been added to the \fIctx\fR so far. Parameters that an
184 implementation doesn't recognise should be ignored by it.
185 .PP
186 \&\fBOSSL_DECODER_CTX_free()\fR frees the given context \fIctx\fR.
187 If the argument is NULL, nothing is done.
188 .PP
189 \&\fBOSSL_DECODER_CTX_add_decoder()\fR populates the \fBOSSL_DECODER_CTX\fR \fIctx\fR with
190 a decoder, to be used to attempt to decode some encoded input.
191 .PP
192 \&\fBOSSL_DECODER_CTX_add_extra()\fR finds decoders that generate input for already
193 added decoders, and adds them as well. This is used to build decoder
194 chains.
195 .PP
196 \&\fBOSSL_DECODER_CTX_set_input_type()\fR sets the starting input type. This limits
197 the decoder chains to be considered, as explained in the general description
198 above.
199 .PP
200 \&\fBOSSL_DECODER_CTX_set_input_structure()\fR sets the name of the structure that
201 the input is expected to have. This may be used to determines what decoder
202 implementations may be used. NULL is a valid input structure, when it's not
203 relevant, or when the decoder implementations are expected to figure it out.
204 .PP
205 \&\fBOSSL_DECODER_CTX_get_num_decoders()\fR gets the number of decoders currently
206 added to the context \fIctx\fR.
207 .PP
208 \&\fBOSSL_DECODER_CTX_set_construct()\fR sets the constructor \fIconstruct\fR.
209 .PP
210 \&\fBOSSL_DECODER_CTX_set_construct_data()\fR sets the constructor data that is
211 passed to the constructor every time it's called.
212 .PP
213 \&\fBOSSL_DECODER_CTX_set_cleanup()\fR sets the constructor data \fIcleanup\fR
214 function. This is called by \fBOSSL_DECODER_CTX_free\fR\|(3).
215 .PP
216 \&\fBOSSL_DECODER_CTX_get_construct()\fR, \fBOSSL_DECODER_CTX_get_construct_data()\fR and
217 \&\fBOSSL_DECODER_CTX_get_cleanup()\fR return the values that have been set by
218 \&\fBOSSL_DECODER_CTX_set_construct()\fR, \fBOSSL_DECODER_CTX_set_construct_data()\fR and
219 \&\fBOSSL_DECODER_CTX_set_cleanup()\fR respectively.
220 .PP
221 \&\fBOSSL_DECODER_export()\fR is a fallback function for constructors that cannot
222 use the data they get directly for diverse reasons. It takes the same
223 decode instance \fIdecoder_inst\fR that the constructor got and an object
224 \&\fIreference\fR, unpacks the object which it refers to, and exports it by
225 creating an \fBOSSL_PARAM\fR\|(3) array that it then passes to \fIexport_cb\fR,
226 along with \fIexport_arg\fR.
227 .PP
228 Note that functions \fBOSSL_DECODER_CTX_set_selection()\fR,
229 \&\fBOSSL_DECODER_CTX_set_output_type()\fR, \fBOSSL_DECODER_CTX_set_output_structure()\fR,
230 \&\fBOSSL_DECODER_CTX_add_encoder()\fR, \fBOSSL_DECODER_CTX_add_extra()\fR,
231 \&\fBOSSL_DECODER_CTX_set_construct()\fR, \fBOSSL_DECODER_CTX_set_construct_data()\fR, and
232 \&\fBOSSL_DECODER_CTX_set_cleanup()\fR shouldn't be used after the context is finalised,
233 in particular after calling the function \fBOSSL_DECODER_CTX_new_for_pkey()\fR.
234 .SS Constructor
235 .IX Subsection "Constructor"
236 A \fBOSSL_DECODER_CONSTRUCT\fR gets the following arguments:
237 .IP \fIdecoder_inst\fR 4
238 .IX Item "decoder_inst"
239 The \fBOSSL_DECODER_INSTANCE\fR for the decoder from which the constructor gets
240 its data.
241 .IP \fIobject\fR 4
242 .IX Item "object"
243 A provider-native object abstraction produced by the decoder. Further
244 information on the provider-native object abstraction can be found in
245 \&\fBprovider\-object\fR\|(7).
246 .IP \fIconstruct_data\fR 4
247 .IX Item "construct_data"
248 The pointer that was set with \fBOSSL_DECODE_CTX_set_construct_data()\fR.
249 .PP
250 The constructor is expected to return 1 when the data it receives can be
251 constructed, otherwise 0.
252 .PP
253 These utility functions may be used by a constructor:
254 .PP
255 \&\fBOSSL_DECODER_INSTANCE_get_decoder()\fR can be used to get the decoder
256 implementation from a decoder instance \fIdecoder_inst\fR.
257 .PP
258 \&\fBOSSL_DECODER_INSTANCE_get_decoder_ctx()\fR can be used to get the decoder
259 implementation's provider context from a decoder instance \fIdecoder_inst\fR.
260 .PP
261 \&\fBOSSL_DECODER_INSTANCE_get_input_type()\fR can be used to get the decoder
262 implementation's input type from a decoder instance \fIdecoder_inst\fR.
263 .PP
264 \&\fBOSSL_DECODER_INSTANCE_get_input_structure()\fR can be used to get the input
265 structure for the decoder implementation from a decoder instance
266 \&\fIdecoder_inst\fR.
267 This may be NULL.
268 .SH "RETURN VALUES"
269 .IX Header "RETURN VALUES"
270 \&\fBOSSL_DECODER_CTX_new()\fR returns a pointer to a \fBOSSL_DECODER_CTX\fR, or NULL
271 if the context structure couldn't be allocated.
272 .PP
273 \&\fBOSSL_DECODER_settable_ctx_params()\fR returns an \fBOSSL_PARAM\fR\|(3) array, or
274 NULL if none is available.
275 .PP
276 \&\fBOSSL_DECODER_CTX_set_params()\fR returns 1 if all recognised parameters were
277 valid, or 0 if one of them was invalid or caused some other failure in the
278 implementation.
279 .PP
280 \&\fBOSSL_DECODER_CTX_add_decoder()\fR, \fBOSSL_DECODER_CTX_add_extra()\fR,
281 \&\fBOSSL_DECODER_CTX_set_construct()\fR, \fBOSSL_DECODER_CTX_set_construct_data()\fR and
282 \&\fBOSSL_DECODER_CTX_set_cleanup()\fR return 1 on success, or 0 on failure.
283 .PP
284 \&\fBOSSL_DECODER_CTX_get_construct()\fR, \fBOSSL_DECODER_CTX_get_construct_data()\fR and
285 \&\fBOSSL_DECODER_CTX_get_cleanup()\fR return the current pointers to the
286 constructor, the constructor data and the cleanup functions, respectively.
287 .PP
288 \&\fBOSSL_DECODER_CTX_num_decoders()\fR returns the current number of decoders. It
289 returns 0 if \fIctx\fR is NULL.
290 .PP
291 \&\fBOSSL_DECODER_export()\fR returns 1 on success, or 0 on failure.
292 .PP
293 \&\fBOSSL_DECODER_INSTANCE_decoder()\fR returns an \fBOSSL_DECODER\fR pointer on
294 success, or NULL on failure.
295 .PP
296 \&\fBOSSL_DECODER_INSTANCE_decoder_ctx()\fR returns a provider context pointer on
297 success, or NULL on failure.
298 .SH "SEE ALSO"
299 .IX Header "SEE ALSO"
300 \&\fBprovider\fR\|(7), \fBOSSL_DECODER\fR\|(3), \fBOSSL_DECODER_from_bio\fR\|(3)
301 .SH HISTORY
302 .IX Header "HISTORY"
303 The functions described here were added in OpenSSL 3.0.
304 .SH COPYRIGHT
305 .IX Header "COPYRIGHT"
306 Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved.
307 .PP
308 Licensed under the Apache License 2.0 (the "License"). You may not use
309 this file except in compliance with the License. You can obtain a copy
310 in the file LICENSE in the source distribution or at
311 <https://www.openssl.org/source/license.html>.