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 <https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange>
o <https://www.rfc-editor.org/rfc/rfc3526>
o <https://www.rfc-editor.org/rfc/rfc7296>
perl v5.34.3 2026-05-11 Crypt::PK::DH(3)
cryptx 0.89.0 - Generated Tue May 12 08:18:48 CDT 2026