Crypt-Ed25519/Ed25519.pm

=head1 NAME

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

=head1 SYNOPSIS

 use Crypt::Ed25519; # no symbols exported

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

 # sign messages
 $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;

=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>.

=cut

package Crypt::Ed25519;

BEGIN {
   $VERSION = '0.9';

   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 $signature = Crypt::Ed25519::sign $message, $public_key, $private_key

Generates a signature for the given message using the public and private keys.

=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.

=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>.

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.

=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

=head2 IMPLEMENTATIOIN

This module currently uses "Nightcracker's Ed25519" implementation, but
the interface is kept implementation-agnostic to allow usage of other
implementations in the future.

=head1 AUTHOR

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

=cut

1

Revision:	1.3
Committed:	Sat Mar 28 19:43:19 2015 UTC (9 years, 1 month ago) by root
Branch:	MAIN
CVS Tags:	rel-0_9
Changes since 1.2:	+1 -1 lines
Log Message:	0.9
#	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			# generate a public/private key pair once
10			($pubkey, $privkey) = Crypt::Ed25519::generate_keypair;
11
12			# sign messages
13			$signature = Crypt::Ed25519::sign $message, $pubkey, $privkey;
14
15			# verify message
16			$valid = Crypt::Ed25519::verify $message, $pubkey, $signature;
17
18			# verify, but croak on failure
19			Crypt::Ed25519::verify_croak $message, $pubkey, $signature;
20
21			=head1 DESCRIPTION
22
23			This module implements Ed25519 public key generation, message signing and
24			verification. It is a pretty bare-bones implementation that implements
25			the standard Ed25519 variant with SHA512 hash, as well as a slower API
26			compatible with the upcoming EdDSA RFC.
27
28			The security target for Ed25519 is to be equivalent to 3000 bit RSA or
29			AES-128.
30
31			The advantages of Ed25519 over most other signing algorithms are:
32			small public/private key and signature sizes (<= 64 octets), good key
33			generation, signing and verification performance, no reliance on random
34			number generators for signing and by-design immunity against branch or
35			memory access pattern side-channel attacks.
36
37			More detailed praise and other info can be found at
38			L<http://ed25519.cr.yp.to/index.html>.
39
40			=cut
41
42			package Crypt::Ed25519;
43
44			BEGIN {
45	root	1.3	$VERSION = '0.9';
46	root	1.1
47			require XSLoader;
48			XSLoader::load Crypt::Ed25519::, $VERSION;
49			}
50
51			=head1 Ed25519 API
52
53			=over 4
54
55			=item ($public_key, $private_key) = Crypt::Ed25519::generate_keypair
56
57			Creates and returns a new random public and private key pair. The public
58			key is always 32 octets, the private key is always 64 octets long.
59
60			=item $signature = Crypt::Ed25519::sign $message, $public_key, $private_key
61
62			Generates a signature for the given message using the public and private keys.
63
64			=item $valid = Crypt::Ed25519::verify $message, $public_key, $signature
65
66			Checks whether the C<$signature> is valid for the C<$message> and C<$public_ke>.
67
68			=item Crypt::Ed25519::verify_croak $message, $public_key, $signature
69
70			Same as C<Crypt::Ed25519::verify>, but instead of returning a boolean,
71			simply croaks with an error message when the signature isn't valid, so you
72			don't have to think about what the return value really means.
73
74			=back
75
76			=head1 EdDSA compatible API
77
78			The upcoming EdDSA draft RFC uses a slightly different (and slower)
79			API for Ed25519. This API is provided by the following functions:
80
81			=over 4
82
83			=item $secret_key = Crypt::Ed25519::eddsa_secret_key
84
85			Creates and returns a new secret key, which is always 32 octets
86			long. The secret key can be used to generate the public key via
87			C<Crypt::Ed25519::eddsa_public_key> and is not the same as the private key
88			used in the Ed25519 API.
89
90			=item $public_key = Crypt::Ed25519::eddsa_public_key $secret_key
91
92			Takes a secret key generated by C<Crypt::Ed25519::eddsa_secret_key> and
93			returns the corresponding C<$public_key>.
94
95			This public key corresponds to the public key in the Ed25519 API above.
96
97			=item $signature = Crypt::Ed25519::eddsa_sign $message, $public_key, $secret_key
98
99			Generates a signature for the given message using the public and secret
100			keys.
101
102			=item $valid = Crypt::Ed25519::eddsa_verify $message, $public_key, $signature
103
104			=item Crypt::Ed25519::eddsa_verify_croak $message, $public_key, $signature
105
106			Really the same as C<Crypt::Ed25519::verify> and
107			C<Crypt::Ed25519::verify_croak>, i.e. the functions without the C<eddsa_>
108			prefix. These aliases are provided so it's clear that you are using EdDSA
109			and not Ed25519 API.
110
111			=back
112
113			=head1 CONVERTING BETWEEN Ed25519 and EdDSA
114
115			The Ed25519 and EdDSA compatible APIs handle keys slightly
116			differently: The Ed25519 API gives you a public/private key pair, while
117			EdDSA takes a secret and generates a public key from it.
118
119			You can convert an EdDSA secret to an Ed25519 private/public key pair
120			using C<Crypt::Ed25519::generate_keypair>:
121
122			($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret
123
124			=head2 IMPLEMENTATIOIN
125
126			This module currently uses "Nightcracker's Ed25519" implementation, but
127			the interface is kept implementation-agnostic to allow usage of other
128			implementations in the future.
129
130			=head1 AUTHOR
131
132			Marc Lehmann <schmorp@schmorp.de>
133			http://sfotware.schmorp.de/pkg/Crypt-Ed25519.html
134
135			=cut
136
137			1
138