1NAME 2 Crypt::DH - Diffie-Hellman key exchange system 3 4SYNOPSIS 5 use Crypt::DH; 6 my $dh = Crypt::DH->new; 7 $dh->g($g); 8 $dh->p($p); 9 10 ## Generate public and private keys. 11 $dh->generate_keys; 12 13 $my_pub_key = $dh->pub_key; 14 15 ## Send $my_pub_key to "other" party, and receive "other" 16 ## public key in return. 17 18 ## Now compute shared secret from "other" public key. 19 my $shared_secret = $dh->compute_secret( $other_pub_key ); 20 21DESCRIPTION 22 *Crypt::DH* is a Perl implementation of the Diffie-Hellman key exchange 23 system. Diffie-Hellman is an algorithm by which two parties can agree on 24 a shared secret key, known only to them. The secret is negotiated over 25 an insecure network without the two parties ever passing the actual 26 shared secret, or their private keys, between them. 27 28THE ALGORITHM 29 The algorithm generally works as follows: Party A and Party B choose a 30 property *p* and a property *g*; these properties are shared by both 31 parties. Each party then computes a random private key integer 32 *priv_key*, where the length of *priv_key* is at most (number of bits in 33 *p*) - 1. Each party then computes a public key based on *g*, 34 *priv_key*, and *p*; the exact value is 35 36 g ^ priv_key mod p 37 38 The parties exchange these public keys. 39 40 The shared secret key is generated based on the exchanged public key, 41 the private key, and *p*. If the public key of Party B is denoted 42 *pub_key_B*, then the shared secret is equal to 43 44 pub_key_B ^ priv_key mod p 45 46 The mathematical principles involved insure that both parties will 47 generate the same shared secret key. 48 49 More information can be found in PKCS #3 (Diffie-Hellman Key Agreement 50 Standard): 51 52 http://www.rsasecurity.com/rsalabs/pkcs/pkcs-3/ 53 54USAGE 55 *Crypt::DH* implements the core routines needed to use Diffie-Hellman 56 key exchange. To actually use the algorithm, you'll need to start with 57 values for *p* and *g*; *p* is a large prime, and *g* is a base which 58 must be larger than 0 and less than *p*. 59 60 *Crypt::DH* uses *Math::BigInt* internally for big-integer calculations. 61 All accessor methods (*p*, *g*, *priv_key*, and *pub_key*) thus return 62 *Math::BigInt* objects, as does the *compute_secret* method. The 63 accessors, however, allow setting with a scalar decimal string, hex 64 string (^0x), Math::BigInt object, or Math::Pari object (for backwards 65 compatibility). 66 67 $dh = Crypt::DH->new([ %param ]). 68 Constructs a new *Crypt::DH* object and returns the object. *%param* may 69 include none, some, or all of the keys *p*, *g*, and *priv_key*. 70 71 $dh->p([ $p ]) 72 Given an argument *$p*, sets the *p* parameter (large prime) for this 73 *Crypt::DH* object. 74 75 Returns the current value of *p*. (as a Math::BigInt object) 76 77 $dh->g([ $g ]) 78 Given an argument *$g*, sets the *g* parameter (base) for this 79 *Crypt::DH* object. 80 81 Returns the current value of *g*. 82 83 $dh->generate_keys 84 Generates the public and private key portions of the *Crypt::DH* object, 85 assuming that you've already filled *p* and *g* with appropriate values. 86 87 If you've provided a priv_key, it's used, otherwise a random priv_key is 88 created using either Crypt::Random (if already loaded), or /dev/urandom, 89 or Perl's rand, in that order. 90 91 $dh->compute_secret( $public_key ) 92 Given the public key *$public_key* of Party B (the party with which 93 you're performing key negotiation and exchange), computes the shared 94 secret key, based on that public key, your own private key, and your own 95 large prime value (*p*). 96 97 The historical method name "compute_key" is aliased to this for 98 compatibility. 99 100 $dh->priv_key([ $priv_key ]) 101 Returns the private key. Given an argument *$priv_key*, sets the 102 *priv_key* parameter for this *Crypt::DH* object. 103 104 $dh->pub_key 105 Returns the public key. 106 107AUTHOR 108 Benjamin Trott (cpan:BTROTT) <ben+cpan@stupidfool.org> 109 110 Brad Fitzpatrick (cpan:BRADFITZ) <brad@danga.com> 111 112CONTRIBUTORS 113 BinGOs - Chris Williams (cpan:BINGOS) <chris@bingosnet.co.uk> 114 115 Mithaldu - Christian Walde (cpan:MITHALDU) 116 <walde.christian@googlemail.com> 117 118COPYRIGHT 119 Copyright (c) 2012 the Crypt::DH "AUTHOR" and "CONTRIBUTORS" as listed 120 above. 121 122LICENSE 123 This library is free software and may be distributed under the same 124 terms as perl itself. 125 126