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