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