EVP_KEYEXCH-DH(7ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💖 EVP_KEYEXCH-DH(7ossl) 💖

okay so bestie, listen up. this is the manual for EVP_KEYEXCH-DH — DH Key Exchange algorithm support. yes i'm literally citing 7ossl because that's the manual family this bad boy lives in, and i need you to know it fr fr. 🫶

✨ NAME ✨

EVP_KEYEXCH-DH — DH Key Exchange algorithm support. that's it, that's the vibe. literally what it says on the tin. 💅

🦋 DESCRIPTION 🦋

so the tea is this: it's the key exchange support for the DH and DHX key types. two keys, one iconic job. ✨

⚠️ but listen, bestie — and this is IMPORTANT — even though both key types support the same key exchange operations, you cannot use them together in a single key exchange. it is not possible to use a private key of the DH type in key exchange with the public key of the DHX type, and vice versa. it's giving "same energy, different worlds." no mixing. periodt. 💀

🎀 DH and DHX key exchange parameters 🎀

"pad" (OSSL_EXCHANGE_PARAM_PAD) <unsigned integer>

sets the padding mode for the associated key exchange ctx. set a value of 1 → padding ON. set a value of 0 → padding OFF. simple as. 🌸

  • if padding is off, the derived shared secret may be smaller than the largest possible secret size 😭
  • if padding is on, the derived shared secret will have its first bytes filled with zeros where necessary, so the shared secret is the same size as the largest possible secret size 👑
🚨 heads up: the padding mode parameter is ignored (and padding is implicitly enabled) when the KDF type is set to "X942KDF-ASN1" (OSSL_KDF_NAME_X942KDF_ASN1). so don't come for me when your pad flag does nothing there. it's by design, iykyk. 💅

here's the rest of the parameter gang — all of these are <UTF8 string>, <unsigned integer>, <octet string> or <integer> depending on the one you're looking at, and honestly the way they all just exist together is iconic:

  • "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>
  • "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>

for all of those, go read "Common Key Exchange parameters" in provider-keyexch(7) — they're literally all documented there and i'm not about to steal their moment. 🌈

and then there's this one, main character energy of its own:

  • "cekalg" (OSSL_KDF_PARAM_CEK_ALG) <octet string ptr>

→ check "KDF Parameters" in provider-kdf(7). yes bestie, another cross-reference, we stay linked. 🦋

🍓 EXAMPLES 🍓

okay so these examples assume a host and peer both generate keys using the same named group (or domain parameters). see "Examples" in EVP_PKEY-DH(7). both the host and peer transfer their public key to each other. teamwork makes the dream work. 💜

🌸 convert the peer's generated key pair to a public key in DER format

so you can transfer it to the host, slay:

EVP_PKEY *peer_key; /* It is assumed this contains the peers generated key */
unsigned char *peer_pub_der = NULL;
int peer_pub_der_len;

peer_pub_der_len = i2d_PUBKEY(peer_key, &peer_pub_der);
...
OPENSSL_free(peer_pub_der);

🧚 convert the received peer's public key from DER format on the host

the receiving end of the glow-up:

const unsigned char *pd = peer_pub_der;
EVP_PKEY *peer_pub_key = d2i_PUBKEY(NULL, &pd, peer_pub_der_len);
...
EVP_PKEY_free(peer_pub_key);

👑 derive a shared secret on the host

using the host's key and the peer's public key. this is the moment. the shared secret reveal. ✨

/* It is assumed that the host_key and peer_pub_key are set up */
void derive_secret(EVP_KEY *host_key, EVP_PKEY *peer_pub_key)
{
    unsigned int pad = 1;
    OSSL_PARAM params[2];
    unsigned char *secret = NULL;
    size_t secret_len = 0;
    EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL);

    EVP_PKEY_derive_init(dctx);

    /* Optionally set the padding */
    params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad);
    params[1] = OSSL_PARAM_construct_end();
    EVP_PKEY_CTX_set_params(dctx, params);

    EVP_PKEY_derive_set_peer(dctx, peer_pub_key);

    /* Get the size by passing NULL as the buffer */
    EVP_PKEY_derive(dctx, NULL, &secret_len);
    secret = OPENSSL_zalloc(secret_len);

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

and the tea is: very similar code can be used by the peer to derive the same shared secret using the host's public key and the peer's generated key pair. symmetry! we love to see it. 💅🫶

🌈 SEE ALSO 🌈

go off and read these, bestie, they're all connected:

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

🎀 and that's the whole page, bestie! this was 3.5.0, dated 2026-09-25 — so go forth, exchange those keys, and remember: DH and DHX do NOT mix. periodt. 💅✨🦋
📦 where this page comes from