5 provider-decoder - The OSSL_DECODER library E<lt>-E<gt> provider functions
9 #include <openssl/core_dispatch.h>
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.
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[]);
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[]);
27 /* Functions to check selection support */
28 int OSSL_FUNC_decoder_does_selection(void *provctx, int selection);
30 /* Functions to decode object data */
31 int OSSL_FUNC_decoder_decode(void *ctx, OSSL_CORE_BIO *in,
33 OSSL_CALLBACK *data_cb, void *data_cbarg,
34 OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
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,
44 I<The term "decode" is used throughout this manual. This includes but is
45 not limited to deserialization as individual decoders can also do
46 decoding into intermediate data formats.>
48 The DECODER operation is a generic method to create a provider-native
49 object reference or intermediate decoded data from an encoded form
50 read from the given B<OSSL_CORE_BIO>. If the caller wants to decode
51 data from memory, it should provide a L<BIO_s_mem(3)> B<BIO>. The decoded
52 data or object reference is passed along with eventual metadata
53 to the I<metadata_cb> as L<OSSL_PARAM(3)> parameters.
55 The decoder doesn't need to know more about the B<OSSL_CORE_BIO>
56 pointer than being able to pass it to the appropriate BIO upcalls (see
57 L<provider-base(7)/Core functions>).
59 The DECODER implementation may be part of a chain, where data is
60 passed from one to the next. For example, there may be an
61 implementation to decode an object from PEM to DER, and another one
62 that decodes DER to a provider-native object.
64 The last decoding step in the decoding chain is usually supposed to create
65 a provider-native object referenced by an object reference. To import
66 that object into a different provider the OSSL_FUNC_decoder_export_object()
67 can be called as the final step of the decoding process.
69 All "functions" mentioned here are passed as function pointers between
70 F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays via
71 L<OSSL_ALGORITHM(3)> arrays that are returned by the provider's
72 provider_query_operation() function
73 (see L<provider-base(7)/Provider Functions>).
75 All these "functions" have a corresponding function type definition
76 named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
77 function pointer from an L<OSSL_DISPATCH(3)> element named
79 For example, the "function" OSSL_FUNC_decoder_decode() has these:
82 (OSSL_FUNC_decoder_decode_fn)(void *ctx, OSSL_CORE_BIO *in,
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);
89 L<OSSL_DISPATCH(3)> arrays are indexed by numbers that are provided as
90 macros in L<openssl-core_dispatch.h(7)>, as follows:
92 OSSL_FUNC_decoder_get_params OSSL_FUNC_DECODER_GET_PARAMS
93 OSSL_FUNC_decoder_gettable_params OSSL_FUNC_DECODER_GETTABLE_PARAMS
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
100 OSSL_FUNC_decoder_does_selection OSSL_FUNC_DECODER_DOES_SELECTION
102 OSSL_FUNC_decoder_decode OSSL_FUNC_DECODER_DECODE
104 OSSL_FUNC_decoder_export_object OSSL_FUNC_DECODER_EXPORT_OBJECT
106 =head2 Names and properties
108 The name of an implementation should match the target type of object
109 it decodes. For example, an implementation that decodes an RSA key
110 should be named "RSA". Likewise, an implementation that decodes DER data
111 from PEM input should be named "DER".
113 Properties can be used to further specify details about an implementation:
119 This property is used to specify what format of input the implementation
122 This property is I<mandatory>.
124 OpenSSL providers recognize the following input types:
130 An implementation with that input type decodes PEM formatted data.
134 An implementation with that input type decodes DER formatted data.
138 An implementation with that input type decodes MSBLOB formatted data.
142 An implementation with that input type decodes PVK formatted data.
148 This property is used to specify the structure that the decoded data is
151 This property is I<optional>.
153 Structures currently recognised by built-in decoders:
157 =item "type-specific"
159 Type specific structure.
163 Structure according to the PKCS#8 specification.
165 =item "SubjectPublicKeyInfo"
167 Encoding of public keys according to the Subject Public Key Info of RFC 5280.
173 The possible values of both these properties is open ended. A provider may
174 very well specify input types and structures that libcrypto doesn't know
177 =head2 Subset selections
179 Sometimes, an object has more than one subset of data that is interesting to
180 treat separately or together. It's possible to specify what subsets are to
181 be decoded, with a set of bits I<selection> that are passed in an B<int>.
183 This set of bits depend entirely on what kind of provider-side object is
184 to be decoded. For example, those bits are assumed to be the same as those
185 used with L<provider-keymgmt(7)> (see L<provider-keymgmt(7)/Key Objects>) when
186 the object is an asymmetric keypair - e.g., B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY>
187 if the object to be decoded is supposed to contain private key components.
189 OSSL_FUNC_decoder_does_selection() should tell if a particular implementation
190 supports any of the combinations given by I<selection>.
192 =head2 Context functions
194 OSSL_FUNC_decoder_newctx() returns a context to be used with the rest of
197 OSSL_FUNC_decoder_freectx() frees the given I<ctx> as created by
198 OSSL_FUNC_decoder_newctx().
200 OSSL_FUNC_decoder_set_ctx_params() sets context data according to parameters
201 from I<params> that it recognises. Unrecognised parameters should be
203 Passing NULL for I<params> should return true.
205 OSSL_FUNC_decoder_settable_ctx_params() returns a constant L<OSSL_PARAM(3)>
206 array describing the parameters that OSSL_FUNC_decoder_set_ctx_params()
209 See L<OSSL_PARAM(3)> for further details on the parameters structure used by
210 OSSL_FUNC_decoder_set_ctx_params() and OSSL_FUNC_decoder_settable_ctx_params().
212 =head2 Export function
214 When a provider-native object is created by a decoder it would be unsuitable
215 for direct use with a foreign provider. The export function allows for
216 exporting the object into that foreign provider if the foreign provider
217 supports the type of the object and provides an import function.
219 OSSL_FUNC_decoder_export_object() should export the object of size I<objref_sz>
220 referenced by I<objref> as an L<OSSL_PARAM(3)> array and pass that into the
221 I<export_cb> as well as the given I<export_cbarg>.
223 =head2 Decoding functions
225 OSSL_FUNC_decoder_decode() should decode the data as read from
226 the B<OSSL_CORE_BIO> I<in> to produce decoded data or an object to be
227 passed as reference in an L<OSSL_PARAM(3)> array along with possible other
228 metadata that was decoded from the input. This L<OSSL_PARAM(3)> array is
229 then passed to the I<data_cb> callback. The I<selection> bits,
230 if relevant, should determine what the input data should contain.
231 The decoding functions also take an L<OSSL_PASSPHRASE_CALLBACK(3)> function
232 pointer along with a pointer to application data I<cbarg>, which should be
233 used when a pass phrase prompt is needed.
235 It's important to understand that the return value from this function is
236 interpreted as follows:
242 This means "carry on the decoding process", and is meaningful even though
243 this function couldn't decode the input into anything, because there may be
244 another decoder implementation that can decode it into something.
246 The I<data_cb> callback should never be called when this function can't
247 decode the input into anything.
251 This means "stop the decoding process", and is meaningful when the input
252 could be decoded into some sort of object that this function understands,
253 but further treatment of that object results into errors that won't be
254 possible for some other decoder implementation to get a different result.
258 The conditions to stop the decoding process are at the discretion of the
261 =head2 Decoder operation parameters
263 There are currently no operation parameters currently recognised by the
266 Parameters currently recognised by the built-in pass phrase callback:
270 =item "info" (B<OSSL_PASSPHRASE_PARAM_INFO>) <UTF8 string>
272 A string of information that will become part of the pass phrase
273 prompt. This could be used to give the user information on what kind
274 of object it's being prompted for.
280 OSSL_FUNC_decoder_newctx() returns a pointer to a context, or NULL on
283 OSSL_FUNC_decoder_set_ctx_params() returns 1, unless a recognised
284 parameter was invalid or caused an error, for which 0 is returned.
286 OSSL_FUNC_decoder_settable_ctx_params() returns a pointer to an array of
287 constant L<OSSL_PARAM(3)> elements.
289 OSSL_FUNC_decoder_does_selection() returns 1 if the decoder implementation
290 supports any of the I<selection> bits, otherwise 0.
292 OSSL_FUNC_decoder_decode() returns 1 to signal that the decoding process
293 should continue, or 0 to signal that it should stop.
301 The DECODER interface was introduced in OpenSSL 3.0.
305 Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
307 Licensed under the Apache License 2.0 (the "License"). You may not use
308 this file except in compliance with the License. You can obtain a copy
309 in the file LICENSE in the source distribution or at
310 L<https://www.openssl.org/source/license.html>.