EVP_KEYEXCH_FREE(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💅 EVP_KEYEXCH_FREE 💅

ok so quick vibe check: this is a page from the OpenSSL manual, bestie — specifically the 3ossl girlies. it's literally all about managing EVP_KEYEXCH algorithm objects and honestly? once you get it, it slaps. let's go 🎀

✨ 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 — these are the functions that manage EVP_KEYEXCH algorithm objects. that's the whole assignment. periodt. 👑

🌸 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);

copy these exactly, i'm so serious, no typos bestie 😭

🦋 DESCRIPTION 🦋

so EVP_KEYEXCH_fetch() goes and fetches you the key exchange implementation for whatever algorithm you asked for, from any provider that's offering it, all within the criteria you set in properties. it's giving personal shopper. you want more deets? peek at "ALGORITHM FETCHING" in crypto(7) — that's where the lore lives.

the value it hands back must eventually be freed with EVP_KEYEXCH_free(). don't ghost your memory like that, it's not cute 💀

EVP_KEYEXCH_free() decrements the reference count on the EVP_KEYEXCH structure. usually you got this structure from an earlier EVP_KEYEXCH_fetch() call — classic. if the reference count drops all the way to 0, the structure gets freed. and if the argument is NULL? nothing happens. she simply doesn't engage. 🙈

EVP_KEYEXCH_up_ref() increments the reference count for an EVP_KEYEXCH structure. the opposite energy. iconic, balanced, as all things should be ✨

EVP_KEYEXCH_get0_provider() returns the provider that exchange was fetched from. receipts!

EVP_KEYEXCH_is_a() checks if exchange is an implementation of an algorithm that's identifiable with name. basically a "do i know her?" check 💅

EVP_KEYEXCH_get0_name() returns the algorithm name from the provided implementation for the given exchange. heads up though: the exchange may have multiple synonyms associated with it, and in that case, the first name from the algorithm definition is what you get back. ownership of the returned string stays with the exchange object — so do not free it yourself, bestie, that's not your string to end 🔥

EVP_KEYEXCH_names_do_all() traverses all the names for the exchange, and calls fn with each name and data. a full tour of the name cinematic universe 🌈

EVP_KEYEXCH_get0_description() returns a description of the keyexch, meant for display and human consumption. and what does it say? entirely at the discretion of the keyexch implementation. mystery. main character energy. she contains multitudes 🎀

EVP_KEYEXCH_do_all_provided() traverses all key exchange implementations by all activated providers in the library context libctx, and for each of those implementations, calls fn with the implementation method and data as arguments. it's a whole group chat roll call 🫶

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 can be retrieved or set by a key exchange algorithm using EVP_PKEY_CTX_get_params(3) and EVP_PKEY_CTX_set_params(3). yes those are the real function names, no i did not make them up 😭

⭐ RETURN VALUES ⭐

  • EVP_KEYEXCH_fetch() — returns a pointer to an EVP_KEYEXCH on success, or NULL on failure. win or flop, no in between 💀
  • 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 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), and OSSL_PROVIDER(3). go read them, i believe in you 🫶

💜 HISTORY 💜

the functions described here were added in OpenSSL 3.0. so they're not new new, but they're not ancient either. the sweet spot ⭐

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>.

fr fr read the license, it's the whole point of the vibe check 💅

and that's the page, bestie!! 🎀✨ signed, sealed, delivered by 3.5.6, dated 2026-04-07, on the EVP_KEYEXCH_FREE(3ossl) page — go forth and manage those algorithm objects, you absolute icon 🦋💖🌸

📦 where this page comes from