Debian Codegraph @

upstream/debian-unstable/man7/provider-decoder.7ssl

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 "PROVIDER-DECODER 7SSL"
58 .TH PROVIDER-DECODER 7SSL 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 provider\-decoder \- The OSSL_DECODER library <\-> provider functions
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/core_dispatch.h>
69 \&
70 \& /*
71 \& * None of these are actual functions, but are displayed like this for
72 \& * the function signatures for functions that are offered as function
73 \& * pointers in OSSL_DISPATCH arrays.
74 \& */
75 \&
76 \& /* Decoder parameter accessor and descriptor */
77 \& const OSSL_PARAM *OSSL_FUNC_decoder_gettable_params(void *provctx);
78 \& int OSSL_FUNC_decoder_get_params(OSSL_PARAM params[]);
79 \&
80 \& /* Functions to construct / destruct / manipulate the decoder context */
81 \& void *OSSL_FUNC_decoder_newctx(void *provctx);
82 \& void OSSL_FUNC_decoder_freectx(void *ctx);
83 \& const OSSL_PARAM *OSSL_FUNC_decoder_settable_ctx_params(void *provctx);
84 \& int OSSL_FUNC_decoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
85 \&
86 \& /* Functions to check selection support */
87 \& int OSSL_FUNC_decoder_does_selection(void *provctx, int selection);
88 \&
89 \& /* Functions to decode object data */
90 \& int OSSL_FUNC_decoder_decode(void *ctx, OSSL_CORE_BIO *in,
91 \& int selection,
92 \& OSSL_CALLBACK *data_cb, void *data_cbarg,
93 \& OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
94 \&
95 \& /* Functions to export a decoded object */
96 \& int OSSL_FUNC_decoder_export_object(void *ctx,
97 \& const void *objref, size_t objref_sz,
98 \& OSSL_CALLBACK *export_cb,
99 \& void *export_cbarg);
100 .Ve
101 .SH DESCRIPTION
102 .IX Header "DESCRIPTION"
103 \&\fIThe term "decode" is used throughout this manual. This includes but is
104 not limited to deserialization as individual decoders can also do
105 decoding into intermediate data formats.\fR
106 .PP
107 The DECODER operation is a generic method to create a provider-native
108 object reference or intermediate decoded data from an encoded form
109 read from the given \fBOSSL_CORE_BIO\fR. If the caller wants to decode
110 data from memory, it should provide a \fBBIO_s_mem\fR\|(3) \fBBIO\fR. The decoded
111 data or object reference is passed along with eventual metadata
112 to the \fImetadata_cb\fR as \fBOSSL_PARAM\fR\|(3) parameters.
113 .PP
114 The decoder doesn't need to know more about the \fBOSSL_CORE_BIO\fR
115 pointer than being able to pass it to the appropriate BIO upcalls (see
116 "Core functions" in \fBprovider\-base\fR\|(7)).
117 .PP
118 The DECODER implementation may be part of a chain, where data is
119 passed from one to the next. For example, there may be an
120 implementation to decode an object from PEM to DER, and another one
121 that decodes DER to a provider-native object.
122 .PP
123 The last decoding step in the decoding chain is usually supposed to create
124 a provider-native object referenced by an object reference. To import
125 that object into a different provider the \fBOSSL_FUNC_decoder_export_object()\fR
126 can be called as the final step of the decoding process.
127 .PP
128 All "functions" mentioned here are passed as function pointers between
129 \&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via
130 \&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider's
131 \&\fBprovider_query_operation()\fR function
132 (see "Provider Functions" in \fBprovider\-base\fR\|(7)).
133 .PP
134 All these "functions" have a corresponding function type definition
135 named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the
136 function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named
137 \&\fBOSSL_FUNC_{name}\fR.
138 For example, the "function" \fBOSSL_FUNC_decoder_decode()\fR has these:
139 .PP
140 .Vb 7
141 \& typedef int
142 \& (OSSL_FUNC_decoder_decode_fn)(void *ctx, OSSL_CORE_BIO *in,
143 \& int selection,
144 \& OSSL_CALLBACK *data_cb, void *data_cbarg,
145 \& OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
146 \& static ossl_inline OSSL_FUNC_decoder_decode_fn*
147 \& OSSL_FUNC_decoder_decode(const OSSL_DISPATCH *opf);
148 .Ve
149 .PP
150 \&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as
151 macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows:
152 .PP
153 .Vb 2
154 \& OSSL_FUNC_decoder_get_params OSSL_FUNC_DECODER_GET_PARAMS
155 \& OSSL_FUNC_decoder_gettable_params OSSL_FUNC_DECODER_GETTABLE_PARAMS
156 \&
157 \& OSSL_FUNC_decoder_newctx OSSL_FUNC_DECODER_NEWCTX
158 \& OSSL_FUNC_decoder_freectx OSSL_FUNC_DECODER_FREECTX
159 \& OSSL_FUNC_decoder_set_ctx_params OSSL_FUNC_DECODER_SET_CTX_PARAMS
160 \& OSSL_FUNC_decoder_settable_ctx_params OSSL_FUNC_DECODER_SETTABLE_CTX_PARAMS
161 \&
162 \& OSSL_FUNC_decoder_does_selection OSSL_FUNC_DECODER_DOES_SELECTION
163 \&
164 \& OSSL_FUNC_decoder_decode OSSL_FUNC_DECODER_DECODE
165 \&
166 \& OSSL_FUNC_decoder_export_object OSSL_FUNC_DECODER_EXPORT_OBJECT
167 .Ve
168 .SS "Names and properties"
169 .IX Subsection "Names and properties"
170 The name of an implementation should match the target type of object
171 it decodes. For example, an implementation that decodes an RSA key
172 should be named "RSA". Likewise, an implementation that decodes DER data
173 from PEM input should be named "DER".
174 .PP
175 Properties, as defined in the \fBOSSL_ALGORITHM\fR\|(3) array element of each
176 decoder implementation, can be used to further specify details about an
177 implementation:
178 .IP input 4
179 .IX Item "input"
180 This property is used to specify what format of input the implementation
181 can decode.
182 .Sp
183 This property is \fImandatory\fR.
184 .Sp
185 OpenSSL providers recognize the following input types:
186 .RS 4
187 .IP pem 4
188 .IX Item "pem"
189 An implementation with that input type decodes PEM formatted data.
190 .IP der 4
191 .IX Item "der"
192 An implementation with that input type decodes DER formatted data.
193 .IP msblob 4
194 .IX Item "msblob"
195 An implementation with that input type decodes MSBLOB formatted data.
196 .IP pvk 4
197 .IX Item "pvk"
198 An implementation with that input type decodes PVK formatted data.
199 .RE
200 .RS 4
201 .RE
202 .IP structure 4
203 .IX Item "structure"
204 This property is used to specify the structure that the decoded data is
205 expected to have.
206 .Sp
207 This property is \fIoptional\fR.
208 .Sp
209 Structures currently recognised by built-in decoders:
210 .RS 4
211 .IP """type-specific""" 4
212 .IX Item """type-specific"""
213 Type specific structure.
214 .IP """pkcs8""" 4
215 .IX Item """pkcs8"""
216 Structure according to the PKCS#8 specification.
217 .IP """SubjectPublicKeyInfo""" 4
218 .IX Item """SubjectPublicKeyInfo"""
219 Encoding of public keys according to the Subject Public Key Info of RFC 5280.
220 .RE
221 .RS 4
222 .RE
223 .PP
224 The possible values of both these properties is open ended. A provider may
225 very well specify input types and structures that libcrypto doesn't know
226 anything about.
227 .SS "Subset selections"
228 .IX Subsection "Subset selections"
229 Sometimes, an object has more than one subset of data that is interesting to
230 treat separately or together. It's possible to specify what subsets are to
231 be decoded, with a set of bits \fIselection\fR that are passed in an \fBint\fR.
232 .PP
233 This set of bits depend entirely on what kind of provider-side object is
234 to be decoded. For example, those bits are assumed to be the same as those
235 used with \fBprovider\-keymgmt\fR\|(7) (see "Key Objects" in \fBprovider\-keymgmt\fR\|(7)) when
236 the object is an asymmetric keypair \- e.g., \fBOSSL_KEYMGMT_SELECT_PRIVATE_KEY\fR
237 if the object to be decoded is supposed to contain private key components.
238 .PP
239 \&\fBOSSL_FUNC_decoder_does_selection()\fR should tell if a particular implementation
240 supports any of the combinations given by \fIselection\fR.
241 .SS "Context functions"
242 .IX Subsection "Context functions"
243 \&\fBOSSL_FUNC_decoder_newctx()\fR returns a context to be used with the rest of
244 the functions.
245 .PP
246 \&\fBOSSL_FUNC_decoder_freectx()\fR frees the given \fIctx\fR as created by
247 \&\fBOSSL_FUNC_decoder_newctx()\fR.
248 .PP
249 \&\fBOSSL_FUNC_decoder_set_ctx_params()\fR sets context data according to parameters
250 from \fIparams\fR that it recognises. Unrecognised parameters should be
251 ignored.
252 Passing NULL for \fIparams\fR should return true.
253 .PP
254 \&\fBOSSL_FUNC_decoder_settable_ctx_params()\fR returns a constant \fBOSSL_PARAM\fR\|(3)
255 array describing the parameters that \fBOSSL_FUNC_decoder_set_ctx_params()\fR
256 can handle.
257 .PP
258 See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by
259 \&\fBOSSL_FUNC_decoder_set_ctx_params()\fR and \fBOSSL_FUNC_decoder_settable_ctx_params()\fR.
260 .SS "Export function"
261 .IX Subsection "Export function"
262 When a provider-native object is created by a decoder it would be unsuitable
263 for direct use with a foreign provider. The export function allows for
264 exporting the object into that foreign provider if the foreign provider
265 supports the type of the object and provides an import function.
266 .PP
267 \&\fBOSSL_FUNC_decoder_export_object()\fR should export the object of size \fIobjref_sz\fR
268 referenced by \fIobjref\fR as an \fBOSSL_PARAM\fR\|(3) array and pass that into the
269 \&\fIexport_cb\fR as well as the given \fIexport_cbarg\fR.
270 .SS "Decoding functions"
271 .IX Subsection "Decoding functions"
272 \&\fBOSSL_FUNC_decoder_decode()\fR should decode the data as read from
273 the \fBOSSL_CORE_BIO\fR \fIin\fR to produce decoded data or an object to be
274 passed as reference in an \fBOSSL_PARAM\fR\|(3) array along with possible other
275 metadata that was decoded from the input. This \fBOSSL_PARAM\fR\|(3) array is
276 then passed to the \fIdata_cb\fR callback. The \fIselection\fR bits,
277 if relevant, should determine what the input data should contain.
278 The decoding functions also take an \fBOSSL_PASSPHRASE_CALLBACK\fR\|(3) function
279 pointer along with a pointer to application data \fIcbarg\fR, which should be
280 used when a pass phrase prompt is needed.
281 .PP
282 It's important to understand that the return value from this function is
283 interpreted as follows:
284 .IP "True (1)" 4
285 .IX Item "True (1)"
286 This means "carry on the decoding process", and is meaningful even though
287 this function couldn't decode the input into anything, because there may be
288 another decoder implementation that can decode it into something.
289 .Sp
290 The \fIdata_cb\fR callback should never be called when this function can't
291 decode the input into anything.
292 .IP "False (0)" 4
293 .IX Item "False (0)"
294 This means "stop the decoding process", and is meaningful when the input
295 could be decoded into some sort of object that this function understands,
296 but further treatment of that object results into errors that won't be
297 possible for some other decoder implementation to get a different result.
298 .PP
299 The conditions to stop the decoding process are at the discretion of the
300 implementation.
301 .SS "Decoder operation parameters"
302 .IX Subsection "Decoder operation parameters"
303 There are currently no operation parameters currently recognised by the
304 built-in decoders.
305 .PP
306 Parameters currently recognised by the built-in pass phrase callback:
307 .IP """info"" (\fBOSSL_PASSPHRASE_PARAM_INFO\fR) <UTF8 string>" 4
308 .IX Item """info"" (OSSL_PASSPHRASE_PARAM_INFO) <UTF8 string>"
309 A string of information that will become part of the pass phrase
310 prompt. This could be used to give the user information on what kind
311 of object it's being prompted for.
312 .SH "RETURN VALUES"
313 .IX Header "RETURN VALUES"
314 \&\fBOSSL_FUNC_decoder_newctx()\fR returns a pointer to a context, or NULL on
315 failure.
316 .PP
317 \&\fBOSSL_FUNC_decoder_set_ctx_params()\fR returns 1, unless a recognised
318 parameter was invalid or caused an error, for which 0 is returned.
319 .PP
320 \&\fBOSSL_FUNC_decoder_settable_ctx_params()\fR returns a pointer to an array of
321 constant \fBOSSL_PARAM\fR\|(3) elements.
322 .PP
323 \&\fBOSSL_FUNC_decoder_does_selection()\fR returns 1 if the decoder implementation
324 supports any of the \fIselection\fR bits, otherwise 0.
325 .PP
326 \&\fBOSSL_FUNC_decoder_decode()\fR returns 1 to signal that the decoding process
327 should continue, or 0 to signal that it should stop.
328 .SH "SEE ALSO"
329 .IX Header "SEE ALSO"
330 \&\fBprovider\fR\|(7)
331 .SH HISTORY
332 .IX Header "HISTORY"
333 The DECODER interface was introduced in OpenSSL 3.0.
334 .SH COPYRIGHT
335 .IX Header "COPYRIGHT"
336 Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved.
337 .PP
338 Licensed under the Apache License 2.0 (the "License"). You may not use
339 this file except in compliance with the License. You can obtain a copy
340 in the file LICENSE in the source distribution or at
341 <https://www.openssl.org/source/license.html>.