File Coverage

blib/lib/Crypt/Ed25519.pm
Criterion Covered Total %
statement 3 3 100.0
branch n/a
condition n/a
subroutine 1 1 100.0
pod n/a
total 4 4 100.0


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             Crypt::Ed25519 - bare-bones Ed25519 public key signing/verification system
4              
5             =head1 SYNOPSIS
6              
7             use Crypt::Ed25519; # no symbols exported
8              
9             ############################################
10             # Ed25519 API - public/private keypair
11              
12             # generate a public/private key pair once
13             ($pubkey, $privkey) = Crypt::Ed25519::generate_keypair;
14              
15             # sign a message
16             $signature = Crypt::Ed25519::sign $message, $pubkey, $privkey;
17              
18             # verify message
19             $valid = Crypt::Ed25519::verify $message, $pubkey, $signature;
20              
21             # verify, but croak on failure
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;
41              
42             =head1 DESCRIPTION
43              
44             This module implements Ed25519 public key generation, message signing and
45             verification. It is a pretty bare-bones implementation that implements
46             the standard Ed25519 variant with SHA512 hash, as well as a slower API
47             compatible with the upcoming EdDSA RFC.
48              
49             The security target for Ed25519 is to be equivalent to 3000 bit RSA or
50             AES-128.
51              
52             The advantages of Ed25519 over most other signing algorithms are:
53             small public/private key and signature sizes (<= 64 octets), good key
54             generation, signing and verification performance, no reliance on random
55             number generators for signing and by-design immunity against branch or
56             memory access pattern side-channel attacks.
57              
58             More detailed praise and other info can be found at
59             L.
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              
74             =cut
75              
76             package Crypt::Ed25519;
77              
78             BEGIN {
79 3     3   1819 $VERSION = 1.04;
80              
81 3         12 require XSLoader;
82 3         1199 XSLoader::load Crypt::Ed25519::, $VERSION;
83             }
84              
85             =head1 Ed25519 API
86              
87             =over 4
88              
89             =item ($public_key, $private_key) = Crypt::Ed25519::generate_keypair
90              
91             Creates and returns a new random public and private key pair. The public
92             key is always 32 octets, the private key is always 64 octets long.
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.
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              
105             =item $signature = Crypt::Ed25519::sign $message, $public_key, $private_key
106              
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.
112              
113             =item $valid = Crypt::Ed25519::verify $message, $public_key, $signature
114              
115             Checks whether the C<$signature> is valid for the C<$message> and C<$public_ke>.
116              
117             =item Crypt::Ed25519::verify_croak $message, $public_key, $signature
118              
119             Same as C, but instead of returning a boolean,
120             simply croaks with an error message when the signature isn't valid, so you
121             don't have to think about what the return value really means.
122              
123             =back
124              
125             =head1 EdDSA compatible API
126              
127             The upcoming EdDSA draft RFC uses a slightly different (and slower)
128             API for Ed25519. This API is provided by the following functions:
129              
130             =over 4
131              
132             =item $secret_key = Crypt::Ed25519::eddsa_secret_key
133              
134             Creates and returns a new secret key, which is always 32 octets
135             long. The secret key can be used to generate the public key via
136             C and is not the same as the private key
137             used in the Ed25519 API.
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              
143             =item $public_key = Crypt::Ed25519::eddsa_public_key $secret_key
144              
145             Takes a secret key generated by C
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.
149              
150             This public key corresponds to the public key in the Ed25519 API above.
151              
152             =item $signature = Crypt::Ed25519::eddsa_sign $message, $public_key, $secret_key
153              
154             Generates a signature for the given message using the public and secret
155             keys. Apart from specifying the C<$secret_key>, this function is identical
156             to C, so everything said about it is true for this
157             function as well.
158              
159             Internally, C derives the corresponding
160             private key first and then calls C, so it is always
161             slower.
162              
163             =item $valid = Crypt::Ed25519::eddsa_verify $message, $public_key, $signature
164              
165             =item Crypt::Ed25519::eddsa_verify_croak $message, $public_key, $signature
166              
167             Really the same as C and
168             C, i.e. the functions without the C
169             prefix. These aliases are provided so it's clear that you are using EdDSA
170             and not Ed25519 API.
171              
172             =back
173              
174             =head1 CONVERTING BETWEEN Ed25519 and EdDSA
175              
176             The Ed25519 and EdDSA compatible APIs handle keys slightly
177             differently: The Ed25519 API gives you a public/private key pair, while
178             EdDSA takes a secret and generates a public key from it.
179              
180             You can convert an EdDSA secret to an Ed25519 private/public key pair
181             using C:
182              
183             ($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret
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) for key generation (usually the
195             slowest operation), and all signing and verification functions.
196              
197             =head1 IMPLEMENTATIOIN
198              
199             This module currently uses "Nightcracker's Ed25519" implementation, which
200             is unmodified except for some portability fixes and static delcarations,
201             but the interface is kept implementation-agnostic to allow usage of other
202             implementations in the future.
203              
204             =head1 AUTHOR
205              
206             Marc Lehmann
207             http://sfotware.schmorp.de/pkg/Crypt-Ed25519.html
208              
209             =cut
210              
211             1
212