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. 65*a7148ab3SEnji CooperIf the argument is NULL, nothing is done. 66b077aed3SPierre Pronchery 67b077aed3SPierre ProncheryEVP_KEYMGMT_get0_provider() returns the provider that has this particular 68b077aed3SPierre Proncheryimplementation. 69b077aed3SPierre Pronchery 70b077aed3SPierre ProncheryEVP_KEYMGMT_is_a() checks if I<keymgmt> is an implementation of an 71b077aed3SPierre Proncheryalgorithm that's identifiable with I<name>. 72b077aed3SPierre Pronchery 73b077aed3SPierre ProncheryEVP_KEYMGMT_get0_name() returns the algorithm name from the provided 74b077aed3SPierre Proncheryimplementation for the given I<keymgmt>. Note that the I<keymgmt> may have 75b077aed3SPierre Proncherymultiple synonyms associated with it. In this case the first name from the 76b077aed3SPierre Proncheryalgorithm definition is returned. Ownership of the returned string is 77b077aed3SPierre Proncheryretained by the I<keymgmt> object and should not be freed by the caller. 78b077aed3SPierre Pronchery 79b077aed3SPierre ProncheryEVP_KEYMGMT_names_do_all() traverses all names for the I<keymgmt>, and 80b077aed3SPierre Proncherycalls I<fn> with each name and I<data>. 81b077aed3SPierre Pronchery 82b077aed3SPierre ProncheryEVP_KEYMGMT_get0_description() returns a description of the I<keymgmt>, meant 83b077aed3SPierre Proncheryfor display and human consumption. The description is at the discretion 84b077aed3SPierre Proncheryof the I<keymgmt> implementation. 85b077aed3SPierre Pronchery 86b077aed3SPierre ProncheryEVP_KEYMGMT_do_all_provided() traverses all key keymgmt implementations by 87b077aed3SPierre Proncheryall activated providers in the library context I<libctx>, and for each 88b077aed3SPierre Proncheryof the implementations, calls I<fn> with the implementation method and 89b077aed3SPierre ProncheryI<data> as arguments. 90b077aed3SPierre Pronchery 91b077aed3SPierre ProncheryEVP_KEYMGMT_gettable_params() and EVP_KEYMGMT_settable_params() return a 92b077aed3SPierre Proncheryconstant L<OSSL_PARAM(3)> array that describes the names and types of key 93b077aed3SPierre Proncheryparameters that can be retrieved or set. 94b077aed3SPierre ProncheryEVP_KEYMGMT_gettable_params() is used by L<EVP_PKEY_gettable_params(3)>. 95b077aed3SPierre Pronchery 96b077aed3SPierre ProncheryEVP_KEYMGMT_gen_settable_params() returns a constant L<OSSL_PARAM(3)> array that 97b077aed3SPierre Proncherydescribes the names and types of key generation parameters that can be set via 98b077aed3SPierre ProncheryL<EVP_PKEY_CTX_set_params(3)>. 99b077aed3SPierre Pronchery 100b077aed3SPierre Pronchery=head1 NOTES 101b077aed3SPierre Pronchery 102b077aed3SPierre ProncheryEVP_KEYMGMT_fetch() may be called implicitly by other fetching 103b077aed3SPierre Proncheryfunctions, using the same library context and properties. 104b077aed3SPierre ProncheryAny other API that uses keys will typically do this. 105b077aed3SPierre Pronchery 106b077aed3SPierre Pronchery=head1 RETURN VALUES 107b077aed3SPierre Pronchery 108b077aed3SPierre ProncheryEVP_KEYMGMT_fetch() returns a pointer to the key management 109b077aed3SPierre Proncheryimplementation represented by an EVP_KEYMGMT object, or NULL on 110b077aed3SPierre Proncheryerror. 111b077aed3SPierre Pronchery 112b077aed3SPierre ProncheryEVP_KEYMGMT_up_ref() returns 1 on success, or 0 on error. 113b077aed3SPierre Pronchery 114b077aed3SPierre ProncheryEVP_KEYMGMT_names_do_all() returns 1 if the callback was called for all 115b077aed3SPierre Proncherynames. A return value of 0 means that the callback was not called for any names. 116b077aed3SPierre Pronchery 117b077aed3SPierre ProncheryEVP_KEYMGMT_free() doesn't return any value. 118b077aed3SPierre Pronchery 119b077aed3SPierre ProncheryEVP_KEYMGMT_get0_provider() returns a pointer to a provider object, or NULL 120b077aed3SPierre Proncheryon error. 121b077aed3SPierre Pronchery 122b077aed3SPierre ProncheryEVP_KEYMGMT_is_a() returns 1 of I<keymgmt> was identifiable, 123b077aed3SPierre Proncheryotherwise 0. 124b077aed3SPierre Pronchery 125b077aed3SPierre ProncheryEVP_KEYMGMT_get0_name() returns the algorithm name, or NULL on error. 126b077aed3SPierre Pronchery 127aa795734SPierre ProncheryEVP_KEYMGMT_get0_description() returns a pointer to a description, or NULL if 128b077aed3SPierre Proncherythere isn't one. 129b077aed3SPierre Pronchery 130b077aed3SPierre ProncheryEVP_KEYMGMT_gettable_params(), EVP_KEYMGMT_settable_params() and 131b077aed3SPierre ProncheryEVP_KEYMGMT_gen_settable_params() return a constant L<OSSL_PARAM(3)> array or 132b077aed3SPierre ProncheryNULL on error. 133b077aed3SPierre Pronchery 134b077aed3SPierre Pronchery=head1 SEE ALSO 135b077aed3SPierre Pronchery 136b077aed3SPierre ProncheryL<EVP_MD_fetch(3)>, L<OSSL_LIB_CTX(3)> 137b077aed3SPierre Pronchery 138b077aed3SPierre Pronchery=head1 HISTORY 139b077aed3SPierre Pronchery 140b077aed3SPierre ProncheryThe functions described here were added in OpenSSL 3.0. 141b077aed3SPierre Pronchery 142b077aed3SPierre Pronchery=head1 COPYRIGHT 143b077aed3SPierre Pronchery 144*a7148ab3SEnji CooperCopyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. 145b077aed3SPierre Pronchery 146b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 147b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 148b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 149b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 150b077aed3SPierre Pronchery 151b077aed3SPierre Pronchery=cut 152