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