5 provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions
9 #include <openssl/core_dispatch.h>
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.
17 /* Key object (keydata) creation and destruction */
18 void *OSSL_FUNC_keymgmt_new(void *provctx);
19 void OSSL_FUNC_keymgmt_free(void *keydata);
21 /* Generation, a more complex constructor */
22 void *OSSL_FUNC_keymgmt_gen_init(void *provctx, int selection,
23 const OSSL_PARAM params[]);
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[]);
26 const OSSL_PARAM *OSSL_FUNC_keymgmt_gen_settable_params(void *genctx,
28 void *OSSL_FUNC_keymgmt_gen(void *genctx, OSSL_CALLBACK *cb, void *cbarg);
29 void OSSL_FUNC_keymgmt_gen_cleanup(void *genctx);
31 /* Key loading by object reference, also a constructor */
32 void *OSSL_FUNC_keymgmt_load(const void *reference, size_t *reference_sz);
34 /* Key object information */
35 int OSSL_FUNC_keymgmt_get_params(void *keydata, OSSL_PARAM params[]);
36 const OSSL_PARAM *OSSL_FUNC_keymgmt_gettable_params(void *provctx);
37 int OSSL_FUNC_keymgmt_set_params(void *keydata, const OSSL_PARAM params[]);
38 const OSSL_PARAM *OSSL_FUNC_keymgmt_settable_params(void *provctx);
40 /* Key object content checks */
41 int OSSL_FUNC_keymgmt_has(const void *keydata, int selection);
42 int OSSL_FUNC_keymgmt_match(const void *keydata1, const void *keydata2,
45 /* Discovery of supported operations */
46 const char *OSSL_FUNC_keymgmt_query_operation_name(int operation_id);
48 /* Key object import and export functions */
49 int OSSL_FUNC_keymgmt_import(int selection, void *keydata, const OSSL_PARAM params[]);
50 const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types(int selection);
51 int OSSL_FUNC_keymgmt_export(int selection, void *keydata,
52 OSSL_CALLBACK *param_cb, void *cbarg);
53 const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types(int selection);
55 /* Key object duplication, a constructor */
56 void *OSSL_FUNC_keymgmt_dup(const void *keydata_from, int selection);
58 /* Key object validation */
59 int OSSL_FUNC_keymgmt_validate(const void *keydata, int selection, int checktype);
63 The KEYMGMT operation doesn't have much public visibility in OpenSSL
64 libraries, it's rather an internal operation that's designed to work
65 in tandem with operations that use private/public key pairs.
67 Because the KEYMGMT operation shares knowledge with the operations it
68 works with in tandem, they must belong to the same provider.
69 The OpenSSL libraries will ensure that they do.
71 The primary responsibility of the KEYMGMT operation is to hold the
72 provider side key data for the OpenSSL library EVP_PKEY structure.
74 All "functions" mentioned here are passed as function pointers between
75 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
76 B<OSSL_ALGORITHM> arrays that are returned by the provider's
77 provider_query_operation() function
78 (see L<provider-base(7)/Provider Functions>).
80 All these "functions" have a corresponding function type definition
81 named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
82 function pointer from a B<OSSL_DISPATCH> element named
84 For example, the "function" OSSL_FUNC_keymgmt_new() has these:
86 typedef void *(OSSL_FUNC_keymgmt_new_fn)(void *provctx);
87 static ossl_inline OSSL_FUNC_keymgmt_new_fn
88 OSSL_FUNC_keymgmt_new(const OSSL_DISPATCH *opf);
90 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
91 macros in L<openssl-core_dispatch.h(7)>, as follows:
93 OSSL_FUNC_keymgmt_new OSSL_FUNC_KEYMGMT_NEW
94 OSSL_FUNC_keymgmt_free OSSL_FUNC_KEYMGMT_FREE
96 OSSL_FUNC_keymgmt_gen_init OSSL_FUNC_KEYMGMT_GEN_INIT
97 OSSL_FUNC_keymgmt_gen_set_template OSSL_FUNC_KEYMGMT_GEN_SET_TEMPLATE
98 OSSL_FUNC_keymgmt_gen_set_params OSSL_FUNC_KEYMGMT_GEN_SET_PARAMS
99 OSSL_FUNC_keymgmt_gen_settable_params OSSL_FUNC_KEYMGMT_GEN_SETTABLE_PARAMS
100 OSSL_FUNC_keymgmt_gen OSSL_FUNC_KEYMGMT_GEN
101 OSSL_FUNC_keymgmt_gen_cleanup OSSL_FUNC_KEYMGMT_GEN_CLEANUP
103 OSSL_FUNC_keymgmt_load OSSL_FUNC_KEYMGMT_LOAD
105 OSSL_FUNC_keymgmt_get_params OSSL_FUNC_KEYMGMT_GET_PARAMS
106 OSSL_FUNC_keymgmt_gettable_params OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS
107 OSSL_FUNC_keymgmt_set_params OSSL_FUNC_KEYMGMT_SET_PARAMS
108 OSSL_FUNC_keymgmt_settable_params OSSL_FUNC_KEYMGMT_SETTABLE_PARAMS
110 OSSL_FUNC_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME
112 OSSL_FUNC_keymgmt_has OSSL_FUNC_KEYMGMT_HAS
113 OSSL_FUNC_keymgmt_validate OSSL_FUNC_KEYMGMT_VALIDATE
114 OSSL_FUNC_keymgmt_match OSSL_FUNC_KEYMGMT_MATCH
116 OSSL_FUNC_keymgmt_import OSSL_FUNC_KEYMGMT_IMPORT
117 OSSL_FUNC_keymgmt_import_types OSSL_FUNC_KEYMGMT_IMPORT_TYPES
118 OSSL_FUNC_keymgmt_export OSSL_FUNC_KEYMGMT_EXPORT
119 OSSL_FUNC_keymgmt_export_types OSSL_FUNC_KEYMGMT_EXPORT_TYPES
121 OSSL_FUNC_keymgmt_dup OSSL_FUNC_KEYMGMT_DUP
125 A key object is a collection of data for an asymmetric key, and is
126 represented as I<keydata> in this manual.
128 The exact contents of a key object are defined by the provider, and it
129 is assumed that different operations in one and the same provider use
130 the exact same structure to represent this collection of data, so that
131 for example, a key object that has been created using the KEYMGMT
132 interface that we document here can be passed as is to other provider
133 operations, such as OP_signature_sign_init() (see
134 L<provider-signature(7)>).
136 With some of the KEYMGMT functions, it's possible to select a specific
137 subset of data to handle, governed by the bits in a I<selection>
138 indicator. The bits are:
142 =item B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY>
144 Indicating that the private key data in a key object should be
147 =item B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY>
149 Indicating that the public key data in a key object should be
152 =item B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS>
154 Indicating that the domain parameters in a key object should be
157 =item B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>
159 Indicating that other parameters in a key object should be
162 Other parameters are key parameters that don't fit any other
163 classification. In other words, this particular selector bit works as
164 a last resort bit bucket selector.
168 Some selector bits have also been combined for easier use:
172 =item B<OSSL_KEYMGMT_SELECT_ALL_PARAMETERS>
174 Indicating that all key object parameters should be considered,
175 regardless of their more granular classification.
177 =for comment This should used by EVP functions such as
178 EVP_PKEY_copy_parameters() and EVP_PKEY_parameters_eq()
180 This is a combination of B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> and
181 B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>.
183 =for comment If more parameter categories are added, they should be
186 =item B<OSSL_KEYMGMT_SELECT_KEYPAIR>
188 Indicating that both the whole key pair in a key object should be
189 considered, i.e. the combination of public and private key.
191 This is a combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and
192 B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY>.
194 =item B<OSSL_KEYMGMT_SELECT_ALL>
196 Indicating that everything in a key object should be considered.
200 The exact interpretation of those bits or how they combine is left to
201 each function where you can specify a selector.
203 =for comment One might think that a combination of bits means that all
204 the selected data subsets must be considered, but then you have to
205 consider that when comparing key objects (future function), an
206 implementation might opt to not compare the private key if it has
207 compared the public key, since a match of one half implies a match of
210 =head2 Constructing and Destructing Functions
212 OSSL_FUNC_keymgmt_new() should create a provider side key object. The
213 provider context I<provctx> is passed and may be incorporated in the
214 key object, but that is not mandatory.
216 OSSL_FUNC_keymgmt_free() should free the passed I<keydata>.
218 OSSL_FUNC_keymgmt_gen_init(), OSSL_FUNC_keymgmt_gen_set_template(),
219 OSSL_FUNC_keymgmt_gen_set_params(), OSSL_FUNC_keymgmt_gen_settable_params(),
220 OSSL_FUNC_keymgmt_gen() and OSSL_FUNC_keymgmt_gen_cleanup() work together as a
221 more elaborate context based key object constructor.
223 OSSL_FUNC_keymgmt_gen_init() should create the key object generation context
224 and initialize it with I<selections>, which will determine what kind
225 of contents the key object to be generated should get.
226 The I<params>, if not NULL, should be set on the context in a manner similar to
227 using OSSL_FUNC_keymgmt_set_params().
229 OSSL_FUNC_keymgmt_gen_set_template() should add I<template> to the context
230 I<genctx>. The I<template> is assumed to be a key object constructed
231 with the same KEYMGMT, and from which content that the implementation
232 chooses can be used as a template for the key object to be generated.
233 Typically, the generation of a DSA or DH key would get the domain
234 parameters from this I<template>.
236 OSSL_FUNC_keymgmt_gen_set_params() should set additional parameters from
237 I<params> in the key object generation context I<genctx>.
239 OSSL_FUNC_keymgmt_gen_settable_params() should return a constant array of
240 descriptor B<OSSL_PARAM>, for parameters that OSSL_FUNC_keymgmt_gen_set_params()
243 OSSL_FUNC_keymgmt_gen() should perform the key object generation itself, and
244 return the result. The callback I<cb> should be called at regular
245 intervals with indications on how the key object generation
248 OSSL_FUNC_keymgmt_gen_cleanup() should clean up and free the key object
249 generation context I<genctx>
251 OSSL_FUNC_keymgmt_load() creates a provider side key object based on a
252 I<reference> object with a size of I<reference_sz> bytes, that only the
253 provider knows how to interpret, but that may come from other operations.
254 Outside the provider, this reference is simply an array of bytes.
256 At least one of OSSL_FUNC_keymgmt_new(), OSSL_FUNC_keymgmt_gen() and
257 OSSL_FUNC_keymgmt_load() are mandatory, as well as OSSL_FUNC_keymgmt_free() and
258 OSSL_FUNC_keymgmt_has(). Additionally, if OSSL_FUNC_keymgmt_gen() is present,
259 OSSL_FUNC_keymgmt_gen_init() and OSSL_FUNC_keymgmt_gen_cleanup() must be
262 =head2 Key Object Information Functions
264 OSSL_FUNC_keymgmt_get_params() should extract information data associated
265 with the given I<keydata>, see L</Common Information Parameters>.
267 OSSL_FUNC_keymgmt_gettable_params() should return a constant array of
268 descriptor B<OSSL_PARAM>, for parameters that OSSL_FUNC_keymgmt_get_params()
271 If OSSL_FUNC_keymgmt_gettable_params() is present, OSSL_FUNC_keymgmt_get_params()
272 must also be present, and vice versa.
274 OSSL_FUNC_keymgmt_set_params() should update information data associated
275 with the given I<keydata>, see L</Common Information Parameters>.
277 OSSL_FUNC_keymgmt_settable_params() should return a constant array of
278 descriptor B<OSSL_PARAM>, for parameters that OSSL_FUNC_keymgmt_set_params()
281 If OSSL_FUNC_keymgmt_settable_params() is present, OSSL_FUNC_keymgmt_set_params()
282 must also be present, and vice versa.
284 =head2 Key Object Checking Functions
286 OSSL_FUNC_keymgmt_query_operation_name() should return the name of the
287 supported algorithm for the operation I<operation_id>. This is
288 similar to provider_query_operation() (see L<provider-base(7)>),
289 but only works as an advisory. If this function is not present, or
290 returns NULL, the caller is free to assume that there's an algorithm
291 from the same provider, of the same name as the one used to fetch the
292 keymgmt and try to use that.
294 OSSL_FUNC_keymgmt_has() should check whether the given I<keydata> contains the subsets
295 of data indicated by the I<selector>. A combination of several
296 selector bits must consider all those subsets, not just one. An
297 implementation is, however, free to consider an empty subset of data
298 to still be a valid subset. For algorithms where some selection is
299 not meaningful such as B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> for
300 RSA keys the function should just return 1 as the selected subset
301 is not really missing in the key.
303 OSSL_FUNC_keymgmt_validate() should check if the I<keydata> contains valid
304 data subsets indicated by I<selection>. Some combined selections of
305 data subsets may cause validation of the combined data.
306 For example, the combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and
307 B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY> (or B<OSSL_KEYMGMT_SELECT_KEYPAIR>
308 for short) is expected to check that the pairwise consistency of
309 I<keydata> is valid. The I<checktype> parameter controls what type of check is
310 performed on the subset of data. Two types of check are defined:
311 B<OSSL_KEYMGMT_VALIDATE_FULL_CHECK> and B<OSSL_KEYMGMT_VALIDATE_QUICK_CHECK>.
312 The interpretation of how much checking is performed in a full check versus a
313 quick check is key type specific. Some providers may have no distinction
314 between a full check and a quick check. For algorithms where some selection is
315 not meaningful such as B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> for
316 RSA keys the function should just return 1 as there is nothing to validate for
319 OSSL_FUNC_keymgmt_match() should check if the data subset indicated by
320 I<selection> in I<keydata1> and I<keydata2> match. It is assumed that
321 the caller has ensured that I<keydata1> and I<keydata2> are both owned
322 by the implementation of this function.
324 =head2 Key Object Import, Export and Duplication Functions
326 OSSL_FUNC_keymgmt_import() should import data indicated by I<selection> into
327 I<keydata> with values taken from the B<OSSL_PARAM> array I<params>.
329 OSSL_FUNC_keymgmt_export() should extract values indicated by I<selection>
330 from I<keydata>, create an B<OSSL_PARAM> array with them and call
331 I<param_cb> with that array as well as the given I<cbarg>.
333 OSSL_FUNC_keymgmt_import_types() should return a constant array of descriptor
334 B<OSSL_PARAM> for data indicated by I<selection>, for parameters that
335 OSSL_FUNC_keymgmt_import() can handle.
337 OSSL_FUNC_keymgmt_export_types() should return a constant array of descriptor
338 B<OSSL_PARAM> for data indicated by I<selection>, that the
339 OSSL_FUNC_keymgmt_export() callback can expect to receive.
341 OSSL_FUNC_keymgmt_dup() should duplicate data subsets indicated by
342 I<selection> or the whole key data I<keydata_from> and create a new
343 provider side key object with the data.
345 =head2 Common Information Parameters
347 See L<OSSL_PARAM(3)> for further details on the parameters structure.
349 Common information parameters currently recognised by all built-in
350 keymgmt algorithms are as follows:
354 =item "bits" (B<OSSL_PKEY_PARAM_BITS>) <integer>
356 The value should be the cryptographic length of the cryptosystem to
357 which the key belongs, in bits. The definition of cryptographic
358 length is specific to the key cryptosystem.
360 =item "max-size" (B<OSSL_PKEY_PARAM_MAX_SIZE>) <integer>
362 The value should be the maximum size that a caller should allocate to
363 safely store a signature (called I<sig> in L<provider-signature(7)>),
364 the result of asymmmetric encryption / decryption (I<out> in
365 L<provider-asym_cipher(7)>, a derived secret (I<secret> in
366 L<provider-keyexch(7)>, and similar data).
368 Because an EVP_KEYMGMT method is always tightly bound to another method
369 (signature, asymmetric cipher, key exchange, ...) and must be of the
370 same provider, this number only needs to be synchronised with the
371 dimensions handled in the rest of the same provider.
373 =item "security-bits" (B<OSSL_PKEY_PARAM_SECURITY_BITS>) <integer>
375 The value should be the number of security bits of the given key.
376 Bits of security is defined in SP800-57.
382 OSSL_FUNC_keymgmt_new() and OSSL_FUNC_keymgmt_dup() should return a valid
383 reference to the newly created provider side key object, or NULL on failure.
385 OSSL_FUNC_keymgmt_import(), OSSL_FUNC_keymgmt_export(), OSSL_FUNC_keymgmt_get_params() and
386 OSSL_FUNC_keymgmt_set_params() should return 1 for success or 0 on error.
388 OSSL_FUNC_keymgmt_validate() should return 1 on successful validation, or 0 on
391 OSSL_FUNC_keymgmt_has() should return 1 if all the selected data subsets are contained
392 in the given I<keydata> or 0 otherwise.
394 OSSL_FUNC_keymgmt_query_operation_name() should return a pointer to a string matching
395 the requested operation, or NULL if the same name used to fetch the keymgmt
398 OSSL_FUNC_keymgmt_gettable_params() and OSSL_FUNC_keymgmt_settable_params()
399 OSSL_FUNC_keymgmt_import_types(), OSSL_FUNC_keymgmt_export_types()
401 always return a constant B<OSSL_PARAM> array.
406 L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>, L<EVP_PKEY-ED25519(7)>,
407 L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-EC(7)>, L<EVP_PKEY-RSA(7)>,
408 L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>
412 The KEYMGMT interface was introduced in OpenSSL 3.0.
416 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
418 Licensed under the Apache License 2.0 (the "License"). You may not use
419 this file except in compliance with the License. You can obtain a copy
420 in the file LICENSE in the source distribution or at
421 L<https://www.openssl.org/source/license.html>.