EVP_KEYEXCH-ECDH(7ossl)

💅 EVP_KEYEXCH-ECDH 💅

hey bestie, welcome to the 7ossl manual page for EVP_KEYEXCH-ECDH — this is OpenSSL’s ECDH Key Exchange algorithm support, and we’re gonna get you comfy with it. no cap. 🫶

✨ NAME ✨

EVP_KEYEXCH-ECDH — ECDH Key Exchange algorithm support 💖

🌸 DESCRIPTION 🌸

It’s the key exchange support for the ECDH key type. literally that’s the whole vibe. ✨

🎀 ECDH Key Exchange parameters 🎀

• "ecdh-cofactor-mode" (OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE) — <integer> — sets or gets the ECDH mode of operation for the associated key exchange ctx.

in an Elliptic Curve Diffie-Hellman key exchange, this parameter lets you pick between the plain Diffie-Hellman (DH) or Cofactor Diffie-Hellman (CDH) variants of the key exchange algorithm. iconic little switch. 🔥

when you’re setting it, the value should be 1, 0 or -1 — those respectively force cofactor mode on, off, or reset it to the default for the private key associated with the given key exchange ctx. 🫶

when you’re getting it, the value should be either 1 or 0, respectively signaling if the cofactor mode is on or off. 💅

see also provider-keymgmt(7) for the related OSSL_PKEY_PARAM_USE_COFACTOR_ECDH parameter that can be set on a per-key basis. 💖

• "kdf-type" (OSSL_EXCHANGE_PARAM_KDF_TYPE) — <UTF8 string>
• "kdf-digest" (OSSL_EXCHANGE_PARAM_KDF_DIGEST) — <UTF8 string>
• "kdf-digest-props" (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) — <UTF8 string>
• "kdf-outlen" (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) — <unsigned integer>
• "kdf-ukm" (OSSL_EXCHANGE_PARAM_KDF_UKM) — <octet string>

these are the KDF-related params, exactly as the page lists them. no extra lore, just the names and types. 🎀

the OpenSSL FIPS provider also supports the following parameters:

• "fips-indicator" (OSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR) — <integer>
• "key-check" (OSSL_EXCHANGE_PARAM_FIPS_KEY_CHECK) — <integer>
• "digest-check" (OSSL_EXCHANGE_PARAM_FIPS_DIGEST_CHECK) — <integer>

see “Common Key Exchange parameters” in provider-keyexch(7). 🌈

• "ecdh-cofactor-check" (OSSL_EXCHANGE_PARAM_FIPS_ECDH_COFACTOR_CHECK) — <integer> — if required, this parameter should come before OSSL_FUNC_keyexch_derive(). the default value of 1 causes an error during the OSSL_FUNC_keyexch_derive if the EC curve has a cofactor that is not 1, and the cofactor is not used. setting this to 0 will ignore the error and set the approved "fips-indicator" to 0.

🚨 this option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0. like, big red flag energy, bestie. be careful. 💀

🦋 EXAMPLES 🦋

examples of key agreement can be found in demos/keyexch. 📁

keys for the host and peer must be generated as shown in “Examples” in EVP_PKEY-EC(7) using the same curve name. same curve, bestie — don’t mix and match. 🎀

the code to generate a shared secret for the normal case is identical to “Examples” in EVP_KEYEXCH-DH(7). 🫶

to derive a shared secret on the host using the host’s key and the peer’s public key but also using X963KDF with a user key material:

/* It is assumed that the host_key, peer_pub_key and ukm are set up */
void derive_secret(EVP_PKEY *host_key, EVP_PKEY *peer_key,
                   unsigned char *ukm, size_t ukm_len)
{
    unsigned char secret[64];
    size_t out_len = sizeof(secret);
    size_t secret_len = out_len;
    unsigned int pad = 1;
    OSSL_PARAM params[6];
    EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL);

    EVP_PKEY_derive_init(dctx);

    params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad);
    params[1] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_TYPE,
                                                 "X963KDF", 0);
    params[2] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_DIGEST,
                                                 "SHA1", 0);
    params[3] = OSSL_PARAM_construct_size_t(OSSL_EXCHANGE_PARAM_KDF_OUTLEN,
                                            &out_len);
    params[4] = OSSL_PARAM_construct_octet_string(OSSL_EXCHANGE_PARAM_KDF_UKM,
                                                  ukm, ukm_len);
    params[5] = OSSL_PARAM_construct_end();
    EVP_PKEY_CTX_set_params(dctx, params);

    EVP_PKEY_derive_set_peer(dctx, peer_pub_key);
    EVP_PKEY_derive(dctx, secret, &secret_len);
    ...
    OPENSSL_clear_free(secret, secret_len);
    EVP_PKEY_CTX_free(dctx);
}

👑 SEE ALSO 👑

the whole squad: EVP_PKEY-EC(7) EVP_PKEY(3), provider-keyexch(7), provider-keymgmt(7), OSSL_PROVIDER-default(7), OSSL_PROVIDER-FIPS(7), 💅

💜 COPYRIGHT 💜

Copyright 2020-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>. 🫶

---

okay that’s the whole page bestie — OpenSSL 3.5.9, dated 2026-09-29, EVP_KEYEXCH-ECDH(7ossl). mwah 💋✨