hcrypto_dh(3)

💖 hcrypto_dh — Diffie-Hellman functions 💖

okay bestie, sit down, hydrate, because we're doing Diffie-Hellman from the Heimdal crypto library and it's honestly giving cryptography main character energy 🔐✨

---

✨ SYNOPSIS ✨

🫶 Functions 🫶

no cap, here's the whole squad, exactly as they come:

const DH_METHOD * DH_ltm_method (void)
DH * DH_new (void)
DH * DH_new_method (ENGINE *engine)
void DH_free (DH *dh)
int DH_up_ref (DH *dh)
int DH_size (const DH *dh)
int DH_set_ex_data (DH *dh, int idx, void *data)
void * DH_get_ex_data (DH *dh, int idx)
int DH_generate_parameters_ex (DH *dh, int prime_len, int generator,
    BN_GENCB *cb)
int DH_check_pubkey (const DH *dh, const BIGNUM *pub_key, int *codes)
int DH_generate_key (DH *dh)
int DH_compute_key (unsigned char *shared_key, const BIGNUM
    *peer_pub_key, DH *dh)
int DH_set_method (DH *dh, const DH_METHOD *method)
const DH_METHOD * DH_null_method (void)
void DH_set_default_method (const DH_METHOD *meth)
const DH_METHOD * DH_get_default_method (void)

---

🌈 Detailed Description 🌈

See the DH - Diffie-Hellman key exchange for description and examples. that's it, that's the whole vibe — go read that one for the lore and the examples 💅

---

🎀 Function Documentation 🎀

🦋 int DH_check_pubkey (const DH * dh, const BIGNUM * pub_key, int * codes) 🦋

girl, we're doing a vibe check on the public key. is it sane? is it normal? let's find out 🕵️♀️

Parameters

• dh — the local peer DH parameters.
• pub_key — the remote peer public key parameters.
• codes — return that the failures of the pub_key are.

Returns

1 on success, 0 on failure and *codes is set the the combined fail check for the public key. (yes, "the the", that's how it's written, i don't make the rules 🙈)

Checks that the function performs are:

• pub_key is not negative
• pub_key > 1 and pub_key < p - 1, to avoid small subgroups attack.
• if g == 2, pub_key have more then one bit set, if bits set is 1, log_2(pub_key) is trival

not me protecting you from small subgroups attacks like the icon you are 🫶

---

🦋 int DH_compute_key (unsigned char * shared_key, const BIGNUM * peer_pub_key, DH * dh) 🦋

Complute the shared secret key. (spelling as-is, bestie, we don't touch the source 💀) this is the moment where you and your peer agree on a secret and it's lowkey iconic ✨

Parameters

• shared_key — the resulting shared key, need to be at least DH_size() large.
• peer_pub_key — the peer's public key.
• dh — the dh key pair.

Returns

1 on success.

Checks that the pubkey passed in is valid using DH_check_pubkey().

---

🦋 void DH_free (DH * dh) 🦋

Free a DH object and release related resources, like ENGINE, that the object was using. it's giving responsible adult, we love a clean exit 💅

Parameters

• dh — object to be freed.

---

🦋 int DH_generate_key (DH * dh) 🦋

Generate a new DH private-public key pair. The dh parameter must be allocted first with DH_new(). dh->p and dp->g must be set.

🚨 heads up bestie: you have to DH_new() that thing first, and dh->p and dp->g must be set. no shortcuts, no cap.

Parameters

• dh — dh parameter.

Returns

1 on success.

---

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

Generate DH parameters for the DH object give parameters. (again, their words, not mine 🍓)

Parameters

• dh — The DH object to generate parameters for.
• prime_len — length of the prime
• generator — generator, g
• cb — Callback parameters to show progress, can be NULL.

Returns

the maximum size in bytes of the out data.

---

🦋 const DH_METHOD* DH_get_default_method (void) 🦋

Return the default DH implementation. the one that shows up when nobody picked a fave 🌸

Returns

pointer to a DH_METHOD.

---

🦋 void* DH_get_ex_data (DH * dh, int idx) 🦋

Get the data for index idx in the DH object. peek inside the little storage locker, slay 🔍

Parameters

• dh — DH object.
• idx — index to get the data for.

Returns

the object store in index idx

---

🦋 const DH_METHOD* DH_ltm_method (void) 🦋

DH implementation using libtommath. math girlies rise 👑

Returns

the DH_METHOD for the DH implementation using libtommath.

---

🦋 DH* DH_new (void) 🦋

Create a new DH object using DH_new_method(NULL), see DH_new_method(). brand new, fresh out the box ✨

Returns

a newly allocated DH object.

---

🦋 DH* DH_new_method (ENGINE * engine) 🦋

Create a new DH object from the given engine, if the NULL is used, the default engine is used. Free the DH object with DH_free(). don't forget the cleanup, bestie 🧹

Parameters

• engine — The engine to use to allocate the DH object.

Returns

a newly allocated DH object.

---

🦋 const DH_METHOD* DH_null_method (void) 🦋

Return the dummy DH implementation. it's the nothing-burger of methods, and honestly? iconic for it 💀

Returns

pointer to a DH_METHOD.

---

🦋 void DH_set_default_method (const DH_METHOD * meth) 🦋

Set the default DH implementation. choosing your fave fr fr 🌟

Parameters

• meth — pointer to a DH_METHOD.

---

🦋 int DH_set_ex_data (DH * dh, int idx, void * data) 🦋

Set the data index idx in the DH object to data. tuck it in, keep it safe 🎀

Parameters

• dh — DH object.
• idx — index to set the data for.
• data — data to store for the index idx.

Returns

1 on success.

---

🦋 int DH_set_method (DH * dh, const DH_METHOD * method) 🦋

Set a new method for the DH keypair. glow-up time 🔥

Parameters

• dh — dh parameter.
• method — the new method for the DH parameter.

Returns

1 on success.

---

🦋 int DH_size (const DH * dh) 🦋

The maximum output size of the DH_compute_key() function. how much room you need to give that shared key, periodt 📏

Parameters

• dh — The DH object to get the size from.

Returns

the maximum size in bytes of the out data.

---

🦋 int DH_up_ref (DH * dh) 🦋

Add a reference to the DH object. The object should be free with DH_free() to drop the reference. keeping the party alive a little longer 🫶

Parameters

• dh — the object to increase the reference count too.

Returns

the updated reference count, can't safely be used except for debug printing.

⚠️ fr fr: that return value is for debug printing only. do not build logic on it, it will not love you back 😭

---

🌟 Author 🌟

Generated automatically by Doxygen for Heimdal crypto library from the source code. so technically the author is a robot and we respect the robot 🤖💖

---

and that's the whole page, bestie!! you now know every single function, every parameter, every return value, and every check. no skips, no summaries, we ate and left no crumbs 👑

this was hcrypto_dh(3) from Version 7.8.0, dated Tue Nov 15 2022 — Heimdal crypto library, out. mwah 💋