PROVIDER-KDF(7ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💖 NAME 💖

okay so bestie, welcome to provider-kdf from the OpenSSL PROVIDER-KDF(7ossl) manual. This page is literally about The KDF library <-> provider functions. That’s the whole name section, and it ate. 🫶

✨ SYNOPSIS ✨

First you gotta pull in the headers, no cap:

#include <openssl/core_dispatch.h>
#include <openssl/core_names.h>

Then the page hits you with this important little note — and yes, keep it in mind, because it’s giving “these look like functions but they’re not actual functions”:

/*
 * 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.
 */

Now here’s the whole lineup of signatures, exactly as the manual shows them. Context management first, then the group labeled Encryption/decryption (that label is literally what the page says, iykyk), then the KDF parameter descriptors, then the KDF parameters 💅:

/* Context management */
void *OSSL_FUNC_kdf_newctx(void *provctx);
void OSSL_FUNC_kdf_freectx(void *kctx);
void *OSSL_FUNC_kdf_dupctx(void *src);

/* 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[]);

/* 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);

/* 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[]);

💖 DESCRIPTION 💖

Okay so first thing's first, bestie: this page is mainly for provider authors, like the people actually writing these algorithm implementations. If that's not you, go peek at provider(7) for the full tea. 🫖

The KDF operation is literally what lets providers implement KDF algorithms and then hand them out to applications through the API functions EVP_KDF_CTX_reset(3) and EVP_KDF_derive(3). Slay. ✨

Every "function" we're about to talk about is passed as a function pointer between libcrypto and the provider, cruising along inside OSSL_DISPATCH(3) arrays, which themselves live in OSSL_ALGORITHM(3) arrays — and those come back out of the provider's provider_query_operation() function. Peep "Provider Functions" in provider-base(7) if you wanna go deeper, iykyk.

Each of these "functions" has a matching function type definition named OSSL_FUNC_{name}_fn, plus a lil helper function to scoop the function pointer out of an OSSL_DISPATCH(3) element, named OSSL_FUNC_{name}. So like, the "function" OSSL_FUNC_kdf_newctx() has these two besties:

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, served up as macros in openssl-core_dispatch.h(7), 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

Now here's the thing: a KDF algorithm implementation does not have to implement all of these. But to be a consistent set of functions, at minimum you gotta bring these four to the party: OSSL_FUNC_kdf_newctx(), OSSL_FUNC_kdf_freectx(), OSSL_FUNC_kdf_set_ctx_params(), OSSL_FUNC_kdf_derive(). Everything else is optional, no pressure. 💅

🎀 Context Management Functions 🎀

  • OSSL_FUNC_kdf_newctx() — should create and return a pointer to a provider side structure that holds the context info during a KDF operation. That context pointer gets passed back in a bunch of the other KDF operation function calls. The provctx parameter is the provider context that was generated during provider initialisation (check provider(7), bestie).
  • OSSL_FUNC_kdf_freectx() — gets handed a pointer to the provider side KDF context in the kctx parameter. If it receives NULL as the kctx value, it should do nothing other than return. Otherwise this function should free any resources associated with that context. Clean up your room. 🧹
  • OSSL_FUNC_kdf_dupctx() — should duplicate the provider side KDF context in the kctx parameter and return the duplicate copy. Twin energy. 👯

🔥 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() — actually performs the KDF operation, after processing the params as per OSSL_FUNC_kdf_set_ctx_params(). The kctx parameter holds a pointer to the provider side context. The resulting key, of the desired keylen, should be written to key. If the algorithm does not support the requested keylen, the function must return error. No fake slay, okay? 😤

🌸 KDF Parameters 🌸

For all the deets on the parameters structure these functions use, go read OSSL_PARAM(3).

  • OSSL_FUNC_kdf_get_params() — gets the 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 — it's a vibe and a cumulative one. 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() — all return constant OSSL_PARAM(3) arrays acting 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. 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.

So these are the parameters that built-in KDFs currently recognise. Heads up: not all of them are relevant to, or understood by, all KDFs. It's giving "menu at a restaurant where half the items are seasonal." 🍓

  • "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, 0 should be returned to indicate 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 mismatched vibes allowed.
  • "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. Package deal, bestie. 🎁
  • "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.

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.

okay bestie, legal era but make it cute — this is the part where we give credit where credit is soooo due. 🎀

Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.

that's it, that's the whole vibe. every single right, reserved, no cap. 🫶

✨ the license bit (read it, fr fr) ✨

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License.

🚨 real talk: this isn't a suggestion, bestie. it's giving "you literally cannot use this file unless you're in compliance with the License." no vibes-based exceptions. 💀

You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

like, go get the actual text, it's right there. don't just trust the group chat screenshot of the license, go to the source. iykyk. 🌸

🦋 sign-off 🦋

and that's the whole page, bestie!! you made it to the very end, main character energy for real. 👑

this one's from source version 3.5.0, dated 2026-09-25, and the page is literally called PROVIDER-KDF(7ossl) — that's the one you just read, start to finish. slay. 💖✨

📦 where this page comes from