ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Crypt-Ed25519/Ed25519.pm
(Generate patch)

Comparing Crypt-Ed25519/Ed25519.pm (file contents):
Revision 1.4 by root, Sun Mar 29 05:55:48 2015 UTC vs.
Revision 1.5 by root, Sun Mar 29 06:19:46 2015 UTC

… …
3Crypt::Ed25519 - bare-bones Ed25519 public key signing/verification system 3Crypt::Ed25519 - bare-bones Ed25519 public key signing/verification system
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use Crypt::Ed25519; # no symbols exported 7 use Crypt::Ed25519; # no symbols exported
8
9 ############################################
10 # Ed25519 API - public/private keypair
8 11
9 # generate a public/private key pair once 12 # generate a public/private key pair once
10 ($pubkey, $privkey) = Crypt::Ed25519::generate_keypair; 13 ($pubkey, $privkey) = Crypt::Ed25519::generate_keypair;
11 14
12 # sign messages 15 # sign a message
13 $signature = Crypt::Ed25519::sign $message, $pubkey, $privkey; 16 $signature = Crypt::Ed25519::sign $message, $pubkey, $privkey;
14 17
15 # verify message 18 # verify message
16 $valid = Crypt::Ed25519::verify $message, $pubkey, $signature; 19 $valid = Crypt::Ed25519::verify $message, $pubkey, $signature;
17 20
18 # verify, but croak on failure 21 # verify, but croak on failure
19 Crypt::Ed25519::verify_croak $message, $pubkey, $signature; 22 Crypt::Ed25519::verify_croak $message, $pubkey, $signature;
23
24 ############################################
25 # EdDSA API - secret key and derived public key
26
27 # generate a secret key
28 $secret = Crypt::EdDSA::eddsa_secret_key;
29
30 # derive public key as needed
31 $pubkey = Crypt::EdDSA::eddsa_public_key $secret;
32
33 # sign a message
34 $signature = Crypt::Ed25519::eddsa_sign $message, $pubkey, $secret;
35
36 # verify message
37 $valid = Crypt::Ed25519::eddsa_verify $message, $pubkey, $signature;
38
39 # verify, but croak on failure
40 Crypt::Ed25519:eddsa_verify_croak $message, $pubkey, $signature;
20 41
21=head1 DESCRIPTION 42=head1 DESCRIPTION
22 43
23This module implements Ed25519 public key generation, message signing and 44This module implements Ed25519 public key generation, message signing and
24verification. It is a pretty bare-bones implementation that implements 45verification. It is a pretty bare-bones implementation that implements
… …
35memory access pattern side-channel attacks. 56memory access pattern side-channel attacks.
36 57
37More detailed praise and other info can be found at 58More detailed praise and other info can be found at
38L<http://ed25519.cr.yp.to/index.html>. 59L<http://ed25519.cr.yp.to/index.html>.
39 60
61=head1 CRYPTOGRAPHY IS HARD
62
63A word of caution: don't use this module unless you really know what you
64are doing - even if this module were completely error-free, that still
65doesn't mean that every way of using it is correct. When in doubt, it's
66best not to design your own cryptographic protocol.
67
68=head1 CONVENTIONS
69
70Public/private/secret keys, messages and signatures are all opaque and
71architecture-independent octet strings, and, except for the message, have
72fixed lengths.
73
40=cut 74=cut
41 75
42package Crypt::Ed25519; 76package Crypt::Ed25519;
43 77
44BEGIN { 78BEGIN {
… …
55=item ($public_key, $private_key) = Crypt::Ed25519::generate_keypair 89=item ($public_key, $private_key) = Crypt::Ed25519::generate_keypair
56 90
57Creates and returns a new random public and private key pair. The public 91Creates and returns a new random public and private key pair. The public
58key is always 32 octets, the private key is always 64 octets long. 92key is always 32 octets, the private key is always 64 octets long.
59 93
94=item ($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret_key
95
96Instead of generating a random keypair, generate them from the given
97C<$secret_key> (e.g. as returned by C<Crypt::Ed25519::eddsa_secret_key>.
98The derivation is deterministic, i.e. a specific C<$secret_key> will
99always result in the same keypair.
100
101A secret key is simply a random bit string, so if you have a good source
102of key material, you can simply generate 32 octets from it and use this as
103your secret key.
104
60=item $signature = Crypt::Ed25519::sign $message, $public_key, $private_key 105=item $signature = Crypt::Ed25519::sign $message, $public_key, $private_key
61 106
62Generates a signature for the given message using the public and private keys. 107Generates a signature for the given message using the public and private
108keys. The signature is always 64 octets long and deterministic, i.e. it is
109always the same for a specific combination of C<$message>, C<$public_key>
110and C<$private_key>, i.e. no external source of randomness is required for
111signing.
63 112
64=item $valid = Crypt::Ed25519::verify $message, $public_key, $signature 113=item $valid = Crypt::Ed25519::verify $message, $public_key, $signature
65 114
66Checks whether the C<$signature> is valid for the C<$message> and C<$public_ke>. 115Checks whether the C<$signature> is valid for the C<$message> and C<$public_ke>.
67 116
… …
85Creates and returns a new secret key, which is always 32 octets 134Creates and returns a new secret key, which is always 32 octets
86long. The secret key can be used to generate the public key via 135long. The secret key can be used to generate the public key via
87C<Crypt::Ed25519::eddsa_public_key> and is not the same as the private key 136C<Crypt::Ed25519::eddsa_public_key> and is not the same as the private key
88used in the Ed25519 API. 137used in the Ed25519 API.
89 138
139A secret key is simply a random bit string, so if you have a good source
140of key material, you can simply generate 32 octets from it and use this as
141your secret key.
142
90=item $public_key = Crypt::Ed25519::eddsa_public_key $secret_key 143=item $public_key = Crypt::Ed25519::eddsa_public_key $secret_key
91 144
92Takes a secret key generated by C<Crypt::Ed25519::eddsa_secret_key> and 145Takes a secret key generated by C<Crypt::Ed25519::eddsa_secret_key>
93returns the corresponding C<$public_key>. 146and returns the corresponding C<$public_key>. The derivation ios
147deterministic, i.e. the C<$public_key> generated for a specific
148C<$secret_key> is always the same.
94 149
95This public key corresponds to the public key in the Ed25519 API above. 150This public key corresponds to the public key in the Ed25519 API above.
96 151
97=item $signature = Crypt::Ed25519::eddsa_sign $message, $public_key, $secret_key 152=item $signature = Crypt::Ed25519::eddsa_sign $message, $public_key, $secret_key
98 153
99Generates a signature for the given message using the public and secret 154Generates a signature for the given message using the public and secret
100keys. 155keys. Apart from specifying the C<$secret_key>, this function is identical
156to C<Crypt::Ed25519::sign>, so everything said about it is true for this
157function as well.
158
159Internally, C<Crypt::Ed25519::eddsa_sign> derives the corresponding
160private key first and then calls C<Crypt::Ed25519::sign>, so it is always
161slower.
101 162
102=item $valid = Crypt::Ed25519::eddsa_verify $message, $public_key, $signature 163=item $valid = Crypt::Ed25519::eddsa_verify $message, $public_key, $signature
103 164
104=item Crypt::Ed25519::eddsa_verify_croak $message, $public_key, $signature 165=item Crypt::Ed25519::eddsa_verify_croak $message, $public_key, $signature
105 166
… …
119You can convert an EdDSA secret to an Ed25519 private/public key pair 180You can convert an EdDSA secret to an Ed25519 private/public key pair
120using C<Crypt::Ed25519::generate_keypair>: 181using C<Crypt::Ed25519::generate_keypair>:
121 182
122 ($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret 183 ($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret
123 184
185As such, the EdDSA-style API allows you to store only the secret key and
186derive the public key as needed. On the other hand, signing using the
187private key is faster than using the secret key, so converting the secret
188key to a public/private key pair allows you to sign a small message, or
189many messages, faster.
190
124=head1 IMPLEMENTATIOIN 191=head1 IMPLEMENTATIOIN
125 192
126This module currently uses "Nightcracker's Ed25519" implementation, but 193This module currently uses "Nightcracker's Ed25519" implementation, but
127the interface is kept implementation-agnostic to allow usage of other 194the interface is kept implementation-agnostic to allow usage of other
128implementations in the future. 195implementations in the future.

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines