1Crypt::DH(3)          User Contributed Perl Documentation         Crypt::DH(3)
2
3
4

NAME

6       Crypt::DH - Diffie-Hellman key exchange system
7

SYNOPSIS

9           use Crypt::DH;
10           my $dh = Crypt::DH->new;
11           $dh->g($g);
12           $dh->p($p);
13
14           ## Generate public and private keys.
15           $dh->generate_keys;
16
17           $my_pub_key = $dh->pub_key;
18
19           ## Send $my_pub_key to "other" party, and receive "other"
20           ## public key in return.
21
22           ## Now compute shared secret from "other" public key.
23           my $shared_secret = $dh->compute_secret( $other_pub_key );
24

DESCRIPTION

26       Crypt::DH is a Perl implementation of the Diffie-Hellman key exchange
27       system. Diffie-Hellman is an algorithm by which two parties can agree
28       on a shared secret key, known only to them.  The secret is negotiated
29       over an insecure network without the two parties ever passing the
30       actual shared secret, or their private keys, between them.
31

THE ALGORITHM

33       The algorithm generally works as follows: Party A and Party B choose a
34       property p and a property g; these properties are shared by both
35       parties. Each party then computes a random private key integer
36       priv_key, where the length of priv_key is at most (number of bits in p)
37       - 1. Each party then computes a public key based on g, priv_key, and p;
38       the exact value is
39
40           g ^ priv_key mod p
41
42       The parties exchange these public keys.
43
44       The shared secret key is generated based on the exchanged public key,
45       the private key, and p. If the public key of Party B is denoted
46       pub_key_B, then the shared secret is equal to
47
48           pub_key_B ^ priv_key mod p
49
50       The mathematical principles involved insure that both parties will
51       generate the same shared secret key.
52
53       More information can be found in PKCS #3 (Diffie-Hellman Key Agreement
54       Standard):
55
56           http://www.rsasecurity.com/rsalabs/pkcs/pkcs-3/
57

USAGE

59       Crypt::DH implements the core routines needed to use Diffie-Hellman key
60       exchange. To actually use the algorithm, you'll need to start with
61       values for p and g; p is a large prime, and g is a base which must be
62       larger than 0 and less than p.
63
64       Crypt::DH uses Math::BigInt internally for big-integer calculations.
65       All accessor methods (p, g, priv_key, and pub_key) thus return
66       Math::BigInt objects, as does the compute_secret method.  The
67       accessors, however, allow setting with a scalar decimal string, hex
68       string (^0x), Math::BigInt object, or Math::Pari object (for backwards
69       compatibility).
70
71   $dh = Crypt::DH->new([ %param ]).
72       Constructs a new Crypt::DH object and returns the object.  %param may
73       include none, some, or all of the keys p, g, and priv_key.
74
75   $dh->p([ $p ])
76       Given an argument $p, sets the p parameter (large prime) for this
77       Crypt::DH object.
78
79       Returns the current value of p.  (as a Math::BigInt object)
80
81   $dh->g([ $g ])
82       Given an argument $g, sets the g parameter (base) for this Crypt::DH
83       object.
84
85       Returns the current value of g.
86
87   $dh->generate_keys
88       Generates the public and private key portions of the Crypt::DH object,
89       assuming that you've already filled p and g with appropriate values.
90
91       If you've provided a priv_key, it's used, otherwise a random priv_key
92       is created using either Crypt::Random (if already loaded), or
93       /dev/urandom, or Perl's rand, in that order.
94
95   $dh->compute_secret( $public_key )
96       Given the public key $public_key of Party B (the party with which
97       you're performing key negotiation and exchange), computes the shared
98       secret key, based on that public key, your own private key, and your
99       own large prime value (p).
100
101       The historical method name "compute_key" is aliased to this for
102       compatibility.
103
104   $dh->priv_key([ $priv_key ])
105       Returns the private key.  Given an argument $priv_key, sets the
106       priv_key parameter for this Crypt::DH object.
107
108   $dh->pub_key
109       Returns the public key.
110

AUTHOR

112       Benjamin Trott (cpan:BTROTT) <ben+cpan@stupidfool.org>
113
114       Brad Fitzpatrick (cpan:BRADFITZ) <brad@danga.com>
115

CONTRIBUTORS

117       BinGOs - Chris Williams (cpan:BINGOS) <chris@bingosnet.co.uk>
118
119       Mithaldu - Christian Walde (cpan:MITHALDU)
120       <walde.christian@googlemail.com>
121

COPYRIGHT

123       Copyright (c) 2012 the Crypt::DH "AUTHOR" and "CONTRIBUTORS" as listed
124       above.
125

LICENSE

127       This library is free software and may be distributed under the same
128       terms as perl itself.
129
130
131
132perl v5.36.0                      2023-01-20                      Crypt::DH(3)