DH_GENERATE_PARAMETERS(3)

💖 DH_GENERATE_PARAMETERS(3) — generate and check Diffie-Hellman parameters 💖

okay so bestie, this one is a whole library functions manual page for libcrypto — yes, that libcrypto, the big one. we're doing Diffie-Hellman parameter generation and validation today and honestly it's giving cryptography main character energy 👑

---

✨ NAME ✨

DH_generate_parameters_ex, DH_check, DH_check_pub_key, DH_generate_parameters — generate and check Diffie-Hellman parameters. that's the whole vibe, no cap 💅

---

🌸 SYNOPSIS 🌸

first things first, you gotta pull in the header, she lives at libcrypto:

#include <openssl/dh.h>

then the fresh functions:

int
DH_generate_parameters_ex(DH *dh, int prime_len, int generator,
    BN_GENCB *cb);

int
DH_check(DH *dh, int *codes);

int
DH_check_pub_key(const DH *dh, const BIGNUM *pub_key, int *codes);

and then... the deprecated one 🙈 (we'll get to her, don't worry):

DH *
DH_generate_parameters(int prime_len, int generator,
    void (*callback)(int, int, void *), void *cb_arg);

---

🦋 DESCRIPTION 🦋

💜 DH_generate_parameters_ex()

so DH_generate_parameters_ex() generates Diffie-Hellman parameters that can be shared among a group of users, and stores them in the DH structure you hand over. group chat cryptography fr fr 🫶

prime_len is the length in bits of the safe prime to be generated. generator is a small number > 1, typically 2 or 5. iconic little guys.

a callback function may be used to give you feedback about the progress of the key generation. if cb is not NULL, it gets called exactly as described in BN_generate_prime(3) while a random prime number is being generated — and when a prime has been found, BN_GENCB_call(cb, 3, 0) is called; see BN_GENCB_call(3). so like, it literally tells you when it's cooking 🔥

🎀 DH_check()

DH_check() validates Diffie-Hellman parameters. if no problems are found, *codes is set to zero. otherwise, one or more of these bits get set:

• DH_CHECK_P_NOT_PRIME — the parameter dh->p is not prime. 💀
• DH_CHECK_P_NOT_SAFE_PRIME — the parameter dh->p is not a safe prime. 😭
• DH_UNABLE_TO_CHECK_GENERATOR — the generator dh->g cannot be checked for suitability: it is neither 2 nor 5. like, girl, we can't even evaluate.
• DH_NOT_SUITABLE_GENERATOR — the generator dh->g is not suitable. that's it, that's the whole note.

🌈 DH_check_pub_key()

DH_check_pub_key() checks whether pub_key is a valid public key when using the domain parameters contained in dh. if no problems are found, *codes is set to zero. otherwise, one or more of these bits are set:

• DH_CHECK_PUBKEY_TOO_SMALL — pub_key is less than or equal to 1. tiny. too tiny.
• DH_CHECK_PUBKEY_TOO_LARGE — pub_key is greater than or equal to dh->p - 1. she's doing too much.
• DH_CHECK_PUBKEY_INVALID — dh->q is set but pub_key to the power of dh->q is not 1 modulo dh->p. ✨ math check failed ✨

---

👑 RETURN VALUES 👑

DH_generate_parameters_ex(), DH_check(), and DH_check_pub_key() return 1 if the check could be performed or 0 otherwise. slay or don't slay, there is no in between.

DH_generate_parameters() (deprecated, remember her?) returns a pointer to the DH structure, or NULL if the parameter generation fails.

the error codes can be obtained by ERR_get_error(3). so if something's off, that's where you go snooping 🔍

---

🧚 SEE ALSO 🧚

• DH_get0_pqg(3)
• DH_new(3)

go read those next, i promise they're worth it 💖

---

⭐ HISTORY ⭐

• DH_check() and DH_generate_parameters() first appeared in SSLeay 0.5.1 and have been available since OpenBSD 2.4. vintage. ancestral. we respect the lineage 🫡
• the cb_arg argument to DH_generate_parameters() was added in SSLeay 0.9.0. a glow-up, honestly.
• DH_check_pub_key() first appeared in OpenSSL 0.9.8a and has been available since OpenBSD 4.0. she's newer, she's thriving 🌱
• DH_generate_parameters_ex() first appeared in OpenSSL 0.9.8 and has been available since OpenBSD 4.5. the youngest sibling, and arguably the favorite 💅

---

🍓 CAVEATS 🍓

ok important, so listen: DH_generate_parameters_ex() and DH_generate_parameters() may run for several hours before finding a suitable prime. HOURS. bestie. go touch grass, make a snack, hydrate, come back 😭

also: the parameters generated by DH_generate_parameters_ex() and DH_generate_parameters() are not to be used in signature schemes. periodt. not a suggestion, it's a rule.

---

💀 BUGS 💀

if generator is not 2 or 5, dh->g=generator is not a usable generator. yeah. that's the bug note. we said what we said 🙈

---

that's the whole page, bestie — go forth and generate responsibly 🦋✨

Debian · June 8, 2025 · DH_GENERATE_PARAMETERS(3) — mwah, love u, bye 💋🎀