EVP_KEM_FREE(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 EVP_KEM_FREE — bestie's guide to managing EVP_KEM algorithm objects

okay so this is from the ossl manual family (OpenSSL, hi 👋), and it's literally all the little functions that babysit an EVP_KEM object — fetching it, freeing it, refcounting it, asking it its name, that whole vibe. no cap, it's the management layer for key encapsulation algorithm objects and we're gonna get into it 💖

✨ SYNOPSIS ✨

like, drop this in first:

#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 fetching era 🌸

EVP_KEM_fetch() pulls the implementation for the algorithm you asked for from any provider that's offering it, matching against the criteria in properties and living inside the scope of the library context ctx (peep OSSL_LIB_CTX(3) for that one). the algorithm is gonna be one that offers functions for asymmetric kem-ish tasks — think key encapsulation and decapsulation 👑. more on the mechanics in "ALGORITHM FETCHING" in crypto(7).

🫶 real talk: whatever you get back from this must eventually be freed with EVP_KEM_free(). don't just abandon it, that's not the vibe.

refcounting, our beloved 💅

EVP_KEM_free() decrements the reference count on the EVP_KEM structure. typically you got that structure from an earlier EVP_KEM_fetch() call, iykyk. if the refcount drops to 0, the structure gets freed — periodt. and if the argument is NULL? nothing happens. iconic, no drama.

EVP_KEM_up_ref() increments the reference count for an EVP_KEM structure. that's it, that's the whole job 💖

identity checks ✨

EVP_KEM_is_a() returns 1 if kem is an implementation of an algorithm identifiable with name, otherwise 0.

EVP_KEM_get0_provider() returns the provider that kem was fetched from. 🧚

the tour de providers 🌈

EVP_KEM_do_all_provided() walks through 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 and arg as the argument. like a little parade of KEMs, and you're the one waving at each one 🎀

names, names, names ⭐

EVP_KEM_get0_name() returns the algorithm name from the provided implementation for the given kem. heads up though: kem may have multiple synonyms hanging out with it — in that case, the first name from the algorithm definition is the one that comes back. and the ownership tea ☕: the returned string is retained by the kem object, so do not free it yourself, bestie.

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

what is it even 📝

EVP_KEM_get0_description() returns a description of the kem, meant for display and human consumption. the description itself is totally at the discretion of the kem implementation, so it can be whatever it wants to be. main character energy fr fr.

params, get and set 🍓

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 can be retrieved or set by a key encapsulation algorithm, using EVP_PKEY_CTX_get_params(3) and EVP_PKEY_CTX_set_params(3). very much giving "here's the menu" 🫶

🔥 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 👀

📜 HISTORY 📜

the functions described here were added in OpenSSL 3.0. so they're not new new, but they're not ancient either — gen z of the API if you will 💜

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 🎀 this was EVP_KEM_FREE(3ossl), version 3.5.0, dated 2026-09-25 — slay, go forth and manage your KEM objects responsibly 💅✨

📦 where this page comes from