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