5 provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions
9 #include <openssl/core_numbers.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 *OP_keymgmt_new(void *provctx);
19 void OP_keymgmt_free(void *keydata);
21 /* Key object information */
22 int OP_keymgmt_get_params(void *keydata, OSSL_PARAM params[]);
23 const OSSL_PARAM *OP_keymgmt_gettable_params(void);
24 int OP_keymgmt_set_params(void *keydata, const OSSL_PARAM params[]);
25 const OSSL_PARAM *OP_keymgmt_settable_params(void);
27 /* Key object content checks */
28 int OP_keymgmt_has(void *keydata, int selection);
29 int OP_keymgmt_match(const void *keydata1, const void *keydata2,
32 /* Discovery of supported operations */
33 const char *OP_keymgmt_query_operation_name(int operation_id);
35 /* Key object import and export functions */
36 int OP_keymgmt_import(int selection, void *keydata, const OSSL_PARAM params[]);
37 const OSSL_PARAM *OP_keymgmt_import_types(int selection);
38 int OP_keymgmt_export(int selection, void *keydata,
39 OSSL_CALLBACK *param_cb, void *cbarg);
40 const OSSL_PARAM *OP_keymgmt_export_types(int selection);
42 /* Key object validation */
43 int OP_keymgmt_validate(void *keydata, int selection);
47 The KEYMGMT operation doesn't have much public visibility in OpenSSL
48 libraries, it's rather an internal operation that's designed to work
49 in tandem with operations that use private/public key pairs.
51 Because the KEYMGMT operation shares knowledge with the operations it
52 works with in tandem, they must belong to the same provider.
53 The OpenSSL libraries will ensure that they do.
55 The primary responsibility of the KEYMGMT operation is to hold the
56 provider side key data for the OpenSSL library EVP_PKEY structure.
58 All "functions" mentioned here are passed as function pointers between
59 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
60 B<OSSL_ALGORITHM> arrays that are returned by the provider's
61 provider_query_operation() function
62 (see L<provider-base(7)/Provider Functions>).
64 All these "functions" have a corresponding function type definition
65 named B<OSSL_{name}_fn>, and a helper function to retrieve the
66 function pointer from a B<OSSL_DISPATCH> element named
68 For example, the "function" OP_keymgmt_new() has these:
70 typedef void *(OSSL_OP_keymgmt_new_fn)(void *provctx);
71 static ossl_inline OSSL_OP_keymgmt_new_fn
72 OSSL_get_OP_keymgmt_new(const OSSL_DISPATCH *opf);
74 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
75 macros in L<openssl-core_numbers.h(7)>, as follows:
77 OP_keymgmt_new OSSL_FUNC_KEYMGMT_NEW
78 OP_keymgmt_free OSSL_FUNC_KEYMGMT_FREE
80 OP_keymgmt_get_params OSSL_FUNC_KEYMGMT_GET_PARAMS
81 OP_keymgmt_gettable_params OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS
82 OP_keymgmt_set_params OSSL_FUNC_KEYMGMT_SET_PARAMS
83 OP_keymgmt_settable_params OSSL_FUNC_KEYMGMT_SETTABLE_PARAMS
85 OP_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME
87 OP_keymgmt_has OSSL_FUNC_KEYMGMT_HAS
88 OP_keymgmt_validate OSSL_FUNC_KEYMGMT_VALIDATE
89 OP_keymgmt_match OSSL_FUNC_KEYMGMT_MATCH
91 OP_keymgmt_import OSSL_FUNC_KEYMGMT_IMPORT
92 OP_keymgmt_import_types OSSL_FUNC_KEYMGMT_IMPORT_TYPES
93 OP_keymgmt_export OSSL_FUNC_KEYMGMT_EXPORT
94 OP_keymgmt_export_types OSSL_FUNC_KEYMGMT_EXPORT_TYPES
99 A key object is a collection of data for an asymmetric key, and is
100 represented as I<keydata> in this manual.
102 The exact contents of a key object are defined by the provider, and it
103 is assumed that different operations in one and the same provider use
104 the exact same structure to represent this collection of data, so that
105 for example, a key object that has been created using the KEYMGMT
106 interface that we document here can be passed as is to other provider
107 operations, such as OP_signature_sign_init() (see
108 L<provider-signature(7)>).
110 With some of the KEYMGMT functions, it's possible to select a specific
111 subset of data to handle, governed by the bits in a I<selection>
112 indicator. The bits are:
116 =item B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY>
118 Indicating that the private key data in a key object should be
121 =item B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY>
123 Indicating that the public key data in a key object should be
126 =item B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS>
128 Indicating that the domain parameters in a key object should be
131 =item B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>
133 Indicating that other parameters in a key object should be
136 Other parameters are key parameters that don't fit any other
137 classification. In other words, this particular selector bit works as
138 a last resort bit bucket selector.
142 Some selector bits have also been combined for easier use:
146 =item B<OSSL_KEYMGMT_SELECT_ALL_PARAMETERS>
148 Indicating that all key object parameters should be considered,
149 regardless of their more granular classification.
151 =for comment This should used by EVP functions such as
152 EVP_PKEY_copy_parameters() and EVP_PKEY_cmp_parameters()
154 This is a combination of B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> and
155 B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>.
157 =for comment If more parameter categories are added, they should be
160 =item B<OSSL_KEYMGMT_SELECT_KEYPAIR>
162 Indicating that both the whole key pair in a key object should be
163 considered, i.e. the combination of public and private key.
165 This is a combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and
166 B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY>.
168 =item B<OSSL_KEYMGMT_SELECT_ALL>
170 Indicating that everything in a key object should be considered.
174 The exact interpretation of those bits or how they combine is left to
175 each function where you can specify a selector.
177 =for comment One might think that a combination of bits means that all
178 the selected data subsets must be considered, but then you have to
179 consider that when comparing key objects (future function), an
180 implementation might opt to not compare the private key if it has
181 compared the public key, since a match of one half implies a match of
184 =head2 Constructing and Destructing Functions
186 OP_keymgmt_new() should create a provider side key object. The
187 provider context I<provctx> is passed and may be incorporated in the
188 key object, but that is not mandatory.
190 OP_keymgmt_free() should free the passed I<keydata>.
192 The constructor and destructor are mandatory, a KEYMGMT implementation
193 without them will not be accepted.
195 =for comment when new constructors appear, it's sufficient if only one
196 of them is present. The remark above will have to change to reflect
199 =head2 Key Object Information Functions
201 OP_keymgmt_get_params() should extract information data associated
202 with the given I<keydata>, see L</Information Parameters>.
204 OP_keymgmt_gettable_params() should return a constant array of
205 descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_get_params()
208 If OP_keymgmt_gettable_params() is present, OP_keymgmt_get_params()
209 must also be present, and vice versa.
211 OP_keymgmt_set_params() should update information data associated
212 with the given I<keydata>, see L</Information Parameters>.
214 OP_keymgmt_settable_params() should return a constant array of
215 descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_set_params()
218 If OP_keymgmt_settable_params() is present, OP_keymgmt_set_params()
219 must also be present, and vice versa.
221 =head2 Key Object Checking Functions
223 OP_keymgmt_query_operation_name() should return the name of the
224 supported algorithm for the operation I<operation_id>. This is
225 similar to provider_query_operation() (see L<provider-base(7)>),
226 but only works as an advisory. If this function is not present, or
227 returns NULL, the caller is free to assume that there's an algorithm
228 from the same provider, of the same name as the one used to fetch the
229 keymgmt and try to use that.
231 OP_keymgmt_has() should check whether the given I<keydata> contains the subsets
232 of data indicated by the I<selector>. A combination of several
233 selector bits must consider all those subsets, not just one. An
234 implementation is, however, free to consider an empty subset of data
235 to still be a valid subset.
237 OP_keymgmt_validate() should check if the I<keydata> contains valid
238 data subsets indicated by I<selection>. Some combined selections of
239 data subsets may cause validation of the combined data.
240 For example, the combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and
241 B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY> (or B<OSSL_KEYMGMT_SELECT_KEYPAIR>
242 for short) is expected to check that the pairwise consistency of
245 OP_keymgmt_match() should check if the data subset indicated by
246 I<selection> in I<keydata1> and I<keydata2> match. It is assumed that
247 the caller has ensured that I<keydata1> and I<keydata2> are both owned
248 by the implementation of this function.
250 =head2 Key Object Import and Export Functions
252 OP_keymgmt_import() should import data indicated by I<selection> into
253 I<keydata> with values taken from the B<OSSL_PARAM> array I<params>.
255 OP_keymgmt_export() should extract values indicated by I<selection>
256 from I<keydata>, create an B<OSSL_PARAM> array with them and call
257 I<param_cb> with that array as well as the given I<cbarg>.
259 OP_keymgmt_import_types() should return a constant array of descriptor
260 B<OSSL_PARAM> for data indicated by I<selection>, for parameters that
261 OP_keymgmt_import() can handle.
263 OP_keymgmt_export_types() should return a constant array of descriptor
264 B<OSSL_PARAM> for data indicated by I<selection>, that the
265 OP_keymgmt_export() callback can expect to receive.
267 =head2 Built-in RSA Import/Export Types
269 The following Import/Export types are available for the built-in RSA algorithm:
273 =item "n" (B<OSSL_PKEY_PARAM_RSA_N>) <integer>
277 =item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <integer>
281 =item "d" (B<OSSL_PKEY_PARAM_RSA_D>) <integer>
285 =item "rsa-factor" (B<OSSL_PKEY_PARAM_RSA_FACTOR>) <integer>
287 An RSA factor. In 2 prime RSA these are often known as "p" or "q". This value
288 may be repeated up to 10 times in a single key.
290 =item "rsa-exponent" (B<OSSL_PKEY_PARAM_RSA_EXPONENT>) <integer>
292 An RSA CRT (Chinese Remainder Theorem) exponent. This value may be repeated up
293 to 10 times in a single key.
295 =item "rsa-coefficient" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT>) <integer>
297 An RSA CRT (Chinese Remainder Theorem) coefficient. This value may be repeated
298 up to 9 times in a single key.
302 =head2 Built-in DSA and Diffie-Hellman Import/Export Types
304 The following Import/Export types are available for the built-in DSA and
305 Diffie-Hellman algorithms:
309 =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <integer> or <octet string>
311 The public key value.
313 =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <integer> or <octet string>
315 The private key value.
317 =item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <integer>
319 A DSA or Diffie-Hellman "p" value.
321 =item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <integer>
323 A DSA or Diffie-Hellman "q" value.
325 =item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <integer>
327 A DSA or Diffie-Hellman "g" value.
331 =head2 Built-in X25519, X448, ED25519 and ED448 Import/Export Types
333 The following Import/Export types are available for the built-in X25519, X448,
334 ED25519 and X448 algorithms:
338 =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
340 The public key value.
342 =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string>
344 The private key value.
348 =head2 Information Parameters
350 See L<OSSL_PARAM(3)> for further details on the parameters structure.
352 Parameters currently recognised by built-in keymgmt algorithms
354 Not all parameters are relevant to, or are understood by all keymgmt
359 =item "bits" (B<OSSL_PKEY_PARAM_BITS>) <integer>
361 The value should be the cryptographic length of the cryptosystem to
362 which the key belongs, in bits. The definition of cryptographic
363 length is specific to the key cryptosystem.
365 =item "max-size" (B<OSSL_PKEY_PARAM_MAX_SIZE>) <integer>
367 The value should be the maximum size that a caller should allocate to
368 safely store a signature (called I<sig> in L<provider-signature(7)>),
369 the result of asymmmetric encryption / decryption (I<out> in
370 L<provider-asym_cipher(7)>, a derived secret (I<secret> in
371 L<provider-keyexch(7)>, and similar data).
373 Because an EVP_KEYMGMT method is always tightly bound to another method
374 (signature, asymmetric cipher, key exchange, ...) and must be of the
375 same provider, this number only needs to be synchronised with the
376 dimensions handled in the rest of the same provider.
378 =item "security-bits" (B<OSSL_PKEY_PARAM_SECURITY_BITS>) <integer>
380 The value should be the number of security bits of the given key.
381 Bits of security is defined in SP800-57.
383 =item "use-cofactor-flag" (B<OSSL_PKEY_PARAM_USE_COFACTOR_FLAG>,
384 B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH>) <integer>
386 The value should be either 1 or 0, to respectively enable or disable
387 use of the cofactor in operations using this key.
389 In the context of a key that can be used to perform an Elliptic Curve
390 Diffie-Hellman key exchange, this parameter can be used to mark a requirement
391 for using the Cofactor Diffie-Hellman (CDH) variant of the key exchange
394 See also L<provider-keyexch(7)> for the related
395 B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a
402 OP_keymgmt_new() should return a valid reference to the newly created provider
403 side key object, or NULL on failure.
405 OP_keymgmt_import(), OP_keymgmt_export(), OP_keymgmt_get_params() and
406 OP_keymgmt_set_params() should return 1 for success or 0 on error.
408 OP_keymgmt_validate() should return 1 on successful validation, or 0 on
411 OP_keymgmt_has() should return 1 if all the selected data subsets are contained
412 in the given I<keydata> or 0 otherwise.
414 OP_keymgmt_query_operation_name() should return a pointer to a string matching
415 the requested operation, or NULL if the same name used to fetch the keymgmt
418 OP_keymgmt_gettable_params() and OP_keymgmt_settable_params()
419 OP_keymgmt_import_types(), OP_keymgmt_export_types()
421 always return a constant B<OSSL_PARAM> array.
429 The KEYMGMT interface was introduced in OpenSSL 3.0.
433 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
435 Licensed under the Apache License 2.0 (the "License"). You may not use
436 this file except in compliance with the License. You can obtain a copy
437 in the file LICENSE in the source distribution or at
438 L<https://www.openssl.org/source/license.html>.