.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Crypt::PK::DH 3"
.TH Crypt::PK::DH 3 "2022-01-07" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Crypt::PK::DH \- Public key cryptography based on Diffie\-Hellman
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& ### OO interface
\&
\& #Shared secret
\& my $priv = Crypt::PK::DH\->new(\*(AqAlice_priv_dh1.key\*(Aq);
\& my $pub = Crypt::PK::DH\->new(\*(AqBob_pub_dh1.key\*(Aq);
\& my $shared_secret = $priv\->shared_secret($pub);
\&
\& #Key generation
\& my $pk = Crypt::PK::DH\->new();
\& $pk\->generate_key(128);
\& my $private = $pk\->export_key(\*(Aqprivate\*(Aq);
\& my $public = $pk\->export_key(\*(Aqpublic\*(Aq);
\&
\& or
\&
\& my $pk = Crypt::PK::DH\->new();
\& $pk\->generate_key(\*(Aqike2048\*(Aq);
\& my $private = $pk\->export_key(\*(Aqprivate\*(Aq);
\& my $public = $pk\->export_key(\*(Aqpublic\*(Aq);
\&
\& or
\&
\& my $pk = Crypt::PK::DH\->new();
\& $pk\->generate_key({ p => $p, g => $g });
\& my $private = $pk\->export_key(\*(Aqprivate\*(Aq);
\& my $public = $pk\->export_key(\*(Aqpublic\*(Aq);
\&
\& ### Functional interface
\&
\& #Shared secret
\& my $shared_secret = dh_shared_secret(\*(AqAlice_priv_dh1.key\*(Aq, \*(AqBob_pub_dh1.key\*(Aq);
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 5
\&  my $pk = Crypt::PK::DH\->new();
\&  #or
\&  my $pk = Crypt::PK::DH\->new($priv_or_pub_key_filename);
\&  #or
\&  my $pk = Crypt::PK::DH\->new(\e$buffer_containing_priv_or_pub_key);
.Ve
.SS "generate_key"
.IX Subsection "generate_key"
Uses Yarrow-based cryptographically strong random number generator seeded with
random data taken from \f(CW\*(C`/dev/random\*(C'\fR (\s-1UNIX\s0) or \f(CW\*(C`CryptGenRandom\*(C'\fR (Win32).
.PP
.Vb 10
\& $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
.Ve
.PP
The following variants are available since CryptX\-0.032
.PP
.Vb 10
\& $pk\->generate_key($groupname)
\& ### $groupname corresponds to values defined in RFC7296 and RFC3526
\& # \*(Aqike768\*(Aq  =>  768\-bit MODP (Group 1)
\& # \*(Aqike1024\*(Aq => 1024\-bit MODP (Group 2)
\& # \*(Aqike1536\*(Aq => 1536\-bit MODP (Group 5)
\& # \*(Aqike2048\*(Aq => 2048\-bit MODP (Group 14)
\& # \*(Aqike3072\*(Aq => 3072\-bit MODP (Group 15)
\& # \*(Aqike4096\*(Aq => 4096\-bit MODP (Group 16)
\& # \*(Aqike6144\*(Aq => 6144\-bit MODP (Group 17)
\& # \*(Aqike8192\*(Aq => 8192\-bit MODP (Group 18)
\&
\& $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
\&
\& $pk\->generate_key(\e$dh_param)
\& # $dh_param is the content of DER or PEM file with DH parameters
\& # e.g. openssl dhparam 2048
.Ve
.SS "import_key"
.IX Subsection "import_key"
Loads private or public key (exported by \*(L"export_key\*(R").
.PP
.Vb 3
\&  $pk\->import_key($filename);
\&  #or
\&  $pk\->import_key(\e$buffer_containing_key);
.Ve
.SS "import_key_raw"
.IX Subsection "import_key_raw"
\&\fISince: CryptX\-0.032\fR
.PP
.Vb 5
\&  $pk\->import_key_raw($raw_bytes, $type, $params)
\&  ### $raw_bytes is a binary string containing the key
\&  ### $type is either \*(Aqprivate\*(Aq or \*(Aqpublic\*(Aq
\&  ### $param is either a name (\*(Aqike2038\*(Aq) or hash containing the p,g values { g=>$g, p=>$p }
\&  ### in hex strings
.Ve
.SS "export_key"
.IX Subsection "export_key"
\&\fB\s-1BEWARE:\s0\fR \s-1DH\s0 key format change \- since v0.049 it is compatible with libtomcrypt 1.18.
.PP
.Vb 3
\& my $private = $pk\->export_key(\*(Aqprivate\*(Aq);
\& #or
\& my $public = $pk\->export_key(\*(Aqpublic\*(Aq);
.Ve
.SS "export_key_raw"
.IX Subsection "export_key_raw"
\&\fISince: CryptX\-0.032\fR
.PP
.Vb 3
\& $raw_bytes = $dh\->export_key_raw(\*(Aqpublic\*(Aq)
\& #or
\& $raw_bytes = $dh\->export_key_raw(\*(Aqprivate\*(Aq)
.Ve
.SS "shared_secret"
.IX Subsection "shared_secret"
.Vb 4
\& # Alice having her priv key $pk and Bob\*(Aqs public key $pkb
\& my $pk  = Crypt::PK::DH\->new($priv_key_filename);
\& my $pkb = Crypt::PK::DH\->new($pub_key_filename);
\& my $shared_secret = $pk\->shared_secret($pkb);
\&
\& # Bob having his priv key $pk and Alice\*(Aqs public key $pka
\& my $pk = Crypt::PK::DH\->new($priv_key_filename);
\& my $pka = Crypt::PK::DH\->new($pub_key_filename);
\& my $shared_secret = $pk\->shared_secret($pka);  # same value as computed by Alice
.Ve
.SS "is_private"
.IX Subsection "is_private"
.Vb 4
\& my $rv = $pk\->is_private;
\& # 1 .. private key loaded
\& # 0 .. public key loaded
\& # undef .. no key loaded
.Ve
.SS "size"
.IX Subsection "size"
.Vb 2
\& my $size = $pk\->size;
\& # returns key size in bytes or undef if no key loaded
.Ve
.SS "key2hash"
.IX Subsection "key2hash"
.Vb 1
\& 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
\&}
.Ve
.SS "params2hash"
.IX Subsection "params2hash"
\&\fISince: CryptX\-0.032\fR
.PP
.Vb 1
\& my $params = $pk\->params2hash;
\&
\& # returns hash like this (or undef if no key loaded):
\& {
\&   g => "2", # generator/base
\&   p => "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80D...", # prime
\&}
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "dh_shared_secret"
.IX Subsection "dh_shared_secret"
\&\s-1DH\s0 based shared secret generation. See method \*(L"shared_secret\*(R" below.
.PP
.Vb 2
\& #on Alice side
\& my $shared_secret = dh_shared_secret(\*(AqAlice_priv_dh1.key\*(Aq, \*(AqBob_pub_dh1.key\*(Aq);
\&
\& #on Bob side
\& my $shared_secret = dh_shared_secret(\*(AqBob_priv_dh1.key\*(Aq, \*(AqAlice_pub_dh1.key\*(Aq);
.Ve
.SH "DEPRECATED INTERFACE"
.IX Header "DEPRECATED INTERFACE"
The following functions/methods were removed in removed in v0.049:
.PP
.Vb 6
\& encrypt
\& decrypt
\& sign_message
\& verify_message
\& sign_hash
\& verify_hash
\&
\& dh_encrypt
\& dh_decrypt
\& dh_sign_message
\& dh_verify_message
\& dh_sign_hash
\& dh_verify_hash
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
<https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange>