]>
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 | ||
23c48d94 | 9 | #include <openssl/core_dispatch.h> |
da2addc5 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 | ||
b305452f | 17 | /* Key object (keydata) creation and destruction */ |
363b1e5d DMSP |
18 | void *OSSL_FUNC_keymgmt_new(void *provctx); |
19 | void OSSL_FUNC_keymgmt_free(void *keydata); | |
da2addc5 | 20 | |
5dacb38c | 21 | /* Generation, a more complex constructor */ |
c4c422e0 P |
22 | void *OSSL_FUNC_keymgmt_gen_init(void *provctx, int selection, |
23 | const OSSL_PARAM params[]); | |
363b1e5d DMSP |
24 | int OSSL_FUNC_keymgmt_gen_set_template(void *genctx, void *template); |
25 | int OSSL_FUNC_keymgmt_gen_set_params(void *genctx, const OSSL_PARAM params[]); | |
fb67126e TM |
26 | const OSSL_PARAM *OSSL_FUNC_keymgmt_gen_settable_params(void *genctx, |
27 | void *provctx); | |
363b1e5d DMSP |
28 | void *OSSL_FUNC_keymgmt_gen(void *genctx, OSSL_CALLBACK *cb, void *cbarg); |
29 | void OSSL_FUNC_keymgmt_gen_cleanup(void *genctx); | |
1a5632e0 | 30 | |
5dacb38c RL |
31 | /* Key loading by object reference, also a constructor */ |
32 | void *OSSL_FUNC_keymgmt_load(const void *reference, size_t *reference_sz); | |
33 | ||
b305452f | 34 | /* Key object information */ |
363b1e5d | 35 | int OSSL_FUNC_keymgmt_get_params(void *keydata, OSSL_PARAM params[]); |
992492f5 | 36 | const OSSL_PARAM *OSSL_FUNC_keymgmt_gettable_params(void *provctx); |
363b1e5d | 37 | int OSSL_FUNC_keymgmt_set_params(void *keydata, const OSSL_PARAM params[]); |
992492f5 | 38 | const OSSL_PARAM *OSSL_FUNC_keymgmt_settable_params(void *provctx); |
da2addc5 | 39 | |
b305452f | 40 | /* Key object content checks */ |
3d914185 | 41 | int OSSL_FUNC_keymgmt_has(const void *keydata, int selection); |
363b1e5d DMSP |
42 | int OSSL_FUNC_keymgmt_match(const void *keydata1, const void *keydata2, |
43 | int selection); | |
da2addc5 | 44 | |
b305452f | 45 | /* Discovery of supported operations */ |
363b1e5d | 46 | const char *OSSL_FUNC_keymgmt_query_operation_name(int operation_id); |
da2addc5 | 47 | |
b305452f | 48 | /* Key object import and export functions */ |
70ed3046 | 49 | int OSSL_FUNC_keymgmt_import(void *keydata, int selection, const OSSL_PARAM params[]); |
363b1e5d | 50 | const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types(int selection); |
5e3b8450 | 51 | const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types_ex(void *provctx, int selection); |
70ed3046 | 52 | int OSSL_FUNC_keymgmt_export(void *keydata, int selection, |
363b1e5d DMSP |
53 | OSSL_CALLBACK *param_cb, void *cbarg); |
54 | const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types(int selection); | |
5e3b8450 | 55 | const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types_ex(void *provctx, int selection); |
6508e858 | 56 | |
4a9fe33c | 57 | /* Key object duplication, a constructor */ |
b4f447c0 | 58 | void *OSSL_FUNC_keymgmt_dup(const void *keydata_from, int selection); |
4a9fe33c | 59 | |
b305452f | 60 | /* Key object validation */ |
899e2564 | 61 | int OSSL_FUNC_keymgmt_validate(const void *keydata, int selection, int checktype); |
12603de6 | 62 | |
da2addc5 RL |
63 | =head1 DESCRIPTION |
64 | ||
65 | The KEYMGMT operation doesn't have much public visibility in OpenSSL | |
66 | libraries, it's rather an internal operation that's designed to work | |
67 | in tandem with operations that use private/public key pairs. | |
68 | ||
69 | Because the KEYMGMT operation shares knowledge with the operations it | |
70 | works with in tandem, they must belong to the same provider. | |
71 | The OpenSSL libraries will ensure that they do. | |
72 | ||
73 | The primary responsibility of the KEYMGMT operation is to hold the | |
b305452f | 74 | provider side key data for the OpenSSL library EVP_PKEY structure. |
da2addc5 RL |
75 | |
76 | All "functions" mentioned here are passed as function pointers between | |
318a9dfa RL |
77 | F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays via |
78 | L<OSSL_ALGORITHM(3)> arrays that are returned by the provider's | |
da2addc5 RL |
79 | provider_query_operation() function |
80 | (see L<provider-base(7)/Provider Functions>). | |
81 | ||
82 | All these "functions" have a corresponding function type definition | |
bd6e7fb7 | 83 | named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the |
318a9dfa | 84 | function pointer from a L<OSSL_DISPATCH(3)> element named |
363b1e5d DMSP |
85 | B<OSSL_FUNC_{name}>. |
86 | For example, the "function" OSSL_FUNC_keymgmt_new() has these: | |
da2addc5 | 87 | |
363b1e5d DMSP |
88 | typedef void *(OSSL_FUNC_keymgmt_new_fn)(void *provctx); |
89 | static ossl_inline OSSL_FUNC_keymgmt_new_fn | |
90 | OSSL_FUNC_keymgmt_new(const OSSL_DISPATCH *opf); | |
da2addc5 | 91 | |
318a9dfa | 92 | L<OSSL_DISPATCH(3)> arrays are indexed by numbers that are provided as |
23c48d94 | 93 | macros in L<openssl-core_dispatch.h(7)>, as follows: |
da2addc5 | 94 | |
363b1e5d DMSP |
95 | OSSL_FUNC_keymgmt_new OSSL_FUNC_KEYMGMT_NEW |
96 | OSSL_FUNC_keymgmt_free OSSL_FUNC_KEYMGMT_FREE | |
b305452f | 97 | |
363b1e5d DMSP |
98 | OSSL_FUNC_keymgmt_gen_init OSSL_FUNC_KEYMGMT_GEN_INIT |
99 | OSSL_FUNC_keymgmt_gen_set_template OSSL_FUNC_KEYMGMT_GEN_SET_TEMPLATE | |
100 | OSSL_FUNC_keymgmt_gen_set_params OSSL_FUNC_KEYMGMT_GEN_SET_PARAMS | |
101 | OSSL_FUNC_keymgmt_gen_settable_params OSSL_FUNC_KEYMGMT_GEN_SETTABLE_PARAMS | |
102 | OSSL_FUNC_keymgmt_gen OSSL_FUNC_KEYMGMT_GEN | |
103 | OSSL_FUNC_keymgmt_gen_cleanup OSSL_FUNC_KEYMGMT_GEN_CLEANUP | |
1a5632e0 | 104 | |
5dacb38c RL |
105 | OSSL_FUNC_keymgmt_load OSSL_FUNC_KEYMGMT_LOAD |
106 | ||
363b1e5d DMSP |
107 | OSSL_FUNC_keymgmt_get_params OSSL_FUNC_KEYMGMT_GET_PARAMS |
108 | OSSL_FUNC_keymgmt_gettable_params OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS | |
109 | OSSL_FUNC_keymgmt_set_params OSSL_FUNC_KEYMGMT_SET_PARAMS | |
110 | OSSL_FUNC_keymgmt_settable_params OSSL_FUNC_KEYMGMT_SETTABLE_PARAMS | |
6508e858 | 111 | |
363b1e5d | 112 | OSSL_FUNC_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME |
da2addc5 | 113 | |
363b1e5d DMSP |
114 | OSSL_FUNC_keymgmt_has OSSL_FUNC_KEYMGMT_HAS |
115 | OSSL_FUNC_keymgmt_validate OSSL_FUNC_KEYMGMT_VALIDATE | |
116 | OSSL_FUNC_keymgmt_match OSSL_FUNC_KEYMGMT_MATCH | |
12603de6 | 117 | |
363b1e5d DMSP |
118 | OSSL_FUNC_keymgmt_import OSSL_FUNC_KEYMGMT_IMPORT |
119 | OSSL_FUNC_keymgmt_import_types OSSL_FUNC_KEYMGMT_IMPORT_TYPES | |
5e3b8450 | 120 | OSSL_FUNC_keymgmt_import_types_ex OSSL_FUNC_KEYMGMT_IMPORT_TYPES_EX |
363b1e5d DMSP |
121 | OSSL_FUNC_keymgmt_export OSSL_FUNC_KEYMGMT_EXPORT |
122 | OSSL_FUNC_keymgmt_export_types OSSL_FUNC_KEYMGMT_EXPORT_TYPES | |
5e3b8450 | 123 | OSSL_FUNC_keymgmt_export_types_ex OSSL_FUNC_KEYMGMT_EXPORT_TYPES_EX |
da2addc5 | 124 | |
4a9fe33c | 125 | OSSL_FUNC_keymgmt_dup OSSL_FUNC_KEYMGMT_DUP |
da2addc5 | 126 | |
b305452f | 127 | =head2 Key Objects |
da2addc5 | 128 | |
b305452f RL |
129 | A key object is a collection of data for an asymmetric key, and is |
130 | represented as I<keydata> in this manual. | |
da2addc5 | 131 | |
b305452f RL |
132 | The exact contents of a key object are defined by the provider, and it |
133 | is assumed that different operations in one and the same provider use | |
134 | the exact same structure to represent this collection of data, so that | |
135 | for example, a key object that has been created using the KEYMGMT | |
136 | interface that we document here can be passed as is to other provider | |
137 | operations, such as OP_signature_sign_init() (see | |
138 | L<provider-signature(7)>). | |
da2addc5 | 139 | |
b305452f RL |
140 | With some of the KEYMGMT functions, it's possible to select a specific |
141 | subset of data to handle, governed by the bits in a I<selection> | |
142 | indicator. The bits are: | |
da2addc5 | 143 | |
b305452f | 144 | =over 4 |
da2addc5 | 145 | |
b305452f | 146 | =item B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> |
6508e858 | 147 | |
b305452f RL |
148 | Indicating that the private key data in a key object should be |
149 | considered. | |
6508e858 | 150 | |
b305452f | 151 | =item B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY> |
12603de6 | 152 | |
b305452f RL |
153 | Indicating that the public key data in a key object should be |
154 | considered. | |
da2addc5 | 155 | |
b305452f | 156 | =item B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> |
da2addc5 | 157 | |
b305452f RL |
158 | Indicating that the domain parameters in a key object should be |
159 | considered. | |
da2addc5 | 160 | |
b305452f | 161 | =item B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS> |
da2addc5 | 162 | |
b305452f RL |
163 | Indicating that other parameters in a key object should be |
164 | considered. | |
da2addc5 | 165 | |
b305452f RL |
166 | Other parameters are key parameters that don't fit any other |
167 | classification. In other words, this particular selector bit works as | |
168 | a last resort bit bucket selector. | |
da2addc5 | 169 | |
b305452f | 170 | =back |
da2addc5 | 171 | |
b305452f RL |
172 | Some selector bits have also been combined for easier use: |
173 | ||
174 | =over 4 | |
175 | ||
176 | =item B<OSSL_KEYMGMT_SELECT_ALL_PARAMETERS> | |
177 | ||
178 | Indicating that all key object parameters should be considered, | |
179 | regardless of their more granular classification. | |
180 | ||
181 | =for comment This should used by EVP functions such as | |
c85c5e1a | 182 | EVP_PKEY_copy_parameters() and EVP_PKEY_parameters_eq() |
b305452f RL |
183 | |
184 | This is a combination of B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> and | |
185 | B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>. | |
186 | ||
187 | =for comment If more parameter categories are added, they should be | |
188 | mentioned here too. | |
189 | ||
190 | =item B<OSSL_KEYMGMT_SELECT_KEYPAIR> | |
191 | ||
192 | Indicating that both the whole key pair in a key object should be | |
193 | considered, i.e. the combination of public and private key. | |
da2addc5 | 194 | |
b305452f RL |
195 | This is a combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and |
196 | B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY>. | |
da2addc5 | 197 | |
b305452f | 198 | =item B<OSSL_KEYMGMT_SELECT_ALL> |
6508e858 | 199 | |
b305452f | 200 | Indicating that everything in a key object should be considered. |
6508e858 | 201 | |
b305452f | 202 | =back |
12603de6 | 203 | |
b305452f RL |
204 | The exact interpretation of those bits or how they combine is left to |
205 | each function where you can specify a selector. | |
12603de6 | 206 | |
e67254e4 RL |
207 | It's left to the provider implementation to decide what is reasonable |
208 | to do with regards to received selector bits and how to do it. | |
209 | Among others, an implementation of OSSL_FUNC_keymgmt_match() might opt | |
210 | to not compare the private half if it has compared the public half, | |
211 | since a match of one half implies a match of the other half. | |
b305452f RL |
212 | |
213 | =head2 Constructing and Destructing Functions | |
214 | ||
363b1e5d | 215 | OSSL_FUNC_keymgmt_new() should create a provider side key object. The |
b305452f RL |
216 | provider context I<provctx> is passed and may be incorporated in the |
217 | key object, but that is not mandatory. | |
218 | ||
363b1e5d | 219 | OSSL_FUNC_keymgmt_free() should free the passed I<keydata>. |
b305452f | 220 | |
363b1e5d DMSP |
221 | OSSL_FUNC_keymgmt_gen_init(), OSSL_FUNC_keymgmt_gen_set_template(), |
222 | OSSL_FUNC_keymgmt_gen_set_params(), OSSL_FUNC_keymgmt_gen_settable_params(), | |
5dacb38c RL |
223 | OSSL_FUNC_keymgmt_gen() and OSSL_FUNC_keymgmt_gen_cleanup() work together as a |
224 | more elaborate context based key object constructor. | |
1a5632e0 | 225 | |
363b1e5d | 226 | OSSL_FUNC_keymgmt_gen_init() should create the key object generation context |
1a5632e0 | 227 | and initialize it with I<selections>, which will determine what kind |
f187d4f9 P |
228 | of contents the key object to be generated should get. |
229 | The I<params>, if not NULL, should be set on the context in a manner similar to | |
230 | using OSSL_FUNC_keymgmt_set_params(). | |
1a5632e0 | 231 | |
363b1e5d | 232 | OSSL_FUNC_keymgmt_gen_set_template() should add I<template> to the context |
1a5632e0 RL |
233 | I<genctx>. The I<template> is assumed to be a key object constructed |
234 | with the same KEYMGMT, and from which content that the implementation | |
235 | chooses can be used as a template for the key object to be generated. | |
236 | Typically, the generation of a DSA or DH key would get the domain | |
237 | parameters from this I<template>. | |
238 | ||
363b1e5d | 239 | OSSL_FUNC_keymgmt_gen_set_params() should set additional parameters from |
1a5632e0 RL |
240 | I<params> in the key object generation context I<genctx>. |
241 | ||
363b1e5d | 242 | OSSL_FUNC_keymgmt_gen_settable_params() should return a constant array of |
318a9dfa | 243 | descriptor L<OSSL_PARAM(3)>, for parameters that OSSL_FUNC_keymgmt_gen_set_params() |
1a5632e0 RL |
244 | can handle. |
245 | ||
363b1e5d | 246 | OSSL_FUNC_keymgmt_gen() should perform the key object generation itself, and |
1a5632e0 RL |
247 | return the result. The callback I<cb> should be called at regular |
248 | intervals with indications on how the key object generation | |
249 | progresses. | |
250 | ||
363b1e5d | 251 | OSSL_FUNC_keymgmt_gen_cleanup() should clean up and free the key object |
1a5632e0 | 252 | generation context I<genctx> |
b305452f | 253 | |
5dacb38c RL |
254 | OSSL_FUNC_keymgmt_load() creates a provider side key object based on a |
255 | I<reference> object with a size of I<reference_sz> bytes, that only the | |
256 | provider knows how to interpret, but that may come from other operations. | |
257 | Outside the provider, this reference is simply an array of bytes. | |
258 | ||
259 | At least one of OSSL_FUNC_keymgmt_new(), OSSL_FUNC_keymgmt_gen() and | |
d270a6c9 | 260 | OSSL_FUNC_keymgmt_load() are mandatory, as well as OSSL_FUNC_keymgmt_free() and |
57cd10dd | 261 | OSSL_FUNC_keymgmt_has(). Additionally, if OSSL_FUNC_keymgmt_gen() is present, |
d270a6c9 AS |
262 | OSSL_FUNC_keymgmt_gen_init() and OSSL_FUNC_keymgmt_gen_cleanup() must be |
263 | present as well. | |
b305452f RL |
264 | |
265 | =head2 Key Object Information Functions | |
266 | ||
363b1e5d | 267 | OSSL_FUNC_keymgmt_get_params() should extract information data associated |
33df1cfd | 268 | with the given I<keydata>, see L</Common Information Parameters>. |
b305452f | 269 | |
363b1e5d | 270 | OSSL_FUNC_keymgmt_gettable_params() should return a constant array of |
318a9dfa | 271 | descriptor L<OSSL_PARAM(3)>, for parameters that OSSL_FUNC_keymgmt_get_params() |
b305452f RL |
272 | can handle. |
273 | ||
363b1e5d | 274 | If OSSL_FUNC_keymgmt_gettable_params() is present, OSSL_FUNC_keymgmt_get_params() |
ce82b892 NT |
275 | must also be present, and vice versa. |
276 | ||
363b1e5d | 277 | OSSL_FUNC_keymgmt_set_params() should update information data associated |
33df1cfd | 278 | with the given I<keydata>, see L</Common Information Parameters>. |
ce82b892 | 279 | |
363b1e5d | 280 | OSSL_FUNC_keymgmt_settable_params() should return a constant array of |
318a9dfa | 281 | descriptor L<OSSL_PARAM(3)>, for parameters that OSSL_FUNC_keymgmt_set_params() |
ce82b892 NT |
282 | can handle. |
283 | ||
363b1e5d | 284 | If OSSL_FUNC_keymgmt_settable_params() is present, OSSL_FUNC_keymgmt_set_params() |
ce82b892 | 285 | must also be present, and vice versa. |
b305452f RL |
286 | |
287 | =head2 Key Object Checking Functions | |
e62a45b6 | 288 | |
363b1e5d | 289 | OSSL_FUNC_keymgmt_query_operation_name() should return the name of the |
e62a45b6 RL |
290 | supported algorithm for the operation I<operation_id>. This is |
291 | similar to provider_query_operation() (see L<provider-base(7)>), | |
292 | but only works as an advisory. If this function is not present, or | |
293 | returns NULL, the caller is free to assume that there's an algorithm | |
294 | from the same provider, of the same name as the one used to fetch the | |
295 | keymgmt and try to use that. | |
296 | ||
363b1e5d | 297 | OSSL_FUNC_keymgmt_has() should check whether the given I<keydata> contains the subsets |
b305452f RL |
298 | of data indicated by the I<selector>. A combination of several |
299 | selector bits must consider all those subsets, not just one. An | |
300 | implementation is, however, free to consider an empty subset of data | |
9a485440 TM |
301 | to still be a valid subset. For algorithms where some selection is |
302 | not meaningful such as B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> for | |
303 | RSA keys the function should just return 1 as the selected subset | |
304 | is not really missing in the key. | |
b305452f | 305 | |
363b1e5d | 306 | OSSL_FUNC_keymgmt_validate() should check if the I<keydata> contains valid |
b305452f RL |
307 | data subsets indicated by I<selection>. Some combined selections of |
308 | data subsets may cause validation of the combined data. | |
309 | For example, the combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and | |
310 | B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY> (or B<OSSL_KEYMGMT_SELECT_KEYPAIR> | |
311 | for short) is expected to check that the pairwise consistency of | |
899e2564 MC |
312 | I<keydata> is valid. The I<checktype> parameter controls what type of check is |
313 | performed on the subset of data. Two types of check are defined: | |
314 | B<OSSL_KEYMGMT_VALIDATE_FULL_CHECK> and B<OSSL_KEYMGMT_VALIDATE_QUICK_CHECK>. | |
315 | The interpretation of how much checking is performed in a full check versus a | |
316 | quick check is key type specific. Some providers may have no distinction | |
9a485440 TM |
317 | between a full check and a quick check. For algorithms where some selection is |
318 | not meaningful such as B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> for | |
319 | RSA keys the function should just return 1 as there is nothing to validate for | |
320 | that selection. | |
b305452f | 321 | |
363b1e5d | 322 | OSSL_FUNC_keymgmt_match() should check if the data subset indicated by |
bee5d6cd RL |
323 | I<selection> in I<keydata1> and I<keydata2> match. It is assumed that |
324 | the caller has ensured that I<keydata1> and I<keydata2> are both owned | |
325 | by the implementation of this function. | |
326 | ||
85fcc3fb | 327 | =head2 Key Object Import, Export and Duplication Functions |
b305452f | 328 | |
363b1e5d | 329 | OSSL_FUNC_keymgmt_import() should import data indicated by I<selection> into |
318a9dfa | 330 | I<keydata> with values taken from the L<OSSL_PARAM(3)> array I<params>. |
b305452f | 331 | |
363b1e5d | 332 | OSSL_FUNC_keymgmt_export() should extract values indicated by I<selection> |
318a9dfa | 333 | from I<keydata>, create an L<OSSL_PARAM(3)> array with them and call |
b305452f RL |
334 | I<param_cb> with that array as well as the given I<cbarg>. |
335 | ||
5e3b8450 IF |
336 | OSSL_FUNC_keymgmt_import_types() and OSSL_FUNC_keymgmt_import_types_ex() |
337 | should return a constant array of descriptor | |
318a9dfa | 338 | L<OSSL_PARAM(3)> for data indicated by I<selection>, for parameters that |
363b1e5d | 339 | OSSL_FUNC_keymgmt_import() can handle. |
5e3b8450 IF |
340 | Either OSSL_FUNC_keymgmt_import_types() or OSSL_FUNC_keymgmt_import_types_ex(), |
341 | must be implemented, if OSSL_FUNC_keymgmt_import_types_ex() is implemented, then | |
342 | it is preferred over OSSL_FUNC_keymgmt_import_types(). | |
343 | Providers that are supposed to be backward compatible with OpenSSL 3.0 or 3.1 | |
344 | must continue to implement OSSL_FUNC_keymgmt_import_types(). | |
345 | ||
346 | OSSL_FUNC_keymgmt_export_types() and OSSL_FUNC_keymgmt_export_types_ex() | |
347 | should return a constant array of descriptor | |
318a9dfa | 348 | L<OSSL_PARAM(3)> for data indicated by I<selection>, that the |
363b1e5d | 349 | OSSL_FUNC_keymgmt_export() callback can expect to receive. |
5e3b8450 IF |
350 | Either OSSL_FUNC_keymgmt_export_types() or OSSL_FUNC_keymgmt_export_types_ex(), |
351 | must be implemented, if OSSL_FUNC_keymgmt_export_types_ex() is implemented, then | |
352 | it is preferred over OSSL_FUNC_keymgmt_export_types(). | |
353 | Providers that are supposed to be backward compatible with OpenSSL 3.0 or 3.1 | |
354 | must continue to implement OSSL_FUNC_keymgmt_export_types(). | |
b305452f | 355 | |
b4f447c0 TM |
356 | OSSL_FUNC_keymgmt_dup() should duplicate data subsets indicated by |
357 | I<selection> or the whole key data I<keydata_from> and create a new | |
358 | provider side key object with the data. | |
4a9fe33c | 359 | |
33df1cfd | 360 | =head2 Common Information Parameters |
6508e858 RL |
361 | |
362 | See L<OSSL_PARAM(3)> for further details on the parameters structure. | |
363 | ||
33df1cfd RL |
364 | Common information parameters currently recognised by all built-in |
365 | keymgmt algorithms are as follows: | |
96ebe52e | 366 | |
6508e858 RL |
367 | =over 4 |
368 | ||
369 | =item "bits" (B<OSSL_PKEY_PARAM_BITS>) <integer> | |
370 | ||
371 | The value should be the cryptographic length of the cryptosystem to | |
372 | which the key belongs, in bits. The definition of cryptographic | |
373 | length is specific to the key cryptosystem. | |
374 | ||
375 | =item "max-size" (B<OSSL_PKEY_PARAM_MAX_SIZE>) <integer> | |
376 | ||
377 | The value should be the maximum size that a caller should allocate to | |
378 | safely store a signature (called I<sig> in L<provider-signature(7)>), | |
379 | the result of asymmmetric encryption / decryption (I<out> in | |
380 | L<provider-asym_cipher(7)>, a derived secret (I<secret> in | |
381 | L<provider-keyexch(7)>, and similar data). | |
382 | ||
383 | Because an EVP_KEYMGMT method is always tightly bound to another method | |
384 | (signature, asymmetric cipher, key exchange, ...) and must be of the | |
385 | same provider, this number only needs to be synchronised with the | |
386 | dimensions handled in the rest of the same provider. | |
387 | ||
388 | =item "security-bits" (B<OSSL_PKEY_PARAM_SECURITY_BITS>) <integer> | |
389 | ||
390 | The value should be the number of security bits of the given key. | |
391 | Bits of security is defined in SP800-57. | |
392 | ||
ac57336c RL |
393 | =item "mandatory-digest" (B<OSSL_PKEY_PARAM_MANDATORY_DIGEST>) <UTF8 string> |
394 | ||
395 | If there is a mandatory digest for performing a signature operation with | |
396 | keys from this keymgmt, this parameter should get its name as value. | |
397 | ||
398 | When EVP_PKEY_get_default_digest_name() queries this parameter and it's | |
399 | filled in by the implementation, its return value will be 2. | |
400 | ||
401 | If the keymgmt implementation fills in the value C<""> or C<"UNDEF">, | |
402 | L<EVP_PKEY_get_default_digest_name(3)> will place the string C<"UNDEF"> into | |
403 | its argument I<mdname>. This signifies that no digest should be specified | |
404 | with the corresponding signature operation. | |
405 | ||
406 | =item "default-digest" (B<OSSL_PKEY_PARAM_DEFAULT_DIGEST>) <UTF8 string> | |
407 | ||
408 | If there is a default digest for performing a signature operation with | |
409 | keys from this keymgmt, this parameter should get its name as value. | |
410 | ||
411 | When L<EVP_PKEY_get_default_digest_name(3)> queries this parameter and it's | |
412 | filled in by the implementation, its return value will be 1. Note that if | |
413 | B<OSSL_PKEY_PARAM_MANDATORY_DIGEST> is responded to as well, | |
414 | L<EVP_PKEY_get_default_digest_name(3)> ignores the response to this | |
415 | parameter. | |
416 | ||
417 | If the keymgmt implementation fills in the value C<""> or C<"UNDEF">, | |
418 | L<EVP_PKEY_get_default_digest_name(3)> will place the string C<"UNDEF"> into | |
419 | its argument I<mdname>. This signifies that no digest has to be specified | |
420 | with the corresponding signature operation, but may be specified as an | |
421 | option. | |
422 | ||
6508e858 RL |
423 | =back |
424 | ||
ce82b892 NT |
425 | =head1 RETURN VALUES |
426 | ||
4a9fe33c TM |
427 | OSSL_FUNC_keymgmt_new() and OSSL_FUNC_keymgmt_dup() should return a valid |
428 | reference to the newly created provider side key object, or NULL on failure. | |
ce82b892 | 429 | |
363b1e5d DMSP |
430 | OSSL_FUNC_keymgmt_import(), OSSL_FUNC_keymgmt_export(), OSSL_FUNC_keymgmt_get_params() and |
431 | OSSL_FUNC_keymgmt_set_params() should return 1 for success or 0 on error. | |
ce82b892 | 432 | |
363b1e5d | 433 | OSSL_FUNC_keymgmt_validate() should return 1 on successful validation, or 0 on |
ce82b892 NT |
434 | failure. |
435 | ||
363b1e5d | 436 | OSSL_FUNC_keymgmt_has() should return 1 if all the selected data subsets are contained |
ce82b892 NT |
437 | in the given I<keydata> or 0 otherwise. |
438 | ||
363b1e5d | 439 | OSSL_FUNC_keymgmt_query_operation_name() should return a pointer to a string matching |
ce82b892 NT |
440 | the requested operation, or NULL if the same name used to fetch the keymgmt |
441 | applies. | |
442 | ||
363b1e5d | 443 | OSSL_FUNC_keymgmt_gettable_params() and OSSL_FUNC_keymgmt_settable_params() |
5e3b8450 IF |
444 | OSSL_FUNC_keymgmt_import_types(), OSSL_FUNC_keymgmt_import_types_ex(), |
445 | OSSL_FUNC_keymgmt_export_types(), OSSL_FUNC_keymgmt_export_types_ex() | |
ce82b892 | 446 | should |
318a9dfa | 447 | always return a constant L<OSSL_PARAM(3)> array. |
ce82b892 | 448 | |
da2addc5 RL |
449 | =head1 SEE ALSO |
450 | ||
33df1cfd RL |
451 | L<provider(7)>, |
452 | L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>, L<EVP_PKEY-ED25519(7)>, | |
453 | L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-EC(7)>, L<EVP_PKEY-RSA(7)>, | |
454 | L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)> | |
da2addc5 RL |
455 | |
456 | =head1 HISTORY | |
457 | ||
458 | The KEYMGMT interface was introduced in OpenSSL 3.0. | |
459 | ||
5e3b8450 IF |
460 | Functions OSSL_FUNC_keymgmt_import_types_ex(), and OSSL_FUNC_keymgmt_export_types_ex() |
461 | were added with OpenSSL 3.2. | |
462 | ||
da2addc5 RL |
463 | =head1 COPYRIGHT |
464 | ||
a28d06f3 | 465 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. |
da2addc5 RL |
466 | |
467 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
468 | this file except in compliance with the License. You can obtain a copy | |
469 | in the file LICENSE in the source distribution or at | |
470 | L<https://www.openssl.org/source/license.html>. | |
471 | ||
472 | =cut |