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