EVP_SKEY(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💖 EVP_SKEY — opaque symmetric key allocation and handling functions 💖

okay bestie, so this is the OpenSSL manual page EVP_SKEY(3ossl) and it's genuinely one of the cutest little abstractions in the whole crypto library. it's all about wrapping up symmetric keys in a nice opaque lil package so you can pass them around without poking at their insides. main character energy fr fr 👑

the cast of characters you're getting here (this is the NAME section, just with way more sparkle): EVP_SKEY, EVP_SKEY_generate, EVP_SKEY_import, EVP_SKEY_import_raw_key, EVP_SKEY_up_ref, EVP_SKEY_export, EVP_SKEY_get0_raw_key, EVP_SKEY_get0_key_id, EVP_SKEY_get0_skeymgmt_name, EVP_SKEY_get0_provider_name, EVP_SKEY_free, EVP_SKEY_is_a, and EVP_SKEY_to_provider — collectively the opaque symmetric key allocation and handling functions. iconic lineup, no notes. ✨

🌸 SYNOPSIS 🌸

#include <openssl/evp.h>

typedef evp_skey_st EVP_SKEY;

EVP_SKEY *EVP_SKEY_generate(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
                            const char *propquery, const OSSL_PARAM *params);
EVP_SKEY *EVP_SKEY_import(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
                          const char *propquery,
                          int selection, const OSSL_PARAM *params);
EVP_SKEY *EVP_SKEY_import_raw_key(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
                                  unsigned char *key, size_t *len,
                                  const char *propquery);
int EVP_SKEY_export(const EVP_SKEY *skey, int selection,
                    OSSL_CALLBACK *export_cb, void *export_cbarg);
int EVP_SKEY_get0_raw_key(const EVP_SKEY *skey, const unsigned char **key,
                         size_t *len);
const char *EVP_SKEY_get0_key_id(const EVP_SKEY *skey);

const char *EVP_SKEY_get0_skeymgmt_name(const EVP_SKEY *skey);
const char *EVP_SKEY_get0_provider_name(const EVP_SKEY *skey);

int EVP_SKEY_up_ref(EVP_SKEY *key);
void EVP_SKEY_free(EVP_SKEY *key);
int EVP_SKEY_is_a(const EVP_SKEY *skey, const char *name);
EVP_SKEY *EVP_SKEY_to_provider(EVP_SKEY *skey, OSSL_LIB_CTX *libctx,
                               OSSL_PROVIDER *prov, const char *propquery);

🦋 DESCRIPTION 🦋

so. EVP_SKEY is this generic structure that holds symmetric keys as opaque objects — meaning you don't get to stare directly at the bytes, you just trust the vibes and the API. the keys inside are often called the "internal key", and they're handled by providers using EVP_SKEYMGMT(3). 💅

conceptually (love that word), an EVP_SKEY internal key may hold a symmetric key, and along with those, key parameters if the key type requires them. so it's like, key + accessories. the key type decides if it needs the accessories. 🎀

let's go through the functions one by one, because i love a list:

  • EVP_SKEY_generate() — creates a new EVP_SKEY object and initializes it according to the params argument. freshly baked key, chef's kiss. 🍓
  • EVP_SKEY_import() — allocates an empty EVP_SKEY structure which is used by OpenSSL to store symmetric keys, assigns the EVP_SKEYMGMT object associated with the key, and initializes the object from the params argument. it's giving "build-a-key workshop". ✨
  • EVP_SKEY_import_raw_key() — a helper that creates an EVP_SKEY object containing the raw byte representation of the symmetric keys. lowkey the shortcut function and we respect it. 🔥
  • EVP_SKEY_export() — extracts values from a key skey using the selection. selection is described below (scroll down bestie, it's the Selections bit). it uses a callback export_cb that gets passed the value of export_cbarg. see openssl-core.h(7) for more information about the callback. ⚠️ and heads up, the OSSL_PARAM(3) array that is passed to the callback is not persistent after the callback returns — so don't go stashing that pointer anywhere, it ghosts you immediately. 😭
  • EVP_SKEY_get0_raw_key() — returns a pointer to a raw key bytes to the passed address and sets the key len. the returned address is managed by the internal key management and shouldn't be freed explicitly — hands off, it's not yours, no cap. the operation can fail when the underlying key management doesn't support export of the secret key. 🙈
  • EVP_SKEY_get0_key_id() — returns a NUL-terminated string providing some human-readable identifier of the key if provided by the underlying key management. the pointer becomes invalid after freeing the EVP_SKEY object. so like, it's a borrow, not a gift. 🫶
  • EVP_SKEY_get0_skeymgmt_name() and EVP_SKEY_get0_provider_name() — return the names of the associated EVP_SKEYMGMT object and its provider correspondingly. matching set, adorable. 💖
  • EVP_SKEY_up_ref() — increments the reference count of key. girl math: one becomes two, but it's the same key. 👑
  • EVP_SKEY_free() — decrements the reference count of key and, if the reference count is zero, frees it. if key is NULL, nothing is done. very chill, very "no worries if not". ✨
  • EVP_SKEY_is_a() — checks if the key type of skey is name. vibe check on the key type, literally. 🌈
  • EVP_SKEY_to_provider() — simplifies the task of importing a skey into a different provider identified by prov. if prov is NULL, the default provider for the key type identified via skey is used. it's the key's passport-renewal function. 🧚

🎀 Selections 🎀

the following constants can be used for selection:

  • OSSL_SKEYMGMT_SELECT_SECRET_KEY — only the raw key representation will be selected.
  • OSSL_SKEYMGMT_SELECT_PARAMETERS — only the key parameters will be selected. this includes optional key parameters. (optional!! fancee)
  • OSSL_SKEYMGMT_SELECT_ALL — all parameters will be selected. the "give me everything" option. 💅

💜 NOTES 💜

the EVP_SKEY structure is used by various OpenSSL functions which require a general symmetric key without reference to any particular algorithm. so it's the social butterfly of key types — algorithm-agnostic and ready to mingle. 🦋

⚠️ important caveat bestie: the EVP_SKEY_to_provider() function will fail and return NULL if the origin key skey cannot be exported from its provider. no export, no travel. that's the rule. 💀

⭐ RETURN VALUES ⭐

  • EVP_SKEY_generate(), EVP_SKEY_import() and EVP_SKEY_import_raw_key() — return either the newly allocated EVP_SKEY structure or NULL if an error occurred.
  • EVP_SKEY_get0_key_id() — returns either a valid pointer or NULL.
  • EVP_SKEY_up_ref() — returns 1 for success and 0 on failure.
  • EVP_SKEY_export() and EVP_SKEY_get0_raw_key() — return 1 for success and 0 on failure.
  • EVP_SKEY_get0_skeymgmt_name() and EVP_SKEY_get0_provider_name() — return the names of the associated EVP_SKEYMGMT object and its provider correspondigly. (yes, the manpage really does spell it "correspondigly" — i'm keeping it exactly as-is because we don't edit the sacred text 💀💖)
  • EVP_SKEY_is_a() — returns 1 if skey has the key type name, otherwise 0.
  • EVP_SKEY_to_provider() — returns a new EVP_SKEY suitable for operations with the prov provider or NULL in case of failure.

🌈 SEE ALSO 🌈

EVP_SKEYMGMT(3), provider(7), OSSL_PARAM(3)

🕰️ HISTORY 🕰️

the EVP_SKEY API and functions EVP_SKEY_export(), EVP_SKEY_free(), EVP_SKEY_get0_raw_key(), EVP_SKEY_import(), EVP_SKEY_import_raw_key(), EVP_SKEY_up_ref(), EVP_SKEY_generate(), EVP_SKEY_get0_key_id(), EVP_SKEY_get0_provider_name(), EVP_SKEY_get0_skeymgmt_name(), EVP_SKEY_is_a(), EVP_SKEY_to_provider() were introduced in OpenSSL 3.5. new drop, era-defining, we were all there. 👑

Copyright 2025 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 version 3.5.0, dated 2026-09-25, filed under EVP_SKEY(3ossl) — go forth and handle those symmetric keys opaquely, mwah 💋🌸

📦 where this page comes from