EVP_SKEY(3ossl) OpenSSL EVP_SKEY(3ossl)
NAME
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,
EVP_SKEY_to_provider - opaque symmetric key allocation and handling
functions
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
EVP_SKEY is a generic structure to hold symmetric keys as opaque
objects. The keys themselves are often referred to as the "internal
key", and are handled by providers using EVP_SKEYMGMT(3).
Conceptually, an EVP_SKEY internal key may hold a symmetric key, and
along with those, key parameters if the key type requires them.
The EVP_SKEY_generate() functions creates a new EVP_SKEY object and
initializes it according to the params argument.
The EVP_SKEY_import() function 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.
The EVP_SKEY_import_raw_key() function is a helper that creates an
EVP_SKEY object containing the raw byte representation of the symmetric
keys.
The EVP_SKEY_export() function extracts values from a key skey using
the selection. selection is described below. 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. Note that
the OSSL_PARAM(3) array that is passed to the callback is not
persistent after the callback returns.
The 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.
The 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.
The 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_up_ref() increments the reference count of 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.
EVP_SKEY_is_a() checks if the key type of skey is name.
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
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.
OSSL_SKEYMGMT_SELECT_ALL
All parameters will be selected.
NOTES
The EVP_SKEY structure is used by various OpenSSL functions which
require a general symmetric key without reference to any particular
algorithm.
The EVP_SKEY_to_provider() function will fail and return NULL if the
origin key skey cannot be exported from its provider.
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.
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.
COPYRIGHT
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>.
3.5.0 2025-04-10 EVP_SKEY(3ossl)
openssl 3.5.0 - Generated Mon Apr 21 07:25:03 CDT 2025