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

Comparing Crypt-Ed25519/README (file contents):
Revision 1.2 by root, Fri Mar 27 20:24:14 2015 UTC vs.
Revision 1.3 by root, Sun Mar 29 06:24:10 2015 UTC

… …
3 system 3 system
4 4
5SYNOPSIS 5SYNOPSIS
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
20DESCRIPTION 41DESCRIPTION
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
59CRYPTOGRAPHY 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
65CONVENTIONS
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
38Ed25519 API 70Ed25519 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 ios
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
97 IMPLEMENTATIOIN 161IMPLEMENTATIOIN
98 This module currently uses "Nightcracker's Ed25519" implementation, but 162 This module currently uses "Nightcracker's Ed25519" implementation, but
99 the interface is kept implementation-agnostic to allow usage of other 163 the interface is kept implementation-agnostic to allow usage of other
100 implementations in the future. 164 implementations in the future.
101 165
102AUTHOR 166AUTHOR

Diff Legend

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