[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

     ############################################
     # 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;

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

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

Key Exchange
    As an extension to Ed25519, this module implements a key exchange
    similar (But not identical) to Curve25519. For 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:

    $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. See SYNOPSIS for an actual example.

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

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.

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

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