DH_GENERATE_PARAMETERS(3)

💖 DH_GENERATE_PARAMETERS(3) 💖

okay so bestie, this one's from the Library Functions Manual and it's literally all about generating and checking Diffie-Hellman parameters ✨ (yes the crypto kind, not the "parameters of my life" kind 😭)

---

✨ SYNOPSIS ✨

#include <openssl/dh.h>

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);

Deprecated: 🫠

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

---

🌸 DESCRIPTION 🌸

So DH_generate_parameters_ex() is the main character here — it generates Diffie-Hellman parameters that can be shared among a whole group of users, and it stashes them in the DH structure you hand it. very "community property" of it 💅

prime_len is the length in bits of the safe prime it's gonna generate. and generator is a small number > 1, typically 2 or 5 — no cap.

A callback function can be used to give you feedback on how the key generation is going (because bestie, it's gonna take a while — see CAVEATS 👀). If cb is not NULL, it gets called as described in BN_generate_prime(3) while a random prime number is generated, and when a prime has been found, BN_GENCB_call(cb, 3, 0) is called; see BN_GENCB_call(3). iconic little progress bar energy 🎀

Then there's DH_check() — it validates your 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. rude.
• DH_CHECK_P_NOT_SAFE_PRIME — the parameter dh->p is not a safe prime. 💀
• DH_UNABLE_TO_CHECK_GENERATOR — the generator dh->g can't even be checked for suitability: it's neither 2 nor 5.
• DH_NOT_SUITABLE_GENERATOR — the generator dh->g is just... not suitable. it's giving wrong vibe 😭

And DH_check_pub_key() checks whether pub_key is a valid public key when you're 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.
• DH_CHECK_PUBKEY_TOO_LARGE — pub_key is greater than or equal to dh->p - 1. too much going on.
• DH_CHECK_PUBKEY_INVALID — dh->q is set but pub_key to the power of dh->q is not 1 modulo dh->p. 🧚 math said no.

---

🔥 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 flop, no in between 🫶

DH_generate_parameters() (the deprecated one, boo 👎) 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) — go look them up if you need the lore.

---

🦋 SEE ALSO 🦋

DH_get0_pqg(3), DH_new(3)

---

🌈 HISTORY 🌈

• DH_check() and DH_generate_parameters() first appeared in SSLeay 0.5.1 and have been available since OpenBSD 2.4. ancient. elders. 👑
• The cb_arg argument to DH_generate_parameters() was added in SSLeay 0.9.0.
• DH_check_pub_key() first appeared in OpenSSL 0.9.8a and has been available since OpenBSD 4.0.
• DH_generate_parameters_ex() first appeared in OpenSSL 0.9.8 and has been available since OpenBSD 4.5.

---

💀 CAVEATS 💀

DH_generate_parameters_ex() and DH_generate_parameters() may run for several hours before finding a suitable prime. 😭😭😭 like genuinely go touch grass, go get a snack, it'll be there when you get back.

Also!! The parameters generated by DH_generate_parameters_ex() and DH_generate_parameters() are not to be used in signature schemes. do not do it. i'm serious. 🙈

---

🙈 BUGS 🙈

If generator is not 2 or 5, dh->g=generator is not a usable generator. that's just how it is bestie, no notes 💅

---

mwah 💖 written with love from the Debian crew — page dated July 13, 2022, and this is DH_GENERATE_PARAMETERS(3) signing off. ily, go generate some primes responsibly 🎀✨