[ViewVC] Annotation of: cvs/Crypt-Ed25519/README

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

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;

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
    <http://ed25519.cr.yp.to/index.html>.

Ed25519 API
    ($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.

    $signature = Crypt::Ed25519::sign $message, $public_key, $private_key
        Generates a signature for the given message using the public and
        private keys.

    $valid = Crypt::Ed25519::verify $message, $public_key, $signature
        Checks whether the $signature is valid for the $message and
        $public_ke.

    Crypt::Ed25519::verify_croak $message, $public_key, $signature
        Same as "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.

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:

    $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
        "Crypt::Ed25519::eddsa_public_key" and is not the same as the
        private key used in the Ed25519 API.

    $public_key = Crypt::Ed25519::eddsa_public_key $secret_key
        Takes a secret key generated by "Crypt::Ed25519::eddsa_secret_key"
        and returns the corresponding $public_key.

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

    $signature = Crypt::Ed25519::eddsa_sign $message, $public_key,
    $secret_key
        Generates a signature for the given message using the public and
        secret keys.

    $valid = Crypt::Ed25519::eddsa_verify $message, $public_key, $signature
    Crypt::Ed25519::eddsa_verify_croak $message, $public_key, $signature
        Really the same as "Crypt::Ed25519::verify" and
        "Crypt::Ed25519::verify_croak", i.e. the functions without the
        "eddsa_" prefix. These aliases are provided so it's clear that you
        are using EdDSA and not Ed25519 API.

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 "Crypt::Ed25519::generate_keypair":

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

  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.

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

Revision:	1.2
Committed:	Fri Mar 27 20:24:14 2015 UTC (9 years, 1 month ago) by root
Branch:	MAIN
CVS Tags:	rel-0_1, rel-0_9
Changes since 1.1:	+63 -3 lines
Log Message:	0.1
#	User	Rev	Content
1	root	1.1	NAME
2			Crypt::Ed25519 - bare-bones Ed25519 public key signing/verification
3			system
4
5			SYNOPSIS
6			use Crypt::Ed25519; # no symbols exported
7
8			# generate a public/private key pair once
9			($pubkey, $privkey) = Crypt::Ed25519::generate_keypair;
10
11			# sign messages
12			$signature = Crypt::Ed25519::sign $message, $pubkey, $privkey;
13
14			# verify message
15			$valid = Crypt::Ed25519::verify $message, $pubkey, $signature;
16
17			# verify, but croak on failure
18			Crypt::Ed25519::verify_croak $message, $pubkey, $signature;
19
20			DESCRIPTION
21			This module implements Ed25519 public key generation, message signing
22			and verification. It is a pretty bare-bones implementation that
23	root	1.2	implements the standard Ed25519 variant with SHA512 hash, as well as a
24			slower API compatible with the upcoming EdDSA RFC.
25	root	1.1
26			The security target for Ed25519 is to be equivalent to 3000 bit RSA or
27			AES-128.
28
29	root	1.2	The advantages of Ed25519 over most other signing algorithms are: small
30			public/private key and signature sizes (<= 64 octets), good key
31	root	1.1	generation, signing and verification performance, no reliance on random
32			number generators for signing and by-design immunity against branch or
33			memory access pattern side-channel attacks.
34
35			More detailed praise and other info can be found at
36			<http://ed25519.cr.yp.to/index.html>.
37
38	root	1.2	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
96
97	root	1.1	IMPLEMENTATIOIN
98			This module currently uses "Nightcracker's Ed25519" implementation, but
99			the interface is kept implementation-agnostic to allow usage of other
100			implementations in the future.
101
102			AUTHOR
103			Marc Lehmann <schmorp@schmorp.de>
104			http://sfotware.schmorp.de/pkg/Crypt-Ed25519.html
105