README
1NAME
2 Crypt::Curve25519 - Generate shared secret using elliptic-curve
3 Diffie-Hellman function
4
5VERSION
6 version 0.06
7
8SYNOPSIS
9 use Crypt::Curve25519;
10
11 # Alice:
12 my $alice_secret_key = curve25519_secret_key(random_32_bytes());
13 my $alice_public_key = curve25519_public_key( $alice_secret_key );
14
15 # Bob:
16 my $bob_secret_key = curve25519_secret_key(random_32_bytes());
17 my $bob_public_key = curve25519_public_key( $bob_secret_key );
18
19 # Alice and Bob exchange their public keys
20 my $alice_public_key_hex = unpack('H64', $alice_public_key);
21 my $bob_public_key_hex = unpack('H64', $bob_public_key);
22
23 # Alice calculates shared secret to communicate with Bob
24 my $shared_secret_with_bob = curve25519_shared_secret(
25 $alice_secret_key,
26 pack('H64', $bob_public_key_hex)
27 );
28
29 # Bob calculates shared secret to communicate with Alice
30 my $shared_secret_with_alice = curve25519_shared_secret(
31 $bob_secret_key,
32 pack('H64', $alice_public_key_hex)
33 );
34
35 # Shared secrets are equal
36 die "Something horrible has happend!"
37 unless $shared_secret_with_bob eq $shared_secret_with_alice;
38
39 This package provides also simplified OO interface:
40
41 use Crypt::Curve25519 ();
42
43 my $c = Crypt::Curve25519->new();
44
45 # Alice:
46 my $alice_secret_key_hex = $c->secret_key(random_hexencoded_32_bytes());
47 my $alice_public_key_hex = $c->public_key( $alice_secret_key_hex );
48
49 # Bob:
50 my $bob_secret_key_hex = $c->secret_key(random_hexencoded_32_bytes());
51 my $bob_public_key_hex = $c->public_key( $bob_secret_key_hex );
52
53 # Alice and Bob exchange their public keys
54
55 # Alice calculates shared secret to communicate with Bob
56 my $shared_secret_with_bob_hex = $c->shared_secret(
57 $alice_secret_key_hex,
58 $bob_public_key_hex);
59
60 # Bob calculates shared secret to communicate with Alice
61 my $shared_secret_with_alice_hex = $c->shared_secret(
62 $bob_secret_key_hex,
63 $alice_public_key_hex);
64
65 # Shared secrets are equal
66 die "Something horrible has happend!"
67 unless $shared_secret_with_bob_hex eq $shared_secret_with_alice_hex;
68
69 Example functions to generate pseudo-random private secret key:
70
71 sub random_32_bytes {
72 return join('', map { chr(int(rand(255))) } 1 .. 32);
73 }
74
75 sub random_hexencoded_32_bytes {
76 return unpack('H64', random_32_bytes());
77 }
78
79DESCRIPTION
80 Curve25519 is a state-of-the-art Diffie-Hellman function suitable for a
81 wide variety of applications.
82
83 Given a user's 32-byte secret key, Curve25519 computes the user's
84 32-byte public key. Given the user's 32-byte secret key and another
85 user's 32-byte public key, Curve25519 computes a 32-byte secret shared
86 by the two users. This secret can then be used to authenticate and
87 encrypt messages between the two users.
88
89METHODS
90 new
91 my $c = Crypt::Curve25519->new();
92
93 Create a new object
94
95 secret_key
96 my $my_secret_key_hex = $c->secret_key( $my_random_32byte_string_hex );
97
98 Using hex encoded 32-byte random string from cryptographically safe
99 source create masked secret key.
100
101 public_key
102 my $public_key_hex = $c->public_key( $my_secret_key_hex );
103
104 Using hex encoded masked secret key generate corresponding hex encoded
105 32-byte Curve25519 public key.
106
107 shared_secret
108 my $shared_secret_hex = $c->shared_secret(
109 $my_secret_key_hex, $his_public_key_hex
110 );
111
112 Using provided hex encoded keys generate 32-byte hex encoded shared
113 secret, that both parties can use without disclosing their private
114 secret keys.
115
116 generate
117 Access to primitive method is also provided.
118
119 my $key_hex = $c->generate($my_secret_key_hex, $basepoint_hex);
120
121 # public key
122 if ( $basepoint_hex eq unpack("H64", pack("H64", "09")) ) {
123 print "\$key_hex is a public key\n";
124 }
125 elsif ( $basepoint_hex eq $his_public_key_hex ) {
126 print "\$key_hex is a shared secret\n";
127 }
128
129 Using provided hex encoded secret key and depending on the 32-byte hex
130 encoded basepoint generate 32-byte hex encoded public key or shared
131 secret.
132
133FUNCTIONS
134 curve25519_secret_key
135 my $my_secret_key = curve25519_secret_key($my_random_32byte_string);
136
137 Using provided 32-byte random string from cryptographically safe source
138 create masked secret key.
139
140 curve25519_public_key
141 my $public_key = curve25519_public_key($my_secret_key);
142
143 Using masked secret key generate corresponding 32-byte Curve25519 public
144 key.
145
146 curve25519_shared_secret
147 my $shared_secret = curve25519_shared_secret(
148 $my_secret_key, $his_public_key
149 );
150
151 Using provided keys generate 32-byte shared secret, that both parties
152 can use without disclosing their private secret keys.
153
154 curve25519
155 Access to primitive function is also provided.
156
157 use Crypt::Curve25519 'curve25519';
158
159 my $key = curve25519($my_secret_key, $basepoint);
160
161 # public key
162 if ( $basepoint eq pack('H64', '09') ) {
163 print "\$key is a public key\n";
164 }
165 elsif ( $basepoint eq $his_public_key ) {
166 print "\$key is a shared secret\n";
167 }
168
169 Using provided secret key and depending on the 32-byte basepoint
170 generate 32-byte public key or shared secret.
171
172SEE ALSO
173 * <http://cr.yp.to/ecdh.html>
174
175AUTHOR
176 Alex J. G. Burzyński <ajgb@cpan.org>
177
178COPYRIGHT AND LICENSE
179 This software is copyright (c) 2014 by Alex J. G. Burzyński
180 <ajgb@cpan.org>.
181
182 This is free software; you can redistribute it and/or modify it under
183 the same terms as the Perl 5 programming language system itself.
184
185