1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryEVP_KEYEXCH_fetch, EVP_KEYEXCH_free, EVP_KEYEXCH_up_ref, 6b077aed3SPierre ProncheryEVP_KEYEXCH_get0_provider, EVP_KEYEXCH_is_a, EVP_KEYEXCH_do_all_provided, 7b077aed3SPierre ProncheryEVP_KEYEXCH_names_do_all, EVP_KEYEXCH_get0_name, EVP_KEYEXCH_get0_description, 8b077aed3SPierre ProncheryEVP_KEYEXCH_gettable_ctx_params, EVP_KEYEXCH_settable_ctx_params 9b077aed3SPierre Pronchery- Functions to manage EVP_KEYEXCH algorithm objects 10b077aed3SPierre Pronchery 11b077aed3SPierre Pronchery=head1 SYNOPSIS 12b077aed3SPierre Pronchery 13b077aed3SPierre Pronchery #include <openssl/evp.h> 14b077aed3SPierre Pronchery 15b077aed3SPierre Pronchery EVP_KEYEXCH *EVP_KEYEXCH_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, 16b077aed3SPierre Pronchery const char *properties); 17b077aed3SPierre Pronchery void EVP_KEYEXCH_free(EVP_KEYEXCH *exchange); 18b077aed3SPierre Pronchery int EVP_KEYEXCH_up_ref(EVP_KEYEXCH *exchange); 19b077aed3SPierre Pronchery OSSL_PROVIDER *EVP_KEYEXCH_get0_provider(const EVP_KEYEXCH *exchange); 20b077aed3SPierre Pronchery int EVP_KEYEXCH_is_a(const EVP_KEYEXCH *exchange, const char *name); 21b077aed3SPierre Pronchery const char *EVP_KEYEXCH_get0_name(const EVP_KEYEXCH *exchange); 22b077aed3SPierre Pronchery void EVP_KEYEXCH_do_all_provided(OSSL_LIB_CTX *libctx, 23b077aed3SPierre Pronchery void (*fn)(EVP_KEYEXCH *exchange, void *arg), 24b077aed3SPierre Pronchery void *arg); 25b077aed3SPierre Pronchery int EVP_KEYEXCH_names_do_all(const EVP_KEYEXCH *exchange, 26b077aed3SPierre Pronchery void (*fn)(const char *name, void *data), 27b077aed3SPierre Pronchery void *data); 28b077aed3SPierre Pronchery const char *EVP_KEYEXCH_get0_description(const EVP_KEYEXCH *keyexch); 29b077aed3SPierre Pronchery const OSSL_PARAM *EVP_KEYEXCH_gettable_ctx_params(const EVP_KEYEXCH *keyexch); 30b077aed3SPierre Pronchery const OSSL_PARAM *EVP_KEYEXCH_settable_ctx_params(const EVP_KEYEXCH *keyexch); 31b077aed3SPierre Pronchery 32b077aed3SPierre Pronchery=head1 DESCRIPTION 33b077aed3SPierre Pronchery 34b077aed3SPierre ProncheryEVP_KEYEXCH_fetch() fetches the key exchange implementation for the given 35b077aed3SPierre ProncheryI<algorithm> from any provider offering it, within the criteria given 36b077aed3SPierre Proncheryby the I<properties>. 37b077aed3SPierre ProncherySee L<crypto(7)/ALGORITHM FETCHING> for further information. 38b077aed3SPierre Pronchery 39b077aed3SPierre ProncheryThe returned value must eventually be freed with EVP_KEYEXCH_free(). 40b077aed3SPierre Pronchery 41b077aed3SPierre ProncheryEVP_KEYEXCH_free() decrements the reference count for the B<EVP_KEYEXCH> 42b077aed3SPierre Proncherystructure. Typically this structure will have been obtained from an earlier call 43b077aed3SPierre Proncheryto EVP_KEYEXCH_fetch(). If the reference count drops to 0 then the 44*a7148ab3SEnji Cooperstructure is freed. If the argument is NULL, nothing is done. 45b077aed3SPierre Pronchery 46b077aed3SPierre ProncheryEVP_KEYEXCH_up_ref() increments the reference count for an B<EVP_KEYEXCH> 47b077aed3SPierre Proncherystructure. 48b077aed3SPierre Pronchery 49b077aed3SPierre ProncheryEVP_KEYEXCH_get0_provider() returns the provider that I<exchange> was 50b077aed3SPierre Proncheryfetched from. 51b077aed3SPierre Pronchery 52b077aed3SPierre ProncheryEVP_KEYEXCH_is_a() checks if I<exchange> is an implementation of an 53b077aed3SPierre Proncheryalgorithm that's identifiable with I<name>. 54b077aed3SPierre Pronchery 55b077aed3SPierre ProncheryEVP_KEYEXCH_get0_name() returns the algorithm name from the provided 56b077aed3SPierre Proncheryimplementation for the given I<exchange>. Note that the I<exchange> may have 57b077aed3SPierre Proncherymultiple synonyms associated with it. In this case the first name from the 58b077aed3SPierre Proncheryalgorithm definition is returned. Ownership of the returned string is retained 59b077aed3SPierre Proncheryby the I<exchange> object and should not be freed by the caller. 60b077aed3SPierre Pronchery 61b077aed3SPierre ProncheryEVP_KEYEXCH_names_do_all() traverses all names for the I<exchange>, and 62b077aed3SPierre Proncherycalls I<fn> with each name and I<data>. 63b077aed3SPierre Pronchery 64b077aed3SPierre ProncheryEVP_KEYEXCH_get0_description() returns a description of the I<keyexch>, meant 65b077aed3SPierre Proncheryfor display and human consumption. The description is at the discretion of 66b077aed3SPierre Proncherythe I<keyexch> implementation. 67b077aed3SPierre Pronchery 68b077aed3SPierre ProncheryEVP_KEYEXCH_do_all_provided() traverses all key exchange implementations by 69b077aed3SPierre Proncheryall activated providers in the library context I<libctx>, and for each 70b077aed3SPierre Proncheryof the implementations, calls I<fn> with the implementation method and 71b077aed3SPierre ProncheryI<data> as arguments. 72b077aed3SPierre Pronchery 73b077aed3SPierre ProncheryEVP_KEYEXCH_gettable_ctx_params() and EVP_KEYEXCH_settable_ctx_params() return 74b077aed3SPierre Proncherya constant L<OSSL_PARAM(3)> array that describes the names and types of key 75b077aed3SPierre Proncheryparameters that can be retrieved or set by a key exchange algorithm using 76b077aed3SPierre ProncheryL<EVP_PKEY_CTX_get_params(3)> and L<EVP_PKEY_CTX_set_params(3)>. 77b077aed3SPierre Pronchery 78b077aed3SPierre Pronchery=head1 RETURN VALUES 79b077aed3SPierre Pronchery 80b077aed3SPierre ProncheryEVP_KEYEXCH_fetch() returns a pointer to a B<EVP_KEYEXCH> for success 81b077aed3SPierre Proncheryor NULL for failure. 82b077aed3SPierre Pronchery 83b077aed3SPierre ProncheryEVP_KEYEXCH_up_ref() returns 1 for success or 0 otherwise. 84b077aed3SPierre Pronchery 85b077aed3SPierre ProncheryEVP_KEYEXCH_names_do_all() returns 1 if the callback was called for all 86b077aed3SPierre Proncherynames. A return value of 0 means that the callback was not called for any names. 87b077aed3SPierre Pronchery 88b077aed3SPierre ProncheryEVP_KEYEXCH_is_a() returns 1 of I<exchange> was identifiable, 89b077aed3SPierre Proncheryotherwise 0. 90b077aed3SPierre Pronchery 91b077aed3SPierre ProncheryEVP_KEYEXCH_gettable_ctx_params() and EVP_KEYEXCH_settable_ctx_params() return 92b077aed3SPierre Proncherya constant L<OSSL_PARAM(3)> array or NULL on error. 93b077aed3SPierre Pronchery 94b077aed3SPierre Pronchery=head1 SEE ALSO 95b077aed3SPierre Pronchery 96b077aed3SPierre ProncheryL<crypto(7)/ALGORITHM FETCHING>, L<OSSL_PROVIDER(3)> 97b077aed3SPierre Pronchery 98b077aed3SPierre Pronchery=head1 HISTORY 99b077aed3SPierre Pronchery 100b077aed3SPierre ProncheryThe functions described here were added in OpenSSL 3.0. 101b077aed3SPierre Pronchery 102b077aed3SPierre Pronchery=head1 COPYRIGHT 103b077aed3SPierre Pronchery 104*a7148ab3SEnji CooperCopyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. 105b077aed3SPierre Pronchery 106b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 107b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 108b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 109b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 110b077aed3SPierre Pronchery 111b077aed3SPierre Pronchery=cut 112