… | |
… | |
18 | Crypt::Ed25519::verify_croak $message, $pubkey, $signature; |
18 | Crypt::Ed25519::verify_croak $message, $pubkey, $signature; |
19 | |
19 | |
20 | DESCRIPTION |
20 | DESCRIPTION |
21 | This module implements Ed25519 public key generation, message signing |
21 | This module implements Ed25519 public key generation, message signing |
22 | and verification. It is a pretty bare-bones implementation that |
22 | and verification. It is a pretty bare-bones implementation that |
23 | implements the standard Ed25519 variant with SHA512 hash. |
23 | implements the standard Ed25519 variant with SHA512 hash, as well as a |
|
|
24 | slower API compatible with the upcoming EdDSA RFC. |
24 | |
25 | |
25 | The security target for Ed25519 is to be equivalent to 3000 bit RSA or |
26 | The security target for Ed25519 is to be equivalent to 3000 bit RSA or |
26 | AES-128. |
27 | AES-128. |
27 | |
28 | |
28 | The advantages of Ed25519 over most other signaturer algorithms are: |
29 | The advantages of Ed25519 over most other signing algorithms are: small |
29 | small public/private key and signature sizes (<= 64 octets), good key |
30 | public/private key and signature sizes (<= 64 octets), good key |
30 | generation, signing and verification performance, no reliance on random |
31 | generation, signing and verification performance, no reliance on random |
31 | number generators for signing and by-design immunity against branch or |
32 | number generators for signing and by-design immunity against branch or |
32 | memory access pattern side-channel attacks. |
33 | memory access pattern side-channel attacks. |
33 | |
34 | |
34 | More detailed praise and other info can be found at |
35 | More detailed praise and other info can be found at |
35 | <http://ed25519.cr.yp.to/index.html>. |
36 | <http://ed25519.cr.yp.to/index.html>. |
|
|
37 | |
|
|
38 | Ed25519 API |
|
|
39 | ($public_key, $private_key) = Crypt::Ed25519::generate_keypair |
|
|
40 | 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 |
|
|
42 | long. |
|
|
43 | |
|
|
44 | $signature = Crypt::Ed25519::sign $message, $public_key, $private_key |
|
|
45 | Generates a signature for the given message using the public and |
|
|
46 | private keys. |
|
|
47 | |
|
|
48 | $valid = Crypt::Ed25519::verify $message, $public_key, $signature |
|
|
49 | Checks whether the $signature is valid for the $message and |
|
|
50 | $public_ke. |
|
|
51 | |
|
|
52 | Crypt::Ed25519::verify_croak $message, $public_key, $signature |
|
|
53 | Same as "Crypt::Ed25519::verify", but instead of returning a |
|
|
54 | boolean, simply croaks with an error message when the signature |
|
|
55 | isn't valid, so you don't have to think about what the return value |
|
|
56 | really means. |
|
|
57 | |
|
|
58 | EdDSA compatible API |
|
|
59 | The upcoming EdDSA draft RFC uses a slightly different (and slower) API |
|
|
60 | for Ed25519. This API is provided by the following functions: |
|
|
61 | |
|
|
62 | $secret_key = Crypt::Ed25519::eddsa_secret_key |
|
|
63 | 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 |
|
|
65 | "Crypt::Ed25519::eddsa_public_key" and is not the same as the |
|
|
66 | private key used in the Ed25519 API. |
|
|
67 | |
|
|
68 | $public_key = Crypt::Ed25519::eddsa_public_key $secret_key |
|
|
69 | Takes a secret key generated by "Crypt::Ed25519::eddsa_secret_key" |
|
|
70 | and returns the corresponding $public_key. |
|
|
71 | |
|
|
72 | This public key corresponds to the public key in the Ed25519 API |
|
|
73 | above. |
|
|
74 | |
|
|
75 | $signature = Crypt::Ed25519::eddsa_sign $message, $public_key, |
|
|
76 | $secret_key |
|
|
77 | Generates a signature for the given message using the public and |
|
|
78 | secret keys. |
|
|
79 | |
|
|
80 | $valid = Crypt::Ed25519::eddsa_verify $message, $public_key, $signature |
|
|
81 | Crypt::Ed25519::eddsa_verify_croak $message, $public_key, $signature |
|
|
82 | Really the same as "Crypt::Ed25519::verify" and |
|
|
83 | "Crypt::Ed25519::verify_croak", i.e. the functions without the |
|
|
84 | "eddsa_" prefix. These aliases are provided so it's clear that you |
|
|
85 | are using EdDSA and not Ed25519 API. |
|
|
86 | |
|
|
87 | CONVERTING BETWEEN Ed25519 and EdDSA |
|
|
88 | The Ed25519 and EdDSA compatible APIs handle keys slightly differently: |
|
|
89 | The Ed25519 API gives you a public/private key pair, while EdDSA takes a |
|
|
90 | secret and generates a public key from it. |
|
|
91 | |
|
|
92 | You can convert an EdDSA secret to an Ed25519 private/public key pair |
|
|
93 | using "Crypt::Ed25519::generate_keypair": |
|
|
94 | |
|
|
95 | ($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret |
36 | |
96 | |
37 | IMPLEMENTATIOIN |
97 | IMPLEMENTATIOIN |
38 | This module currently uses "Nightcracker's Ed25519" implementation, but |
98 | This module currently uses "Nightcracker's Ed25519" implementation, but |
39 | the interface is kept implementation-agnostic to allow usage of other |
99 | the interface is kept implementation-agnostic to allow usage of other |
40 | implementations in the future. |
100 | implementations in the future. |