DH_NEW(3)

💖 DH_NEW(3) — like, the whole allocate-and-free situation for DH objects 💖

okay bestie, this one's from the Library Functions Manual (yes, the Library Functions Manual, we stan a classic) and it's all about the three little functions that birth a DH object, keep it alive, and yeet it into the void. let's get into it 🫶

---

✨ NAME ✨

DH_new, DH_up_ref, DH_free — allocate and free DH objects. that's the whole vibe. 💅

---

🌸 SYNOPSIS 🌸

#include <openssl/dh.h>

DH*
DH_new(void);

int
DH_up_ref(DH *dh);

void
DH_free(DH *dh);

look at them. three little icons. 👑

---

🦋 DESCRIPTION 🦋

so the DH functions implement the Diffie-Hellman key agreement protocol — yes that Diffie-Hellman, the og key agreement protocol, main character energy fr fr 🔥

• DH_new() — allocates and initializes a DH structure, and sets the reference count to 1. it's literally equivalent to DH_new_method(3) with a NULL argument. no cap, that's the exact same thing. ✨
• DH_up_ref() — increments the reference count by 1. that's it. that's the whole job. keep it alive bestie 💖
• DH_free() — decrements the reference count by 1. and if it hits 0? it frees the DH structure and its components. the values are erased before the memory is returned to the system (yes, they're being responsible about it, we love to see it 🙈). and if dh is a NULL pointer, no action occurs — nothing happens, no drama, no crash, we simply move on. 💀

lowkey important: reference counting is a whole thing, so don't go freeing stuff twice or the vibe check will fail catastrophically 😭

---

🎀 RETURN VALUES 🎀

• if the allocation fails, DH_new() returns NULL and sets an error code that you can grab with ERR_get_error(3). so if you see a NULL, go check the error stack, bestie. otherwise it returns a pointer to the newly allocated structure 🌈
• DH_up_ref() returns 1 for success or 0 for failure. simple as that. 🍓

---

⭐ SEE ALSO ⭐

the whole friend group, gathered together 🫶

BN_new(3), crypto(3), d2i_DHparams(3), DH_generate_key(3), DH_generate_parameters(3), DH_get0_pqg(3), DH_get_ex_new_index(3), DH_security_bits(3), DH_set_method(3), DH_size(3), DHparams_print(3), DSA_dup_DH(3), EVP_PKEY_CTX_set_dh_paramgen_prime_len(3), EVP_PKEY_set1_DH(3)

like, go read them. iykyk 💜

---

🧚 HISTORY 🧚

• DH_new() and DH_free() first appeared in SSLeay 0.5.1 and have been available since OpenBSD 2.4. vintage. iconic. they've been doing this since before we were born 💅
• DH_up_ref() first appeared in OpenSSL 0.9.7 and has been available since OpenBSD 3.2. a slightly younger legend but a legend nonetheless 👑

---

and that's the page, bestie!! this one's from Debian, dated July 13, 2022 — so go forth, allocate responsibly, and remember: every DH_new() deserves its DH_free(). mwah 💋🎀✨