=pod =head1 NAME provider-keymgmt - The KEYMGMT library E-E provider functions =head1 SYNOPSIS #include /* * None of these are actual functions, but are displayed like this for * the function signatures for functions that are offered as function * pointers in OSSL_DISPATCH arrays. */ /* Key object (keydata) creation and destruction */ void *OSSL_FUNC_keymgmt_new(void *provctx); void OSSL_FUNC_keymgmt_free(void *keydata); /* Generation, a more complex constructor */ void *OSSL_FUNC_keymgmt_gen_init(void *provctx, int selection, const OSSL_PARAM params[]); int OSSL_FUNC_keymgmt_gen_set_template(void *genctx, void *template); int OSSL_FUNC_keymgmt_gen_set_params(void *genctx, const OSSL_PARAM params[]); const OSSL_PARAM *OSSL_FUNC_keymgmt_gen_settable_params(void *genctx, void *provctx); void *OSSL_FUNC_keymgmt_gen(void *genctx, OSSL_CALLBACK *cb, void *cbarg); void OSSL_FUNC_keymgmt_gen_cleanup(void *genctx); /* Key loading by object reference, also a constructor */ void *OSSL_FUNC_keymgmt_load(const void *reference, size_t *reference_sz); /* Key object information */ int OSSL_FUNC_keymgmt_get_params(void *keydata, OSSL_PARAM params[]); const OSSL_PARAM *OSSL_FUNC_keymgmt_gettable_params(void *provctx); int OSSL_FUNC_keymgmt_set_params(void *keydata, const OSSL_PARAM params[]); const OSSL_PARAM *OSSL_FUNC_keymgmt_settable_params(void *provctx); /* Key object content checks */ int OSSL_FUNC_keymgmt_has(const void *keydata, int selection); int OSSL_FUNC_keymgmt_match(const void *keydata1, const void *keydata2, int selection); /* Discovery of supported operations */ const char *OSSL_FUNC_keymgmt_query_operation_name(int operation_id); /* Key object import and export functions */ int OSSL_FUNC_keymgmt_import(void *keydata, int selection, const OSSL_PARAM params[]); const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types(int selection); const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types_ex(void *provctx, int selection); int OSSL_FUNC_keymgmt_export(void *keydata, int selection, OSSL_CALLBACK *param_cb, void *cbarg); const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types(int selection); const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types_ex(void *provctx, int selection); /* Key object duplication, a constructor */ void *OSSL_FUNC_keymgmt_dup(const void *keydata_from, int selection); /* Key object validation */ int OSSL_FUNC_keymgmt_validate(const void *keydata, int selection, int checktype); =head1 DESCRIPTION The KEYMGMT operation doesn't have much public visibility in OpenSSL libraries, it's rather an internal operation that's designed to work in tandem with operations that use private/public key pairs. Because the KEYMGMT operation shares knowledge with the operations it works with in tandem, they must belong to the same provider. The OpenSSL libraries will ensure that they do. The primary responsibility of the KEYMGMT operation is to hold the provider side key data for the OpenSSL library EVP_PKEY structure. All "functions" mentioned here are passed as function pointers between F and the provider in L arrays via L arrays that are returned by the provider's provider_query_operation() function (see L). All these "functions" have a corresponding function type definition named B, and a helper function to retrieve the function pointer from a L element named B. For example, the "function" OSSL_FUNC_keymgmt_new() has these: typedef void *(OSSL_FUNC_keymgmt_new_fn)(void *provctx); static ossl_inline OSSL_FUNC_keymgmt_new_fn OSSL_FUNC_keymgmt_new(const OSSL_DISPATCH *opf); L arrays are indexed by numbers that are provided as macros in L, as follows: OSSL_FUNC_keymgmt_new OSSL_FUNC_KEYMGMT_NEW OSSL_FUNC_keymgmt_free OSSL_FUNC_KEYMGMT_FREE OSSL_FUNC_keymgmt_gen_init OSSL_FUNC_KEYMGMT_GEN_INIT OSSL_FUNC_keymgmt_gen_set_template OSSL_FUNC_KEYMGMT_GEN_SET_TEMPLATE OSSL_FUNC_keymgmt_gen_set_params OSSL_FUNC_KEYMGMT_GEN_SET_PARAMS OSSL_FUNC_keymgmt_gen_settable_params OSSL_FUNC_KEYMGMT_GEN_SETTABLE_PARAMS OSSL_FUNC_keymgmt_gen OSSL_FUNC_KEYMGMT_GEN OSSL_FUNC_keymgmt_gen_cleanup OSSL_FUNC_KEYMGMT_GEN_CLEANUP OSSL_FUNC_keymgmt_load OSSL_FUNC_KEYMGMT_LOAD OSSL_FUNC_keymgmt_get_params OSSL_FUNC_KEYMGMT_GET_PARAMS OSSL_FUNC_keymgmt_gettable_params OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS OSSL_FUNC_keymgmt_set_params OSSL_FUNC_KEYMGMT_SET_PARAMS OSSL_FUNC_keymgmt_settable_params OSSL_FUNC_KEYMGMT_SETTABLE_PARAMS OSSL_FUNC_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME OSSL_FUNC_keymgmt_has OSSL_FUNC_KEYMGMT_HAS OSSL_FUNC_keymgmt_validate OSSL_FUNC_KEYMGMT_VALIDATE OSSL_FUNC_keymgmt_match OSSL_FUNC_KEYMGMT_MATCH OSSL_FUNC_keymgmt_import OSSL_FUNC_KEYMGMT_IMPORT OSSL_FUNC_keymgmt_import_types OSSL_FUNC_KEYMGMT_IMPORT_TYPES OSSL_FUNC_keymgmt_import_types_ex OSSL_FUNC_KEYMGMT_IMPORT_TYPES_EX OSSL_FUNC_keymgmt_export OSSL_FUNC_KEYMGMT_EXPORT OSSL_FUNC_keymgmt_export_types OSSL_FUNC_KEYMGMT_EXPORT_TYPES OSSL_FUNC_keymgmt_export_types_ex OSSL_FUNC_KEYMGMT_EXPORT_TYPES_EX OSSL_FUNC_keymgmt_dup OSSL_FUNC_KEYMGMT_DUP =head2 Key Objects A key object is a collection of data for an asymmetric key, and is represented as I in this manual. The exact contents of a key object are defined by the provider, and it is assumed that different operations in one and the same provider use the exact same structure to represent this collection of data, so that for example, a key object that has been created using the KEYMGMT interface that we document here can be passed as is to other provider operations, such as OP_signature_sign_init() (see L). With some of the KEYMGMT functions, it's possible to select a specific subset of data to handle, governed by the bits in a I indicator. The bits are: =over 4 =item B Indicating that the private key data in a key object should be considered. =item B Indicating that the public key data in a key object should be considered. =item B Indicating that the domain parameters in a key object should be considered. =item B Indicating that other parameters in a key object should be considered. Other parameters are key parameters that don't fit any other classification. In other words, this particular selector bit works as a last resort bit bucket selector. =back Some selector bits have also been combined for easier use: =over 4 =item B Indicating that all key object parameters should be considered, regardless of their more granular classification. =for comment This should used by EVP functions such as EVP_PKEY_copy_parameters() and EVP_PKEY_parameters_eq() This is a combination of B and B. =for comment If more parameter categories are added, they should be mentioned here too. =item B Indicating that both the whole key pair in a key object should be considered, i.e. the combination of public and private key. This is a combination of B and B. =item B Indicating that everything in a key object should be considered. =back The exact interpretation of those bits or how they combine is left to each function where you can specify a selector. It's left to the provider implementation to decide what is reasonable to do with regards to received selector bits and how to do it. Among others, an implementation of OSSL_FUNC_keymgmt_match() might opt to not compare the private half if it has compared the public half, since a match of one half implies a match of the other half. =head2 Constructing and Destructing Functions OSSL_FUNC_keymgmt_new() should create a provider side key object. The provider context I is passed and may be incorporated in the key object, but that is not mandatory. OSSL_FUNC_keymgmt_free() should free the passed I. OSSL_FUNC_keymgmt_gen_init(), OSSL_FUNC_keymgmt_gen_set_template(), OSSL_FUNC_keymgmt_gen_set_params(), OSSL_FUNC_keymgmt_gen_settable_params(), OSSL_FUNC_keymgmt_gen() and OSSL_FUNC_keymgmt_gen_cleanup() work together as a more elaborate context based key object constructor. OSSL_FUNC_keymgmt_gen_init() should create the key object generation context and initialize it with I, which will determine what kind of contents the key object to be generated should get. The I, if not NULL, should be set on the context in a manner similar to using OSSL_FUNC_keymgmt_set_params(). OSSL_FUNC_keymgmt_gen_set_template() should add I