1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryEVP_KEYMGMT, 6b077aed3SPierre ProncheryEVP_KEYMGMT_fetch, 7b077aed3SPierre ProncheryEVP_KEYMGMT_up_ref, 8b077aed3SPierre ProncheryEVP_KEYMGMT_free, 9b077aed3SPierre ProncheryEVP_KEYMGMT_get0_provider, 10b077aed3SPierre ProncheryEVP_KEYMGMT_is_a, 11b077aed3SPierre ProncheryEVP_KEYMGMT_get0_description, 12b077aed3SPierre ProncheryEVP_KEYMGMT_get0_name, 13b077aed3SPierre ProncheryEVP_KEYMGMT_do_all_provided, 14b077aed3SPierre ProncheryEVP_KEYMGMT_names_do_all, 15b077aed3SPierre ProncheryEVP_KEYMGMT_gettable_params, 16b077aed3SPierre ProncheryEVP_KEYMGMT_settable_params, 17b077aed3SPierre ProncheryEVP_KEYMGMT_gen_settable_params 18b077aed3SPierre Pronchery- EVP key management routines 19b077aed3SPierre Pronchery 20b077aed3SPierre Pronchery=head1 SYNOPSIS 21b077aed3SPierre Pronchery 22b077aed3SPierre Pronchery #include <openssl/evp.h> 23b077aed3SPierre Pronchery 24b077aed3SPierre Pronchery typedef struct evp_keymgmt_st EVP_KEYMGMT; 25b077aed3SPierre Pronchery 26b077aed3SPierre Pronchery EVP_KEYMGMT *EVP_KEYMGMT_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, 27b077aed3SPierre Pronchery const char *properties); 28b077aed3SPierre Pronchery int EVP_KEYMGMT_up_ref(EVP_KEYMGMT *keymgmt); 29b077aed3SPierre Pronchery void EVP_KEYMGMT_free(EVP_KEYMGMT *keymgmt); 30b077aed3SPierre Pronchery const OSSL_PROVIDER *EVP_KEYMGMT_get0_provider(const EVP_KEYMGMT *keymgmt); 31b077aed3SPierre Pronchery int EVP_KEYMGMT_is_a(const EVP_KEYMGMT *keymgmt, const char *name); 32b077aed3SPierre Pronchery const char *EVP_KEYMGMT_get0_name(const EVP_KEYMGMT *keymgmt); 33b077aed3SPierre Pronchery const char *EVP_KEYMGMT_get0_description(const EVP_KEYMGMT *keymgmt); 34b077aed3SPierre Pronchery 35b077aed3SPierre Pronchery void EVP_KEYMGMT_do_all_provided(OSSL_LIB_CTX *libctx, 36b077aed3SPierre Pronchery void (*fn)(EVP_KEYMGMT *keymgmt, void *arg), 37b077aed3SPierre Pronchery void *arg); 38b077aed3SPierre Pronchery int EVP_KEYMGMT_names_do_all(const EVP_KEYMGMT *keymgmt, 39b077aed3SPierre Pronchery void (*fn)(const char *name, void *data), 40b077aed3SPierre Pronchery void *data); 41b077aed3SPierre Pronchery const OSSL_PARAM *EVP_KEYMGMT_gettable_params(const EVP_KEYMGMT *keymgmt); 42b077aed3SPierre Pronchery const OSSL_PARAM *EVP_KEYMGMT_settable_params(const EVP_KEYMGMT *keymgmt); 43b077aed3SPierre Pronchery const OSSL_PARAM *EVP_KEYMGMT_gen_settable_params(const EVP_KEYMGMT *keymgmt); 44b077aed3SPierre Pronchery 45b077aed3SPierre Pronchery=head1 DESCRIPTION 46b077aed3SPierre Pronchery 47b077aed3SPierre ProncheryB<EVP_KEYMGMT> is a method object that represents key management 48b077aed3SPierre Proncheryimplementations for different cryptographic algorithms. 49b077aed3SPierre ProncheryThis method object provides functionality to have providers import key 50b077aed3SPierre Proncherymaterial from the outside, as well as export key material to the 51b077aed3SPierre Proncheryoutside. 52b077aed3SPierre ProncheryMost of the functionality can only be used internally and has no 53b077aed3SPierre Proncherypublic interface, this object is simply passed into other functions 54b077aed3SPierre Proncherywhen needed. 55b077aed3SPierre Pronchery 56b077aed3SPierre ProncheryEVP_KEYMGMT_fetch() looks for an algorithm within the provider that 57b077aed3SPierre Proncheryhas been loaded into the B<OSSL_LIB_CTX> given by I<ctx>, having the 58b077aed3SPierre Proncheryname given by I<algorithm> and the properties given by I<properties>. 59b077aed3SPierre Pronchery 60b077aed3SPierre ProncheryEVP_KEYMGMT_up_ref() increments the reference count for the given 61b077aed3SPierre ProncheryB<EVP_KEYMGMT> I<keymgmt>. 62b077aed3SPierre Pronchery 63b077aed3SPierre ProncheryEVP_KEYMGMT_free() decrements the reference count for the given 64b077aed3SPierre ProncheryB<EVP_KEYMGMT> I<keymgmt>, and when the count reaches zero, frees it. 65b077aed3SPierre Pronchery 66b077aed3SPierre ProncheryEVP_KEYMGMT_get0_provider() returns the provider that has this particular 67b077aed3SPierre Proncheryimplementation. 68b077aed3SPierre Pronchery 69b077aed3SPierre ProncheryEVP_KEYMGMT_is_a() checks if I<keymgmt> is an implementation of an 70b077aed3SPierre Proncheryalgorithm that's identifiable with I<name>. 71b077aed3SPierre Pronchery 72b077aed3SPierre ProncheryEVP_KEYMGMT_get0_name() returns the algorithm name from the provided 73b077aed3SPierre Proncheryimplementation for the given I<keymgmt>. Note that the I<keymgmt> may have 74b077aed3SPierre Proncherymultiple synonyms associated with it. In this case the first name from the 75b077aed3SPierre Proncheryalgorithm definition is returned. Ownership of the returned string is 76b077aed3SPierre Proncheryretained by the I<keymgmt> object and should not be freed by the caller. 77b077aed3SPierre Pronchery 78b077aed3SPierre ProncheryEVP_KEYMGMT_names_do_all() traverses all names for the I<keymgmt>, and 79b077aed3SPierre Proncherycalls I<fn> with each name and I<data>. 80b077aed3SPierre Pronchery 81b077aed3SPierre ProncheryEVP_KEYMGMT_get0_description() returns a description of the I<keymgmt>, meant 82b077aed3SPierre Proncheryfor display and human consumption. The description is at the discretion 83b077aed3SPierre Proncheryof the I<keymgmt> implementation. 84b077aed3SPierre Pronchery 85b077aed3SPierre ProncheryEVP_KEYMGMT_do_all_provided() traverses all key keymgmt implementations by 86b077aed3SPierre Proncheryall activated providers in the library context I<libctx>, and for each 87b077aed3SPierre Proncheryof the implementations, calls I<fn> with the implementation method and 88b077aed3SPierre ProncheryI<data> as arguments. 89b077aed3SPierre Pronchery 90b077aed3SPierre ProncheryEVP_KEYMGMT_gettable_params() and EVP_KEYMGMT_settable_params() return a 91b077aed3SPierre Proncheryconstant L<OSSL_PARAM(3)> array that describes the names and types of key 92b077aed3SPierre Proncheryparameters that can be retrieved or set. 93b077aed3SPierre ProncheryEVP_KEYMGMT_gettable_params() is used by L<EVP_PKEY_gettable_params(3)>. 94b077aed3SPierre Pronchery 95b077aed3SPierre ProncheryEVP_KEYMGMT_gen_settable_params() returns a constant L<OSSL_PARAM(3)> array that 96b077aed3SPierre Proncherydescribes the names and types of key generation parameters that can be set via 97b077aed3SPierre ProncheryL<EVP_PKEY_CTX_set_params(3)>. 98b077aed3SPierre Pronchery 99b077aed3SPierre Pronchery=head1 NOTES 100b077aed3SPierre Pronchery 101b077aed3SPierre ProncheryEVP_KEYMGMT_fetch() may be called implicitly by other fetching 102b077aed3SPierre Proncheryfunctions, using the same library context and properties. 103b077aed3SPierre ProncheryAny other API that uses keys will typically do this. 104b077aed3SPierre Pronchery 105b077aed3SPierre Pronchery=head1 RETURN VALUES 106b077aed3SPierre Pronchery 107b077aed3SPierre ProncheryEVP_KEYMGMT_fetch() returns a pointer to the key management 108b077aed3SPierre Proncheryimplementation represented by an EVP_KEYMGMT object, or NULL on 109b077aed3SPierre Proncheryerror. 110b077aed3SPierre Pronchery 111b077aed3SPierre ProncheryEVP_KEYMGMT_up_ref() returns 1 on success, or 0 on error. 112b077aed3SPierre Pronchery 113b077aed3SPierre ProncheryEVP_KEYMGMT_names_do_all() returns 1 if the callback was called for all 114b077aed3SPierre Proncherynames. A return value of 0 means that the callback was not called for any names. 115b077aed3SPierre Pronchery 116b077aed3SPierre ProncheryEVP_KEYMGMT_free() doesn't return any value. 117b077aed3SPierre Pronchery 118b077aed3SPierre ProncheryEVP_KEYMGMT_get0_provider() returns a pointer to a provider object, or NULL 119b077aed3SPierre Proncheryon error. 120b077aed3SPierre Pronchery 121b077aed3SPierre ProncheryEVP_KEYMGMT_is_a() returns 1 of I<keymgmt> was identifiable, 122b077aed3SPierre Proncheryotherwise 0. 123b077aed3SPierre Pronchery 124b077aed3SPierre ProncheryEVP_KEYMGMT_get0_name() returns the algorithm name, or NULL on error. 125b077aed3SPierre Pronchery 126*aa795734SPierre ProncheryEVP_KEYMGMT_get0_description() returns a pointer to a description, or NULL if 127b077aed3SPierre Proncherythere isn't one. 128b077aed3SPierre Pronchery 129b077aed3SPierre ProncheryEVP_KEYMGMT_gettable_params(), EVP_KEYMGMT_settable_params() and 130b077aed3SPierre ProncheryEVP_KEYMGMT_gen_settable_params() return a constant L<OSSL_PARAM(3)> array or 131b077aed3SPierre ProncheryNULL on error. 132b077aed3SPierre Pronchery 133b077aed3SPierre Pronchery=head1 SEE ALSO 134b077aed3SPierre Pronchery 135b077aed3SPierre ProncheryL<EVP_MD_fetch(3)>, L<OSSL_LIB_CTX(3)> 136b077aed3SPierre Pronchery 137b077aed3SPierre Pronchery=head1 HISTORY 138b077aed3SPierre Pronchery 139b077aed3SPierre ProncheryThe functions described here were added in OpenSSL 3.0. 140b077aed3SPierre Pronchery 141b077aed3SPierre Pronchery=head1 COPYRIGHT 142b077aed3SPierre Pronchery 143*aa795734SPierre ProncheryCopyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. 144b077aed3SPierre Pronchery 145b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 146b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 147b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 148b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 149b077aed3SPierre Pronchery 150b077aed3SPierre Pronchery=cut 151