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

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

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;

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

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.

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

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.

    ($public_key, $private_key) = Crypt::Ed25519::generate_keypair
    $secret_key
        Instead of generating a random keypair, generate them from the given
        $secret_key (e.g. as returned by "Crypt::Ed25519::eddsa_secret_key".
        The derivation is deterministic, i.e. a specific $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.

    $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 $message, $public_key and $private_key, i.e. no external source
        of randomness is required for signing.

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

        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.

    $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. The derivation ios
        deterministic, i.e. the $public_key generated for a specific
        $secret_key is always the same.

        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. Apart from specifying the $secret_key, this function is
        identical to "Crypt::Ed25519::sign", so everything said about it is
        true for this function as well.

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

    $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

    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.

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

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

Revision:	1.4
Committed:	Wed Jun 24 12:18:02 2015 UTC (11 years, 2 months ago) by root
Branch:	MAIN
CVS Tags:	rel-1_02, rel-1_01
Changes since 1.3:	+4 -3 lines
Log Message:	1.01
#	Content
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	############################################
9	# Ed25519 API - public/private keypair
10
11	# generate a public/private key pair once
12	($pubkey, $privkey) = Crypt::Ed25519::generate_keypair;
13
14	# sign a message
15	$signature = Crypt::Ed25519::sign $message, $pubkey, $privkey;
16
17	# verify message
18	$valid = Crypt::Ed25519::verify $message, $pubkey, $signature;
19
20	# verify, but croak on failure
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;
40
41	DESCRIPTION
42	This module implements Ed25519 public key generation, message signing
43	and verification. It is a pretty bare-bones implementation that
44	implements the standard Ed25519 variant with SHA512 hash, as well as a
45	slower API compatible with the upcoming EdDSA RFC.
46
47	The security target for Ed25519 is to be equivalent to 3000 bit RSA or
48	AES-128.
49
50	The advantages of Ed25519 over most other signing algorithms are: small
51	public/private key and signature sizes (<= 64 octets), good key
52	generation, signing and verification performance, no reliance on random
53	number generators for signing and by-design immunity against branch or
54	memory access pattern side-channel attacks.
55
56	More detailed praise and other info can be found at
57	<http://ed25519.cr.yp.to/index.html>.
58
59	CRYPTOGRAPHY 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
65	CONVENTIONS
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
70	Ed25519 API
71	($public_key, $private_key) = Crypt::Ed25519::generate_keypair
72	Creates and returns a new random public and private key pair. The
73	public key is always 32 octets, the private key is always 64 octets
74	long.
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
87	$signature = Crypt::Ed25519::sign $message, $public_key, $private_key
88	Generates a signature for the given message using the public and
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.
93
94	$valid = Crypt::Ed25519::verify $message, $public_key, $signature
95	Checks whether the $signature is valid for the $message and
96	$public_ke.
97
98	Crypt::Ed25519::verify_croak $message, $public_key, $signature
99	Same as "Crypt::Ed25519::verify", but instead of returning a
100	boolean, simply croaks with an error message when the signature
101	isn't valid, so you don't have to think about what the return value
102	really means.
103
104	EdDSA compatible API
105	The upcoming EdDSA draft RFC uses a slightly different (and slower) API
106	for Ed25519. This API is provided by the following functions:
107
108	$secret_key = Crypt::Ed25519::eddsa_secret_key
109	Creates and returns a new secret key, which is always 32 octets
110	long. The secret key can be used to generate the public key via
111	"Crypt::Ed25519::eddsa_public_key" and is not the same as the
112	private key used in the Ed25519 API.
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
118	$public_key = Crypt::Ed25519::eddsa_public_key $secret_key
119	Takes a secret key generated by "Crypt::Ed25519::eddsa_secret_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.
123
124	This public key corresponds to the public key in the Ed25519 API
125	above.
126
127	$signature = Crypt::Ed25519::eddsa_sign $message, $public_key,
128	$secret_key
129	Generates a signature for the given message using the public and
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.
137
138	$valid = Crypt::Ed25519::eddsa_verify $message, $public_key, $signature
139	Crypt::Ed25519::eddsa_verify_croak $message, $public_key, $signature
140	Really the same as "Crypt::Ed25519::verify" and
141	"Crypt::Ed25519::verify_croak", i.e. the functions without the
142	"eddsa_" prefix. These aliases are provided so it's clear that you
143	are using EdDSA and not Ed25519 API.
144
145	CONVERTING BETWEEN Ed25519 and EdDSA
146	The Ed25519 and EdDSA compatible APIs handle keys slightly differently:
147	The Ed25519 API gives you a public/private key pair, while EdDSA takes a
148	secret and generates a public key from it.
149
150	You can convert an EdDSA secret to an Ed25519 private/public key pair
151	using "Crypt::Ed25519::generate_keypair":
152
153	($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret
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
161	IMPLEMENTATIOIN
162	This module currently uses "Nightcracker's Ed25519" implementation,
163	which is unmodified except for some portability fixes and static
164	delcarations, but the interface is kept implementation-agnostic to allow
165	usage of other implementations in the future.
166
167	AUTHOR
168	Marc Lehmann <schmorp@schmorp.de>
169	http://sfotware.schmorp.de/pkg/Crypt-Ed25519.html
170