.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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::DH 3pm"
.TH Crypt::DH 3pm "2022-06-12" "perl v5.34.0" "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::DH \- Diffie\-Hellman key exchange system
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    use Crypt::DH;
\&    my $dh = Crypt::DH\->new;
\&    $dh\->g($g);
\&    $dh\->p($p);
\&
\&    ## Generate public and private keys.
\&    $dh\->generate_keys;
\&
\&    $my_pub_key = $dh\->pub_key;
\&
\&    ## Send $my_pub_key to "other" party, and receive "other"
\&    ## public key in return.
\&
\&    ## Now compute shared secret from "other" public key.
\&    my $shared_secret = $dh\->compute_secret( $other_pub_key );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fICrypt::DH\fR is a Perl implementation of the Diffie-Hellman key
exchange system. Diffie-Hellman is an algorithm by which two
parties can agree on a shared secret key, known only to them.
The secret is negotiated over an insecure network without the
two parties ever passing the actual shared secret, or their
private keys, between them.
.SH "THE ALGORITHM"
.IX Header "THE ALGORITHM"
The algorithm generally works as follows: Party A and Party B
choose a property \fIp\fR and a property \fIg\fR; these properties are
shared by both parties. Each party then computes a random private
key integer \fIpriv_key\fR, where the length of \fIpriv_key\fR is at
most (number of bits in \fIp\fR) \- 1. Each party then computes a
public key based on \fIg\fR, \fIpriv_key\fR, and \fIp\fR; the exact value
is
.PP
.Vb 1
\&    g ^ priv_key mod p
.Ve
.PP
The parties exchange these public keys.
.PP
The shared secret key is generated based on the exchanged public
key, the private key, and \fIp\fR. If the public key of Party B is
denoted \fIpub_key_B\fR, then the shared secret is equal to
.PP
.Vb 1
\&    pub_key_B ^ priv_key mod p
.Ve
.PP
The mathematical principles involved insure that both parties will
generate the same shared secret key.
.PP
More information can be found in \s-1PKCS\s0 #3 (Diffie-Hellman Key
Agreement Standard):
.PP
.Vb 1
\&    http://www.rsasecurity.com/rsalabs/pkcs/pkcs\-3/
.Ve
.SH "USAGE"
.IX Header "USAGE"
\&\fICrypt::DH\fR implements the core routines needed to use
Diffie-Hellman key exchange. To actually use the algorithm,
you'll need to start with values for \fIp\fR and \fIg\fR; \fIp\fR is a
large prime, and \fIg\fR is a base which must be larger than 0
and less than \fIp\fR.
.PP
\&\fICrypt::DH\fR uses \fIMath::BigInt\fR internally for big-integer
calculations. All accessor methods (\fIp\fR, \fIg\fR, \fIpriv_key\fR, and
\&\fIpub_key\fR) thus return \fIMath::BigInt\fR objects, as does the
\&\fIcompute_secret\fR method.  The accessors, however, allow setting with a
scalar decimal string, hex string (^0x), Math::BigInt object, or
Math::Pari object (for backwards compatibility).
.ie n .SS "$dh = Crypt::DH\->new([ %param ])."
.el .SS "\f(CW$dh\fP = Crypt::DH\->new([ \f(CW%param\fP ])."
.IX Subsection "$dh = Crypt::DH->new([ %param ])."
Constructs a new \fICrypt::DH\fR object and returns the object.
\&\fI\f(CI%param\fI\fR may include none, some, or all of the keys \fIp\fR, \fIg\fR, and
\&\fIpriv_key\fR.
.ie n .SS "$dh\->p([ $p ])"
.el .SS "\f(CW$dh\fP\->p([ \f(CW$p\fP ])"
.IX Subsection "$dh->p([ $p ])"
Given an argument \fI\f(CI$p\fI\fR, sets the \fIp\fR parameter (large prime) for
this \fICrypt::DH\fR object.
.PP
Returns the current value of \fIp\fR.  (as a Math::BigInt object)
.ie n .SS "$dh\->g([ $g ])"
.el .SS "\f(CW$dh\fP\->g([ \f(CW$g\fP ])"
.IX Subsection "$dh->g([ $g ])"
Given an argument \fI\f(CI$g\fI\fR, sets the \fIg\fR parameter (base) for
this \fICrypt::DH\fR object.
.PP
Returns the current value of \fIg\fR.
.ie n .SS "$dh\->generate_keys"
.el .SS "\f(CW$dh\fP\->generate_keys"
.IX Subsection "$dh->generate_keys"
Generates the public and private key portions of the \fICrypt::DH\fR
object, assuming that you've already filled \fIp\fR and \fIg\fR with
appropriate values.
.PP
If you've provided a priv_key, it's used, otherwise a random priv_key
is created using either Crypt::Random (if already loaded), or
/dev/urandom, or Perl's rand, in that order.
.ie n .SS "$dh\->compute_secret( $public_key )"
.el .SS "\f(CW$dh\fP\->compute_secret( \f(CW$public_key\fP )"
.IX Subsection "$dh->compute_secret( $public_key )"
Given the public key \fI\f(CI$public_key\fI\fR of Party B (the party with which
you're performing key negotiation and exchange), computes the shared
secret key, based on that public key, your own private key, and your
own large prime value (\fIp\fR).
.PP
The historical method name \*(L"compute_key\*(R" is aliased to this for
compatibility.
.ie n .SS "$dh\->priv_key([ $priv_key ])"
.el .SS "\f(CW$dh\fP\->priv_key([ \f(CW$priv_key\fP ])"
.IX Subsection "$dh->priv_key([ $priv_key ])"
Returns the private key.  Given an argument \fI\f(CI$priv_key\fI\fR, sets the
\&\fIpriv_key\fR parameter for this \fICrypt::DH\fR object.
.ie n .SS "$dh\->pub_key"
.el .SS "\f(CW$dh\fP\->pub_key"
.IX Subsection "$dh->pub_key"
Returns the public key.
.SH "AUTHOR"
.IX Header "AUTHOR"
Benjamin Trott (cpan:BTROTT) <ben+cpan@stupidfool.org>
.PP
Brad Fitzpatrick (cpan:BRADFITZ) <brad@danga.com>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
BinGOs \- Chris Williams (cpan:BINGOS) <chris@bingosnet.co.uk>
.PP
Mithaldu \- Christian Walde (cpan:MITHALDU) <walde.christian@googlemail.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2012 the Crypt::DH \*(L"\s-1AUTHOR\*(R"\s0 and \*(L"\s-1CONTRIBUTORS\*(R"\s0 as listed
above.
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software and may be distributed under the same terms
as perl itself.