… | |
… | |
3 | system |
3 | system |
4 | |
4 | |
5 | SYNOPSIS |
5 | SYNOPSIS |
6 | use Crypt::Ed25519; # no symbols exported |
6 | use Crypt::Ed25519; # no symbols exported |
7 | |
7 | |
|
|
8 | ############################################ |
|
|
9 | # Ed25519 API - public/private keypair |
|
|
10 | |
8 | # generate a public/private key pair once |
11 | # generate a public/private key pair once |
9 | ($pubkey, $privkey) = Crypt::Ed25519::generate_keypair; |
12 | ($pubkey, $privkey) = Crypt::Ed25519::generate_keypair; |
10 | |
13 | |
11 | # sign messages |
14 | # sign a message |
12 | $signature = Crypt::Ed25519::sign $message, $pubkey, $privkey; |
15 | $signature = Crypt::Ed25519::sign $message, $pubkey, $privkey; |
13 | |
16 | |
14 | # verify message |
17 | # verify message |
15 | $valid = Crypt::Ed25519::verify $message, $pubkey, $signature; |
18 | $valid = Crypt::Ed25519::verify $message, $pubkey, $signature; |
16 | |
19 | |
17 | # verify, but croak on failure |
20 | # verify, but croak on failure |
18 | Crypt::Ed25519::verify_croak $message, $pubkey, $signature; |
21 | Crypt::Ed25519::verify_croak $message, $pubkey, $signature; |
|
|
22 | |
|
|
23 | ############################################ |
|
|
24 | # EdDSA API - secret key and derived public key |
|
|
25 | |
|
|
26 | # generate a secret key |
|
|
27 | $secret = Crypt::EdDSA::eddsa_secret_key; |
|
|
28 | |
|
|
29 | # derive public key as needed |
|
|
30 | $pubkey = Crypt::EdDSA::eddsa_public_key $secret; |
|
|
31 | |
|
|
32 | # sign a message |
|
|
33 | $signature = Crypt::Ed25519::eddsa_sign $message, $pubkey, $secret; |
|
|
34 | |
|
|
35 | # verify message |
|
|
36 | $valid = Crypt::Ed25519::eddsa_verify $message, $pubkey, $signature; |
|
|
37 | |
|
|
38 | # verify, but croak on failure |
|
|
39 | Crypt::Ed25519:eddsa_verify_croak $message, $pubkey, $signature; |
19 | |
40 | |
20 | DESCRIPTION |
41 | DESCRIPTION |
21 | This module implements Ed25519 public key generation, message signing |
42 | This module implements Ed25519 public key generation, message signing |
22 | and verification. It is a pretty bare-bones implementation that |
43 | and verification. It is a pretty bare-bones implementation that |
23 | implements the standard Ed25519 variant with SHA512 hash, as well as a |
44 | implements the standard Ed25519 variant with SHA512 hash, as well as a |
… | |
… | |
33 | memory access pattern side-channel attacks. |
54 | memory access pattern side-channel attacks. |
34 | |
55 | |
35 | More detailed praise and other info can be found at |
56 | More detailed praise and other info can be found at |
36 | <http://ed25519.cr.yp.to/index.html>. |
57 | <http://ed25519.cr.yp.to/index.html>. |
37 | |
58 | |
|
|
59 | CRYPTOGRAPHY IS HARD |
|
|
60 | A word of caution: don't use this module unless you really know what you |
|
|
61 | are doing - even if this module were completely error-free, that still |
|
|
62 | doesn't mean that every way of using it is correct. When in doubt, it's |
|
|
63 | best not to design your own cryptographic protocol. |
|
|
64 | |
|
|
65 | CONVENTIONS |
|
|
66 | Public/private/secret keys, messages and signatures are all opaque and |
|
|
67 | architecture-independent octet strings, and, except for the message, |
|
|
68 | have fixed lengths. |
|
|
69 | |
38 | Ed25519 API |
70 | Ed25519 API |
39 | ($public_key, $private_key) = Crypt::Ed25519::generate_keypair |
71 | ($public_key, $private_key) = Crypt::Ed25519::generate_keypair |
40 | Creates and returns a new random public and private key pair. The |
72 | Creates and returns a new random public and private key pair. The |
41 | public key is always 32 octets, the private key is always 64 octets |
73 | public key is always 32 octets, the private key is always 64 octets |
42 | long. |
74 | long. |
43 | |
75 | |
|
|
76 | ($public_key, $private_key) = Crypt::Ed25519::generate_keypair |
|
|
77 | $secret_key |
|
|
78 | Instead of generating a random keypair, generate them from the given |
|
|
79 | $secret_key (e.g. as returned by "Crypt::Ed25519::eddsa_secret_key". |
|
|
80 | The derivation is deterministic, i.e. a specific $secret_key will |
|
|
81 | always result in the same keypair. |
|
|
82 | |
|
|
83 | A secret key is simply a random bit string, so if you have a good |
|
|
84 | source of key material, you can simply generate 32 octets from it |
|
|
85 | and use this as your secret key. |
|
|
86 | |
44 | $signature = Crypt::Ed25519::sign $message, $public_key, $private_key |
87 | $signature = Crypt::Ed25519::sign $message, $public_key, $private_key |
45 | Generates a signature for the given message using the public and |
88 | Generates a signature for the given message using the public and |
46 | private keys. |
89 | private keys. The signature is always 64 octets long and |
|
|
90 | deterministic, i.e. it is always the same for a specific combination |
|
|
91 | of $message, $public_key and $private_key, i.e. no external source |
|
|
92 | of randomness is required for signing. |
47 | |
93 | |
48 | $valid = Crypt::Ed25519::verify $message, $public_key, $signature |
94 | $valid = Crypt::Ed25519::verify $message, $public_key, $signature |
49 | Checks whether the $signature is valid for the $message and |
95 | Checks whether the $signature is valid for the $message and |
50 | $public_ke. |
96 | $public_ke. |
51 | |
97 | |
… | |
… | |
63 | Creates and returns a new secret key, which is always 32 octets |
109 | Creates and returns a new secret key, which is always 32 octets |
64 | long. The secret key can be used to generate the public key via |
110 | long. The secret key can be used to generate the public key via |
65 | "Crypt::Ed25519::eddsa_public_key" and is not the same as the |
111 | "Crypt::Ed25519::eddsa_public_key" and is not the same as the |
66 | private key used in the Ed25519 API. |
112 | private key used in the Ed25519 API. |
67 | |
113 | |
|
|
114 | A secret key is simply a random bit string, so if you have a good |
|
|
115 | source of key material, you can simply generate 32 octets from it |
|
|
116 | and use this as your secret key. |
|
|
117 | |
68 | $public_key = Crypt::Ed25519::eddsa_public_key $secret_key |
118 | $public_key = Crypt::Ed25519::eddsa_public_key $secret_key |
69 | Takes a secret key generated by "Crypt::Ed25519::eddsa_secret_key" |
119 | Takes a secret key generated by "Crypt::Ed25519::eddsa_secret_key" |
70 | and returns the corresponding $public_key. |
120 | and returns the corresponding $public_key. The derivation is |
|
|
121 | deterministic, i.e. the $public_key generated for a specific |
|
|
122 | $secret_key is always the same. |
71 | |
123 | |
72 | This public key corresponds to the public key in the Ed25519 API |
124 | This public key corresponds to the public key in the Ed25519 API |
73 | above. |
125 | above. |
74 | |
126 | |
75 | $signature = Crypt::Ed25519::eddsa_sign $message, $public_key, |
127 | $signature = Crypt::Ed25519::eddsa_sign $message, $public_key, |
76 | $secret_key |
128 | $secret_key |
77 | Generates a signature for the given message using the public and |
129 | Generates a signature for the given message using the public and |
78 | secret keys. |
130 | secret keys. Apart from specifying the $secret_key, this function is |
|
|
131 | identical to "Crypt::Ed25519::sign", so everything said about it is |
|
|
132 | true for this function as well. |
|
|
133 | |
|
|
134 | Internally, "Crypt::Ed25519::eddsa_sign" derives the corresponding |
|
|
135 | private key first and then calls "Crypt::Ed25519::sign", so it is |
|
|
136 | always slower. |
79 | |
137 | |
80 | $valid = Crypt::Ed25519::eddsa_verify $message, $public_key, $signature |
138 | $valid = Crypt::Ed25519::eddsa_verify $message, $public_key, $signature |
81 | Crypt::Ed25519::eddsa_verify_croak $message, $public_key, $signature |
139 | Crypt::Ed25519::eddsa_verify_croak $message, $public_key, $signature |
82 | Really the same as "Crypt::Ed25519::verify" and |
140 | Really the same as "Crypt::Ed25519::verify" and |
83 | "Crypt::Ed25519::verify_croak", i.e. the functions without the |
141 | "Crypt::Ed25519::verify_croak", i.e. the functions without the |
… | |
… | |
92 | You can convert an EdDSA secret to an Ed25519 private/public key pair |
150 | You can convert an EdDSA secret to an Ed25519 private/public key pair |
93 | using "Crypt::Ed25519::generate_keypair": |
151 | using "Crypt::Ed25519::generate_keypair": |
94 | |
152 | |
95 | ($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret |
153 | ($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret |
96 | |
154 | |
|
|
155 | As such, the EdDSA-style API allows you to store only the secret key and |
|
|
156 | derive the public key as needed. On the other hand, signing using the |
|
|
157 | private key is faster than using the secret key, so converting the |
|
|
158 | secret key to a public/private key pair allows you to sign a small |
|
|
159 | message, or many messages, faster. |
|
|
160 | |
|
|
161 | SUPPORT FOR THE PERL MULTICORE SPECIFICATION |
|
|
162 | This module supports the perl multicore specification |
|
|
163 | (<http://perlmulticore.schmorp.de/>) for key generation (usually the |
|
|
164 | slowest operation), and all signing and verification functions. |
|
|
165 | |
97 | IMPLEMENTATIOIN |
166 | IMPLEMENTATIOIN |
98 | This module currently uses "Nightcracker's Ed25519" implementation, but |
167 | This module currently uses "Nightcracker's Ed25519" implementation, |
|
|
168 | which is unmodified except for some portability fixes and static |
99 | the interface is kept implementation-agnostic to allow usage of other |
169 | delcarations, but the interface is kept implementation-agnostic to allow |
100 | implementations in the future. |
170 | usage of other implementations in the future. |
101 | |
171 | |
102 | AUTHOR |
172 | AUTHOR |
103 | Marc Lehmann <schmorp@schmorp.de> |
173 | Marc Lehmann <schmorp@schmorp.de> |
104 | http://sfotware.schmorp.de/pkg/Crypt-Ed25519.html |
174 | http://sfotware.schmorp.de/pkg/Crypt-Ed25519.html |
105 | |
175 | |