Crypt::DH(3pm)

💖 Crypt::DH — the manual page, but make it a group chat 💖

okay bestie, sit DOWN. this is Crypt::DH(3pm), a page from the User Contributed Perl Documentation section, and it's literally the Diffie-Hellman key exchange system in Perl. no cap, this is the math that lets two strangers whisper secrets to each other across the whole entire internet without ever saying the secret out loud. iconic behavior. 🫶

---

✨ NAME ✨

Crypt::DH — Diffie-Hellman key exchange system. that's it, that's the name, she's simple, she's elegant, she's the moment. 💅

---

🌸 SYNOPSIS 🌸

okay so here's the vibe, copy-paste coded exactly like this:

use Crypt::DH;
my $dh = Crypt::DH->new;
$dh->g($g);
$dh->p($p);

## Generate public and private keys.
$dh->generate_keys;

$my_pub_key = $dh->pub_key;

## Send $my_pub_key to "other" party, and receive "other"
## public key in return.

## Now compute shared secret from "other" public key.
my $shared_secret = $dh->compute_secret( $other_pub_key );

like… you set g, you set p, you make the keys, you yeet your public key into the void, and the other party yeets theirs back, and then boom — shared secret. 🦋

---

💜 DESCRIPTION 💜

Crypt::DH is a Perl implementation of the Diffie-Hellman key exchange system. and what IS Diffie-Hellman? it's an algorithm where two parties can agree on a shared secret key, known only to them. like, only. them. nobody else. 🙈

and the way that they negotiate it over an insecure network without the two parties ever passing the actual shared secret, or their private keys, between them?? it's giving magic. it's giving sorcery. it's giving "how is this even real" and yet. it is real. 🔥

---

🧚 THE ALGORITHM 🧚

so here's how the algorithm generally works, bestie, follow me:

Party A and Party B both choose a property p and a property g — these properties are shared by both parties. (shared! mutual! collaborative! we love to see it 💖)

then each party computes a random private key integer priv_key, where the length of priv_key is at most (number of bits in p) - 1. yes that's a real constraint, write it down. 📝

then each party computes a public key based on g, priv_key, and p. and the exact value is:

g ^ priv_key mod p

then the parties exchange these public keys. handshake! trading cards! mutuals! 🤝

the shared secret key is generated based on the exchanged public key, the private key, and p. so if the public key of Party B is denoted pub_key_B, then the shared secret is equal to:

pub_key_B ^ priv_key mod p

and the mathematical principles involved insure that both parties will generate the same shared secret key. like, they both land on the exact same number without ever comparing notes. it's giving soulmates fr fr. 😭

more information can be found in PKCS #3 (Diffie-Hellman Key Agreement Standard):

http://www.rsasecurity.com/rsalabs/pkcs/pkcs-3/

---

👑 USAGE 👑

Crypt::DH implements the core routines needed to use Diffie-Hellman key exchange. to actually use the algorithm, you'll need to start with values for p and g. quick definition check: p is a large prime, and g is a base which must be larger than 0 and less than p. don't skip that part, the vibes will not save you here. 💀

Crypt::DH uses Math::BigInt internally for big-integer calculations. so all the accessor methods (p, g, priv_key, and pub_key) return Math::BigInt objects, and so does the compute_secret method. the accessors, however, allow setting with a scalar decimal string, hex string (^0x), Math::BigInt object, or Math::Pari object (for backwards compatibility). so many options, we love flexibility. ✨

🌈 $dh = Crypt::DH->new([ %param ]).

Constructs a new Crypt::DH object and returns the object. %param may include none, some, or all of the keys p, g, and priv_key. choose your own adventure, bestie. 🎀

⭐ $dh->p([ $p ])

Given an argument $p, sets the p parameter (large prime) for this Crypt::DH object.

Returns the current value of p. (as a Math::BigInt object)

⭐ $dh->g([ $g ])

Given an argument $g, sets the g parameter (base) for this Crypt::DH object.

Returns the current value of g.

⭐ $dh->generate_keys

Generates the public and private key portions of the Crypt::DH object, assuming that you've already filled p and g with appropriate values. (assuming! key word! do your homework first 📚)

If you've provided a priv_key, it's used. otherwise a random priv_key is created using either Crypt::Random (if already loaded), or /dev/urandom, or Perl's rand, in that order. order matters, don't come for me. 🙅

⭐ $dh->compute_secret( $public_key )

Given the public key $public_key of Party B (the party with which you're performing key negotiation and exchange), computes the shared secret key, based on that public key, your own private key, and your own large prime value (p).

the historical method name compute_key is aliased to this for compatibility. she goes by both names, respect the lore. 💫

⭐ $dh->priv_key([ $priv_key ])

Returns the private key. Given an argument $priv_key, sets the priv_key parameter for this Crypt::DH object.

⭐ $dh->pub_key

Returns the public key.

---

💜 AUTHOR 💜

Benjamin Trott (cpan:BTROTT) <ben+cpan@stupidfool.org>

Brad Fitzpatrick (cpan:BRADFITZ) <brad@danga.com>

legends. both of them. 👑

---

🌟 CONTRIBUTORS 🌟

BinGOs - Chris Williams (cpan:BINGOS) <chris@bingosnet.co.uk>

Mithaldu - Christian Walde (cpan:MITHALDU) <walde.christian@googlemail.com>

---

🎀 COPYRIGHT 🎀

Copyright (c) 2012 the Crypt::DH "AUTHOR" and "CONTRIBUTORS" as listed above.

---

🦋 LICENSE 🦋

This library is free software and may be distributed under the same terms as perl itself.

---

and that's the whole page bestie!! 🫶 this was documented in perl v5.34.0, dated 2022-06-12, under the name Crypt::DH(3pm). go forth and exchange keys responsibly. mwah. 💅✨