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().
258 Additionally, if OSSL_FUNC_keymgmt_gen() is present, OSSL_FUNC_keymgmt_gen_init()
259 and OSSL_FUNC_keymgmt_gen_cleanup() must be present as well.
261 =head2 Key Object Information Functions
263 OSSL_FUNC_keymgmt_get_params() should extract information data associated
264 with the given I<keydata>, see L</Common Information Parameters>.
266 OSSL_FUNC_keymgmt_gettable_params() should return a constant array of
267 descriptor B<OSSL_PARAM>, for parameters that OSSL_FUNC_keymgmt_get_params()
270 If OSSL_FUNC_keymgmt_gettable_params() is present, OSSL_FUNC_keymgmt_get_params()
271 must also be present, and vice versa.
273 OSSL_FUNC_keymgmt_set_params() should update information data associated
274 with the given I<keydata>, see L</Common Information Parameters>.
276 OSSL_FUNC_keymgmt_settable_params() should return a constant array of
277 descriptor B<OSSL_PARAM>, for parameters that OSSL_FUNC_keymgmt_set_params()
280 If OSSL_FUNC_keymgmt_settable_params() is present, OSSL_FUNC_keymgmt_set_params()
281 must also be present, and vice versa.
283 =head2 Key Object Checking Functions
285 OSSL_FUNC_keymgmt_query_operation_name() should return the name of the
286 supported algorithm for the operation I<operation_id>. This is
287 similar to provider_query_operation() (see L<provider-base(7)>),
288 but only works as an advisory. If this function is not present, or
289 returns NULL, the caller is free to assume that there's an algorithm
290 from the same provider, of the same name as the one used to fetch the
291 keymgmt and try to use that.
293 OSSL_FUNC_keymgmt_has() should check whether the given I<keydata> contains the subsets
294 of data indicated by the I<selector>. A combination of several
295 selector bits must consider all those subsets, not just one. An
296 implementation is, however, free to consider an empty subset of data
297 to still be a valid subset. For algorithms where some selection is
298 not meaningful such as B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> for
299 RSA keys the function should just return 1 as the selected subset
300 is not really missing in the key.
302 OSSL_FUNC_keymgmt_validate() should check if the I<keydata> contains valid
303 data subsets indicated by I<selection>. Some combined selections of
304 data subsets may cause validation of the combined data.
305 For example, the combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and
306 B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY> (or B<OSSL_KEYMGMT_SELECT_KEYPAIR>
307 for short) is expected to check that the pairwise consistency of
308 I<keydata> is valid. The I<checktype> parameter controls what type of check is
309 performed on the subset of data. Two types of check are defined:
310 B<OSSL_KEYMGMT_VALIDATE_FULL_CHECK> and B<OSSL_KEYMGMT_VALIDATE_QUICK_CHECK>.
311 The interpretation of how much checking is performed in a full check versus a
312 quick check is key type specific. Some providers may have no distinction
313 between a full check and a quick check. For algorithms where some selection is
314 not meaningful such as B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> for
315 RSA keys the function should just return 1 as there is nothing to validate for
318 OSSL_FUNC_keymgmt_match() should check if the data subset indicated by
319 I<selection> in I<keydata1> and I<keydata2> match. It is assumed that
320 the caller has ensured that I<keydata1> and I<keydata2> are both owned
321 by the implementation of this function.
323 =head2 Key Object Import, Export and Duplication Functions
325 OSSL_FUNC_keymgmt_import() should import data indicated by I<selection> into
326 I<keydata> with values taken from the B<OSSL_PARAM> array I<params>.
328 OSSL_FUNC_keymgmt_export() should extract values indicated by I<selection>
329 from I<keydata>, create an B<OSSL_PARAM> array with them and call
330 I<param_cb> with that array as well as the given I<cbarg>.
332 OSSL_FUNC_keymgmt_import_types() should return a constant array of descriptor
333 B<OSSL_PARAM> for data indicated by I<selection>, for parameters that
334 OSSL_FUNC_keymgmt_import() can handle.
336 OSSL_FUNC_keymgmt_export_types() should return a constant array of descriptor
337 B<OSSL_PARAM> for data indicated by I<selection>, that the
338 OSSL_FUNC_keymgmt_export() callback can expect to receive.
340 OSSL_FUNC_keymgmt_dup() should duplicate data subsets indicated by
341 I<selection> or the whole key data I<keydata_from> and create a new
342 provider side key object with the data.
344 =head2 Common Information Parameters
346 See L<OSSL_PARAM(3)> for further details on the parameters structure.
348 Common information parameters currently recognised by all built-in
349 keymgmt algorithms are as follows:
353 =item "bits" (B<OSSL_PKEY_PARAM_BITS>) <integer>
355 The value should be the cryptographic length of the cryptosystem to
356 which the key belongs, in bits. The definition of cryptographic
357 length is specific to the key cryptosystem.
359 =item "max-size" (B<OSSL_PKEY_PARAM_MAX_SIZE>) <integer>
361 The value should be the maximum size that a caller should allocate to
362 safely store a signature (called I<sig> in L<provider-signature(7)>),
363 the result of asymmmetric encryption / decryption (I<out> in
364 L<provider-asym_cipher(7)>, a derived secret (I<secret> in
365 L<provider-keyexch(7)>, and similar data).
367 Because an EVP_KEYMGMT method is always tightly bound to another method
368 (signature, asymmetric cipher, key exchange, ...) and must be of the
369 same provider, this number only needs to be synchronised with the
370 dimensions handled in the rest of the same provider.
372 =item "security-bits" (B<OSSL_PKEY_PARAM_SECURITY_BITS>) <integer>
374 The value should be the number of security bits of the given key.
375 Bits of security is defined in SP800-57.
381 OSSL_FUNC_keymgmt_new() and OSSL_FUNC_keymgmt_dup() should return a valid
382 reference to the newly created provider side key object, or NULL on failure.
384 OSSL_FUNC_keymgmt_import(), OSSL_FUNC_keymgmt_export(), OSSL_FUNC_keymgmt_get_params() and
385 OSSL_FUNC_keymgmt_set_params() should return 1 for success or 0 on error.
387 OSSL_FUNC_keymgmt_validate() should return 1 on successful validation, or 0 on
390 OSSL_FUNC_keymgmt_has() should return 1 if all the selected data subsets are contained
391 in the given I<keydata> or 0 otherwise.
393 OSSL_FUNC_keymgmt_query_operation_name() should return a pointer to a string matching
394 the requested operation, or NULL if the same name used to fetch the keymgmt
397 OSSL_FUNC_keymgmt_gettable_params() and OSSL_FUNC_keymgmt_settable_params()
398 OSSL_FUNC_keymgmt_import_types(), OSSL_FUNC_keymgmt_export_types()
400 always return a constant B<OSSL_PARAM> array.
405 L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>, L<EVP_PKEY-ED25519(7)>,
406 L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-EC(7)>, L<EVP_PKEY-RSA(7)>,
407 L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>
411 The KEYMGMT interface was introduced in OpenSSL 3.0.
415 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
417 Licensed under the Apache License 2.0 (the "License"). You may not use
418 this file except in compliance with the License. You can obtain a copy
419 in the file LICENSE in the source distribution or at
420 L<https://www.openssl.org/source/license.html>.