EVP_SKEY(3SSL)

📦

version 4.0.3 · 3 versions

✨ EVP_SKEY ✨

okay so bestie, this is the EVP_SKEY(3SSL) page from the OpenSSL fam — the one all about opaque symmetric key allocation and handling functions. Sit down, hydrate, we're learning key objects 💅

EVP_SKEY, EVP_SKEY_generate, EVP_SKEY_import, EVP_SKEY_import_raw_key, EVP_SKEY_import_SKEYMGMT, 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, EVP_SKEY_to_provider — that's the whole lineup, no one's left out.

🌸 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);
EVP_SKEY *EVP_SKEY_import_SKEYMGMT(OSSL_LIB_CTX *libctx, EVP_SKEYMGMT *skeymgmt,
                                   int selection, const OSSL_PARAM *params);
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 🦋

EVP_SKEY is like... a generic lil structure that holds symmetric keys as opaque objects. The keys themselves get called the "internal key" all the time, and providers handle them through EVP_SKEYMGMT(3). iykyk.

So conceptually? An EVP_SKEY internal key may hold a symmetric key, and along with it, key parameters — but only if the key type requires them. Not every key is high-maintenance like that. 🎀

EVP_SKEY_generate() — creates a new EVP_SKEY object and initializes it according to the params argument. Fresh key, who dis.
EVP_SKEY_import() — allocates an empty EVP_SKEY structure (which is what OpenSSL uses to store symmetric keys), assigns the EVP_SKEYMGMT object associated with the key, and initializes the object from the params argument.
EVP_SKEY_import_raw_key() — a lil helper that creates an EVP_SKEY object holding the raw byte representation of the symmetric keys from the buffer key having length len. The skeymgmtname defines the name of the target EVP_SKEYMGMT for the newly created key.
EVP_SKEY_import_SKEYMGMT() — another helper, this one creating an EVP_SKEY object containing the representation of the symmetric keys specific to that particular EVP_SKEYMGMT.
EVP_SKEY_export() — extracts values from a key skey using the selection. (selection is described below, don't worry.) It uses a callback export_cb that gets passed the value of export_cbarg. Peep openssl-core.h(7) for more info about the callback. ⚠️ Note that the OSSL_PARAM(3) array that is passed to the callback is not persistent after the callback returns — so don't be out here holding onto it like it's yours.
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. 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. Gone. Poof. 💀
EVP_SKEY_get0_skeymgmt_name() and EVP_SKEY_get0_provider_name() — return the names of the associated EVP_SKEYMGMT object and its provider, correspondingly. Matchy matchy.
EVP_SKEY_up_ref() — increments the reference count of key. Bestie's getting popular.
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. No drama.
EVP_SKEY_is_a() — checks if the key type of skey is name. Vibe check, basically.
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.

👑 Selections 👑

These are the constants you can use for selection, and honestly? Pick your fighter:

OSSL_SKEYMGMT_SELECT_SECRET_KEY — only the raw key representation will be selected. Just the secret, thank you. 💅
OSSL_SKEYMGMT_SELECT_PARAMETERS — only the key parameters will be selected. This includes optional key parameters too, we're inclusive here.
OSSL_SKEYMGMT_SELECT_ALL — all parameters will be selected. Give me everything, main character energy. ✨

Notes

The EVP_SKEY structure is used by various OpenSSL functions which require a general symmetric key without reference to any particular algorithm. Mysterious. Versatile. Iconic.

The EVP_SKEY_to_provider() function will fail and return NULL if the origin key skey cannot be exported from its provider. 🫠

Real talk: that's a documented failure mode, not a "huh it broke" moment. Plan for it.

🌈 RETURN VALUES 🌈

EVP_SKEY_generate(), EVP_SKEY_import(), EVP_SKEY_import_raw_key(), and EVP_SKEY_import_SKEYMGMT() 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 correspondingly.
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) — go read those next, bestie, it's the whole friend group 🫶

💜 HISTORY 💜

The EVP_SKEY API and the 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.

The EVP_SKEY_import_SKEYMGMT() function is the baby of the bunch — introduced in OpenSSL 4.0. Not me being late to the party, I'm just newer. 🙈

🍓 COPYRIGHT 🍓

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 the OpenSSL 4.0.3 version, dated 2026-09-29 — go forth and hold your symmetric keys as the gorgeous opaque objects they were always meant to be. slay, no cap. 💖✨

📦 where this page comes from

ubuntu stonking: libssl-doc 4.0.3-1ubuntu1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms