… | |
… | |
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; |
19 | |
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; |
|
|
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. |
44 | implements the standard Ed25519 variant with SHA512 hash, as well as a |
|
|
45 | slower API compatible with the upcoming EdDSA RFC. |
24 | |
46 | |
25 | The security target for Ed25519 is to be equivalent to 3000 bit RSA or |
47 | The security target for Ed25519 is to be equivalent to 3000 bit RSA or |
26 | AES-128. |
48 | AES-128. |
27 | |
49 | |
28 | The advantages of Ed25519 over most other signaturer algorithms are: |
50 | The advantages of Ed25519 over most other signing algorithms are: small |
29 | small public/private key and signature sizes (<= 64 octets), good key |
51 | public/private key and signature sizes (<= 64 octets), good key |
30 | generation, signing and verification performance, no reliance on random |
52 | generation, signing and verification performance, no reliance on random |
31 | number generators for signing and by-design immunity against branch or |
53 | number generators for signing and by-design immunity against branch or |
32 | memory access pattern side-channel attacks. |
54 | memory access pattern side-channel attacks. |
33 | |
55 | |
34 | More detailed praise and other info can be found at |
56 | More detailed praise and other info can be found at |
35 | <http://ed25519.cr.yp.to/index.html>. |
57 | <http://ed25519.cr.yp.to/index.html>. |
36 | |
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 | |
|
|
70 | Ed25519 API |
|
|
71 | ($public_key, $private_key) = Crypt::Ed25519::generate_keypair |
|
|
72 | Creates and returns a new random public and private key pair. The |
|
|
73 | public key is always 32 octets, the private key is always 64 octets |
|
|
74 | long. |
|
|
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 | |
|
|
87 | $signature = Crypt::Ed25519::sign $message, $public_key, $private_key |
|
|
88 | Generates a signature for the given message using the public and |
|
|
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. |
|
|
93 | |
|
|
94 | $valid = Crypt::Ed25519::verify $message, $public_key, $signature |
|
|
95 | Checks whether the $signature is valid for the $message and |
|
|
96 | $public_ke. |
|
|
97 | |
|
|
98 | Crypt::Ed25519::verify_croak $message, $public_key, $signature |
|
|
99 | Same as "Crypt::Ed25519::verify", but instead of returning a |
|
|
100 | boolean, simply croaks with an error message when the signature |
|
|
101 | isn't valid, so you don't have to think about what the return value |
|
|
102 | really means. |
|
|
103 | |
|
|
104 | EdDSA compatible API |
|
|
105 | The upcoming EdDSA draft RFC uses a slightly different (and slower) API |
|
|
106 | for Ed25519. This API is provided by the following functions: |
|
|
107 | |
|
|
108 | $secret_key = Crypt::Ed25519::eddsa_secret_key |
|
|
109 | Creates and returns a new secret key, which is always 32 octets |
|
|
110 | long. The secret key can be used to generate the public key via |
|
|
111 | "Crypt::Ed25519::eddsa_public_key" and is not the same as the |
|
|
112 | private key used in the Ed25519 API. |
|
|
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 | |
|
|
118 | $public_key = Crypt::Ed25519::eddsa_public_key $secret_key |
|
|
119 | Takes a secret key generated by "Crypt::Ed25519::eddsa_secret_key" |
|
|
120 | and returns the corresponding $public_key. The derivation ios |
|
|
121 | deterministic, i.e. the $public_key generated for a specific |
|
|
122 | $secret_key is always the same. |
|
|
123 | |
|
|
124 | This public key corresponds to the public key in the Ed25519 API |
|
|
125 | above. |
|
|
126 | |
|
|
127 | $signature = Crypt::Ed25519::eddsa_sign $message, $public_key, |
|
|
128 | $secret_key |
|
|
129 | Generates a signature for the given message using the public and |
|
|
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. |
|
|
137 | |
|
|
138 | $valid = Crypt::Ed25519::eddsa_verify $message, $public_key, $signature |
|
|
139 | Crypt::Ed25519::eddsa_verify_croak $message, $public_key, $signature |
|
|
140 | Really the same as "Crypt::Ed25519::verify" and |
|
|
141 | "Crypt::Ed25519::verify_croak", i.e. the functions without the |
|
|
142 | "eddsa_" prefix. These aliases are provided so it's clear that you |
|
|
143 | are using EdDSA and not Ed25519 API. |
|
|
144 | |
|
|
145 | CONVERTING BETWEEN Ed25519 and EdDSA |
|
|
146 | The Ed25519 and EdDSA compatible APIs handle keys slightly differently: |
|
|
147 | The Ed25519 API gives you a public/private key pair, while EdDSA takes a |
|
|
148 | secret and generates a public key from it. |
|
|
149 | |
|
|
150 | You can convert an EdDSA secret to an Ed25519 private/public key pair |
|
|
151 | using "Crypt::Ed25519::generate_keypair": |
|
|
152 | |
|
|
153 | ($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret |
|
|
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 | |
37 | IMPLEMENTATIOIN |
166 | IMPLEMENTATIOIN |
38 | 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 |
39 | the interface is kept implementation-agnostic to allow usage of other |
169 | delcarations, but the interface is kept implementation-agnostic to allow |
40 | implementations in the future. |
170 | usage of other implementations in the future. |
41 | |
171 | |
42 | AUTHOR |
172 | AUTHOR |
43 | Marc Lehmann <schmorp@schmorp.de> |
173 | Marc Lehmann <schmorp@schmorp.de> |
44 | http://sfotware.schmorp.de/pkg/Crypt-Ed25519.html |
174 | http://sfotware.schmorp.de/pkg/Crypt-Ed25519.html |
45 | |
175 | |