PROVIDER-SKEYMGMT(7SSL)

📦
version 4.0.3 · 6 versions
, in ubuntu stonking

✨ NAME ✨

provider-skeymgmt — the SKEYMGMT library <-> provider functions, bestie 💖

it's a page from the OpenSSL manual, section 7SSL, and it's all about the secret handshake between libcrypto and your provider 🫶

🌸 SYNOPSIS 🌸

#include <openssl/core_dispatch.h>

/*
 * None of these are actual functions, but are displayed like this for
 * the function signatures for functions that are offered as function
 * pointers in OSSL_DISPATCH arrays.
 */

/* Key object destruction */
void OSSL_FUNC_skeymgmt_free(void *keydata);

/* Key object import and export functions */
void *OSSL_FUNC_skeymgmt_import(void *provctx, int selection,
                                const OSSL_PARAM params[]);
int OSSL_FUNC_skeymgmt_export(void *keydata, int selection,
                              OSSL_CALLBACK *param_cb, void *cbarg);
void *OSSL_FUNC_skeymgmt_generate(void *provctx,
                                  const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_skeymgmt_gen_settable_params(void *provctx);
const OSSL_PARAM *OSSL_FUNC_skeymgmt_imp_settable_params(void *provctx);
const char *OSSL_FUNC_skeymgmt_get_key_id(void *keydata);

💅 DESCRIPTION 💅

okay so, the SKEYMGMT operation is lowkey not that visible in the OpenSSL libraries publicly 👀 like, it's an internal operation, and it's designed to vibe with operations that use opaque symmetric key objects. that's its whole thing.

SKEYMGMT shares knowledge with the operations it works with, so — important — the SKEYMGMT and the algorithms which use it must belong to the same provider. good news: the OpenSSL libraries will make sure that they do 🫡 no cap.

the main character job of the SKEYMGMT operation? holding the provider-side key data for the OpenSSL library EVP_SKEY structure. that's the moment. 💅

all the "functions" mentioned here get passed as function pointers between libcrypto and the provider in OSSL_DISPATCH(3) arrays, via OSSL_ALGORITHM(3) arrays that get returned by the provider's provider_query_operation() function (peep "Provider Functions" in provider-base(7)).

every one of these "functions" has a matching function type definition named OSSL_FUNC_{name}_fn, plus a lil helper function to grab the function pointer out of an OSSL_DISPATCH(3) element, named OSSL_FUNC_{name}. iconic ✨

OSSL_DISPATCH(3) arrays are indexed by numbers that are provided as macros in openssl-core_dispatch.h(7), like this:

OSSL_FUNC_skeymgmt_free                 OSSL_FUNC_SKEYMGMT_FREE

OSSL_FUNC_skeymgmt_import               OSSL_FUNC_SKEYMGMT_IMPORT
OSSL_FUNC_skeymgmt_export               OSSL_FUNC_SKEYMGMT_EXPORT

OSSL_FUNC_skeymgmt_generate             OSSL_FUNC_SKEYMGMT_GENERATE

OSSL_FUNC_skeymgmt_get_key_id           OSSL_FUNC_SKEYMGMT_GET_KEY_ID
OSSL_FUNC_skeymgmt_imp_settable_params  OSSL_FUNC_SKEYMGMT_IMP_SETTABLE_PARAMS
OSSL_FUNC_skeymgmt_gen_settable_params  OSSL_FUNC_SKEYMGMT_GEN_SETTABLE_PARAMS

the SKEYMGMT management is inspired by KEYMGMT, it's just simpler bestie 💁‍♀️

🔑 Key Objects 🔑

a key object is a lil collection of data for a symmetric key, and in this manual it's written as keydata 🎀

what's actually inside a key object is defined by the provider. and here's the assumption: different operations within one and the same provider use the exact same structure to represent this collection of data. so like, a key object that was created using the SKEYMGMT interface can be passed as-is to other algorithms from the same provider operations, e.g. OSSL_FUNC_mac_init_opaque() (see provider-mac(7)). sharing is caring fr fr 🫶

with the export SKEYMGMT function, you can select a specific subset of data to handle, governed by the bits in a selection indicator. the bits are:

  • OSSL_SKEYMGMT_SELECT_SECRET_KEY — indicating that the secret key raw bytes in a key object should be included. 🍓
  • OSSL_SKEYMGMT_SELECT_PARAMETERS — indicating that the parameters in a key object should be included.

and combined selector bits are defined too, for easier use:

  • OSSL_SKEYMGMT_SELECT_ALL — indicating that everything in a key object should be included. the whole package 💖

the exact interpretation of those bits, or how they combine, is left to each function where you can specify a selector. so read the function, bestie, don't assume 😌

💀 Destructing Function 💀

  • OSSL_FUNC_skeymgmt_free() — should free the passed keydata. that's it, that's the tweet.

📥 Key Object Import and Export Functions 📤

  • OSSL_FUNC_skeymgmt_import() — should import data into keydata with values taken from the OSSL_PARAM(3) array params. it allocates the keydata object itself (there is no separate allocation function, so don't go looking for one 🕵️‍♀️).
  • OSSL_FUNC_skeymgmt_imp_settable_params() — returns a list of parameters that can be provided to the OSSL_FUNC_skeymgmt_import() function.
  • OSSL_FUNC_skeymgmt_export() — should extract values indicated by selection from keydata, create an OSSL_PARAM(3) array with them, and call param_cb with that array as well as the given cbarg. heads up: the passed OSSL_PARAM(3) array is transient and is freed upon the return from param_cb 😭 so don't hold onto it.

⭐ Key Object Generation Functions ⭐

  • OSSL_FUNC_skeymgmt_generate() — creates a new key according to the values taken from the OSSL_PARAM(3) array params. it allocates the keydata object. fresh key, who dis ✨
  • OSSL_FUNC_skeymgmt_gen_settable_params() — returns a list of parameters that can be provided to the OSSL_FUNC_skeymgmt_generate() function.

🕵️ Key Object Information functions 🕵️

  • OSSL_FUNC_skeymgmt_get_key_id() — returns a NUL-terminated string identifying the particular key. the returned string will be freed by a call to EVP_SKEY_free(), so callers need to copy it themselves if they want to preserve the value past the key lifetime 👑 the purpose of this function is providing a printable string that can help users access the specific key. the content of this string is provider-specific.

🌈 Common Import and Export Parameters 🌈

see OSSL_PARAM(3) for further details on the parameters structure.

common information parameters currently recognised by built-in skeymgmt algorithms are as follows:

  • "raw-bytes" (SKEY_PARAM_RAW_BYTES) <octet string> — the value represents symmetric key as a byte array.
  • "key-length" (SKEY_PARAM_KEY_LENGTH) <integer> — the value is the byte length of the given key.

🫶 RETURN VALUES 🫶

  • OSSL_FUNC_skeymgmt_import() and OSSL_FUNC_skeymgmt_generate() return a pointer to an allocated object on success and NULL on error. 😭
  • OSSL_FUNC_skeymgmt_export() returns 1 for success or 0 on error.
  • OSSL_FUNC_skeymgmt_get_key_id() returns a pointer to a 0-terminated string or NULL.
  • OSSL_FUNC_skeymgmt_gen_settable_params() and OSSL_FUNC_skeymgmt_imp_settable_params() return references to an array of OSSL_PARAM which can be NULL if there are no settable parameters.

👀 SEE ALSO 👀

provider(7), EVP_SKEY(3), EVP_KEYMGMT(3)

🦋 HISTORY 🦋

the SKEYMGMT interface was introduced in OpenSSL 3.5. baby of the family, but thriving 💜

Copyright 2024-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 4.0.3, dated 2026-09-29, and you absolutely ate it. go forth and be opaque with your symmetric keys ✨ mwah 💅

📦 where this page comes from