EVP_KEYEXCH_FREE(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

💖 EVP_KEYEXCH_FREE 💖

okay bestie, welcome to the EVP_KEYEXCH_FREE(3SSL) era ✨ this is the whole vibe of managing EVP_KEYEXCH algorithm objects — fetching them, freeing them, refcounting them, and snooping on all their little names. it's giving "key exchange implementation handler" and honestly? iconic. 💅

🌸 NAME 🌸

EVP_KEYEXCH_fetch, EVP_KEYEXCH_free, EVP_KEYEXCH_up_ref, EVP_KEYEXCH_get0_provider, EVP_KEYEXCH_is_a, EVP_KEYEXCH_do_all_provided, EVP_KEYEXCH_names_do_all, EVP_KEYEXCH_get0_name, EVP_KEYEXCH_get0_description, EVP_KEYEXCH_gettable_ctx_params, EVP_KEYEXCH_settable_ctx_params — literally the functions that manage EVP_KEYEXCH algorithm objects 🫶

✨ SYNOPSIS ✨

#include <openssl/evp.h>

EVP_KEYEXCH *EVP_KEYEXCH_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
                               const char *properties);
void EVP_KEYEXCH_free(EVP_KEYEXCH *exchange);
int EVP_KEYEXCH_up_ref(EVP_KEYEXCH *exchange);
OSSL_PROVIDER *EVP_KEYEXCH_get0_provider(const EVP_KEYEXCH *exchange);
int EVP_KEYEXCH_is_a(const EVP_KEYEXCH *exchange, const char *name);
const char *EVP_KEYEXCH_get0_name(const EVP_KEYEXCH *exchange);
void EVP_KEYEXCH_do_all_provided(OSSL_LIB_CTX *libctx,
                                 void (*fn)(EVP_KEYEXCH *exchange, void *arg),
                                 void *arg);
int EVP_KEYEXCH_names_do_all(const EVP_KEYEXCH *exchange,
                             void (*fn)(const char *name, void *data),
                             void *data);
const char *EVP_KEYEXCH_get0_description(const EVP_KEYEXCH *keyexch);
const OSSL_PARAM *EVP_KEYEXCH_gettable_ctx_params(const EVP_KEYEXCH *keyexch);
const OSSL_PARAM *EVP_KEYEXCH_settable_ctx_params(const EVP_KEYEXCH *keyexch);

👑 DESCRIPTION 👑

okay so, function by function, no skips:

  • EVP_KEYEXCH_fetch() fetches the key exchange implementation for the given algorithm from any provider willing to offer it, and it has to fit inside the criteria you handed it via properties. if you wanna go deeper on how fetching even works, go read "ALGORITHM FETCHING" in crypto(7). 📚
the value it gives you back must eventually get freed with EVP_KEYEXCH_free(). fr fr, do not just leave it there bestie, that's a leak. 💀
  • EVP_KEYEXCH_free() decrements the reference count on the EVP_KEYEXCH structure. usually this structure came from an earlier EVP_KEYEXCH_fetch() call. the moment that refcount hits 0, the structure gets freed. and if the argument is NULL? nothing happens. not a single thing. we love a function that minds its own business. 🙈
  • EVP_KEYEXCH_up_ref() increments the reference count for an EVP_KEYEXCH structure. hold it down, keep it alive. 🫶
  • EVP_KEYEXCH_get0_provider() returns the provider that exchange was fetched from. iykyk which one babe.
  • EVP_KEYEXCH_is_a() checks if exchange is an implementation of an algorithm that's identifiable with name. 🕵️
  • EVP_KEYEXCH_get0_name() returns the algorithm name from the provided implementation for the given exchange. heads up though — the exchange can have multiple synonyms associated with it, and in that case you get the first name from the algorithm definition. also, ownership of the returned string stays with the exchange object, so do not free it yourself, that's not your string to free. 🙅
  • EVP_KEYEXCH_names_do_all() walks through all the names for the exchange, hitting up fn with each name and data. a little tour of the whole name roster. 🌈
  • EVP_KEYEXCH_get0_description() returns a description of the keyexch, and it's meant for display and human consumption — like, for actual eyeballs. the description itself is entirely at the discretion of the keyexch implementation. 👀
  • EVP_KEYEXCH_do_all_provided() traverses every key exchange implementation across all the activated providers in the library context libctx, and for each implementation it calls fn with the implementation method and data as the arguments. main character energy: it visits everyone. 👑
  • EVP_KEYEXCH_gettable_ctx_params() and EVP_KEYEXCH_settable_ctx_params() return a constant OSSL_PARAM(3) array that describes the names and types of key parameters that a key exchange algorithm can retrieve or set using EVP_PKEY_CTX_get_params(3) and EVP_PKEY_CTX_set_params(3). basically the menu of what's gettable and what's settable. 🍓

🎀 RETURN VALUES 🎀

  • EVP_KEYEXCH_fetch() returns a pointer to an EVP_KEYEXCH on success, or NULL on failure. 🤞
  • EVP_KEYEXCH_up_ref() returns 1 for success or 0 otherwise.
  • EVP_KEYEXCH_names_do_all() returns 1 if the callback was called for all names. a return value of 0 means the callback was not called for any names.
  • EVP_KEYEXCH_is_a() returns 1 if exchange was identifiable, otherwise 0.
  • EVP_KEYEXCH_gettable_ctx_params() and EVP_KEYEXCH_settable_ctx_params() return a constant OSSL_PARAM(3) array, or NULL on error.

🔥 SEE ALSO 🔥

"ALGORITHM FETCHING" in crypto(7), OSSL_PROVIDER(3)

💜 HISTORY 💜

the functions described right here were added in OpenSSL 3.0. so yeah, they're relatively fresh, and they ate. 💅

Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

and that's the whole page bestie, no cap 🧚 this was EVP_KEYEXCH_FREE(3SSL) from the 4.0.3 drop, dated 2026-09-29. go forth and manage your key exchange objects responsibly, mwah 💖🦋✨

📦 where this page comes from