PROVIDER-KDF(7ossl)

📦

version 3.5.9 · 8 versions

3.5.9 · alpine 3.23, alpine 3.24 (latest)
3.5.9 · centos-stream 9
3.5.9 · centos-stream 10
3.5.9 · alpine 3.22
3.5.8 · fedora 43
3.5.1 · fedora 43
3.5.9 · fedora 43, fedora 44
3.5.5 · fedora 44

💖 PROVIDER-KDF 💖

okay so bestie, welcome to provider-kdf, a page from the OpenSSL manual set (that's the 7ossl bit — manual section 7, OpenSSL gang, iykyk 🫶). this one's all about the KDF library <-> provider functions, and honestly? it's giving glue code, and glue code ate. ✨

this is part 1 of the page — keep scrolling, there's more coming 🌈

🎀 NAME 🎀

provider-kdf — the KDF library <-> provider functions. literally that's it, that's the whole name section. no cap 💅

✨ SYNOPSIS ✨

okay so here's the whole thing, copied exactly, don't touch a single character bestie 🙈

#include <openssl/core_dispatch.h>
#include <openssl/core_names.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.
 */

🫶 real talk before you read the code: none of these are actual functions babe. they're displayed like this so you can see the function signatures for functions that get offered as function pointers in OSSL_DISPATCH arrays. so don't go tryna call them like normal functions, mwah 💋

🧚 Context management

void *OSSL_FUNC_kdf_newctx(void *provctx);
void OSSL_FUNC_kdf_freectx(void *kctx);
void *OSSL_FUNC_kdf_dupctx(void *src);

OSSL_FUNC_kdf_newctx — makes you a fresh new context, takes provctx, hands back a void * 💖
OSSL_FUNC_kdf_freectx — frees that context (kctx) so you're not leaking, we love a clean exit 🎀
OSSL_FUNC_kdf_dupctx — duplicates a context from src, returns the new one 🦋

🌸 Encryption/decryption

int OSSL_FUNC_kdf_reset(void *kctx);
int OSSL_FUNC_kdf_derive(void *kctx, unsigned char *key, size_t keylen,
                         const OSSL_PARAM params[]);

OSSL_FUNC_kdf_reset — resets the context kctx, returns an int ⭐
OSSL_FUNC_kdf_derive — the main character fr 🔥 takes kctx, your key buffer as an unsigned char *, the keylen as a size_t, and the params as a const OSSL_PARAM params[]. returns an int.

💜 KDF parameter descriptors

const OSSL_PARAM *OSSL_FUNC_kdf_gettable_params(void *provctx);
const OSSL_PARAM *OSSL_FUNC_kdf_gettable_ctx_params(void *kcxt, void *provctx);
const OSSL_PARAM *OSSL_FUNC_kdf_settable_ctx_params(void *kcxt, void *provctx);

OSSL_FUNC_kdf_gettable_params — tells you which params you can get, takes provctx, returns a const OSSL_PARAM * 🍓
OSSL_FUNC_kdf_gettable_ctx_params — same vibe but for the context: takes kcxt and provctx, returns a const OSSL_PARAM * 🌸
OSSL_FUNC_kdf_settable_ctx_params — the set list this time, takes kcxt and provctx, returns a const OSSL_PARAM * ✨

🦋 KDF parameters

int OSSL_FUNC_kdf_get_params(OSSL_PARAM params[]);
int OSSL_FUNC_kdf_get_ctx_params(void *kctx, OSSL_PARAM params[]);
int OSSL_FUNC_kdf_set_ctx_params(void *kctx, const OSSL_PARAM params[]);

OSSL_FUNC_kdf_get_params — grabs params into params (OSSL_PARAM params[]), returns an int 💅
OSSL_FUNC_kdf_get_ctx_params — grabs context params from kctx into params, returns an int 👑
OSSL_FUNC_kdf_set_ctx_params — sets context params from params (const OSSL_PARAM params[]) on kctx, returns an int 🔥

and that's the synopsis bestie, every signature intact, nothing dropped, periodt 💅✨ more coming in the next part, don't go anywhere 🫶

💖 DESCRIPTION 💖

okay so bestie, real talk — this page is primarily aimed at provider authors. If that's not you yet, go peek at provider(7) first, no cap, it'll set you up. ✨

So the KDF operation is literally the thing that lets providers implement KDF algorithms and serve them up to applications through the API functions EVP_KDF_CTX_reset(3) and EVP_KDF_derive(3). Slay. 🎀

Now, all the "functions" we're yapping about here? They get passed as function pointers between libcrypto and the provider inside OSSL_DISPATCH(3) arrays, which ride along in OSSL_ALGORITHM(3) arrays that come back from the provider's provider_query_operation() function (see "Provider Functions" in provider-base(7)). Iconic chain of custody, honestly. 💅

Every single one of these "functions" has a matching function type definition named OSSL_FUNC_{name}_fn, plus a helper function that fishes the function pointer out of an OSSL_DISPATCH(3) element, named OSSL_FUNC_{name}. Like, for example, the "function" OSSL_FUNC_kdf_newctx() has these two cuties:

 typedef void *(OSSL_FUNC_kdf_newctx_fn)(void *provctx);
 static ossl_inline OSSL_FUNC_kdf_newctx_fn
     OSSL_FUNC_kdf_newctx(const OSSL_DISPATCH *opf);

OSSL_DISPATCH(3) array entries get identified by numbers that are handed to you as macros in openssl-core_dispatch.h(7), and the whole roster goes like this:

OSSL_FUNC_kdf_newctx → OSSL_FUNC_KDF_NEWCTX
OSSL_FUNC_kdf_freectx → OSSL_FUNC_KDF_FREECTX
OSSL_FUNC_kdf_dupctx → OSSL_FUNC_KDF_DUPCTX
OSSL_FUNC_kdf_reset → OSSL_FUNC_KDF_RESET
OSSL_FUNC_kdf_derive → OSSL_FUNC_KDF_DERIVE
OSSL_FUNC_kdf_get_params → OSSL_FUNC_KDF_GET_PARAMS
OSSL_FUNC_kdf_get_ctx_params → OSSL_FUNC_KDF_GET_CTX_PARAMS
OSSL_FUNC_kdf_set_ctx_params → OSSL_FUNC_KDF_SET_CTX_PARAMS
OSSL_FUNC_kdf_gettable_params → OSSL_FUNC_KDF_GETTABLE_PARAMS
OSSL_FUNC_kdf_gettable_ctx_params → OSSL_FUNC_KDF_GETTABLE_CTX_PARAMS
OSSL_FUNC_kdf_settable_ctx_params → OSSL_FUNC_KDF_SETTABLE_CTX_PARAMS

A KDF algorithm implementation does not have to implement all of these, bestie — it's not a collect-them-all situation. But to be a consistent set of functions, at least these four are mandatory: OSSL_FUNC_kdf_newctx(), OSSL_FUNC_kdf_freectx(), OSSL_FUNC_kdf_set_ctx_params(), and OSSL_FUNC_kdf_derive(). Everything else is optional. 🦋

🌸 Context Management Functions 🌸

OSSL_FUNC_kdf_newctx() — should create and return a pointer to a provider-side structure that holds context information during a KDF operation. That pointer gets passed right back in a bunch of the other KDF operation function calls. The parameter provctx is the provider context that got generated during provider initialisation (see provider(7)). 🫶
OSSL_FUNC_kdf_freectx() — gets handed a pointer to the provider-side KDF context in the kctx parameter. And listen: if it receives NULL as the kctx value, it should not do anything other than return. Do not touch. Do not free. Just vibe and return. 🙈 Otherwise, this function should free any resources associated with that context.
OSSL_FUNC_kdf_dupctx() — should duplicate the provider-side KDF context in the kctx parameter and return the duplicate copy. Copy-paste but make it cryptography. ✨

💜 Encryption/Decryption Functions 💜

OSSL_FUNC_kdf_reset() — initialises a KDF operation, given a provider-side KDF context in the kctx parameter.
OSSL_FUNC_kdf_derive() — performs the actual KDF operation, after processing the params as per OSSL_FUNC_kdf_set_ctx_params(). The kctx parameter contains a pointer to the provider-side context. The resulting key, of the desired keylen, should be written to key. And here's the important bit, fr fr: if the algorithm does not support the requested keylen, the function must return error. No silently truncating, no pretending, no "close enough". 💀

🎀 KDF Parameters 🎀

See OSSL_PARAM(3) for further details on the parameters structure these functions use. It's giving essential reading. 📚

OSSL_FUNC_kdf_get_params() — gets details of parameter values associated with the provider algorithm and stores them in params.
OSSL_FUNC_kdf_set_ctx_params() — sets KDF parameters associated with the given provider-side KDF context kctx to params. Any parameter settings are additional to any that were previously set (they stack, they don't reset — noted bestie 💅). Passing NULL for params should return true.
OSSL_FUNC_kdf_get_ctx_params() — retrieves gettable parameter values associated with the given provider-side KDF context kctx and stores them in params. Passing NULL for params should return true.
OSSL_FUNC_kdf_gettable_params(), OSSL_FUNC_kdf_gettable_ctx_params(), and OSSL_FUNC_kdf_settable_ctx_params() — these three all return constant OSSL_PARAM(3) arrays as descriptors of the parameters that OSSL_FUNC_kdf_get_params(), OSSL_FUNC_kdf_get_ctx_params(), and OSSL_FUNC_kdf_set_ctx_params() can handle, respectively. And OSSL_FUNC_kdf_gettable_ctx_params() and OSSL_FUNC_kdf_settable_ctx_params() will return the parameters associated with the provider-side context kctx in its current state if it is not NULL. Otherwise, they return the parameters associated with the provider-side algorithm provctx. iykyk 🌈

So the parameters currently recognised by built-in KDFs are as follows, bestie. Big list incoming, drink some water 🍓. And heads up: not all parameters are relevant to, or are understood by, all KDFs — so don't come for me if your favourite KDF ignores one.

"size" (OSSL_KDF_PARAM_SIZE) <unsigned integer> — gets the output size from the associated KDF ctx. If the algorithm produces a variable amount of output, SIZE_MAX should be returned. And if the input parameters required to calculate the fixed output size haven't been supplied yet, return 0, which signals an error. ⭐
"key" (OSSL_KDF_PARAM_KEY) <octet string> — sets the key in the associated KDF ctx.
"secret" (OSSL_KDF_PARAM_SECRET) <octet string> — sets the secret in the associated KDF ctx.
"pass" (OSSL_KDF_PARAM_PASSWORD) <octet string> — sets the password in the associated KDF ctx.
"cipher" (OSSL_KDF_PARAM_CIPHER) <UTF8 string>, "digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>, "mac" (OSSL_KDF_PARAM_MAC) <UTF8 string> — these three set the name of the underlying cipher, digest or MAC to be used. It must name a suitable algorithm for the KDF that's being used. No rogue picks. 🙅‍♀️
"maclen" (OSSL_KDF_PARAM_MAC_SIZE) <octet string> — sets the length of the MAC in the associated KDF ctx.
"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string> — sets the properties to be queried when trying to fetch the underlying algorithm. This must be given together with the algorithm naming parameter to be considered valid. They're a package deal. 🫶
"iter" (OSSL_KDF_PARAM_ITER) <unsigned integer> — sets the number of iterations in the associated KDF ctx.
"mode" (OSSL_KDF_PARAM_MODE) <UTF8 string> — sets the mode in the associated KDF ctx.
"pkcs5" (OSSL_KDF_PARAM_PKCS5) <integer> — enables or disables the SP800-132 compliance checks. A mode of 0 enables the compliance checks (yes, zero means on, we don't make the rules 😭). The checks performed are:
- the iteration count is at least 1000.
- the salt length is at least 128 bits.
- the derived key length is at least 112 bits.
"ukm" (OSSL_KDF_PARAM_UKM) <octet string> — sets an optional random string that is provided by the sender, called "partyAInfo". In CMS this is the user keying material. 🎉
"cekalg" (OSSL_KDF_PARAM_CEK_ALG) <UTF8 string> — sets the CEK wrapping algorithm name in the associated KDF ctx.
"n" (OSSL_KDF_PARAM_SCRYPT_N) <unsigned integer> — sets the scrypt work factor parameter N in the associated KDF ctx.
"r" (OSSL_KDF_PARAM_SCRYPT_R) <unsigned integer> — sets the scrypt work factor parameter r in the associated KDF ctx.
"p" (OSSL_KDF_PARAM_SCRYPT_P) <unsigned integer> — sets the scrypt work factor parameter p in the associated KDF ctx.
"maxmem_bytes" (OSSL_KDF_PARAM_SCRYPT_MAXMEM) <unsigned integer> — sets the scrypt work factor parameter maxmem in the associated KDF ctx.
"prefix" (OSSL_KDF_PARAM_PREFIX) <octet string> — sets the prefix string using by the TLS 1.3 version of HKDF in the associated KDF ctx.
"label" (OSSL_KDF_PARAM_LABEL) <octet string> — sets the label string using by the TLS 1.3 version of HKDF in the associated KDF ctx.
"data" (OSSL_KDF_PARAM_DATA) <octet string> — sets the context string using by the TLS 1.3 version of HKDF in the associated KDF ctx.
"info" (OSSL_KDF_PARAM_INFO) <octet string> — sets the optional shared info in the associated KDF ctx.
"seed" (OSSL_KDF_PARAM_SEED) <octet string> — sets the IV in the associated KDF ctx.
"xcghash" (OSSL_KDF_PARAM_SSHKDF_XCGHASH) <octet string> — sets the xcghash in the associated KDF ctx.
"session_id" (OSSL_KDF_PARAM_SSHKDF_SESSION_ID) <octet string> — sets the session ID in the associated KDF ctx.
"type" (OSSL_KDF_PARAM_SSHKDF_TYPE) <UTF8 string> — sets the SSH KDF type parameter in the associated KDF ctx. There are six supported types, and they are:
- EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV — the Initial IV from client to server. A single char of value 65 (ASCII char 'A'). 💖
- EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI — the Initial IV from server to client. A single char of value 66 (ASCII char 'B'). 🌸
- EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV — the Encryption Key from client to server. A single char of value 67 (ASCII char 'C'). 🦋
- EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI — the Encryption Key from server to client. A single char of value 68 (ASCII char 'D'). ✨
- EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV — the Integrity Key from client to server. A single char of value 69 (ASCII char 'E'). 💜
- EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI — the Integrity Key from client to server. A single char of value 70 (ASCII char 'F'). 👑

🎀 COPYRIGHT 🎀

okay so before anyone comes for me — this whole page is copyrighted, bestie. fr fr.

Like, all the rights. Reserved. Every single one. 💅

✨ the license tea ✨

This file is licensed under the Apache License 2.0 (yep, the one they just call "the License" — capital L, main character energy 👑).

⚠️ real talk: you may not use this file except in compliance with the License. that's not a vibe, that's a rule. 😭

You can grab a copy of the License from the file LICENSE in the source distribution, or online at:

wait, no, let me give you the actual line so you can copy-paste it exactly, no typos, no cap:

<https://www.openssl.org/source/license.html>

and the file path, exact, character for character:

LICENSE

in the source distribution. that's it, that's the whole license situation. 🦋

🌸 the cute lil sign-off 🌸

This gorgeous page comes from OpenSSL version 3.5.9, dated 2026-09-29 — so you know it's fresh ✨. That's the source and the date right there at the bottom of the page, and honestly? iconic. periodt. 💖🧚‍♀️

📦 where this page comes from

alpine 3.23: openssl-doc 3.5.9-r0 · Apache-2.0
alpine 3.24: openssl-doc 3.5.9-r0 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms