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 int OSSL_FUNC_keymgmt_export(void *keydata, int selection, 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 L<OSSL_DISPATCH(3)> arrays via 76L<OSSL_ALGORITHM(3)> 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 L<OSSL_DISPATCH(3)> 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 90L<OSSL_DISPATCH(3)> 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 203It's left to the provider implementation to decide what is reasonable 204to do with regards to received selector bits and how to do it. 205Among others, an implementation of OSSL_FUNC_keymgmt_match() might opt 206to not compare the private half if it has compared the public half, 207since a match of one half implies a match of the other half. 208 209=head2 Constructing and Destructing Functions 210 211OSSL_FUNC_keymgmt_new() should create a provider side key object. The 212provider context I<provctx> is passed and may be incorporated in the 213key object, but that is not mandatory. 214 215OSSL_FUNC_keymgmt_free() should free the passed I<keydata>. 216 217OSSL_FUNC_keymgmt_gen_init(), OSSL_FUNC_keymgmt_gen_set_template(), 218OSSL_FUNC_keymgmt_gen_set_params(), OSSL_FUNC_keymgmt_gen_settable_params(), 219OSSL_FUNC_keymgmt_gen() and OSSL_FUNC_keymgmt_gen_cleanup() work together as a 220more elaborate context based key object constructor. 221 222OSSL_FUNC_keymgmt_gen_init() should create the key object generation context 223and initialize it with I<selections>, which will determine what kind 224of contents the key object to be generated should get. 225The I<params>, if not NULL, should be set on the context in a manner similar to 226using OSSL_FUNC_keymgmt_set_params(). 227 228OSSL_FUNC_keymgmt_gen_set_template() should add I<template> to the context 229I<genctx>. The I<template> is assumed to be a key object constructed 230with the same KEYMGMT, and from which content that the implementation 231chooses can be used as a template for the key object to be generated. 232Typically, the generation of a DSA or DH key would get the domain 233parameters from this I<template>. 234 235OSSL_FUNC_keymgmt_gen_set_params() should set additional parameters from 236I<params> in the key object generation context I<genctx>. 237 238OSSL_FUNC_keymgmt_gen_settable_params() should return a constant array of 239descriptor L<OSSL_PARAM(3)>, for parameters that OSSL_FUNC_keymgmt_gen_set_params() 240can handle. 241 242OSSL_FUNC_keymgmt_gen() should perform the key object generation itself, and 243return the result. The callback I<cb> should be called at regular 244intervals with indications on how the key object generation 245progresses. 246 247OSSL_FUNC_keymgmt_gen_cleanup() should clean up and free the key object 248generation context I<genctx> 249 250OSSL_FUNC_keymgmt_load() creates a provider side key object based on a 251I<reference> object with a size of I<reference_sz> bytes, that only the 252provider knows how to interpret, but that may come from other operations. 253Outside the provider, this reference is simply an array of bytes. 254 255At least one of OSSL_FUNC_keymgmt_new(), OSSL_FUNC_keymgmt_gen() and 256OSSL_FUNC_keymgmt_load() are mandatory, as well as OSSL_FUNC_keymgmt_free() and 257OSSL_FUNC_keymgmt_has(). Additionally, if OSSL_FUNC_keymgmt_gen() is present, 258OSSL_FUNC_keymgmt_gen_init() and OSSL_FUNC_keymgmt_gen_cleanup() must be 259present as well. 260 261=head2 Key Object Information Functions 262 263OSSL_FUNC_keymgmt_get_params() should extract information data associated 264with the given I<keydata>, see L</Common Information Parameters>. 265 266OSSL_FUNC_keymgmt_gettable_params() should return a constant array of 267descriptor L<OSSL_PARAM(3)>, for parameters that OSSL_FUNC_keymgmt_get_params() 268can handle. 269 270If OSSL_FUNC_keymgmt_gettable_params() is present, OSSL_FUNC_keymgmt_get_params() 271must also be present, and vice versa. 272 273OSSL_FUNC_keymgmt_set_params() should update information data associated 274with the given I<keydata>, see L</Common Information Parameters>. 275 276OSSL_FUNC_keymgmt_settable_params() should return a constant array of 277descriptor L<OSSL_PARAM(3)>, for parameters that OSSL_FUNC_keymgmt_set_params() 278can handle. 279 280If OSSL_FUNC_keymgmt_settable_params() is present, OSSL_FUNC_keymgmt_set_params() 281must also be present, and vice versa. 282 283=head2 Key Object Checking Functions 284 285OSSL_FUNC_keymgmt_query_operation_name() should return the name of the 286supported algorithm for the operation I<operation_id>. This is 287similar to provider_query_operation() (see L<provider-base(7)>), 288but only works as an advisory. If this function is not present, or 289returns NULL, the caller is free to assume that there's an algorithm 290from the same provider, of the same name as the one used to fetch the 291keymgmt and try to use that. 292 293OSSL_FUNC_keymgmt_has() should check whether the given I<keydata> contains the subsets 294of data indicated by the I<selector>. A combination of several 295selector bits must consider all those subsets, not just one. An 296implementation is, however, free to consider an empty subset of data 297to still be a valid subset. For algorithms where some selection is 298not meaningful such as B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> for 299RSA keys the function should just return 1 as the selected subset 300is not really missing in the key. 301 302OSSL_FUNC_keymgmt_validate() should check if the I<keydata> contains valid 303data subsets indicated by I<selection>. Some combined selections of 304data subsets may cause validation of the combined data. 305For example, the combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and 306B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY> (or B<OSSL_KEYMGMT_SELECT_KEYPAIR> 307for short) is expected to check that the pairwise consistency of 308I<keydata> is valid. The I<checktype> parameter controls what type of check is 309performed on the subset of data. Two types of check are defined: 310B<OSSL_KEYMGMT_VALIDATE_FULL_CHECK> and B<OSSL_KEYMGMT_VALIDATE_QUICK_CHECK>. 311The interpretation of how much checking is performed in a full check versus a 312quick check is key type specific. Some providers may have no distinction 313between a full check and a quick check. For algorithms where some selection is 314not meaningful such as B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> for 315RSA keys the function should just return 1 as there is nothing to validate for 316that selection. 317 318OSSL_FUNC_keymgmt_match() should check if the data subset indicated by 319I<selection> in I<keydata1> and I<keydata2> match. It is assumed that 320the caller has ensured that I<keydata1> and I<keydata2> are both owned 321by the implementation of this function. 322 323=head2 Key Object Import, Export and Duplication Functions 324 325OSSL_FUNC_keymgmt_import() should import data indicated by I<selection> into 326I<keydata> with values taken from the L<OSSL_PARAM(3)> array I<params>. 327 328OSSL_FUNC_keymgmt_export() should extract values indicated by I<selection> 329from I<keydata>, create an L<OSSL_PARAM(3)> array with them and call 330I<param_cb> with that array as well as the given I<cbarg>. 331 332OSSL_FUNC_keymgmt_import_types() should return a constant array of descriptor 333L<OSSL_PARAM(3)> for data indicated by I<selection>, for parameters that 334OSSL_FUNC_keymgmt_import() can handle. 335 336OSSL_FUNC_keymgmt_export_types() should return a constant array of descriptor 337L<OSSL_PARAM(3)> for data indicated by I<selection>, that the 338OSSL_FUNC_keymgmt_export() callback can expect to receive. 339 340OSSL_FUNC_keymgmt_dup() should duplicate data subsets indicated by 341I<selection> or the whole key data I<keydata_from> and create a new 342provider side key object with the data. 343 344=head2 Common Information Parameters 345 346See L<OSSL_PARAM(3)> for further details on the parameters structure. 347 348Common information parameters currently recognised by all built-in 349keymgmt algorithms are as follows: 350 351=over 4 352 353=item "bits" (B<OSSL_PKEY_PARAM_BITS>) <integer> 354 355The value should be the cryptographic length of the cryptosystem to 356which the key belongs, in bits. The definition of cryptographic 357length is specific to the key cryptosystem. 358 359=item "max-size" (B<OSSL_PKEY_PARAM_MAX_SIZE>) <integer> 360 361The value should be the maximum size that a caller should allocate to 362safely store a signature (called I<sig> in L<provider-signature(7)>), 363the result of asymmmetric encryption / decryption (I<out> in 364L<provider-asym_cipher(7)>, a derived secret (I<secret> in 365L<provider-keyexch(7)>, and similar data). 366 367Because an EVP_KEYMGMT method is always tightly bound to another method 368(signature, asymmetric cipher, key exchange, ...) and must be of the 369same provider, this number only needs to be synchronised with the 370dimensions handled in the rest of the same provider. 371 372=item "security-bits" (B<OSSL_PKEY_PARAM_SECURITY_BITS>) <integer> 373 374The value should be the number of security bits of the given key. 375Bits of security is defined in SP800-57. 376 377=item "mandatory-digest" (B<OSSL_PKEY_PARAM_MANDATORY_DIGEST>) <UTF8 string> 378 379If there is a mandatory digest for performing a signature operation with 380keys from this keymgmt, this parameter should get its name as value. 381 382When EVP_PKEY_get_default_digest_name() queries this parameter and it's 383filled in by the implementation, its return value will be 2. 384 385If the keymgmt implementation fills in the value C<""> or C<"UNDEF">, 386L<EVP_PKEY_get_default_digest_name(3)> will place the string C<"UNDEF"> into 387its argument I<mdname>. This signifies that no digest should be specified 388with the corresponding signature operation. 389 390=item "default-digest" (B<OSSL_PKEY_PARAM_DEFAULT_DIGEST>) <UTF8 string> 391 392If there is a default digest for performing a signature operation with 393keys from this keymgmt, this parameter should get its name as value. 394 395When L<EVP_PKEY_get_default_digest_name(3)> queries this parameter and it's 396filled in by the implementation, its return value will be 1. Note that if 397B<OSSL_PKEY_PARAM_MANDATORY_DIGEST> is responded to as well, 398L<EVP_PKEY_get_default_digest_name(3)> ignores the response to this 399parameter. 400 401If the keymgmt implementation fills in the value C<""> or C<"UNDEF">, 402L<EVP_PKEY_get_default_digest_name(3)> will place the string C<"UNDEF"> into 403its argument I<mdname>. This signifies that no digest has to be specified 404with the corresponding signature operation, but may be specified as an 405option. 406 407=back 408 409=head1 RETURN VALUES 410 411OSSL_FUNC_keymgmt_new() and OSSL_FUNC_keymgmt_dup() should return a valid 412reference to the newly created provider side key object, or NULL on failure. 413 414OSSL_FUNC_keymgmt_import(), OSSL_FUNC_keymgmt_export(), OSSL_FUNC_keymgmt_get_params() and 415OSSL_FUNC_keymgmt_set_params() should return 1 for success or 0 on error. 416 417OSSL_FUNC_keymgmt_validate() should return 1 on successful validation, or 0 on 418failure. 419 420OSSL_FUNC_keymgmt_has() should return 1 if all the selected data subsets are contained 421in the given I<keydata> or 0 otherwise. 422 423OSSL_FUNC_keymgmt_query_operation_name() should return a pointer to a string matching 424the requested operation, or NULL if the same name used to fetch the keymgmt 425applies. 426 427OSSL_FUNC_keymgmt_gettable_params() and OSSL_FUNC_keymgmt_settable_params() 428OSSL_FUNC_keymgmt_import_types(), OSSL_FUNC_keymgmt_export_types() 429should 430always return a constant L<OSSL_PARAM(3)> array. 431 432=head1 SEE ALSO 433 434L<provider(7)>, 435L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>, L<EVP_PKEY-ED25519(7)>, 436L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-EC(7)>, L<EVP_PKEY-RSA(7)>, 437L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)> 438 439=head1 HISTORY 440 441The KEYMGMT interface was introduced in OpenSSL 3.0. 442 443=head1 COPYRIGHT 444 445Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. 446 447Licensed under the Apache License 2.0 (the "License"). You may not use 448this file except in compliance with the License. You can obtain a copy 449in the file LICENSE in the source distribution or at 450L<https://www.openssl.org/source/license.html>. 451 452=cut 453