EVP_KEYMGMT(3ossl)

📦
version 3.5.9 · 8 versions
, in fedora 43, fedora 44

💖 EVP_KEYMGMT — the key management glow-up (OpenSSL, EVP_KEYMGMT(3ossl)) 💖

okay bestie, sit down, hydrate, because we're talking about key management method objects and it's genuinely so much cooler than it sounds. this whole page is the manual for EVP_KEYMGMT and its little friend group: EVP_KEYMGMT_fetch, EVP_KEYMGMT_up_ref, EVP_KEYMGMT_free, EVP_KEYMGMT_get0_provider, EVP_KEYMGMT_is_a, EVP_KEYMGMT_get0_description, EVP_KEYMGMT_get0_name, EVP_KEYMGMT_do_all_provided, EVP_KEYMGMT_names_do_all, EVP_KEYMGMT_gettable_params, EVP_KEYMGMT_settable_params, EVP_KEYMGMT_gen_gettable_params, EVP_KEYMGMT_gen_settable_params — aka the EVP key management routines. let's go 🦋

✨ SYNOPSIS ✨

like, here's the whole cast list in code form, no notes:

#include <openssl/evp.h>

typedef struct evp_keymgmt_st EVP_KEYMGMT;

EVP_KEYMGMT *EVP_KEYMGMT_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
                               const char *properties);
int EVP_KEYMGMT_up_ref(EVP_KEYMGMT *keymgmt);
void EVP_KEYMGMT_free(EVP_KEYMGMT *keymgmt);
const OSSL_PROVIDER *EVP_KEYMGMT_get0_provider(const EVP_KEYMGMT *keymgmt);
int EVP_KEYMGMT_is_a(const EVP_KEYMGMT *keymgmt, const char *name);
const char *EVP_KEYMGMT_get0_name(const EVP_KEYMGMT *keymgmt);
const char *EVP_KEYMGMT_get0_description(const EVP_KEYMGMT *keymgmt);

void EVP_KEYMGMT_do_all_provided(OSSL_LIB_CTX *libctx,
                                 void (*fn)(EVP_KEYMGMT *keymgmt, void *arg),
                                 void *arg);
int EVP_KEYMGMT_names_do_all(const EVP_KEYMGMT *keymgmt,
                             void (*fn)(const char *name, void *data),
                             void *data);
const OSSL_PARAM *EVP_KEYMGMT_gettable_params(const EVP_KEYMGMT *keymgmt);
const OSSL_PARAM *EVP_KEYMGMT_settable_params(const EVP_KEYMGMT *keymgmt);
const OSSL_PARAM *EVP_KEYMGMT_gen_settable_params(const EVP_KEYMGMT *keymgmt);
const OSSL_PARAM *EVP_KEYMGMT_gen_gettable_params(const EVP_KEYMGMT *keymgmt);

🌸 DESCRIPTION 🌸

okay so EVP_KEYMGMT is a method object that represents key management implementations for all the different cryptographic algorithms. think of it as the main character that lets providers import key material from the outside and also export key material to the outside. but here's the tea: most of this functionality is internal-only and has no public interface at all — this object basically just gets passed into other functions whenever they need it. it's giving backstage pass. 🎀

  • EVP_KEYMGMT_fetch() — goes looking for an algorithm inside the provider that's been loaded into the OSSL_LIB_CTX you passed as ctx, matching the name in algorithm and the properties in properties. 🕵️♀️
  • EVP_KEYMGMT_up_ref() — bumps the reference count on the given EVP_KEYMGMT keymgmt. up up up ⬆️
  • EVP_KEYMGMT_free() — drops the reference count on the given EVP_KEYMGMT keymgmt, and when that count hits zero, it frees it. and if the argument is NULL? nothing happens, no drama, no tears. 💀
  • EVP_KEYMGMT_get0_provider() — hands you back the provider that owns this particular implementation. 👑
  • EVP_KEYMGMT_is_a() — vibe checks whether keymgmt is an implementation of an algorithm that's identifiable with name.
  • EVP_KEYMGMT_get0_name() — returns the algorithm name from the provided implementation for the given keymgmt. heads up though: a keymgmt can have multiple synonyms attached to it, and in that case you get the first name from the algorithm definition. ownership of that returned string stays with the keymgmt object, so do NOT free it yourself, bestie, that's not your string. 🙈
  • EVP_KEYMGMT_names_do_all() — walks through every single name for the keymgmt and calls fn with each name and data. it's giving roll call. 📋
  • EVP_KEYMGMT_get0_description() — returns a description of the keymgmt, meant for display and human consumption. what that description actually says is entirely at the discretion of the keymgmt implementation. ✨
  • EVP_KEYMGMT_do_all_provided() — traverses all key keymgmt implementations across all activated providers in the library context libctx, and for each one it calls fn with the implementation method and data as arguments.
  • EVP_KEYMGMT_gettable_params() and EVP_KEYMGMT_settable_params() — return a constant OSSL_PARAM(3) array describing the names and types of key parameters that can be retrieved or set. also, EVP_KEYMGMT_gettable_params() is the one used by EVP_PKEY_gettable_params(3). 🫶
  • EVP_KEYMGMT_gen_gettable_params() and EVP_KEYMGMT_gen_settable_params() — return a constant OSSL_PARAM(3) array describing the names and types of key generation parameters that can be retrieved or set via EVP_PKEY_CTX_get_params(3) or EVP_PKEY_CTX_set_params(3) respectively. yes, respectively. we love a paired set. 💅

📝 NOTES 📝

EVP_KEYMGMT_fetch() might get called implicitly by other fetching functions, using the exact same library context and properties. honestly, any other API that touches keys will typically do this too. so if you're like "wait, who called fetch??" — it was the group chat, not you. 😭

💫 RETURN VALUES 💫

  • EVP_KEYMGMT_fetch() — returns a pointer to the key management implementation (as an EVP_KEYMGMT object), or NULL on error.
  • EVP_KEYMGMT_up_ref() — returns 1 on success, or 0 on error.
  • EVP_KEYMGMT_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_KEYMGMT_free() — returns absolutely nothing. doesn't return any value. periodt. 💅
  • EVP_KEYMGMT_get0_provider() — returns a pointer to a provider object, or NULL on error.
  • EVP_KEYMGMT_is_a() — returns 1 if keymgmt was identifiable, otherwise 0.
  • EVP_KEYMGMT_get0_name() — returns the algorithm name, or NULL on error.
  • EVP_KEYMGMT_get0_description() — returns a pointer to a description, or NULL if there isn't one.
  • EVP_KEYMGMT_gettable_params(), EVP_KEYMGMT_settable_params(), EVP_KEYMGMT_gen_gettable_params() and EVP_KEYMGMT_gen_settable_params() — return a constant OSSL_PARAM(3) array, or NULL on error. ✨

🦋 SEE ALSO 🦋

EVP_MD_fetch(3), OSSL_LIB_CTX(3)

go read those next, iykyk. 📚

🎀 HISTORY 🎀

  • EVP_KEYMGMT_gen_gettable_params() was added in OpenSSL 3.4.0 — the new girl on the block. 👑
  • All other functions described here were added in OpenSSL 3.0 — the OGs.

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 ate it, no crumbs left 🍓 — this was EVP_KEYMGMT(3ossl) from OpenSSL 3.5.9, dated 2026-09-29. go forth and manage those keys, bestie, you're literally the main character 💖✨👑

📦 where this page comes from