]>
Commit | Line | Data |
---|---|---|
0d003c52 RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5a6d6fe6 | 5 | provider-encoder - The OSSL_ENCODER library E<lt>-E<gt> provider functions |
0d003c52 RL |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
23c48d94 | 9 | #include <openssl/core_dispatch.h> |
0d003c52 RL |
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 | ||
5a6d6fe6 RL |
17 | /* Encoder parameter accessor and descriptor */ |
18 | const OSSL_PARAM *OSSL_FUNC_encoder_gettable_params(void *provctx); | |
19 | int encoder_get_params(OSSL_PARAM params[]); | |
20 | ||
ece9304c RL |
21 | /* Functions to construct / destruct / manipulate the encoder context */ |
22 | void *OSSL_FUNC_encoder_newctx(void *provctx); | |
23 | void OSSL_FUNC_encoder_freectx(void *ctx); | |
24 | int OSSL_FUNC_encoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]); | |
25 | const OSSL_PARAM *OSSL_FUNC_encoder_settable_ctx_params(void *provctx) | |
0d003c52 | 26 | |
cd861ab7 RL |
27 | /* Functions to check selection support */ |
28 | int OSSL_FUNC_encoder_does_selection(void *provctx, int selection); | |
29 | ||
ece9304c | 30 | /* Functions to encode object data */ |
5a6d6fe6 RL |
31 | int OSSL_FUNC_encoder_encode(void *ctx, OSSL_CORE_BIO *out, |
32 | const void *obj_raw, | |
33 | const OSSL_PARAM obj_abstract[], | |
34 | int selection, | |
35 | OSSL_PASSPHRASE_CALLBACK *cb, | |
36 | void *cbarg); | |
37 | ||
38 | /* Functions to import and free a temporary object to be encoded */ | |
39 | void *encoder_import_object(void *ctx, int selection, | |
40 | const OSSL_PARAM params[]); | |
41 | void encoder_free_object(void *obj); | |
42 | ||
0d003c52 RL |
43 | |
44 | =head1 DESCRIPTION | |
45 | ||
ece9304c RL |
46 | I<We use the wide term "encode" in this manual. This includes but is |
47 | not limited to serialization.> | |
48 | ||
5a6d6fe6 RL |
49 | The ENCODER operation is a generic method to encode a provider-native |
50 | object (I<obj_raw>) or an object abstraction (I<object_abstract>, see | |
51 | L<provider-object(7)>) into an encoded form, and write the result to | |
52 | the given OSSL_CORE_BIO. If the caller wants to get the encoded | |
53 | stream to memory, it should provide a L<BIO_s_membuf(3)>. | |
0d003c52 | 54 | |
5a6d6fe6 RL |
55 | The encoder 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 | |
0d003c52 RL |
57 | L<provider-base(7)/Core functions>). |
58 | ||
5a6d6fe6 RL |
59 | The ENCODER 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 encode an object to DER (that object is assumed to | |
62 | be provider-native and thereby passed via I<obj_raw>), and another one | |
63 | that encodes DER to PEM (that one would receive the DER encoding via | |
64 | I<obj_abstract>). | |
65 | ||
66 | =begin comment | |
67 | ||
68 | Having the DER encoding passed via I<obj_abstract> may seem | |
69 | complicated. However, there may be associated meta-data, such as the | |
70 | original data type, that need to be passed alongside it, and since | |
71 | L<provider-object(7)> already defines a way to pass such data, | |
72 | inventing another way to do it makes things even more complicated. | |
73 | ||
74 | =end comment | |
75 | ||
ece9304c RL |
76 | The encoding using the L<OSSL_PARAM(3)> array form allows a |
77 | encoder to be used for data that's been exported from another | |
0d003c52 RL |
78 | provider, and thereby allow them to exist independently of each |
79 | other. | |
80 | ||
ece9304c | 81 | The encoding using a provider side object can only be safely used |
0d003c52 RL |
82 | with provider data coming from the same provider, for example keys |
83 | with the L<KEYMGMT|provider-keymgmt(7)> provider. | |
84 | ||
85 | All "functions" mentioned here are passed as function pointers between | |
86 | F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via | |
87 | B<OSSL_ALGORITHM> arrays that are returned by the provider's | |
88 | provider_query_operation() function | |
89 | (see L<provider-base(7)/Provider Functions>). | |
90 | ||
91 | All these "functions" have a corresponding function type definition | |
92 | named B<OSSL_{name}_fn>, and a helper function to retrieve the | |
93 | function pointer from a B<OSSL_DISPATCH> element named | |
363b1e5d | 94 | B<OSSL_FUNC_{name}>. |
ece9304c | 95 | For example, the "function" OSSL_FUNC_encoder_encode_data() has these: |
0d003c52 RL |
96 | |
97 | typedef int | |
5a6d6fe6 RL |
98 | (OSSL_FUNC_encoder_encode_fn)(void *ctx, OSSL_CORE_BIO *out, |
99 | const void *obj_raw, | |
100 | const OSSL_PARAM obj_abstract[], | |
101 | int selection, | |
102 | OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); | |
103 | static ossl_inline OSSL_FUNC_encoder_encode_fn | |
ece9304c | 104 | OSSL_FUNC_encoder_encode_data(const OSSL_DISPATCH *opf); |
0d003c52 RL |
105 | |
106 | B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as | |
23c48d94 | 107 | macros in L<openssl-core_dispatch.h(7)>, as follows: |
0d003c52 | 108 | |
5a6d6fe6 RL |
109 | OSSL_FUNC_encoder_get_params OSSL_FUNC_ENCODER_GET_PARAMS |
110 | OSSL_FUNC_encoder_gettable_params OSSL_FUNC_ENCODER_GETTABLE_PARAMS | |
111 | ||
ece9304c RL |
112 | OSSL_FUNC_encoder_newctx OSSL_FUNC_ENCODER_NEWCTX |
113 | OSSL_FUNC_encoder_freectx OSSL_FUNC_ENCODER_FREECTX | |
114 | OSSL_FUNC_encoder_set_ctx_params OSSL_FUNC_ENCODER_SET_CTX_PARAMS | |
115 | OSSL_FUNC_encoder_settable_ctx_params OSSL_FUNC_ENCODER_SETTABLE_CTX_PARAMS | |
0d003c52 | 116 | |
cd861ab7 RL |
117 | OSSL_FUNC_encoder_does_selection OSSL_FUNC_ENCODER_DOES_SELECTION |
118 | ||
5a6d6fe6 RL |
119 | OSSL_FUNC_encoder_encode OSSL_FUNC_ENCODER_ENCODE_DATA |
120 | ||
121 | OSSL_FUNC_encoder_import_object OSSL_FUNC_ENCODER_IMPORT_OBJECT | |
122 | OSSL_FUNC_encoder_free_object OSSL_FUNC_ENCODER_FREE_OBJECT | |
0d003c52 RL |
123 | |
124 | =head2 Names and properties | |
125 | ||
5a6d6fe6 RL |
126 | The name of an implementation should match the type of object it handles. |
127 | For example, an implementation that encodes an RSA key should be named "RSA". | |
128 | Likewise, an implementation that further encodes DER should be named "DER". | |
0d003c52 | 129 | |
5a6d6fe6 | 130 | Properties can be use to further specify details about an implementation: |
0d003c52 RL |
131 | |
132 | =over 4 | |
133 | ||
5a6d6fe6 | 134 | =item output |
0d003c52 | 135 | |
5a6d6fe6 RL |
136 | This property is used to specify what type of output implementation |
137 | produces. Currently known output types are: | |
0d003c52 RL |
138 | |
139 | =over 4 | |
140 | ||
141 | =item text | |
142 | ||
5a6d6fe6 RL |
143 | An implementation with that output type outputs human readable text, making |
144 | that implementation suitable for C<-text> output in diverse L<openssl(1)> | |
145 | commands. | |
0d003c52 RL |
146 | |
147 | =item pem | |
148 | ||
5a6d6fe6 | 149 | An implementation with that output type outputs PEM formatted data. |
0d003c52 RL |
150 | |
151 | =item der | |
152 | ||
5a6d6fe6 | 153 | An implementation with that output type outputs DER formatted data. |
0d003c52 RL |
154 | |
155 | =back | |
156 | ||
5a6d6fe6 | 157 | =item structure |
0d003c52 | 158 | |
5a6d6fe6 RL |
159 | This property is used to specify the structure that is used for the encoded |
160 | object. An example could be C<pkcs8>, to specify explicitly that an object | |
161 | (presumably an asymmetric key pair, in this case) will be wrapped in a | |
162 | PKCS#8 structure as part of the encoding. | |
0d003c52 | 163 | |
5a6d6fe6 | 164 | =back |
0d003c52 | 165 | |
5a6d6fe6 RL |
166 | The possible values of both these properties is open ended. A provider may |
167 | very well specify output types and structures that libcrypto doesn't know | |
168 | anything about. | |
0d003c52 | 169 | |
5a6d6fe6 | 170 | =head2 Subset selections |
0d003c52 | 171 | |
5a6d6fe6 RL |
172 | Sometimes, an object has more than one subset of data that is interesting to |
173 | treat separately or together. It's possible to specify what subsets are to | |
174 | be encoded, with a set of bits I<selection> that are passed in an B<int>. | |
0d003c52 | 175 | |
5a6d6fe6 RL |
176 | This set of bits depend entirely on what kind of provider-side object is |
177 | passed. For example, those bits are assumed to be the same as those used | |
178 | with L<provider-keymgmt(7)> (see L<provider-keymgmt(7)/Key Objects>) when | |
cd861ab7 | 179 | the object is an asymmetric keypair. |
0d003c52 | 180 | |
5a6d6fe6 RL |
181 | ENCODER implementations are free to regard the I<selection> as a set of |
182 | hints, but must do so with care. In the end, the output must make sense, | |
183 | and if there's a corresponding decoder, the resulting decoded object must | |
184 | match the original object that was encoded. | |
0d003c52 | 185 | |
cd861ab7 RL |
186 | OSSL_FUNC_encoder_does_selection() should tell if a particular implementation |
187 | supports any of the combinations given by I<selection>. | |
188 | ||
0d003c52 RL |
189 | =head2 Context functions |
190 | ||
ece9304c | 191 | OSSL_FUNC_encoder_newctx() returns a context to be used with the rest of |
0d003c52 RL |
192 | the functions. |
193 | ||
ece9304c RL |
194 | OSSL_FUNC_encoder_freectx() frees the given I<ctx>, if it was created by |
195 | OSSL_FUNC_encoder_newctx(). | |
0d003c52 | 196 | |
5a6d6fe6 RL |
197 | OSSL_FUNC_encoder_set_ctx_params() sets context data according to parameters |
198 | from I<params> that it recognises. Unrecognised parameters should be | |
199 | ignored. | |
f59612fe | 200 | Passing NULL for I<params> should return true. |
0d003c52 | 201 | |
ece9304c RL |
202 | OSSL_FUNC_encoder_settable_ctx_params() returns a constant B<OSSL_PARAM> |
203 | array describing the parameters that OSSL_FUNC_encoder_set_ctx_params() | |
0d003c52 RL |
204 | can handle. |
205 | ||
5a6d6fe6 RL |
206 | See L<OSSL_PARAM(3)> for further details on the parameters structure used by |
207 | OSSL_FUNC_encoder_set_ctx_params() and OSSL_FUNC_encoder_settable_ctx_params(). | |
208 | ||
209 | =head2 Import functions | |
210 | ||
211 | A provider-native object may be associated with a foreign provider, and may | |
212 | therefore be unsuitable for direct use with a given ENCODER implementation. | |
213 | Provided that the foreign provider's implementation to handle the object has | |
214 | a function to export that object in L<OSSL_PARAM(3)> array form, the ENCODER | |
215 | implementation should be able to import that array and create a suitable | |
216 | object to be passed to OSSL_FUNC_encoder_encode()'s I<obj_raw>. | |
217 | ||
218 | OSSL_FUNC_encoder_import_object() should import the subset of I<params> | |
219 | given with I<selection> to create a provider-native object that can be | |
220 | passed as I<obj_raw> to OSSL_FUNC_encoder_encode(). | |
221 | ||
222 | OSSL_FUNC_encoder_free_object() should free the object that was created with | |
223 | OSSL_FUNC_encoder_import_object(). | |
0d003c52 | 224 | |
ece9304c | 225 | =head2 Encoding functions |
0d003c52 | 226 | |
5a6d6fe6 RL |
227 | OSSL_FUNC_encoder_encode() should take an provider-native object (in |
228 | I<obj_raw>) or an object abstraction (in I<obj_abstract>), and should output | |
229 | the object in encoded form to the B<OSSL_CORE_BIO>. The I<selection> bits, | |
230 | if relevant, should determine in greater detail what will be output. | |
231 | The encoding functions also take an B<OSSL_PASSPHRASE_CALLBACK> function | |
232 | pointer along with a pointer to application data I<cbarg>, which should be | |
233 | used when a pass phrase prompt is needed. | |
0d003c52 | 234 | |
5a6d6fe6 | 235 | =head2 Encoder parameters |
0d003c52 | 236 | |
5a6d6fe6 RL |
237 | The ENCODER implementation itself has parameters that can be used to |
238 | determine how it fits in a chain of encoders: | |
0d003c52 | 239 | |
5a6d6fe6 RL |
240 | =over 4 |
241 | ||
242 | =item "input-type" (B<OSSL_ENCODER_PARAM_INPUT_TYPE>) <UTF8 string> | |
243 | ||
244 | This is used to specify a distinct type name for the object passed as | |
245 | I<obj_raw> to OSSL_FUNC_encoder_encode. | |
246 | ||
247 | This parameter is an optional parameter, to be used if the name of the | |
248 | implementation can be ambiguous because of aliases, and something more | |
249 | deterministic is needed. | |
250 | ||
251 | =item "output-type" (B<OSSL_ENCODER_PARAM_OUTPUT_TYPE>) <UTF8 string> | |
866234ac | 252 | |
5a6d6fe6 RL |
253 | This is used to specify the output type for an ENCODER implementation. |
254 | ||
255 | This parameter is I<mandatory>. | |
256 | ||
257 | =for comment If we had functionality to get the value of a specific property | |
258 | in a set of properties, it would be possible to determine the output type | |
259 | from the C<output> property. | |
260 | ||
8a98a507 RL |
261 | =item "output-structure" (B<OSSL_ENCODER_PARAM_OUTPUT_STRUCTURE>) <UTF8 string> |
262 | ||
263 | This is used to specify the outermost output structure for an ENCODER | |
264 | implementation. | |
265 | ||
266 | For example, an output of type "DER" for a key pair could be structured | |
267 | using PKCS#8, or a key type specific structure, such as PKCS#1 for RSA | |
268 | keys. | |
269 | ||
270 | =for comment If we had functionality to get the value of a specific property | |
271 | in a set of properties, it would be possible to determine the output | |
272 | structure from the C<structure> property. | |
273 | ||
5a6d6fe6 RL |
274 | =back |
275 | ||
276 | =head2 Encoder operation parameters | |
277 | ||
278 | Operation parameters currently recognised by built-in encoders are as | |
866234ac RL |
279 | follows: |
280 | ||
281 | =over 4 | |
282 | ||
ece9304c | 283 | =item "cipher" (B<OSSL_ENCODER_PARAM_CIPHER>) <UTF8 string> |
866234ac RL |
284 | |
285 | The name of the encryption cipher to be used when generating encrypted | |
ece9304c | 286 | encoding. This is used when encoding private keys, as well as |
866234ac RL |
287 | other objects that need protection. |
288 | ||
ece9304c RL |
289 | If this name is invalid for the encoding implementation, the |
290 | implementation should refuse to perform the encoding, i.e. | |
291 | OSSL_FUNC_encoder_encode_data() and OSSL_FUNC_encoder_encode_object() | |
866234ac RL |
292 | should return an error. |
293 | ||
ece9304c | 294 | =item "properties" (B<OSSL_ENCODER_PARAM_PROPERTIES>) <UTF8 string> |
866234ac RL |
295 | |
296 | The properties to be queried when trying to fetch the algorithm given | |
297 | with the "cipher" parameter. | |
298 | This must be given together with the "cipher" parameter to be | |
299 | considered valid. | |
300 | ||
ece9304c | 301 | The encoding implementation isn't obligated to use this value. |
866234ac RL |
302 | However, it is recommended that implementations that do not handle |
303 | property strings return an error on receiving this parameter unless | |
304 | its value NULL or the empty string. | |
305 | ||
78043fe8 TM |
306 | =item "save-parameters" (B<OSSL_ENCODER_PARAM_SAVE_PARAMETERS>) <integer> |
307 | ||
308 | If set to 0 disables saving of key domain parameters. Default is 1. | |
309 | It currently has an effect only on DSA keys. | |
310 | ||
866234ac RL |
311 | =back |
312 | ||
313 | Parameters currently recognised by the built-in pass phrase callback: | |
314 | ||
315 | =over 4 | |
316 | ||
317 | =item "info" (B<OSSL_PASSPHRASE_PARAM_INFO>) <UTF8 string> | |
318 | ||
319 | A string of information that will become part of the pass phrase | |
320 | prompt. This could be used to give the user information on what kind | |
321 | of object it's being prompted for. | |
322 | ||
323 | =back | |
324 | ||
0d003c52 RL |
325 | =head1 RETURN VALUES |
326 | ||
ece9304c | 327 | OSSL_FUNC_encoder_newctx() returns a pointer to a context, or NULL on |
0d003c52 RL |
328 | failure. |
329 | ||
ece9304c | 330 | OSSL_FUNC_encoder_set_ctx_params() returns 1, unless a recognised |
0d003c52 RL |
331 | parameters was invalid or caused an error, for which 0 is returned. |
332 | ||
ece9304c | 333 | OSSL_FUNC_encoder_settable_ctx_params() returns a pointer to an array of |
0d003c52 RL |
334 | constant B<OSSL_PARAM> elements. |
335 | ||
cd861ab7 RL |
336 | OSSL_FUNC_encoder_does_selection() returns 1 if the encoder implementation |
337 | supports any of the I<selection> bits, otherwise 0. | |
338 | ||
5a6d6fe6 | 339 | OSSL_FUNC_encoder_encode() return 1 on success, or 0 on failure. |
0d003c52 RL |
340 | |
341 | =head1 SEE ALSO | |
342 | ||
343 | L<provider(7)> | |
344 | ||
345 | =head1 HISTORY | |
346 | ||
ece9304c | 347 | The ENCODER interface was introduced in OpenSSL 3.0. |
0d003c52 RL |
348 | |
349 | =head1 COPYRIGHT | |
350 | ||
3c2bdd7d | 351 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. |
0d003c52 RL |
352 | |
353 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
354 | this file except in compliance with the License. You can obtain a copy | |
355 | in the file LICENSE in the source distribution or at | |
356 | L<https://www.openssl.org/source/license.html>. | |
357 | ||
358 | =cut |