NAME

Crypt::DH - Diffie-Hellman key exchange system

SYNOPSIS

    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 );

DESCRIPTION

Crypt::DH 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.

THE ALGORITHM

The algorithm generally works as follows: Party A and Party B choose a property p and a property g; these properties are shared by both parties. Each party then computes a random private key integer priv_key, where the length of priv_key is at most (number of bits in p) - 1. Each party then computes a public key based on g, priv_key, and p; the exact value is

    g ^ priv_key mod p

The parties exchange these public keys.

The shared secret key is generated based on the exchanged public key, the private key, and p. If the public key of Party B is denoted pub_key_B, then the shared secret is equal to

    pub_key_B ^ priv_key mod p

The mathematical principles involved insure that both parties will generate the same shared secret key.

More information can be found in PKCS #3 (Diffie-Hellman Key Agreement Standard):

    http://www.rsasecurity.com/rsalabs/pkcs/pkcs-3/

USAGE

Crypt::DH implements the core routines needed to use Diffie-Hellman key exchange. To actually use the algorithm, you'll need to start with values for p and g; p is a large prime, and g is a base which must be larger than 0 and less than p.

Crypt::DH uses Math::BigInt internally for big-integer calculations. All accessor methods (p, g, priv_key, and pub_key) thus return Math::BigInt objects, as does the compute_secret method. The accessors, however, allow setting with a scalar decimal string, hex string (^0x), Math::BigInt object, or Math::Pari object (for backwards compatibility).