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

NAME

6       Crypt::Curve25519 - Generate shared secret using elliptic-curve
7       Diffie-Hellman function
8

SYNOPSIS

10           use Crypt::Curve25519;
11
12           # Alice:
13           my $alice_secret_key = curve25519_secret_key(random_32_bytes());
14           my $alice_public_key = curve25519_public_key( $alice_secret_key );
15
16           # Bob:
17           my $bob_secret_key = curve25519_secret_key(random_32_bytes());
18           my $bob_public_key = curve25519_public_key( $bob_secret_key );
19
20           # Alice and Bob exchange their public keys
21           my $alice_public_key_hex = unpack('H64', $alice_public_key);
22           my $bob_public_key_hex   = unpack('H64', $bob_public_key);
23
24           # Alice calculates shared secret to communicate with Bob
25           my $shared_secret_with_bob = curve25519_shared_secret(
26               $alice_secret_key,
27               pack('H64', $bob_public_key_hex)
28           );
29
30           # Bob calculates shared secret to communicate with Alice
31           my $shared_secret_with_alice = curve25519_shared_secret(
32               $bob_secret_key,
33               pack('H64', $alice_public_key_hex)
34           );
35
36           # Shared secrets are equal
37           die "Something horrible has happend!"
38             unless $shared_secret_with_bob eq $shared_secret_with_alice;
39
40       This package provides also simplified OO interface:
41
42           use Crypt::Curve25519 ();
43
44           my $c = Crypt::Curve25519->new();
45
46           # Alice:
47           my $alice_secret_key_hex = $c->secret_key(random_hexencoded_32_bytes());
48           my $alice_public_key_hex = $c->public_key( $alice_secret_key_hex );
49
50           # Bob:
51           my $bob_secret_key_hex = $c->secret_key(random_hexencoded_32_bytes());
52           my $bob_public_key_hex = $c->public_key( $bob_secret_key_hex );
53
54           # Alice and Bob exchange their public keys
55
56           # Alice calculates shared secret to communicate with Bob
57           my $shared_secret_with_bob_hex = $c->shared_secret(
58                                           $alice_secret_key_hex,
59                                           $bob_public_key_hex);
60
61           # Bob calculates shared secret to communicate with Alice
62           my $shared_secret_with_alice_hex = $c->shared_secret(
63                                           $bob_secret_key_hex,
64                                           $alice_public_key_hex);
65
66           # Shared secrets are equal
67           die "Something horrible has happend!"
68             unless $shared_secret_with_bob_hex eq $shared_secret_with_alice_hex;
69
70       Example functions to generate pseudo-random private secret key:
71
72           sub random_32_bytes {
73               return join('', map { chr(int(rand(255))) } 1 .. 32);
74           }
75
76           sub random_hexencoded_32_bytes {
77              return unpack('H64', random_32_bytes());
78           }
79

DESCRIPTION

81       Curve25519 is a state-of-the-art Diffie-Hellman function suitable for a
82       wide variety of applications.
83
84       Given a user's 32-byte secret key, Curve25519 computes the user's
85       32-byte public key. Given the user's 32-byte secret key and another
86       user's 32-byte public key, Curve25519 computes a 32-byte secret shared
87       by the two users. This secret can then be used to authenticate and
88       encrypt messages between the two users.
89

METHODS

91       curve25519_secret_key
92               my $my_secret_key = curve25519_secret_key($my_random_32byte_string);
93
94           Using provided 32-byte random string from cryptographically safe
95           source create masked secret key.
96
97       curve25519_public_key
98               my $public_key = curve25519_public_key($my_secret_key);
99
100           Using masked secret key generate corresponding 32-byte Curve25519
101           public key.
102
103       curve25519_shared_secret
104               my $shared_secret = curve25519_shared_secret(
105                   $my_secret_key, $his_public_key
106               );
107
108           Using provided keys generate 32-byte shared secret, that both
109           parties can use without disclosing their private secret keys.
110
111       curve25519
112           Access to primitive function is also provided.
113
114               use Crypt::Curve25519 'curve25519';
115
116               my $key = curve25519($my_secret_key, $basepoint);
117
118               # public key
119               if ( $basepoint eq pack('H64', '09') ) {
120                   print "\$key is a public key\n";
121               }
122               elsif ( $basepoint eq $his_public_key ) {
123                   print "\$key is a shared secret\n";
124               }
125
126           Using provided secret key and depending on the 32-byte basepoint
127           generate 32-byte public key or shared secret.
128
129       new
130               my $c = Crypt::Curve25519->new();
131
132           Create a new object
133
134       secret_key
135               my $my_secret_key_hex = $c->secret_key( $my_random_32byte_string_hex );
136
137           Using hex encoded 32-byte random string from cryptographically safe
138           source create masked secret key.
139
140       public_key
141               my $public_key_hex = $c->public_key( $my_secret_key_hex );
142
143           Using hex encoded masked secret key generate corresponding hex
144           encoded 32-byte Curve25519 public key.
145
146       shared_secret
147               my $shared_secret_hex = $c->shared_secret(
148                   $my_secret_key_hex, $his_public_key_hex
149               );
150
151           Using provided hex encoded keys generate 32-byte hex encoded shared
152           secret, that both parties can use without disclosing their private
153           secret keys.
154
155       generate
156           Access to primitive method is also provided.
157
158               my $key_hex = $c->generate($my_secret_key_hex, $basepoint_hex);
159
160               # public key
161               if ( $basepoint_hex eq unpack("H64", pack("H64", "09")) ) {
162                   print "\$key_hex is a public key\n";
163               }
164               elsif ( $basepoint_hex eq $his_public_key_hex ) {
165                   print "\$key_hex is a shared secret\n";
166               }
167
168           Using provided hex encoded secret key and depending on the 32-byte
169           hex encoded basepoint generate 32-byte hex encoded public key or
170           shared secret.
171

SEE ALSO

173       •   <http://cr.yp.to/ecdh.html>
174

AUTHOR

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

MAINTAINER

179       Dmitry Karasik <dmitry@karasik.eu.org>
180

182           This software is copyright (c) 2014 by Alex J. G. Burzyński
183           <ajgb@cpan.org>.
184
185           This is free software; you can redistribute it and/or modify it under
186           the same terms as the Perl 5 programming language system itself.
187
188
189
190perl v5.36.0                      2023-01-20              Crypt::Curve25519(3)
Impressum