NAME
    Crypt::Curve25519 - Generate shared secret using elliptic-curve
    Diffie-Hellman function

VERSION
    version 0.01

SYNOPSIS
        use Crypt::Curve25519;
    
        # Alice:
        my $alice_secret_key = random_32_bytes();
        my $alice_public_key = curve25519_public_key( $alice_secret_key );
    
        # Bob:
        my $bob_secret_key = random_32_bytes();
        my $bob_public_key = curve25519_public_key( $bob_secret_key );
    
        # Alice and Bob exchange their public keys
        my $alice_public_key_hex = unpack('H*', $alice_public_key);
        my $bob_public_key_hex = unpack('H*', $bob_public_key);
    
        # Alice calculates shared secret to communicate with Bob
        my $shared_secret_with_bob = curve25519_shared_secret( $alice_secret_key,
                                          pack('H*', $bob_public_key_hex));
    
        # Bob calculates shared secret to communicate with Alice
        my $shared_secret_with_alice = curve25519_shared_secret( $bob_secret_key,
                                          pack('H*', $alice_public_key_hex));
    
        # Shared secrets are equal
        die "Something horrible has happend!"
          unless $shared_secret_with_bob eq $shared_secret_with_alice;

    This package provides also simplified OO interface:

        use Crypt::Curve25519 ();

        my $c = Crypt::Curve25519->new();

        # Alice:
        my $alice_secret_key_hex = random_hexencoded_32_bytes();
        my $alice_public_key_hex = $c->public_key( $alice_secret_key_hex );

        # Bob:
        my $bob_secret_key_hex = random_hexencoded_32_bytes();
        my $bob_public_key_hex = $c->public_key( $bob_secret_key_hex );

        # Alice and Bob exchange their public keys

        # Alice calculates shared secret to communicate with Bob
        my $shared_secret_with_bob_hex = $c->shared_secret(
                                        $alice_secret_key_hex,
                                        $bob_public_key_hex);

        # Bob calculates shared secret to communicate with Alice
        my $shared_secret_with_alice_hex = $c->shared_secret(
                                        $bob_secret_key_hex,
                                        $alice_public_key_hex);

        # Shared secrets are equal
        die "Something horrible has happend!"
          unless $shared_secret_with_bob_hex eq $shared_secret_with_alice_hex;

    Example functions to generate pseudo-random private secret key:

        sub random_32_bytes {
            return join('', map { chr(int(rand(255))) } 1 .. 32);
        }

        sub random_hexencoded_32_bytes {
           return unpack('H*', random_32_bytes());
        }

DESCRIPTION
    Curve25519 is a state-of-the-art Diffie-Hellman function suitable for a
    wide variety of applications.

    Given a user's 32-byte secret key, Curve25519 computes the user's
    32-byte public key. Given the user's 32-byte secret key and another
    user's 32-byte public key, Curve25519 computes a 32-byte secret shared
    by the two users. This secret can then be used to authenticate and
    encrypt messages between the two users.

METHODS
  new
        my $c = Crypt::Curve25519->new();

    Create a new object

  public_key($my_secret_key_hex)
        my $public_key_hex = $c->public_key( $my_secret_key_hex );

    Using hex encoded 32-byte secret from cryptographically safe source key
    generate corresponding hex encoded 32-byte Curve25519 public key.

  shared_secret($my_secret_key_hex, $his_public_key_hex)
        my $shared_secret_hex = $c->shared_secret(
                                $my_secret_key_hex,
                                $his_public_key_hex);

    Using provided hex encoded keys generate 32-byte hex encoded shared
    secret, that both parties can use without disclosing their private
    secret keys.

FUNCTIONS
  curve25519_public_key($my_secret_key)
        my $public_key = curve25519_public_key($my_secret_key);

    Using provided 32-byte secret key from cryptographically safe source
    generate corresponding 32-byte Curve25519 public key.

  curve25519_shared_secret($my_secret_key, $his_public_key)
        my $shared_secret = curve25519_shared_secret($my_secret_key, $his_public_key);

    Using provided keys generate 32-byte shared secret, that both parties
    can use without disclosing their private secret keys.

EXPORT
    Both functions are exported by default.

SEE ALSO
    *   <http://cr.yp.to/ecdh.html>

AUTHOR
    Alex J. G. Burzyński <ajgb@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2014 by Alex J. G. Burzyński
    <ajgb@cpan.org>.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

