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