]>
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 | |
261 | with the given I<keydata>, see L</Information Parameters>. | |
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 | |
271 | with the given I<keydata>, see L</Information Parameters>. | |
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 | ||
b03ec3b5 SL |
331 | =head2 Built-in DSA Key Generation Types |
332 | ||
333 | The following Key Generation types are available for the built-in DSA algorithm: | |
334 | ||
335 | =over 4 | |
336 | ||
337 | =item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer> | |
338 | ||
339 | Sets the DSA size (in bits) of the prime 'p'. | |
340 | The value should be 2048 or 3072. | |
341 | ||
342 | =item "qbits" (B<OSSL_PKEY_PARAM_FFC_QBITS>) <unsigned integer> | |
343 | ||
344 | Sets the DSA size (in bits) of the prime 'q'. | |
345 | The value should be 224 or 256. | |
346 | ||
347 | =item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <integer> | |
348 | ||
349 | Sets the type of parameter generation. | |
350 | Use 0 for FIPS186-4, or 1 for legacy FIPS186-2. | |
351 | The default is 0. | |
352 | ||
353 | =item "digest" (B<OSSL_PKEY_PARAM_FFC_DIGEST>) <utf8_string> | |
354 | ||
355 | Sets the Digest algorithm to be used as part of the Key Generation Function | |
356 | associated with the given Key Generation I<ctx>. | |
357 | ||
358 | =item "properties" (B<OSSL_PKEY_PARAM_FFC_DIGEST_PROPS>) <utf8_string> | |
359 | ||
360 | Sets properties to be used upon look up of the implementation for the selected | |
361 | Digest algorithm for the Key Generation Function associated with the given key | |
362 | Generation I<ctx>. | |
363 | ||
364 | =item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer> | |
365 | ||
366 | Sets the index to use for canonical generation and verification of the generator g. | |
367 | Set this to a positive value to use this mode. This I<index> can then be reused | |
368 | during key validation to verify the value of g. If this value is not set then | |
369 | g is not verifiable. The default value is -1. | |
370 | ||
371 | =item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet_string> | |
372 | ||
373 | Sets the I<seed> data to use instead of generating a random seed internally. | |
374 | This should be used for testing purposes only. This will either produced fixed | |
375 | values for the generated parameters OR it will fail if the seed did not | |
376 | generate valid primes. | |
377 | ||
378 | =back | |
379 | ||
380 | ||
8efc4a9c MC |
381 | =head2 Built-in RSA Import/Export Types |
382 | ||
383 | The following Import/Export types are available for the built-in RSA algorithm: | |
384 | ||
385 | =over 4 | |
386 | ||
b4dc705a | 387 | =item "n" (B<OSSL_PKEY_PARAM_RSA_N>) <unsigned integer> |
8efc4a9c MC |
388 | |
389 | The RSA "n" value. | |
390 | ||
b4dc705a | 391 | =item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <unsigned integer> |
8efc4a9c MC |
392 | |
393 | The RSA "e" value. | |
394 | ||
b4dc705a | 395 | =item "d" (B<OSSL_PKEY_PARAM_RSA_D>) <unsigned integer> |
8efc4a9c MC |
396 | |
397 | The RSA "d" value. | |
398 | ||
96ebe52e | 399 | =item "rsa-factor1" (B<OSSL_PKEY_PARAM_RSA_FACTOR1>) <unsigned integer> |
8efc4a9c | 400 | |
96ebe52e | 401 | =item "rsa-factor2" (B<OSSL_PKEY_PARAM_RSA_FACTOR2>) <unsigned integer> |
8efc4a9c | 402 | |
96ebe52e | 403 | =item "rsa-factor3" (B<OSSL_PKEY_PARAM_RSA_FACTOR3>) <unsigned integer> |
8efc4a9c | 404 | |
96ebe52e | 405 | =item "rsa-factor4" (B<OSSL_PKEY_PARAM_RSA_FACTOR4>) <unsigned integer> |
8efc4a9c | 406 | |
96ebe52e | 407 | =item "rsa-factor5" (B<OSSL_PKEY_PARAM_RSA_FACTOR5>) <unsigned integer> |
8efc4a9c | 408 | |
96ebe52e SL |
409 | =item "rsa-factor6" (B<OSSL_PKEY_PARAM_RSA_FACTOR6>) <unsigned integer> |
410 | ||
411 | =item "rsa-factor7" (B<OSSL_PKEY_PARAM_RSA_FACTOR7>) <unsigned integer> | |
412 | ||
413 | =item "rsa-factor8" (B<OSSL_PKEY_PARAM_RSA_FACTOR8>) <unsigned integer> | |
414 | ||
415 | =item "rsa-factor9" (B<OSSL_PKEY_PARAM_RSA_FACTOR9>) <unsigned integer> | |
416 | ||
417 | =item "rsa-factor10" (B<OSSL_PKEY_PARAM_RSA_FACTOR10>) <unsigned integer> | |
418 | ||
419 | RSA prime factors. The factors are known as "p", "q" and "r_i" in RFC8017. | |
420 | Up to eight additional "r_i" prime factors are supported. | |
421 | ||
422 | =item "rsa-exponent1" (B<OSSL_PKEY_PARAM_RSA_EXPONENT1>) <unsigned integer> | |
423 | ||
424 | =item "rsa-exponent2" (B<OSSL_PKEY_PARAM_RSA_EXPONENT2>) <unsigned integer> | |
425 | ||
426 | =item "rsa-exponent3" (B<OSSL_PKEY_PARAM_RSA_EXPONENT3>) <unsigned integer> | |
427 | ||
428 | =item "rsa-exponent4" (B<OSSL_PKEY_PARAM_RSA_EXPONENT4>) <unsigned integer> | |
429 | ||
430 | =item "rsa-exponent5" (B<OSSL_PKEY_PARAM_RSA_EXPONENT5>) <unsigned integer> | |
431 | ||
432 | =item "rsa-exponent6" (B<OSSL_PKEY_PARAM_RSA_EXPONENT6>) <unsigned integer> | |
433 | ||
434 | =item "rsa-exponent7" (B<OSSL_PKEY_PARAM_RSA_EXPONENT7>) <unsigned integer> | |
435 | ||
436 | =item "rsa-exponent8" (B<OSSL_PKEY_PARAM_RSA_EXPONENT8>) <unsigned integer> | |
437 | ||
438 | =item "rsa-exponent9" (B<OSSL_PKEY_PARAM_RSA_EXPONENT9>) <unsigned integer> | |
439 | ||
440 | =item "rsa-exponent10" (B<OSSL_PKEY_PARAM_RSA_EXPONENT10>) <unsigned integer> | |
441 | ||
442 | RSA CRT (Chinese Remainder Theorem) exponents. The exponents are known | |
443 | as "dP", "dQ" and "d_i in RFC8017". | |
444 | Up to eight additional "d_i" exponents are supported. | |
445 | ||
446 | =item "rsa-coefficient1" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT1>) <unsigned integer> | |
447 | ||
448 | =item "rsa-coefficient2" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT2>) <unsigned integer> | |
449 | ||
450 | =item "rsa-coefficient3" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT3>) <unsigned integer> | |
451 | ||
452 | =item "rsa-coefficient4" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT4>) <unsigned integer> | |
453 | ||
454 | =item "rsa-coefficient5" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT5>) <unsigned integer> | |
455 | ||
456 | =item "rsa-coefficient6" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT6>) <unsigned integer> | |
457 | ||
458 | =item "rsa-coefficient7" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT7>) <unsigned integer> | |
459 | ||
460 | =item "rsa-coefficient8" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT8>) <unsigned integer> | |
461 | ||
462 | =item "rsa-coefficient9" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT9>) <unsigned integer> | |
463 | ||
464 | RSA CRT (Chinese Remainder Theorem) coefficients. The coefficients are known as | |
465 | "qInv" and "t_i". | |
466 | Up to eight additional "t_i" exponents are supported. | |
8efc4a9c MC |
467 | |
468 | =back | |
469 | ||
470 | =head2 Built-in DSA and Diffie-Hellman Import/Export Types | |
471 | ||
472 | The following Import/Export types are available for the built-in DSA and | |
473 | Diffie-Hellman algorithms: | |
474 | ||
475 | =over 4 | |
476 | ||
b4dc705a | 477 | =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <unsigned integer> |
8efc4a9c MC |
478 | |
479 | The public key value. | |
480 | ||
b4dc705a | 481 | =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer> |
8efc4a9c MC |
482 | |
483 | The private key value. | |
484 | ||
b4dc705a | 485 | =item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <unsigned integer> |
8efc4a9c MC |
486 | |
487 | A DSA or Diffie-Hellman "p" value. | |
488 | ||
b4dc705a | 489 | =item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <unsigned integer> |
8efc4a9c MC |
490 | |
491 | A DSA or Diffie-Hellman "q" value. | |
492 | ||
b4dc705a | 493 | =item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer> |
8efc4a9c MC |
494 | |
495 | A DSA or Diffie-Hellman "g" value. | |
496 | ||
497 | =back | |
498 | ||
499 | =head2 Built-in X25519, X448, ED25519 and ED448 Import/Export Types | |
500 | ||
501 | The following Import/Export types are available for the built-in X25519, X448, | |
502 | ED25519 and X448 algorithms: | |
503 | ||
504 | =over 4 | |
505 | ||
506 | =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string> | |
507 | ||
508 | The public key value. | |
509 | ||
510 | =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string> | |
511 | ||
512 | The private key value. | |
513 | ||
514 | =back | |
515 | ||
f552d900 SL |
516 | =head2 Built-in EC Import/Export Types |
517 | ||
518 | The following Import/Export types are available for the built-in EC algorithm: | |
519 | ||
520 | =over 4 | |
521 | ||
522 | =item "curve-name" (B<OSSL_PKEY_PARAM_EC_NAME>) <utf8 string> | |
523 | ||
524 | The EC curve name. | |
525 | ||
526 | =item "use-cofactor-flag" (B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH>) <integer> | |
527 | ||
528 | Enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses normal EC DH | |
529 | if the value is zero. The cofactor variant multiplies the shared secret by the | |
530 | EC curve's cofactor (note for some curves the cofactor is 1). | |
531 | ||
532 | =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string> | |
533 | ||
534 | The public key value in EC point format. | |
535 | ||
b4dc705a | 536 | =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer> |
f552d900 SL |
537 | |
538 | The private key value. | |
539 | ||
540 | =back | |
541 | ||
6508e858 RL |
542 | =head2 Information Parameters |
543 | ||
544 | See L<OSSL_PARAM(3)> for further details on the parameters structure. | |
545 | ||
96ebe52e | 546 | The Built-in Import/Export Types listed above are also Information Parameters. |
ce82b892 NT |
547 | Not all parameters are relevant to, or are understood by all keymgmt |
548 | algorithms: | |
6508e858 | 549 | |
96ebe52e SL |
550 | Parameters currently recognised by built-in keymgmt algorithms |
551 | also include the following. | |
552 | ||
6508e858 RL |
553 | =over 4 |
554 | ||
555 | =item "bits" (B<OSSL_PKEY_PARAM_BITS>) <integer> | |
556 | ||
557 | The value should be the cryptographic length of the cryptosystem to | |
558 | which the key belongs, in bits. The definition of cryptographic | |
559 | length is specific to the key cryptosystem. | |
560 | ||
561 | =item "max-size" (B<OSSL_PKEY_PARAM_MAX_SIZE>) <integer> | |
562 | ||
563 | The value should be the maximum size that a caller should allocate to | |
564 | safely store a signature (called I<sig> in L<provider-signature(7)>), | |
565 | the result of asymmmetric encryption / decryption (I<out> in | |
566 | L<provider-asym_cipher(7)>, a derived secret (I<secret> in | |
567 | L<provider-keyexch(7)>, and similar data). | |
568 | ||
569 | Because an EVP_KEYMGMT method is always tightly bound to another method | |
570 | (signature, asymmetric cipher, key exchange, ...) and must be of the | |
571 | same provider, this number only needs to be synchronised with the | |
572 | dimensions handled in the rest of the same provider. | |
573 | ||
574 | =item "security-bits" (B<OSSL_PKEY_PARAM_SECURITY_BITS>) <integer> | |
575 | ||
576 | The value should be the number of security bits of the given key. | |
577 | Bits of security is defined in SP800-57. | |
578 | ||
ce82b892 NT |
579 | =item "use-cofactor-flag" (B<OSSL_PKEY_PARAM_USE_COFACTOR_FLAG>, |
580 | B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH>) <integer> | |
581 | ||
582 | The value should be either 1 or 0, to respectively enable or disable | |
583 | use of the cofactor in operations using this key. | |
584 | ||
585 | In the context of a key that can be used to perform an Elliptic Curve | |
586 | Diffie-Hellman key exchange, this parameter can be used to mark a requirement | |
587 | for using the Cofactor Diffie-Hellman (CDH) variant of the key exchange | |
588 | algorithm. | |
589 | ||
590 | See also L<provider-keyexch(7)> for the related | |
591 | B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a | |
592 | per-operation basis. | |
593 | ||
6508e858 RL |
594 | =back |
595 | ||
ce82b892 NT |
596 | =head1 RETURN VALUES |
597 | ||
598 | OP_keymgmt_new() should return a valid reference to the newly created provider | |
599 | side key object, or NULL on failure. | |
600 | ||
601 | OP_keymgmt_import(), OP_keymgmt_export(), OP_keymgmt_get_params() and | |
602 | OP_keymgmt_set_params() should return 1 for success or 0 on error. | |
603 | ||
604 | OP_keymgmt_validate() should return 1 on successful validation, or 0 on | |
605 | failure. | |
606 | ||
607 | OP_keymgmt_has() should return 1 if all the selected data subsets are contained | |
608 | in the given I<keydata> or 0 otherwise. | |
609 | ||
610 | OP_keymgmt_query_operation_name() should return a pointer to a string matching | |
611 | the requested operation, or NULL if the same name used to fetch the keymgmt | |
612 | applies. | |
613 | ||
614 | OP_keymgmt_gettable_params() and OP_keymgmt_settable_params() | |
615 | OP_keymgmt_import_types(), OP_keymgmt_export_types() | |
616 | should | |
617 | always return a constant B<OSSL_PARAM> array. | |
618 | ||
da2addc5 RL |
619 | =head1 SEE ALSO |
620 | ||
621 | L<provider(7)> | |
622 | ||
623 | =head1 HISTORY | |
624 | ||
625 | The KEYMGMT interface was introduced in OpenSSL 3.0. | |
626 | ||
627 | =head1 COPYRIGHT | |
628 | ||
12603de6 | 629 | Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. |
da2addc5 RL |
630 | |
631 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
632 | this file except in compliance with the License. You can obtain a copy | |
633 | in the file LICENSE in the source distribution or at | |
634 | L<https://www.openssl.org/source/license.html>. | |
635 | ||
636 | =cut |