EVP_KDF-X963(7ossl)

📦
version 3.5.9 · 8 versions
, in alpine 3.23, alpine 3.24

💜 EVP_KDF-X963 — the X9.63-2001 EVP_KDF glow-up

ok so this is a page from the OpenSSL manual, bestie, and it's about the X963 key derivation function. let's get into it ✨

🌸 NAME 🌸

EVP_KDF-X963 — literally the X9.63-2001 EVP_KDF implementation. that's the whole vibe of this page, no cap 💅

🦋 DESCRIPTION 🦋

so the EVP_KDF-X963 algorithm implements the key derivation function, aka X963KDF (yes it's giving acronym-on-acronym, we love that for us). X963KDF gets used by Cryptographic Message Syntax (CMS) for EC KeyAgreement, to derive a key using input like a shared secret key and shared info 🔑

and the output? considered to be keying material. periodt.

🎀 Identity 🎀

"X963KDF" is the name for this implementation — that's your girl's government name, fr fr. you can use it with the EVP_KDF_fetch() function 🫶

⭐ Supported parameters ⭐

here's the roster, and yes, every single one is invited to the party:

  • "properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>
  • "digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>

these two work exactly as described in "PARAMETERS" in EVP_KDF(3). no notes, iconic behavior 💖

  • "key" (OSSL_KDF_PARAM_KEY) <octet string> — the shared secret used for key derivation. this parameter sets the secret 🔐
  • "info" (OSSL_KDF_PARAM_INFO) <octet string> — specifies an optional value for shared info. optional! she can show up or she can stay home 💅

the OpenSSL FIPS provider also supports these next ones 👑:

  • "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 any "***-check" related parameter is set to 0 and the check fails 🕵️
  • "digest-check" (OSSL_KDF_PARAM_FIPS_DIGEST_CHECK) <int> — the default value of 1 causes an error during EVP_KDF_CTX_set_params() if the used digest is not approved. setting this to zero will ignore the error and set the approved "fips-indicator" to 0.
⚠️ heads up bestie: this option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0. like, actually breaks it. don't play 🙈

according to ANSI X9.63-2001, the approved digest algorithms are: SHA2-224, SHA2-256, SHA2-384, SHA2-512, SHA2-512/224, SHA2-512/256, SHA3-224, SHA3-256, SHA3-384, SHA3-512. the whole approved squad, honorable mentions only 🌈

  • "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.
⚠️ same warning, same energy: this option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0. lowkey important, highkey important, all the keys 🔑

🌟 NOTES 🌟

X963KDF is very similar to the SSKDF that uses a digest as the auxiliary function — but here's the plot twist: X963KDF appends the counter to the secret, whereas SSKDF prepends the counter. the way that one little ordering difference changes everything 😭

to get a context for X963KDF, you literally just call:

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

and the output length of an X963KDF is specified via the keylen parameter to the EVP_KDF_derive(3) function. that's where you tell her how much material you want 🎀

🔥 EXAMPLES 🔥

this example derives 10 bytes, with the secret key "secret" and sharedinfo value "label". copy it exactly, don't be cute with it:

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

kdf = EVP_KDF_fetch(NULL, "X963KDF", 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_SECRET,
                                         "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);

🧚 CONFORMING TO 🧚

"SEC 1: Elliptic Curve Cryptography" — she's certified, she's standards-compliant, she's that girl 💅

💀 SEE ALSO 💀

go read these next, bestie, iykyk:

🌈 HISTORY 🌈

this functionality was added in OpenSSL 3.0. she's not a legacy icon, she's a modern one ✨

Copyright 2019-2024 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 OpenSSL 3.5.9, dated 2026-09-29 — go derive some keys, slay, and remember: append the counter, not prepend. periodt 💅🎀

📦 where this page comes from