EVP_KEM_FREE(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

💖 EVP_KEM_FREE ✨

okay so bestie, this is the <openssl/evp.h> girlie who manages your EVP_KEM algorithm objects, from the OpenSSL squad 💅 technically the page is EVP_KEM_FREE(3SSL) and she's part of the OpenSSL family, but honestly she's so much more than one function, she's a whole friend group of functions. let's get into it 🫶

🌸 NAME 🌸

EVP_KEM_fetch, EVP_KEM_free, EVP_KEM_up_ref, EVP_KEM_get0_name, EVP_KEM_is_a, EVP_KEM_get0_provider, EVP_KEM_do_all_provided, EVP_KEM_names_do_all, EVP_KEM_get0_description, EVP_KEM_gettable_ctx_params, EVP_KEM_settable_ctx_params — the functions that manage your EVP_KEM algorithm objects. no cap, that's literally the whole job description 💖

✨ SYNOPSIS ✨

#include <openssl/evp.h>

EVP_KEM *EVP_KEM_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
                       const char *properties);
void EVP_KEM_free(EVP_KEM *kem);
int EVP_KEM_up_ref(EVP_KEM *kem);
const char *EVP_KEM_get0_name(const EVP_KEM *kem);
int EVP_KEM_is_a(const EVP_KEM *kem, const char *name);
OSSL_PROVIDER *EVP_KEM_get0_provider(const EVP_KEM *kem);
void EVP_KEM_do_all_provided(OSSL_LIB_CTX *libctx,
                             void (*fn)(EVP_KEM *kem, void *arg), void *arg);
int EVP_KEM_names_do_all(const EVP_KEM *kem,
                         void (*fn)(const char *name, void *data), void *data);
const char *EVP_KEM_get0_description(const EVP_KEM *kem);
const OSSL_PARAM *EVP_KEM_gettable_ctx_params(const EVP_KEM *kem);
const OSSL_PARAM *EVP_KEM_settable_ctx_params(const EVP_KEM *kem);

like, look at them all, standing in a lil lineup 🎀 so organized.

👑 DESCRIPTION 👑

EVP_KEM_fetch() goes and fetches the implementation for the algorithm you asked for, from any provider that offers it, matching the criteria in properties, all scoped to the library context ctx (peep OSSL_LIB_CTX(3) for that one). the algorithm it brings back is one that offers functions for doing asymmetric kem-related tasks, aka key encapsulation and decapsulation 🔥 see "ALGORITHM FETCHING" in crypto(7) if you want the full lore.

bestie, listen: the returned value must eventually be freed with EVP_KEM_free(). that's not optional. that's the vibe check. 💀

EVP_KEM_free() decrements the reference count for the EVP_KEM structure. usually you got this structure from an earlier call to EVP_KEM_fetch(). if the reference count drops all the way to 0, then the structure is freed — she's gone, she said her goodbyes 💅 and if the argument is NULL? nothing happens. no drama. love that for us.

EVP_KEM_up_ref() increments the reference count for an EVP_KEM structure. keeping her alive, main character energy 👑

EVP_KEM_is_a() returns 1 if kem is an implementation of an algorithm that's identifiable with name, otherwise it returns 0. simple as that, no notes.

EVP_KEM_get0_provider() returns the provider that kem was fetched from. where's she from? now you know 🦋

EVP_KEM_do_all_provided() traverses all the EVP_KEMs implemented by all activated providers in the given library context libctx, and for each of the implementations it calls the given function fn with the implementation method and the given arg as argument. it's giving full tour of the roster 🌈

EVP_KEM_get0_name() returns the algorithm name from the provided implementation for the given kem. heads up though: the kem may have multiple synonyms associated with it, and in that case the first name from the algorithm definition is what gets returned. also, ownership of the returned string stays with the kem object — do NOT free it yourself, that's her string, not yours 🙈

EVP_KEM_names_do_all() traverses all the names for kem, and calls fn with each name and data.

EVP_KEM_get0_description() returns a description of the kem, meant for display and human consumption 👀 the description is at the discretion of the kem implementation, so like, she decides what her bio says.

EVP_KEM_gettable_ctx_params() and EVP_KEM_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 encapsulation algorithm using EVP_PKEY_CTX_get_params(3) and EVP_PKEY_CTX_set_params(3) 🎀

💜 RETURN VALUES 💜

  • EVP_KEM_fetch() — returns a pointer to an EVP_KEM on success, or NULL on failure 😭
  • EVP_KEM_up_ref() — returns 1 for success, or 0 otherwise.
  • EVP_KEM_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_KEM_gettable_ctx_params() and EVP_KEM_settable_ctx_params() — return a constant OSSL_PARAM(3) array, or NULL on error.

🦋 SEE ALSO 🦋

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

go read the friends, they're iconic too ✨

⭐ HISTORY ⭐

the functions described here were added in OpenSSL 3.0 🌱 baby era, and look at them now.

Copyright 2020-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 skips, no skims, we read everything 💅 mwah 😘

OpenSSL version 4.0.3, dated 2026-09-29 — EVP_KEM_FREE(3SSL), and yes she ate. periodt 🎀💖

📦 where this page comes from