EVP_ASYM_CIPHER_FREE(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💖 EVP_ASYM_CIPHER_FREE — OpenSSL 3ossl girlypop edition 🎀

okay so bestie, this is the 3ossl manual page for the whole EVP_ASYM_CIPHER squad, and I promise it's not as scary as it looks. It's giving "reference page" but honestly it's just a group chat of functions that manage EVP_ASYM_CIPHER algorithm objects. Let's get into it ✨

🌸 NAME 🌸

Girl, meet the whole crew: EVP_ASYM_CIPHER_fetch, EVP_ASYM_CIPHER_free, EVP_ASYM_CIPHER_up_ref, EVP_ASYM_CIPHER_is_a, EVP_ASYM_CIPHER_get0_provider, EVP_ASYM_CIPHER_do_all_provided, EVP_ASYM_CIPHER_names_do_all, EVP_ASYM_CIPHER_get0_name, EVP_ASYM_CIPHER_get0_description, EVP_ASYM_CIPHER_gettable_ctx_params, EVP_ASYM_CIPHER_settable_ctx_params — and what do they all do? They're the functions to manage EVP_ASYM_CIPHER algorithm objects. That's it, that's the vibe 💅

🌈 SYNOPSIS 🌈

#include <openssl/evp.h>

EVP_ASYM_CIPHER *EVP_ASYM_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
                                       const char *properties);
void EVP_ASYM_CIPHER_free(EVP_ASYM_CIPHER *cipher);
int EVP_ASYM_CIPHER_up_ref(EVP_ASYM_CIPHER *cipher);
const char *EVP_ASYM_CIPHER_get0_name(const EVP_ASYM_CIPHER *cipher);
int EVP_ASYM_CIPHER_is_a(const EVP_ASYM_CIPHER *cipher, const char *name);
OSSL_PROVIDER *EVP_ASYM_CIPHER_get0_provider(const EVP_ASYM_CIPHER *cipher);
void EVP_ASYM_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx,
                                     void (*fn)(EVP_ASYM_CIPHER *cipher,
                                                void *arg),
                                     void *arg);
int EVP_ASYM_CIPHER_names_do_all(const EVP_ASYM_CIPHER *cipher,
                                 void (*fn)(const char *name, void *data),
                                 void *data);
const char *EVP_ASYM_CIPHER_get0_description(const EVP_ASYM_CIPHER *cipher);
const OSSL_PARAM *EVP_ASYM_CIPHER_gettable_ctx_params(const EVP_ASYM_CIPHER *cip);
const OSSL_PARAM *EVP_ASYM_CIPHER_settable_ctx_params(const EVP_ASYM_CIPHER *cip);

Like, copy it exactly, don't freestyle the signatures, they're iconic as-is 🫶

✨ DESCRIPTION ✨

🦋 the fetch era

EVP_ASYM_CIPHER_fetch() goes out and fetches the implementation for the given algorithm from any provider that's offering it, within the criteria given by the properties and in the scope of the given library context ctx (peep OSSL_LIB_CTX(3) for the deets). And what kind of algorithm is it? The kind offering functions for performing asymmetric cipher related tasks, like asymmetric encryption and decryption. No cap, that's the whole point. See "ALGORITHM FETCHING" in crypto(7) for further information, okay bestie?

🚨 real talk: the returned value must eventually be freed with EVP_ASYM_CIPHER_free(). Don't just leave it out there, that's not giving responsibility.

🎀 refcount szn

EVP_ASYM_CIPHER_free() decrements the reference count for the EVP_ASYM_CIPHER structure. Typically this structure will have been obtained from an earlier call to EVP_ASYM_CIPHER_fetch(). If the reference count drops to 0 then the structure is freed. And if the argument is NULL? Nothing is done. Chillest function ever, lowkey.

EVP_ASYM_CIPHER_up_ref() does the opposite energy — it increments the reference count for an EVP_ASYM_CIPHER structure. Keeping that thing alive 💖

💀 identity check

EVP_ASYM_CIPHER_is_a() returns 1 if cipher is an implementation of an algorithm that's identifiable with name, otherwise 0. It's a vibe check, but for algorithms.

👑 provider lore

EVP_ASYM_CIPHER_get0_provider() returns the provider that cipher was fetched from. Like finding out which friend group they came from.

🌟 the traversal ones

EVP_ASYM_CIPHER_do_all_provided() traverses all EVP_ASYM_CIPHERs implemented by all activated providers in the given library context libctx, and for each of the implementations, calls the given function fn with the implementation method and the given arg as argument. Group tour, everyone gets a turn ✨

EVP_ASYM_CIPHER_get0_name() returns the algorithm name from the provided implementation for the given cipher. But heads up — the cipher may have multiple synonyms associated with it, and in that case the first name from the algorithm definition is returned. Also super important: ownership of the returned string is retained by the cipher object and should not be freed by the caller. So do not touch, do not free, do not pass go 🙈

EVP_ASYM_CIPHER_names_do_all() traverses all names for cipher, and calls fn with each name and data. Every alias gets its moment 💅

EVP_ASYM_CIPHER_get0_description() returns a description of the cipher, meant for display and human consumption. And here's the thing — the description is at the discretion of the cipher implementation. So whatever it says, that's what it says, iykyk.

🍓 params girly

EVP_ASYM_CIPHER_gettable_ctx_params() and EVP_ASYM_CIPHER_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 encryption algorithm using EVP_PKEY_CTX_get_params(3) and EVP_PKEY_CTX_set_params(3). Yes, that's a mouthful. Yes, it's correct. Slay.

🔥 RETURN VALUES 🔥

  • EVP_ASYM_CIPHER_fetch() — returns a pointer to an EVP_ASYM_CIPHER for success, or NULL for failure 😭
  • EVP_ASYM_CIPHER_up_ref() — returns 1 for success or 0 otherwise
  • EVP_ASYM_CIPHER_names_do_all() — returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names. (Not me realizing that's a very specific definition, but okay, that's what it says 💀)
  • EVP_ASYM_CIPHER_gettable_ctx_params() and EVP_ASYM_CIPHER_settable_ctx_params() — return a constant OSSL_PARAM(3) array or NULL on error

🧚 SEE ALSO 🧚

Go read those, bestie, they're the prerequisites fr fr 🌸

⭐ HISTORY ⭐

The functions described here were added in OpenSSL 3.0. Retro but make it modern, we love an origin story 💜

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

okay that's the whole page, you made it, I'm so proud of you 🫶✨ this was version 3.5.6, dated 2026-04-07, bringing you EVP_ASYM_CIPHER_FREE(3ossl) — go forth and fetch responsibly, mwah 💋🎀

📦 where this page comes from