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