… | |
… | |
3 | Crypt::Ed25519 - bare-bones Ed25519 public key signing/verification system |
3 | Crypt::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 | |
23 | This module implements Ed25519 public key generation, message signing and |
44 | This module implements Ed25519 public key generation, message signing and |
24 | verification. It is a pretty bare-bones implementation that implements |
45 | verification. It is a pretty bare-bones implementation that implements |
… | |
… | |
35 | memory access pattern side-channel attacks. |
56 | memory access pattern side-channel attacks. |
36 | |
57 | |
37 | More detailed praise and other info can be found at |
58 | More detailed praise and other info can be found at |
38 | L<http://ed25519.cr.yp.to/index.html>. |
59 | L<http://ed25519.cr.yp.to/index.html>. |
39 | |
60 | |
|
|
61 | =head1 CRYPTOGRAPHY IS HARD |
|
|
62 | |
|
|
63 | A word of caution: don't use this module unless you really know what you |
|
|
64 | are doing - even if this module were completely error-free, that still |
|
|
65 | doesn't mean that every way of using it is correct. When in doubt, it's |
|
|
66 | best not to design your own cryptographic protocol. |
|
|
67 | |
|
|
68 | =head1 CONVENTIONS |
|
|
69 | |
|
|
70 | Public/private/secret keys, messages and signatures are all opaque and |
|
|
71 | architecture-independent octet strings, and, except for the message, have |
|
|
72 | fixed lengths. |
|
|
73 | |
40 | =cut |
74 | =cut |
41 | |
75 | |
42 | package Crypt::Ed25519; |
76 | package Crypt::Ed25519; |
43 | |
77 | |
44 | BEGIN { |
78 | BEGIN { |
45 | $VERSION = '0.9'; |
79 | $VERSION = 1.04; |
46 | |
80 | |
47 | require XSLoader; |
81 | require XSLoader; |
48 | XSLoader::load Crypt::Ed25519::, $VERSION; |
82 | XSLoader::load Crypt::Ed25519::, $VERSION; |
49 | } |
83 | } |
50 | |
84 | |
… | |
… | |
55 | =item ($public_key, $private_key) = Crypt::Ed25519::generate_keypair |
89 | =item ($public_key, $private_key) = Crypt::Ed25519::generate_keypair |
56 | |
90 | |
57 | Creates and returns a new random public and private key pair. The public |
91 | Creates and returns a new random public and private key pair. The public |
58 | key is always 32 octets, the private key is always 64 octets long. |
92 | key 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 | |
|
|
96 | Instead of generating a random keypair, generate them from the given |
|
|
97 | C<$secret_key> (e.g. as returned by C<Crypt::Ed25519::eddsa_secret_key>. |
|
|
98 | The derivation is deterministic, i.e. a specific C<$secret_key> will |
|
|
99 | always result in the same keypair. |
|
|
100 | |
|
|
101 | A secret key is simply a random bit string, so if you have a good source |
|
|
102 | of key material, you can simply generate 32 octets from it and use this as |
|
|
103 | your 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 | |
62 | Generates a signature for the given message using the public and private keys. |
107 | Generates a signature for the given message using the public and private |
|
|
108 | keys. The signature is always 64 octets long and deterministic, i.e. it is |
|
|
109 | always the same for a specific combination of C<$message>, C<$public_key> |
|
|
110 | and C<$private_key>, i.e. no external source of randomness is required for |
|
|
111 | signing. |
63 | |
112 | |
64 | =item $valid = Crypt::Ed25519::verify $message, $public_key, $signature |
113 | =item $valid = Crypt::Ed25519::verify $message, $public_key, $signature |
65 | |
114 | |
66 | Checks whether the C<$signature> is valid for the C<$message> and C<$public_ke>. |
115 | Checks whether the C<$signature> is valid for the C<$message> and C<$public_ke>. |
67 | |
116 | |
… | |
… | |
85 | Creates and returns a new secret key, which is always 32 octets |
134 | Creates and returns a new secret key, which is always 32 octets |
86 | long. The secret key can be used to generate the public key via |
135 | long. The secret key can be used to generate the public key via |
87 | C<Crypt::Ed25519::eddsa_public_key> and is not the same as the private key |
136 | C<Crypt::Ed25519::eddsa_public_key> and is not the same as the private key |
88 | used in the Ed25519 API. |
137 | used in the Ed25519 API. |
89 | |
138 | |
|
|
139 | A secret key is simply a random bit string, so if you have a good source |
|
|
140 | of key material, you can simply generate 32 octets from it and use this as |
|
|
141 | your 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 | |
92 | Takes a secret key generated by C<Crypt::Ed25519::eddsa_secret_key> and |
145 | Takes a secret key generated by C<Crypt::Ed25519::eddsa_secret_key> |
93 | returns the corresponding C<$public_key>. |
146 | and returns the corresponding C<$public_key>. The derivation is |
|
|
147 | deterministic, i.e. the C<$public_key> generated for a specific |
|
|
148 | C<$secret_key> is always the same. |
94 | |
149 | |
95 | This public key corresponds to the public key in the Ed25519 API above. |
150 | This 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 | |
99 | Generates a signature for the given message using the public and secret |
154 | Generates a signature for the given message using the public and secret |
100 | keys. |
155 | keys. Apart from specifying the C<$secret_key>, this function is identical |
|
|
156 | to C<Crypt::Ed25519::sign>, so everything said about it is true for this |
|
|
157 | function as well. |
|
|
158 | |
|
|
159 | Internally, C<Crypt::Ed25519::eddsa_sign> derives the corresponding |
|
|
160 | private key first and then calls C<Crypt::Ed25519::sign>, so it is always |
|
|
161 | slower. |
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 | |
… | |
… | |
119 | You can convert an EdDSA secret to an Ed25519 private/public key pair |
180 | You can convert an EdDSA secret to an Ed25519 private/public key pair |
120 | using C<Crypt::Ed25519::generate_keypair>: |
181 | using 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 | |
|
|
185 | As such, the EdDSA-style API allows you to store only the secret key and |
|
|
186 | derive the public key as needed. On the other hand, signing using the |
|
|
187 | private key is faster than using the secret key, so converting the secret |
|
|
188 | key to a public/private key pair allows you to sign a small message, or |
|
|
189 | many messages, faster. |
|
|
190 | |
|
|
191 | =head1 SUPPORT FOR THE PERL MULTICORE SPECIFICATION |
|
|
192 | |
|
|
193 | This module supports the perl multicore specification |
|
|
194 | (L<http://perlmulticore.schmorp.de/>) for key generation (usually the |
|
|
195 | slowest operation), and all signing and verification functions. |
|
|
196 | |
124 | =head1 IMPLEMENTATIOIN |
197 | =head1 IMPLEMENTATIOIN |
125 | |
198 | |
126 | This module currently uses "Nightcracker's Ed25519" implementation, but |
199 | This module currently uses "Nightcracker's Ed25519" implementation, which |
|
|
200 | is unmodified except for some portability fixes and static delcarations, |
127 | the interface is kept implementation-agnostic to allow usage of other |
201 | but the interface is kept implementation-agnostic to allow usage of other |
128 | implementations in the future. |
202 | implementations in the future. |
129 | |
203 | |
130 | =head1 AUTHOR |
204 | =head1 AUTHOR |
131 | |
205 | |
132 | Marc Lehmann <schmorp@schmorp.de> |
206 | Marc Lehmann <schmorp@schmorp.de> |