Crypt::PK::DH(3) User Contributed Perl Documentation Crypt::PK::DH(3) NAME Crypt::PK::DH - Public key cryptography based on Diffie-Hellman SYNOPSIS ### OO interface #Shared secret my $alice = Crypt::PK::DH->new(); $alice->generate_key('ike2048'); my $bob = Crypt::PK::DH->new(); $bob->generate_key($alice->params2hash); my $alice_public = $alice->export_key('public'); my $bob_public = $bob->export_key('public'); my $alice_shared = $alice->shared_secret(Crypt::PK::DH->new(\$bob_public)); my $bob_shared = $bob->shared_secret(Crypt::PK::DH->new(\$alice_public)); #Key generation my $pk = Crypt::PK::DH->new(); $pk->generate_key(256); my $private = $pk->export_key('private'); my $public = $pk->export_key('public'); #or use a named IKE group my $pk = Crypt::PK::DH->new(); $pk->generate_key('ike2048'); my $private = $pk->export_key('private'); my $public = $pk->export_key('public'); #or provide explicit parameters my $pk = Crypt::PK::DH->new(); $pk->generate_key({ p => $p, g => $g }); my $private = $pk->export_key('private'); my $public = $pk->export_key('public'); DESCRIPTION Provides Diffie-Hellman key agreement. Use it to generate a DH private/public key pair and to derive a shared secret from your private key and the peer's public key. Parameters can come from libtomcrypt's built-in groups, the named IKE groups, an explicit "{ p => ..., g => ... }" hash, or a PEM/DER buffer that contains DH parameters. Legacy function-style wrappers still exist in code for backwards compatibility, but they are intentionally undocumented. METHODS new my $pk = Crypt::PK::DH->new(); $pk->generate_key('ike2048'); my $public_blob = $pk->export_key('public'); my $pub = Crypt::PK::DH->new(\$public_blob); Passing $filename or "\$buffer" to "new" is equivalent: both forms immediately import the key material into the new object. generate_key Uses the bundled "chacha20" PRNG via libtomcrypt's "rng_make_prng". Returns the object itself (for chaining). $pk->generate_key($groupsize); ### $groupsize (in bytes) corresponds to DH parameters (p, g) predefined by libtomcrypt # 96 => DH-768 # 128 => DH-1024 # 192 => DH-1536 # 256 => DH-2048 # 384 => DH-3072 # 512 => DH-4096 # 768 => DH-6144 # 1024 => DH-8192 The following variants are available since CryptX-0.032 $pk->generate_key($groupname) ### $groupname selects a named IKE/MODP group from RFC 7296 and RFC 3526. ### The number suffix is the bit size of the prime (p). # 'ike768' => 768-bit MODP (IKE Group 1 - RFC 2409) -- NOT recommended # 'ike1024' => 1024-bit MODP (IKE Group 2 - RFC 2409) -- NOT recommended # 'ike1536' => 1536-bit MODP (IKE Group 5 - RFC 3526) # 'ike2048' => 2048-bit MODP (IKE Group 14 - RFC 3526) -- minimum recommended # 'ike3072' => 3072-bit MODP (IKE Group 15 - RFC 3526) # 'ike4096' => 4096-bit MODP (IKE Group 16 - RFC 3526) # 'ike6144' => 6144-bit MODP (IKE Group 17 - RFC 3526) # 'ike8192' => 8192-bit MODP (IKE Group 18 - RFC 3526) $pk->generate_key($param_hash) # $param_hash is { g => $g, p => $p } # where $g is the generator (base) in a hex string and $p is the prime in a hex string # practical current limit: custom p/g values must fit into the current XS buffers # (roughly up to the built-in 8192-bit group sizes) $pk->generate_key(\$dh_param) # $dh_param is the content of DER or PEM file with DH parameters # e.g. openssl dhparam 2048 import_key Loads private or public key (exported by "export_key"). my $source = Crypt::PK::DH->new(); $source->generate_key('ike2048'); my $public_blob = $source->export_key('public'); my $pub = Crypt::PK::DH->new(); $pub->import_key(\$public_blob); The same method also accepts a filename instead of "\$public_blob". import_key_raw Since: CryptX-0.032 $pk->import_key_raw($raw_bytes, $type, $params) # $raw_bytes .. [binary string] raw key data # $type ....... [string] 'private' or 'public' # $params ..... [string | hashref] group name (e.g. 'ike2048') or { g => $g, p => $p } with hex strings export_key BEWARE: DH key format change - since v0.049 it is compatible with libtomcrypt 1.18. my $private = $pk->export_key('private'); #or my $public = $pk->export_key('public'); export_key_raw Since: CryptX-0.032 Returns the raw key as a binary string. $raw_bytes = $dh->export_key_raw('public') #or $raw_bytes = $dh->export_key_raw('private') shared_secret Returns the shared secret as a binary string (raw bytes). my $alice = Crypt::PK::DH->new(); $alice->generate_key('ike2048'); my $bob = Crypt::PK::DH->new(); $bob->generate_key($alice->params2hash); my $alice_public = $alice->export_key('public'); my $bob_public = $bob->export_key('public'); my $alice_shared = $alice->shared_secret(Crypt::PK::DH->new(\$bob_public)); my $bob_shared = $bob->shared_secret(Crypt::PK::DH->new(\$alice_public)); is_private my $rv = $pk->is_private; # 1 .. private key loaded # 0 .. public key loaded # undef .. no key loaded size my $size = $pk->size; # returns key size in bytes or undef if no key loaded key2hash Returns a hashref with the key components, or "undef" if no key is loaded. my $hash = $pk->key2hash; # returns hash like this (or undef if no key loaded): { type => 0, # integer: 1 .. private, 0 .. public size => 256, # integer: key size in bytes x => "FBC1062F73B9A17BB8473A2F5A074911FA7F20D28FB...", #private key y => "AB9AAA40774D3CD476B52F82E7EE2D8A8D40CD88BF4...", #public key g => "2", # generator/base p => "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80D...", # prime } params2hash Since: CryptX-0.032 my $params = $pk->params2hash; # returns hash like this (or undef if no key loaded): { g => "2", # generator/base p => "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80D...", # prime } SEE ALSO o o o perl v5.42.2 2026-08-10 Crypt::PK::DH(3)