EVP_KDF-SS(7ossl)

📦
version 15.1 · 3 versions
, in freebsd 15.1

💅 EVP_KDF-SS — the Single Step KDF, explained by your favorite crypto bestie

okay so this is the EVP_KDF-SS(7ossl) page from the OpenSSL manual set, and it's genuinely one of the cuter KDF pages because it's literally just one step. let's get into it 🎀

✨ NAME ✨

EVP_KDF-SS — the Single Step / One Step EVP_KDF implementation. yes bestie, "single step" is the whole personality. no cap.

🌸 DESCRIPTION 🌸

So the EVP_KDF-SS algorithm implements the Single Step key derivation function (SSKDF). What does SSKDF do? It derives a key using inputs like a shared secret key (the kind that gets generated while a key establishment scheme is running) plus fixedinfo. That's it. That's the vibe.

SSKDF also gets called 'Concat KDF' informally, iykyk.

And the output? The output is considered to be keying material. 👑

🧚 Auxiliary function

The implementation uses a selectable auxiliary function H, which can be one of these three icons:

H(x) = hash(x, digest=md)
H(x) = HMAC_hash(x, key=salt, digest=md)
H(x) = KMACxxx(x, key=salt, custom="KDF", outlen=mac_size)

Both the HMAC and KMAC implementations set the key using the 'salt' value. The hash and HMAC also require the digest to be set. that's the rule, don't forget it 🫶

🦋 Identity

"SSKDF" is the name for this implementation — that's its whole government name — and it can be used with the EVP_KDF_fetch() function.

👑 Supported parameters

Here's the lineup, bestie. The supported parameters are:

  • "properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>
  • "digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string> — lowkey important note: this parameter is ignored for KMAC. 🙈
  • "mac" (OSSL_KDF_PARAM_MAC) <UTF8 string>
  • "maclen" (OSSL_KDF_PARAM_MAC_SIZE) <unsigned integer>
  • "salt" (OSSL_KDF_PARAM_SALT) <octet string> — these three work exactly as described in "PARAMETERS" in EVP_KDF(3). go check that page if you want the full lore.
  • "key" (OSSL_KDF_PARAM_SECRET) <octet string> — this parameter sets the shared secret that is used for key derivation. it's giving main character energy, honestly.
  • "info" (OSSL_KDF_PARAM_INFO) <octet string> — this parameter sets an optional value for fixedinfo, also known as otherinfo. two names, one icon. 💅

The OpenSSL FIPS provider also supports the following parameters:

  • "fips-indicator" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) <integer> — a getter that returns 1 if the operation is FIPS approved, or 0 otherwise. You can use this after calling EVP_KDF_derive. It returns 0 if "key-check" is set to 0 and the check fails.
  • "key-check" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) <integer> — the default value of 1 causes an error during EVP_KDF_CTX_set_params() if the length of the used key-derivation key (OSSL_KDF_PARAM_KEY) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0.
⚠️ heads up: this option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0. not a vibe, so know what you're doing 💀

🌈 NOTES 🌈

A context for SSKDF can be obtained by calling:

EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);

And the output length of an SSKDF is specified via the keylen parameter to the EVP_KDF_derive(3) function. so you don't guess the length — you tell it. periodt.

🔥 EXAMPLES 🔥

💖 Example 1 — hash mode

This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret" and fixedinfo value "label":

EVP_KDF *kdf;
EVP_KDF_CTX *kctx;
unsigned char out[10];
OSSL_PARAM params[4], *p = params;

kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_free(kdf);

*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
                                        SN_sha256, strlen(SN_sha256));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
                                         "secret", (size_t)6);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
                                         "label", (size_t)5);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
    error("EVP_KDF_derive");
}

EVP_KDF_CTX_free(kctx);

💜 Example 2 — HMAC mode

This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret", fixedinfo value "label" and salt "salt":

EVP_KDF *kdf;
EVP_KDF_CTX *kctx;
unsigned char out[10];
OSSL_PARAM params[6], *p = params;

kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_free(kdf);

*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
                                        SN_hmac, strlen(SN_hmac));
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
                                        SN_sha256, strlen(SN_sha256));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET,
                                         "secret", (size_t)6);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
                                         "label", (size_t)5);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                         "salt", (size_t)4);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
    error("EVP_KDF_derive");
}

EVP_KDF_CTX_free(kctx);

🍓 Example 3 — KMAC mode

This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret", fixedinfo value "label", salt of "salt" and KMAC outlen of 20:

EVP_KDF *kdf;
EVP_KDF_CTX *kctx;
unsigned char out[10];
OSSL_PARAM params[6], *p = params;

kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_free(kdf);

*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
                                        SN_kmac128, strlen(SN_kmac128));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET,
                                         "secret", (size_t)6);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
                                         "label", (size_t)5);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                         "salt", (size_t)4);
*p++ = OSSL_PARAM_construct_size_t(OSSL_KDF_PARAM_MAC_SIZE, (size_t)20);
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
    error("EVP_KDF_derive");
}

EVP_KDF_CTX_free(kctx);

🧚 CONFORMING TO 🧚

NIST SP800-56Cr1. that's the standard, bestie, it ate. ⭐

🌟 SEE ALSO 🌟

Go give these pages some love:

🎀 HISTORY 🎀

This functionality was added in OpenSSL 3.0. so it's not ancient, it's just iconic. 👑

Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved.

Copyright (c) 2019, Oracle and/or its affiliates. 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>.

okay that's the whole page, you understood it, I'm so proud of you 🫶 this was version 3.5.6, dated 2026-04-07, and it's the EVP_KDF-SS page in the OpenSSL 7ossl manual section — now go derive some keys, bestie, slay 💅✨

📦 where this page comes from