Crypt-Ed25519/Ed25519.pm

=head1 NAME

Crypt::Ed25519 - bare-bones Ed25519 public key signing/verification system

=head1 SYNOPSIS

 use Crypt::Ed25519; # no symbols exported

 ############################################
 # Ed25519 API - public/private keypair

 # generate a public/private key pair once
 ($pubkey, $privkey) = Crypt::Ed25519::generate_keypair;

 # sign a message
 $signature = Crypt::Ed25519::sign $message, $pubkey, $privkey;

 # verify message
 $valid = Crypt::Ed25519::verify $message, $pubkey, $signature;

 # verify, but croak on failure
 Crypt::Ed25519::verify_croak $message, $pubkey, $signature;

 ############################################
 # EdDSA API - secret key and derived public key

 # generate a secret key
 $secret = Crypt::EdDSA::eddsa_secret_key;

 # derive public key as needed
 $pubkey = Crypt::EdDSA::eddsa_public_key $secret;

 # sign a message
 $signature = Crypt::Ed25519::eddsa_sign $message, $pubkey, $secret;

 # verify message
 $valid = Crypt::Ed25519::eddsa_verify $message, $pubkey, $signature;

 # verify, but croak on failure
 Crypt::Ed25519:eddsa_verify_croak $message, $pubkey, $signature;

 ############################################
 # Curve25519 key exchange

 # side A:
 ($pubkey_a, $privkey_a) = Crypt::Ed25519::generate_keypair;
 # send $pubkey to side B

 # side B:
 ($pubkey_b, $privkey_b) = Crypt::Ed25519::generate_keypair;
 # send $pubkey to side A

 # side A then calculates their shared secret:
 $shared_secret = Crypt::Ed25519::key_exchange $pubkey_b, $privkey_a;

 # and side B does this:
 $shared_secret = Crypt::Ed25519::key_exchange $pubkey_a, $privkey_b;

 # the generated $shared_secret will be the same - you cna now
 # hash it with hkdf or something else to generate symmetric private keys

=head1 DESCRIPTION

This module implements Ed25519 public key generation, message signing and
verification. It is a pretty bare-bones implementation that implements
the standard Ed25519 variant with SHA512 hash, as well as a slower API
compatible with the upcoming EdDSA RFC.

The security target for Ed25519 is to be equivalent to 3000 bit RSA or
AES-128.

The advantages of Ed25519 over most other signing algorithms are:
small public/private key and signature sizes (<= 64 octets), good key
generation, signing and verification performance, no reliance on random
number generators for signing and by-design immunity against branch or
memory access pattern side-channel attacks.

More detailed praise and other info can be found at
L<http://ed25519.cr.yp.to/index.html>.

=head1 CRYPTOGRAPHY IS HARD

A word of caution: don't use this module unless you really know what you
are doing - even if this module were completely error-free, that still
doesn't mean that every way of using it is correct. When in doubt, it's
best not to design your own cryptographic protocol.

=head1 CONVENTIONS

Public/private/secret keys, messages and signatures are all opaque and
architecture-independent octet strings, and, except for the message, have
fixed lengths.

=cut

package Crypt::Ed25519;

BEGIN {
   $VERSION = 1.05;

   require XSLoader;
   XSLoader::load Crypt::Ed25519::, $VERSION;
}

=head1 Ed25519 API

=over 4

=item ($public_key, $private_key) = Crypt::Ed25519::generate_keypair

Creates and returns a new random public and private key pair. The public
key is always 32 octets, the private key is always 64 octets long.

=item ($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret_key

Instead of generating a random keypair, generate them from the given
C<$secret_key> (e.g. as returned by C<Crypt::Ed25519::eddsa_secret_key>.
The derivation is deterministic, i.e. a specific C<$secret_key> will
always result in the same keypair.

A secret key is simply a random bit string, so if you have a good source
of key material, you can simply generate 32 octets from it and use this as
your secret key.

=item $signature = Crypt::Ed25519::sign $message, $public_key, $private_key

Generates a signature for the given message using the public and private
keys. The signature is always 64 octets long and deterministic, i.e. it is
always the same for a specific combination of C<$message>, C<$public_key>
and C<$private_key>, i.e. no external source of randomness is required for
signing.

=item $valid = Crypt::Ed25519::verify $message, $public_key, $signature

Checks whether the C<$signature> is valid for the C<$message> and C<$public_ke>.

=item Crypt::Ed25519::verify_croak $message, $public_key, $signature

Same as C<Crypt::Ed25519::verify>, but instead of returning a boolean,
simply croaks with an error message when the signature isn't valid, so you
don't have to think about what the return value really means.

=back

=head1 EdDSA compatible API

The upcoming EdDSA draft RFC uses a slightly different (and slower)
API for Ed25519. This API is provided by the following functions:

=over 4

=item $secret_key = Crypt::Ed25519::eddsa_secret_key

Creates and returns a new secret key, which is always 32 octets
long. The secret key can be used to generate the public key via
C<Crypt::Ed25519::eddsa_public_key> and is not the same as the private key
used in the Ed25519 API.

A secret key is simply a random bit string, so if you have a good source
of key material, you can simply generate 32 octets from it and use this as
your secret key.

=item $public_key = Crypt::Ed25519::eddsa_public_key $secret_key

Takes a secret key generated by C<Crypt::Ed25519::eddsa_secret_key>
and returns the corresponding C<$public_key>. The derivation is
deterministic, i.e. the C<$public_key> generated for a specific
C<$secret_key> is always the same.

This public key corresponds to the public key in the Ed25519 API above.

=item $signature = Crypt::Ed25519::eddsa_sign $message, $public_key, $secret_key

Generates a signature for the given message using the public and secret
keys. Apart from specifying the C<$secret_key>, this function is identical
to C<Crypt::Ed25519::sign>, so everything said about it is true for this
function as well.

Internally, C<Crypt::Ed25519::eddsa_sign> derives the corresponding
private key first and then calls C<Crypt::Ed25519::sign>, so it is always
slower.

=item $valid = Crypt::Ed25519::eddsa_verify $message, $public_key, $signature

=item Crypt::Ed25519::eddsa_verify_croak $message, $public_key, $signature

Really the same as C<Crypt::Ed25519::verify> and
C<Crypt::Ed25519::verify_croak>, i.e. the functions without the C<eddsa_>
prefix. These aliases are provided so it's clear that you are using EdDSA
and not Ed25519 API.

=back

=head1 CONVERTING BETWEEN Ed25519 and EdDSA

The Ed25519 and EdDSA compatible APIs handle keys slightly
differently: The Ed25519 API gives you a public/private key pair, while
EdDSA takes a secret and generates a public key from it.

You can convert an EdDSA secret to an Ed25519 private/public key pair
using C<Crypt::Ed25519::generate_keypair>:

   ($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret

As such, the EdDSA-style API allows you to store only the secret key and
derive the public key as needed. On the other hand, signing using the
private key is faster than using the secret key, so converting the secret
key to a public/private key pair allows you to sign a small message, or
many messages, faster.

=head1 Curve25519 Key Exchange

As an extension to Ed25519, this module implements a key exchange similar
to Curve25519, which should be compatible to other implementations of
Curv25519, depending on how the resulting shared secret is hashed.

To do this, both sides generate a keypair and send their public key to the
other side. Then both sides can generate the same shared secret using this
function:

=over

=item $shared_secret = Crypt::Ed25519::key_exchange $other_public_key, $own_private_key

Return the 32 octet shared secret generated from the given public and
private key.

The resulting C<$shared_key> should be hashed before use (for example, by
using it in a KDF such as HKDF).

See SYNOPSIS for an actual example.

=back

=head1 SUPPORT FOR THE PERL MULTICORE SPECIFICATION
        
This module supports the perl multicore specification
(L<http://perlmulticore.schmorp.de/>) for all operations, although it
makes most sense to use it when signing or verifying longer messages.

=head1 IMPLEMENTATION

This module currently uses "Nightcracker's Ed25519" implementation, which
is unmodified except for some portability fixes and static delcarations,
but the interface is kept implementation-agnostic to allow usage of other
implementations in the future.

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://software.schmorp.de/pkg/Crypt-Ed25519.html

=cut

1

Revision:	1.16
Committed:	Wed Aug 11 23:15:25 2021 UTC (2 years, 9 months ago) by root
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.15:	+2 -2 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.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	root	1.5	############################################
10			# Ed25519 API - public/private keypair
11
12	root	1.1	# generate a public/private key pair once
13			($pubkey, $privkey) = Crypt::Ed25519::generate_keypair;
14
15	root	1.5	# sign a message
16	root	1.1	$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	root	1.5	############################################
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	root	1.14	############################################
43	root	1.16	# Curve25519 key exchange
44	root	1.14
45			# side A:
46			($pubkey_a, $privkey_a) = Crypt::Ed25519::generate_keypair;
47			# send $pubkey to side B
48
49			# side B:
50			($pubkey_b, $privkey_b) = Crypt::Ed25519::generate_keypair;
51			# send $pubkey to side A
52
53			# side A then calculates their shared secret:
54			$shared_secret = Crypt::Ed25519::key_exchange $pubkey_b, $privkey_a;
55
56			# and side B does this:
57			$shared_secret = Crypt::Ed25519::key_exchange $pubkey_a, $privkey_b;
58
59			# the generated $shared_secret will be the same - you cna now
60			# hash it with hkdf or something else to generate symmetric private keys
61
62	root	1.1	=head1 DESCRIPTION
63
64			This module implements Ed25519 public key generation, message signing and
65			verification. It is a pretty bare-bones implementation that implements
66			the standard Ed25519 variant with SHA512 hash, as well as a slower API
67			compatible with the upcoming EdDSA RFC.
68
69			The security target for Ed25519 is to be equivalent to 3000 bit RSA or
70			AES-128.
71
72			The advantages of Ed25519 over most other signing algorithms are:
73			small public/private key and signature sizes (<= 64 octets), good key
74			generation, signing and verification performance, no reliance on random
75			number generators for signing and by-design immunity against branch or
76			memory access pattern side-channel attacks.
77
78			More detailed praise and other info can be found at
79			L<http://ed25519.cr.yp.to/index.html>.
80
81	root	1.5	=head1 CRYPTOGRAPHY IS HARD
82
83			A word of caution: don't use this module unless you really know what you
84			are doing - even if this module were completely error-free, that still
85			doesn't mean that every way of using it is correct. When in doubt, it's
86			best not to design your own cryptographic protocol.
87
88			=head1 CONVENTIONS
89
90			Public/private/secret keys, messages and signatures are all opaque and
91			architecture-independent octet strings, and, except for the message, have
92			fixed lengths.
93
94	root	1.1	=cut
95
96			package Crypt::Ed25519;
97
98			BEGIN {
99	root	1.14	$VERSION = 1.05;
100	root	1.1
101			require XSLoader;
102			XSLoader::load Crypt::Ed25519::, $VERSION;
103			}
104
105			=head1 Ed25519 API
106
107			=over 4
108
109			=item ($public_key, $private_key) = Crypt::Ed25519::generate_keypair
110
111			Creates and returns a new random public and private key pair. The public
112			key is always 32 octets, the private key is always 64 octets long.
113
114	root	1.5	=item ($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret_key
115
116			Instead of generating a random keypair, generate them from the given
117			C<$secret_key> (e.g. as returned by C<Crypt::Ed25519::eddsa_secret_key>.
118			The derivation is deterministic, i.e. a specific C<$secret_key> will
119			always result in the same keypair.
120
121			A secret key is simply a random bit string, so if you have a good source
122			of key material, you can simply generate 32 octets from it and use this as
123			your secret key.
124
125	root	1.1	=item $signature = Crypt::Ed25519::sign $message, $public_key, $private_key
126
127	root	1.5	Generates a signature for the given message using the public and private
128			keys. The signature is always 64 octets long and deterministic, i.e. it is
129			always the same for a specific combination of C<$message>, C<$public_key>
130			and C<$private_key>, i.e. no external source of randomness is required for
131			signing.
132	root	1.1
133			=item $valid = Crypt::Ed25519::verify $message, $public_key, $signature
134
135			Checks whether the C<$signature> is valid for the C<$message> and C<$public_ke>.
136
137			=item Crypt::Ed25519::verify_croak $message, $public_key, $signature
138
139			Same as C<Crypt::Ed25519::verify>, but instead of returning a boolean,
140			simply croaks with an error message when the signature isn't valid, so you
141			don't have to think about what the return value really means.
142
143			=back
144
145			=head1 EdDSA compatible API
146
147			The upcoming EdDSA draft RFC uses a slightly different (and slower)
148			API for Ed25519. This API is provided by the following functions:
149
150			=over 4
151
152			=item $secret_key = Crypt::Ed25519::eddsa_secret_key
153
154			Creates and returns a new secret key, which is always 32 octets
155			long. The secret key can be used to generate the public key via
156			C<Crypt::Ed25519::eddsa_public_key> and is not the same as the private key
157			used in the Ed25519 API.
158
159	root	1.5	A secret key is simply a random bit string, so if you have a good source
160			of key material, you can simply generate 32 octets from it and use this as
161			your secret key.
162
163	root	1.1	=item $public_key = Crypt::Ed25519::eddsa_public_key $secret_key
164
165	root	1.5	Takes a secret key generated by C<Crypt::Ed25519::eddsa_secret_key>
166	root	1.12	and returns the corresponding C<$public_key>. The derivation is
167	root	1.5	deterministic, i.e. the C<$public_key> generated for a specific
168			C<$secret_key> is always the same.
169	root	1.1
170			This public key corresponds to the public key in the Ed25519 API above.
171
172			=item $signature = Crypt::Ed25519::eddsa_sign $message, $public_key, $secret_key
173
174			Generates a signature for the given message using the public and secret
175	root	1.5	keys. Apart from specifying the C<$secret_key>, this function is identical
176			to C<Crypt::Ed25519::sign>, so everything said about it is true for this
177			function as well.
178
179			Internally, C<Crypt::Ed25519::eddsa_sign> derives the corresponding
180			private key first and then calls C<Crypt::Ed25519::sign>, so it is always
181			slower.
182	root	1.1
183			=item $valid = Crypt::Ed25519::eddsa_verify $message, $public_key, $signature
184
185			=item Crypt::Ed25519::eddsa_verify_croak $message, $public_key, $signature
186
187			Really the same as C<Crypt::Ed25519::verify> and
188			C<Crypt::Ed25519::verify_croak>, i.e. the functions without the C<eddsa_>
189			prefix. These aliases are provided so it's clear that you are using EdDSA
190			and not Ed25519 API.
191
192			=back
193
194			=head1 CONVERTING BETWEEN Ed25519 and EdDSA
195
196			The Ed25519 and EdDSA compatible APIs handle keys slightly
197			differently: The Ed25519 API gives you a public/private key pair, while
198			EdDSA takes a secret and generates a public key from it.
199
200			You can convert an EdDSA secret to an Ed25519 private/public key pair
201			using C<Crypt::Ed25519::generate_keypair>:
202
203			($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret
204
205	root	1.5	As such, the EdDSA-style API allows you to store only the secret key and
206			derive the public key as needed. On the other hand, signing using the
207			private key is faster than using the secret key, so converting the secret
208			key to a public/private key pair allows you to sign a small message, or
209			many messages, faster.
210
211	root	1.16	=head1 Curve25519 Key Exchange
212	root	1.14
213			As an extension to Ed25519, this module implements a key exchange similar
214	root	1.15	to Curve25519, which should be compatible to other implementations of
215			Curv25519, depending on how the resulting shared secret is hashed.
216
217			To do this, both sides generate a keypair and send their public key to the
218			other side. Then both sides can generate the same shared secret using this
219			function:
220	root	1.14
221			=over
222
223			=item $shared_secret = Crypt::Ed25519::key_exchange $other_public_key, $own_private_key
224
225			Return the 32 octet shared secret generated from the given public and
226	root	1.15	private key.
227
228			The resulting C<$shared_key> should be hashed before use (for example, by
229			using it in a KDF such as HKDF).
230
231			See SYNOPSIS for an actual example.
232	root	1.14
233			=back
234
235	root	1.9	=head1 SUPPORT FOR THE PERL MULTICORE SPECIFICATION
236
237			This module supports the perl multicore specification
238	root	1.14	(L<http://perlmulticore.schmorp.de/>) for all operations, although it
239			makes most sense to use it when signing or verifying longer messages.
240	root	1.9
241	root	1.14	=head1 IMPLEMENTATION
242	root	1.1
243	root	1.7	This module currently uses "Nightcracker's Ed25519" implementation, which
244			is unmodified except for some portability fixes and static delcarations,
245			but the interface is kept implementation-agnostic to allow usage of other
246	root	1.1	implementations in the future.
247
248			=head1 AUTHOR
249
250			Marc Lehmann <schmorp@schmorp.de>
251	root	1.14	http://software.schmorp.de/pkg/Crypt-Ed25519.html
252	root	1.1
253			=cut
254
255			1
256