1PROVIDER-DECODER(7ossl) OpenSSL PROVIDER-DECODER(7ossl)
2
6 provider-decoder - The OSSL_DECODER library <-> provider functions
7
9 #include <openssl/core_dispatch.h>
10 /*
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 /* 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 /* 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 /* Functions to check selection support */
28 int OSSL_FUNC_decoder_does_selection(void *provctx, int selection);
29 /* 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 /* 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
43 The term "decode" is used throughout this manual. This includes but is
44 not limited to deserialization as individual decoders can also do
45 decoding into intermediate data formats.
46 The DECODER operation is a generic method to create a provider-native
48 object reference or intermediate decoded data from an encoded form read
49 from the given OSSL_CORE_BIO. If the caller wants to decode data from
50 memory, it should provide a BIO_s_mem(3) BIO. The decoded data or
51 object reference is passed along with eventual metadata to the
52 metadata_cb as OSSL_PARAM(3) parameters.
53 The decoder doesn't need to know more about the OSSL_CORE_BIO pointer
55 than being able to pass it to the appropriate BIO upcalls (see "Core
56 functions" in provider-base(7)).
57 The DECODER implementation may be part of a chain, where data is passed
59 from one to the next. For example, there may be an implementation to
60 decode an object from PEM to DER, and another one that decodes DER to a
61 provider-native object.
62 The last decoding step in the decoding chain is usually supposed to
64 create a provider-native object referenced by an object reference. To
65 import that object into a different provider the
66 OSSL_FUNC_decoder_export_object() can be called as the final step of
67 the decoding process.
68 All "functions" mentioned here are passed as function pointers between
70 libcrypto and the provider in OSSL_DISPATCH(3) arrays via
71 OSSL_ALGORITHM(3) arrays that are returned by the provider's
72 provider_query_operation() function (see "Provider Functions" in
73 provider-base(7)).
74 All these "functions" have a corresponding function type definition
76 named OSSL_FUNC_{name}_fn, and a helper function to retrieve the
77 function pointer from an OSSL_DISPATCH(3) element named
78 OSSL_FUNC_{name}. For example, the "function"
79 OSSL_FUNC_decoder_decode() has these:
80 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 OSSL_DISPATCH(3) arrays are indexed by numbers that are provided as
90 macros in openssl-core_dispatch.h(7), as follows:
91 OSSL_FUNC_decoder_get_params OSSL_FUNC_DECODER_GET_PARAMS
93 OSSL_FUNC_decoder_gettable_params OSSL_FUNC_DECODER_GETTABLE_PARAMS
94 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 OSSL_FUNC_decoder_does_selection OSSL_FUNC_DECODER_DOES_SELECTION
101 OSSL_FUNC_decoder_decode OSSL_FUNC_DECODER_DECODE
103 OSSL_FUNC_decoder_export_object OSSL_FUNC_DECODER_EXPORT_OBJECT
105 Names and properties
107 The name of an implementation should match the target type of object it
108 decodes. For example, an implementation that decodes an RSA key should
109 be named "RSA". Likewise, an implementation that decodes DER data from
110 PEM input should be named "DER".
111 Properties can be used to further specify details about an
113 implementation:
114 input
116 This property is used to specify what format of input the
117 implementation can decode.
118 This property is mandatory.
120 OpenSSL providers recognize the following input types:
122 pem An implementation with that input type decodes PEM formatted
124 data.
125 der An implementation with that input type decodes DER formatted
127 data.
128 msblob
130 An implementation with that input type decodes MSBLOB formatted
131 data.
132 pvk An implementation with that input type decodes PVK formatted
134 data.
135 structure
137 This property is used to specify the structure that the decoded
138 data is expected to have.
139 This property is optional.
141 Structures currently recognised by built-in decoders:
143 "type-specific"
145 Type specific structure.
146 "pkcs8"
148 Structure according to the PKCS#8 specification.
149 "SubjectPublicKeyInfo"
151 Encoding of public keys according to the Subject Public Key
152 Info of RFC 5280.
153 The possible values of both these properties is open ended. A provider
155 may very well specify input types and structures that libcrypto doesn't
156 know anything about.
157 Subset selections
159 Sometimes, an object has more than one subset of data that is
160 interesting to treat separately or together. It's possible to specify
161 what subsets are to be decoded, with a set of bits selection that are
162 passed in an int.
163 This set of bits depend entirely on what kind of provider-side object
165 is to be decoded. For example, those bits are assumed to be the same
166 as those used with provider-keymgmt(7) (see "Key Objects" in
167 provider-keymgmt(7)) when the object is an asymmetric keypair - e.g.,
168 OSSL_KEYMGMT_SELECT_PRIVATE_KEY if the object to be decoded is supposed
169 to contain private key components.
170 OSSL_FUNC_decoder_does_selection() should tell if a particular
172 implementation supports any of the combinations given by selection.
173 Context functions
175 OSSL_FUNC_decoder_newctx() returns a context to be used with the rest
176 of the functions.
177 OSSL_FUNC_decoder_freectx() frees the given ctx as created by
179 OSSL_FUNC_decoder_newctx().
180 OSSL_FUNC_decoder_set_ctx_params() sets context data according to
182 parameters from params that it recognises. Unrecognised parameters
183 should be ignored. Passing NULL for params should return true.
184 OSSL_FUNC_decoder_settable_ctx_params() returns a constant
186 OSSL_PARAM(3) array describing the parameters that
187 OSSL_FUNC_decoder_set_ctx_params() can handle.
188 See OSSL_PARAM(3) for further details on the parameters structure used
190 by OSSL_FUNC_decoder_set_ctx_params() and
191 OSSL_FUNC_decoder_settable_ctx_params().
192 Export function
194 When a provider-native object is created by a decoder it would be
195 unsuitable for direct use with a foreign provider. The export function
196 allows for exporting the object into that foreign provider if the
197 foreign provider supports the type of the object and provides an import
198 function.
199 OSSL_FUNC_decoder_export_object() should export the object of size
201 objref_sz referenced by objref as an OSSL_PARAM(3) array and pass that
202 into the export_cb as well as the given export_cbarg.
203 Decoding functions
205 OSSL_FUNC_decoder_decode() should decode the data as read from the
206 OSSL_CORE_BIO in to produce decoded data or an object to be passed as
207 reference in an OSSL_PARAM(3) array along with possible other metadata
208 that was decoded from the input. This OSSL_PARAM(3) array is then
209 passed to the data_cb callback. The selection bits, if relevant,
210 should determine what the input data should contain. The decoding
211 functions also take an OSSL_PASSPHRASE_CALLBACK(3) function pointer
212 along with a pointer to application data cbarg, which should be used
213 when a pass phrase prompt is needed.
214 It's important to understand that the return value from this function
216 is interpreted as follows:
217 True (1)
219 This means "carry on the decoding process", and is meaningful even
220 though this function couldn't decode the input into anything,
221 because there may be another decoder implementation that can decode
222 it into something.
223 The data_cb callback should never be called when this function
225 can't decode the input into anything.
226 False (0)
228 This means "stop the decoding process", and is meaningful when the
229 input could be decoded into some sort of object that this function
230 understands, but further treatment of that object results into
231 errors that won't be possible for some other decoder implementation
232 to get a different result.
233 The conditions to stop the decoding process are at the discretion of
235 the implementation.
236 Decoder operation parameters
238 There are currently no operation parameters currently recognised by the
239 built-in decoders.
240 Parameters currently recognised by the built-in pass phrase callback:
242 "info" (OSSL_PASSPHRASE_PARAM_INFO) <UTF8 string>
244 A string of information that will become part of the pass phrase
245 prompt. This could be used to give the user information on what
246 kind of object it's being prompted for.
247
249 OSSL_FUNC_decoder_newctx() returns a pointer to a context, or NULL on
250 failure.
251 OSSL_FUNC_decoder_set_ctx_params() returns 1, unless a recognised
253 parameter was invalid or caused an error, for which 0 is returned.
254 OSSL_FUNC_decoder_settable_ctx_params() returns a pointer to an array
256 of constant OSSL_PARAM(3) elements.
257 OSSL_FUNC_decoder_does_selection() returns 1 if the decoder
259 implementation supports any of the selection bits, otherwise 0.
260 OSSL_FUNC_decoder_decode() returns 1 to signal that the decoding
262 process should continue, or 0 to signal that it should stop.
263
265 provider(7)
266
268 The DECODER interface was introduced in OpenSSL 3.0.
269
271 Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
272 Licensed under the Apache License 2.0 (the "License"). You may not use
274 this file except in compliance with the License. You can obtain a copy
275 in the file LICENSE in the source distribution or at
276 <https://www.openssl.org/source/license.html>.
2773.0.9 2023-07-27 PROVIDER-DECODER(7ossl)