]>
Commit | Line | Data |
---|---|---|
da2addc5 RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/core_numbers.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 | ||
b305452f RL |
17 | /* Key object (keydata) creation and destruction */ |
18 | void *OP_keymgmt_new(void *provctx); | |
19 | void OP_keymgmt_free(void *keydata); | |
da2addc5 | 20 | |
1a5632e0 RL |
21 | void *OP_keymgmt_gen_init(void *provctx, int selection); |
22 | int OP_keymgmt_gen_set_template(void *genctx, void *template); | |
23 | int OP_keymgmt_gen_set_params(void *genctx, const OSSL_PARAM params[]); | |
24 | const OSSL_PARAM *OP_keymgmt_gen_settable_params(void *provctx); | |
2b9add69 RL |
25 | int OP_keymgmt_gen_get_params(void *genctx, const OSSL_PARAM params[]); |
26 | const OSSL_PARAM *OP_keymgmt_gen_gettable_params(void *provctx); | |
1a5632e0 RL |
27 | void *OP_keymgmt_gen(void *genctx, OSSL_CALLBACK *cb, void *cbarg); |
28 | void OP_keymgmt_gen_cleanup(void *genctx); | |
29 | ||
b305452f RL |
30 | /* Key object information */ |
31 | int OP_keymgmt_get_params(void *keydata, OSSL_PARAM params[]); | |
32 | const OSSL_PARAM *OP_keymgmt_gettable_params(void); | |
ce82b892 NT |
33 | int OP_keymgmt_set_params(void *keydata, const OSSL_PARAM params[]); |
34 | const OSSL_PARAM *OP_keymgmt_settable_params(void); | |
da2addc5 | 35 | |
b305452f RL |
36 | /* Key object content checks */ |
37 | int OP_keymgmt_has(void *keydata, int selection); | |
bee5d6cd RL |
38 | int OP_keymgmt_match(const void *keydata1, const void *keydata2, |
39 | int selection); | |
da2addc5 | 40 | |
b305452f RL |
41 | /* Discovery of supported operations */ |
42 | const char *OP_keymgmt_query_operation_name(int operation_id); | |
da2addc5 | 43 | |
b305452f RL |
44 | /* Key object import and export functions */ |
45 | int OP_keymgmt_import(int selection, void *keydata, const OSSL_PARAM params[]); | |
ce82b892 | 46 | const OSSL_PARAM *OP_keymgmt_import_types(int selection); |
b305452f RL |
47 | int OP_keymgmt_export(int selection, void *keydata, |
48 | OSSL_CALLBACK *param_cb, void *cbarg); | |
49 | const OSSL_PARAM *OP_keymgmt_export_types(int selection); | |
6508e858 | 50 | |
13697f1c RL |
51 | /* Key object copy */ |
52 | int OP_keymgmt_copy(void *keydata_to, const void *keydata_from, int selection); | |
53 | ||
b305452f RL |
54 | /* Key object validation */ |
55 | int OP_keymgmt_validate(void *keydata, int selection); | |
12603de6 | 56 | |
da2addc5 RL |
57 | =head1 DESCRIPTION |
58 | ||
59 | The KEYMGMT operation doesn't have much public visibility in OpenSSL | |
60 | libraries, it's rather an internal operation that's designed to work | |
61 | in tandem with operations that use private/public key pairs. | |
62 | ||
63 | Because the KEYMGMT operation shares knowledge with the operations it | |
64 | works with in tandem, they must belong to the same provider. | |
65 | The OpenSSL libraries will ensure that they do. | |
66 | ||
67 | The primary responsibility of the KEYMGMT operation is to hold the | |
b305452f | 68 | provider side key data for the OpenSSL library EVP_PKEY structure. |
da2addc5 RL |
69 | |
70 | All "functions" mentioned here are passed as function pointers between | |
71 | F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via | |
72 | B<OSSL_ALGORITHM> arrays that are returned by the provider's | |
73 | provider_query_operation() function | |
74 | (see L<provider-base(7)/Provider Functions>). | |
75 | ||
76 | All these "functions" have a corresponding function type definition | |
77 | named B<OSSL_{name}_fn>, and a helper function to retrieve the | |
78 | function pointer from a B<OSSL_DISPATCH> element named | |
79 | B<OSSL_get_{name}>. | |
b305452f | 80 | For example, the "function" OP_keymgmt_new() has these: |
da2addc5 | 81 | |
b305452f RL |
82 | typedef void *(OSSL_OP_keymgmt_new_fn)(void *provctx); |
83 | static ossl_inline OSSL_OP_keymgmt_new_fn | |
84 | OSSL_get_OP_keymgmt_new(const OSSL_DISPATCH *opf); | |
da2addc5 RL |
85 | |
86 | B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as | |
87 | macros in L<openssl-core_numbers.h(7)>, as follows: | |
88 | ||
b305452f RL |
89 | OP_keymgmt_new OSSL_FUNC_KEYMGMT_NEW |
90 | OP_keymgmt_free OSSL_FUNC_KEYMGMT_FREE | |
91 | ||
1a5632e0 RL |
92 | OP_keymgmt_gen_init OSSL_FUNC_KEYMGMT_GEN_INIT |
93 | OP_keymgmt_gen_set_template OSSL_FUNC_KEYMGMT_GEN_SET_TEMPLATE | |
94 | OP_keymgmt_gen_set_params OSSL_FUNC_KEYMGMT_GEN_SET_PARAMS | |
95 | OP_keymgmt_gen_settable_params OSSL_FUNC_KEYMGMT_GEN_SETTABLE_PARAMS | |
2b9add69 RL |
96 | OP_keymgmt_gen_get_params OSSL_FUNC_KEYMGMT_GEN_GET_PARAMS |
97 | OP_keymgmt_gen_gettable_params OSSL_FUNC_KEYMGMT_GEN_GETTABLE_PARAMS | |
1a5632e0 RL |
98 | OP_keymgmt_gen OSSL_FUNC_KEYMGMT_GEN |
99 | OP_keymgmt_gen_cleanup OSSL_FUNC_KEYMGMT_GEN_CLEANUP | |
100 | ||
b305452f RL |
101 | OP_keymgmt_get_params OSSL_FUNC_KEYMGMT_GET_PARAMS |
102 | OP_keymgmt_gettable_params OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS | |
ce82b892 NT |
103 | OP_keymgmt_set_params OSSL_FUNC_KEYMGMT_SET_PARAMS |
104 | OP_keymgmt_settable_params OSSL_FUNC_KEYMGMT_SETTABLE_PARAMS | |
6508e858 RL |
105 | |
106 | OP_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME | |
da2addc5 | 107 | |
b305452f RL |
108 | OP_keymgmt_has OSSL_FUNC_KEYMGMT_HAS |
109 | OP_keymgmt_validate OSSL_FUNC_KEYMGMT_VALIDATE | |
bee5d6cd | 110 | OP_keymgmt_match OSSL_FUNC_KEYMGMT_MATCH |
12603de6 | 111 | |
b305452f RL |
112 | OP_keymgmt_import OSSL_FUNC_KEYMGMT_IMPORT |
113 | OP_keymgmt_import_types OSSL_FUNC_KEYMGMT_IMPORT_TYPES | |
114 | OP_keymgmt_export OSSL_FUNC_KEYMGMT_EXPORT | |
115 | OP_keymgmt_export_types OSSL_FUNC_KEYMGMT_EXPORT_TYPES | |
da2addc5 | 116 | |
13697f1c | 117 | OP_keymgmt_copy OSSL_FUNC_KEYMGMT_COPY |
da2addc5 | 118 | |
b305452f | 119 | =head2 Key Objects |
da2addc5 | 120 | |
b305452f RL |
121 | A key object is a collection of data for an asymmetric key, and is |
122 | represented as I<keydata> in this manual. | |
da2addc5 | 123 | |
b305452f RL |
124 | The exact contents of a key object are defined by the provider, and it |
125 | is assumed that different operations in one and the same provider use | |
126 | the exact same structure to represent this collection of data, so that | |
127 | for example, a key object that has been created using the KEYMGMT | |
128 | interface that we document here can be passed as is to other provider | |
129 | operations, such as OP_signature_sign_init() (see | |
130 | L<provider-signature(7)>). | |
da2addc5 | 131 | |
b305452f RL |
132 | With some of the KEYMGMT functions, it's possible to select a specific |
133 | subset of data to handle, governed by the bits in a I<selection> | |
134 | indicator. The bits are: | |
da2addc5 | 135 | |
b305452f | 136 | =over 4 |
da2addc5 | 137 | |
b305452f | 138 | =item B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> |
6508e858 | 139 | |
b305452f RL |
140 | Indicating that the private key data in a key object should be |
141 | considered. | |
6508e858 | 142 | |
b305452f | 143 | =item B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY> |
12603de6 | 144 | |
b305452f RL |
145 | Indicating that the public key data in a key object should be |
146 | considered. | |
da2addc5 | 147 | |
b305452f | 148 | =item B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> |
da2addc5 | 149 | |
b305452f RL |
150 | Indicating that the domain parameters in a key object should be |
151 | considered. | |
da2addc5 | 152 | |
b305452f | 153 | =item B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS> |
da2addc5 | 154 | |
b305452f RL |
155 | Indicating that other parameters in a key object should be |
156 | considered. | |
da2addc5 | 157 | |
b305452f RL |
158 | Other parameters are key parameters that don't fit any other |
159 | classification. In other words, this particular selector bit works as | |
160 | a last resort bit bucket selector. | |
da2addc5 | 161 | |
b305452f | 162 | =back |
da2addc5 | 163 | |
b305452f RL |
164 | Some selector bits have also been combined for easier use: |
165 | ||
166 | =over 4 | |
167 | ||
168 | =item B<OSSL_KEYMGMT_SELECT_ALL_PARAMETERS> | |
169 | ||
170 | Indicating that all key object parameters should be considered, | |
171 | regardless of their more granular classification. | |
172 | ||
173 | =for comment This should used by EVP functions such as | |
174 | EVP_PKEY_copy_parameters() and EVP_PKEY_cmp_parameters() | |
175 | ||
176 | This is a combination of B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> and | |
177 | B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>. | |
178 | ||
179 | =for comment If more parameter categories are added, they should be | |
180 | mentioned here too. | |
181 | ||
182 | =item B<OSSL_KEYMGMT_SELECT_KEYPAIR> | |
183 | ||
184 | Indicating that both the whole key pair in a key object should be | |
185 | considered, i.e. the combination of public and private key. | |
da2addc5 | 186 | |
b305452f RL |
187 | This is a combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and |
188 | B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY>. | |
da2addc5 | 189 | |
b305452f | 190 | =item B<OSSL_KEYMGMT_SELECT_ALL> |
6508e858 | 191 | |
b305452f | 192 | Indicating that everything in a key object should be considered. |
6508e858 | 193 | |
b305452f | 194 | =back |
12603de6 | 195 | |
b305452f RL |
196 | The exact interpretation of those bits or how they combine is left to |
197 | each function where you can specify a selector. | |
12603de6 | 198 | |
b305452f RL |
199 | =for comment One might think that a combination of bits means that all |
200 | the selected data subsets must be considered, but then you have to | |
201 | consider that when comparing key objects (future function), an | |
202 | implementation might opt to not compare the private key if it has | |
203 | compared the public key, since a match of one half implies a match of | |
204 | the other half. | |
205 | ||
206 | =head2 Constructing and Destructing Functions | |
207 | ||
208 | OP_keymgmt_new() should create a provider side key object. The | |
209 | provider context I<provctx> is passed and may be incorporated in the | |
210 | key object, but that is not mandatory. | |
211 | ||
212 | OP_keymgmt_free() should free the passed I<keydata>. | |
213 | ||
1a5632e0 RL |
214 | OP_keymgmt_gen_init(), OP_keymgmt_gen_set_template(), |
215 | OP_keymgmt_gen_set_params(), OP_keymgmt_gen_settable_params(), | |
2b9add69 | 216 | OP_keymgmt_gen_get_params(), OP_keymgmt_gen_gettable_params(), |
1a5632e0 RL |
217 | OP_keymgmt_gen() and OP_keymgmt_gen_cleanup() work together as a more |
218 | elaborate context based key object constructor. | |
219 | ||
220 | OP_keymgmt_gen_init() should create the key object generation context | |
221 | and initialize it with I<selections>, which will determine what kind | |
222 | of contents the key object to be generated should get. | |
223 | ||
224 | OP_keymgmt_gen_set_template() should add I<template> to the context | |
225 | I<genctx>. The I<template> is assumed to be a key object constructed | |
226 | with the same KEYMGMT, and from which content that the implementation | |
227 | chooses can be used as a template for the key object to be generated. | |
228 | Typically, the generation of a DSA or DH key would get the domain | |
229 | parameters from this I<template>. | |
230 | ||
231 | OP_keymgmt_gen_set_params() should set additional parameters from | |
232 | I<params> in the key object generation context I<genctx>. | |
233 | ||
234 | OP_keymgmt_gen_settable_params() should return a constant array of | |
235 | descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_gen_set_params() | |
236 | can handle. | |
237 | ||
2b9add69 RL |
238 | OP_keymgmt_gen_get_params() should extract information data associated |
239 | with the key object generation context I<genctx>. | |
240 | ||
241 | OP_keymgmt_gen_gettable_params() should return a constant array of | |
242 | descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_gen_get_params() | |
243 | can handle. | |
244 | ||
1a5632e0 RL |
245 | OP_keymgmt_gen() should perform the key object generation itself, and |
246 | return the result. The callback I<cb> should be called at regular | |
247 | intervals with indications on how the key object generation | |
248 | progresses. | |
249 | ||
250 | OP_keymgmt_gen_cleanup() should clean up and free the key object | |
251 | generation context I<genctx> | |
b305452f | 252 | |
1a5632e0 RL |
253 | At least one of OP_keymgmt_new() and OP_keymgmt_gen() are mandatory, |
254 | as well as OP_keymgmt_free(). Additionally, if OP_keymgmt_gen() is | |
255 | present, OP_keymgmt_gen_init() and OP_keymgmt_gen_cleanup() must be | |
256 | present as well. | |
b305452f RL |
257 | |
258 | =head2 Key Object Information Functions | |
259 | ||
260 | OP_keymgmt_get_params() should extract information data associated | |
33df1cfd | 261 | with the given I<keydata>, see L</Common Information Parameters>. |
b305452f RL |
262 | |
263 | OP_keymgmt_gettable_params() should return a constant array of | |
264 | descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_get_params() | |
265 | can handle. | |
266 | ||
267 | If OP_keymgmt_gettable_params() is present, OP_keymgmt_get_params() | |
ce82b892 NT |
268 | must also be present, and vice versa. |
269 | ||
270 | OP_keymgmt_set_params() should update information data associated | |
33df1cfd | 271 | with the given I<keydata>, see L</Common Information Parameters>. |
ce82b892 NT |
272 | |
273 | OP_keymgmt_settable_params() should return a constant array of | |
274 | descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_set_params() | |
275 | can handle. | |
276 | ||
277 | If OP_keymgmt_settable_params() is present, OP_keymgmt_set_params() | |
278 | must also be present, and vice versa. | |
b305452f RL |
279 | |
280 | =head2 Key Object Checking Functions | |
e62a45b6 RL |
281 | |
282 | OP_keymgmt_query_operation_name() should return the name of the | |
283 | supported algorithm for the operation I<operation_id>. This is | |
284 | similar to provider_query_operation() (see L<provider-base(7)>), | |
285 | but only works as an advisory. If this function is not present, or | |
286 | returns NULL, the caller is free to assume that there's an algorithm | |
287 | from the same provider, of the same name as the one used to fetch the | |
288 | keymgmt and try to use that. | |
289 | ||
ce82b892 | 290 | OP_keymgmt_has() should check whether the given I<keydata> contains the subsets |
b305452f RL |
291 | of data indicated by the I<selector>. A combination of several |
292 | selector bits must consider all those subsets, not just one. An | |
293 | implementation is, however, free to consider an empty subset of data | |
294 | to still be a valid subset. | |
295 | ||
296 | OP_keymgmt_validate() should check if the I<keydata> contains valid | |
297 | data subsets indicated by I<selection>. Some combined selections of | |
298 | data subsets may cause validation of the combined data. | |
299 | For example, the combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and | |
300 | B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY> (or B<OSSL_KEYMGMT_SELECT_KEYPAIR> | |
301 | for short) is expected to check that the pairwise consistency of | |
302 | I<keydata> is valid. | |
303 | ||
bee5d6cd RL |
304 | OP_keymgmt_match() should check if the data subset indicated by |
305 | I<selection> in I<keydata1> and I<keydata2> match. It is assumed that | |
306 | the caller has ensured that I<keydata1> and I<keydata2> are both owned | |
307 | by the implementation of this function. | |
308 | ||
13697f1c | 309 | =head2 Key Object Import, Export and Copy Functions |
b305452f RL |
310 | |
311 | OP_keymgmt_import() should import data indicated by I<selection> into | |
312 | I<keydata> with values taken from the B<OSSL_PARAM> array I<params>. | |
313 | ||
314 | OP_keymgmt_export() should extract values indicated by I<selection> | |
315 | from I<keydata>, create an B<OSSL_PARAM> array with them and call | |
316 | I<param_cb> with that array as well as the given I<cbarg>. | |
317 | ||
318 | OP_keymgmt_import_types() should return a constant array of descriptor | |
319 | B<OSSL_PARAM> for data indicated by I<selection>, for parameters that | |
320 | OP_keymgmt_import() can handle. | |
321 | ||
322 | OP_keymgmt_export_types() should return a constant array of descriptor | |
323 | B<OSSL_PARAM> for data indicated by I<selection>, that the | |
324 | OP_keymgmt_export() callback can expect to receive. | |
325 | ||
13697f1c RL |
326 | OP_keymgmt_copy() should copy data subsets indicated by I<selection> |
327 | from I<keydata_from> to I<keydata_to>. It is assumed that the caller | |
328 | has ensured that I<keydata_to> and I<keydata_from> are both owned by | |
329 | the implementation of this function. | |
330 | ||
33df1cfd | 331 | =head2 Common Information Parameters |
6508e858 RL |
332 | |
333 | See L<OSSL_PARAM(3)> for further details on the parameters structure. | |
334 | ||
33df1cfd RL |
335 | Common information parameters currently recognised by all built-in |
336 | keymgmt algorithms are as follows: | |
96ebe52e | 337 | |
6508e858 RL |
338 | =over 4 |
339 | ||
340 | =item "bits" (B<OSSL_PKEY_PARAM_BITS>) <integer> | |
341 | ||
342 | The value should be the cryptographic length of the cryptosystem to | |
343 | which the key belongs, in bits. The definition of cryptographic | |
344 | length is specific to the key cryptosystem. | |
345 | ||
346 | =item "max-size" (B<OSSL_PKEY_PARAM_MAX_SIZE>) <integer> | |
347 | ||
348 | The value should be the maximum size that a caller should allocate to | |
349 | safely store a signature (called I<sig> in L<provider-signature(7)>), | |
350 | the result of asymmmetric encryption / decryption (I<out> in | |
351 | L<provider-asym_cipher(7)>, a derived secret (I<secret> in | |
352 | L<provider-keyexch(7)>, and similar data). | |
353 | ||
354 | Because an EVP_KEYMGMT method is always tightly bound to another method | |
355 | (signature, asymmetric cipher, key exchange, ...) and must be of the | |
356 | same provider, this number only needs to be synchronised with the | |
357 | dimensions handled in the rest of the same provider. | |
358 | ||
359 | =item "security-bits" (B<OSSL_PKEY_PARAM_SECURITY_BITS>) <integer> | |
360 | ||
361 | The value should be the number of security bits of the given key. | |
362 | Bits of security is defined in SP800-57. | |
363 | ||
364 | =back | |
365 | ||
ce82b892 NT |
366 | =head1 RETURN VALUES |
367 | ||
368 | OP_keymgmt_new() should return a valid reference to the newly created provider | |
369 | side key object, or NULL on failure. | |
370 | ||
371 | OP_keymgmt_import(), OP_keymgmt_export(), OP_keymgmt_get_params() and | |
372 | OP_keymgmt_set_params() should return 1 for success or 0 on error. | |
373 | ||
374 | OP_keymgmt_validate() should return 1 on successful validation, or 0 on | |
375 | failure. | |
376 | ||
377 | OP_keymgmt_has() should return 1 if all the selected data subsets are contained | |
378 | in the given I<keydata> or 0 otherwise. | |
379 | ||
380 | OP_keymgmt_query_operation_name() should return a pointer to a string matching | |
381 | the requested operation, or NULL if the same name used to fetch the keymgmt | |
382 | applies. | |
383 | ||
384 | OP_keymgmt_gettable_params() and OP_keymgmt_settable_params() | |
385 | OP_keymgmt_import_types(), OP_keymgmt_export_types() | |
386 | should | |
387 | always return a constant B<OSSL_PARAM> array. | |
388 | ||
da2addc5 RL |
389 | =head1 SEE ALSO |
390 | ||
33df1cfd RL |
391 | L<provider(7)>, |
392 | L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>, L<EVP_PKEY-ED25519(7)>, | |
393 | L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-EC(7)>, L<EVP_PKEY-RSA(7)>, | |
394 | L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)> | |
da2addc5 RL |
395 | |
396 | =head1 HISTORY | |
397 | ||
398 | The KEYMGMT interface was introduced in OpenSSL 3.0. | |
399 | ||
400 | =head1 COPYRIGHT | |
401 | ||
12603de6 | 402 | Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. |
da2addc5 RL |
403 | |
404 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
405 | this file except in compliance with the License. You can obtain a copy | |
406 | in the file LICENSE in the source distribution or at | |
407 | L<https://www.openssl.org/source/license.html>. | |
408 | ||
409 | =cut |