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