EVP_KEM_FREE(3ossl)

💜 EVP_KEM_FREE — the OpenSSL 3ossl glow-up

okay so bestie, welcome to the KEM corner of OpenSSL ✨ this page is all about the little functions that manage EVP_KEM algorithm objects — fetching them, freeing them, refcounting them, naming them, and asking them nosy questions about their params. No crypto math here, just vibes and lifecycle management 🎀

---

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

---

🦋 DESCRIPTION 🦋

💫 the fetch era

EVP_KEM_fetch() is your main character moment — it goes and fetches the implementation for algorithm from any provider that's offering it, filtered by the criteria in properties, all within the scope of the library context ctx (peep OSSL_LIB_CTX(3) if you need the lore). The algorithm it hands you back is one that offers functions for doing asymmetric kem-type tasks — think key encapsulation and decapsulation ✨

if you want the full tea on how fetching works, check "ALGORITHM FETCHING" in crypto(7) 💅

and like, fr fr — the value that comes back must eventually be freed with EVP_KEM_free(). no ghosting your structs, bestie 😭

🧚 free & refcount energy

• EVP_KEM_free() decrements the reference count on the EVP_KEM structure. Usually you got this thing from an earlier call to EVP_KEM_fetch(). Once the refcount hits 0, the structure gets freed. And if the argument is NULL? literally nothing happens, it's giving unbothered 💀
• EVP_KEM_up_ref() is the opposite vibe — it increments the reference count on an EVP_KEM structure 🔥

👑 identity checks

• EVP_KEM_is_a() returns 1 if kem is an implementation of an algorithm that's identifiable with name, and 0 otherwise. it's a vibe check for algorithms 🫶
• EVP_KEM_get0_provider() returns the provider that kem was fetched from — like finding out which group chat they came from 🌈

⭐ the traversal girlies

• EVP_KEM_do_all_provided() walks all the EVP_KEMs implemented by all activated providers in the given library context libctx, and for each implementation it calls your function fn with the implementation method plus arg as the argument 🦋
• EVP_KEM_names_do_all() traverses all the names for kem, calling fn with each name and data 💜

🎀 names & descriptions

• EVP_KEM_get0_name() returns the algorithm name from the provided implementation for the given kem. Important caveat though — kem may have multiple synonyms associated with it, and in that case it returns the first name from the algorithm definition. Ownership of the returned string stays with the kem object, so do not free it yourself, bestie, that's not your string 🙈
• EVP_KEM_get0_description() returns a description of the kem, meant for display and human consumption. The description is entirely at the discretion of the kem implementation, so it's giving author's choice ✨

🔥 ctx params

EVP_KEM_gettable_ctx_params() and EVP_KEM_settable_ctx_params() return a constant OSSL_PARAM(3) array describing the names and types of key parameters that a key encapsulation algorithm can retrieve or set using EVP_PKEY_CTX_get_params(3) and EVP_PKEY_CTX_set_params(3). it's the parameter menu, basically 🍓

---

🌟 RETURN VALUES 🌟

• EVP_KEM_fetch() returns a pointer to an EVP_KEM for success, or NULL for 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 — so like, empty roster energy 💀
• 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)

---

💅 HISTORY 💅

The functions described here were added in OpenSSL 3.0 — so they're not new new, but they're still iconic 👑

---

🌸 COPYRIGHT 🌸

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

---

okay that's the whole page, bestie, you ate that 🫶 this was the EVP_KEM_FREE(3ossl) manual page, version 3.5.6, dated 2026-04-07 — go forth and manage your KEM objects responsibly, mwah 💖✨🎀