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-8192The 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 2048import_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 stringsexport_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 loadedsize
my $size = $pk->size;
# returns key size in bytes or undef if no key loadedkey2hash
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
}