Reference

Crypt::PK::DH(3pm)

Public key cryptography based on Diffie-Hellman

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

•

<https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange>

•

<https://www.rfc-editor.org/rfc/rfc3526>

•

<https://www.rfc-editor.org/rfc/rfc7296>

History