[ViewVC] Diff of: cvs/Crypt-Ed25519/Ed25519.pm

Comparing Crypt-Ed25519/Ed25519.pm (file contents):
Revision 1.2 by root, Sat Mar 28 19:42:35 2015 UTC vs.
Revision 1.16 by root, Wed Aug 11 23:15:25 2021 UTC

…		…
3	Crypt::Ed25519 - bare-bones Ed25519 public key signing/verification system	3	Crypt::Ed25519 - bare-bones Ed25519 public key signing/verification system
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
7	use Crypt::Ed25519; # no symbols exported	7	use Crypt::Ed25519; # no symbols exported
		8
		9	############################################
		10	# Ed25519 API - public/private keypair
8		11
9	# generate a public/private key pair once	12	# generate a public/private key pair once
10	($pubkey, $privkey) = Crypt::Ed25519::generate_keypair;	13	($pubkey, $privkey) = Crypt::Ed25519::generate_keypair;
11		14
12	# sign messages	15	# sign a message
13	$signature = Crypt::Ed25519::sign $message, $pubkey, $privkey;	16	$signature = Crypt::Ed25519::sign $message, $pubkey, $privkey;
14		17
15	# verify message	18	# verify message
16	$valid = Crypt::Ed25519::verify $message, $pubkey, $signature;	19	$valid = Crypt::Ed25519::verify $message, $pubkey, $signature;
17		20
18	# verify, but croak on failure	21	# verify, but croak on failure
19	Crypt::Ed25519::verify_croak $message, $pubkey, $signature;	22	Crypt::Ed25519::verify_croak $message, $pubkey, $signature;
		23
		24	############################################
		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	############################################
		43	# Curve25519 key exchange
		44
		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
20		61
21	=head1 DESCRIPTION	62	=head1 DESCRIPTION
22		63
23	This module implements Ed25519 public key generation, message signing and	64	This module implements Ed25519 public key generation, message signing and
24	verification. It is a pretty bare-bones implementation that implements	65	verification. It is a pretty bare-bones implementation that implements
…		…
35	memory access pattern side-channel attacks.	76	memory access pattern side-channel attacks.
36		77
37	More detailed praise and other info can be found at	78	More detailed praise and other info can be found at
38	L<http://ed25519.cr.yp.to/index.html>.	79	L<http://ed25519.cr.yp.to/index.html>.
39		80
		81	=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
40	=cut	94	=cut
41		95
42	package Crypt::Ed25519;	96	package Crypt::Ed25519;
43		97
44	BEGIN {	98	BEGIN {
45	$VERSION = '0.2';	99	$VERSION = 1.05;
46		100
47	require XSLoader;	101	require XSLoader;
48	XSLoader::load Crypt::Ed25519::, $VERSION;	102	XSLoader::load Crypt::Ed25519::, $VERSION;
49	}	103	}
50		104
…		…
55	=item ($public_key, $private_key) = Crypt::Ed25519::generate_keypair	109	=item ($public_key, $private_key) = Crypt::Ed25519::generate_keypair
56		110
57	Creates and returns a new random public and private key pair. The public	111	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.	112	key is always 32 octets, the private key is always 64 octets long.
59		113
		114	=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
60	=item $signature = Crypt::Ed25519::sign $message, $public_key, $private_key	125	=item $signature = Crypt::Ed25519::sign $message, $public_key, $private_key
61		126
62	Generates a signature for the given message using the public and private keys.	127	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.
63		132
64	=item $valid = Crypt::Ed25519::verify $message, $public_key, $signature	133	=item $valid = Crypt::Ed25519::verify $message, $public_key, $signature
65		134
66	Checks whether the C<$signature> is valid for the C<$message> and C<$public_ke>.	135	Checks whether the C<$signature> is valid for the C<$message> and C<$public_ke>.
67		136
…		…
85	Creates and returns a new secret key, which is always 32 octets	154	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	155	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	156	C<Crypt::Ed25519::eddsa_public_key> and is not the same as the private key
88	used in the Ed25519 API.	157	used in the Ed25519 API.
89		158
		159	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
90	=item $public_key = Crypt::Ed25519::eddsa_public_key $secret_key	163	=item $public_key = Crypt::Ed25519::eddsa_public_key $secret_key
91		164
92	Takes a secret key generated by C<Crypt::Ed25519::eddsa_secret_key> and	165	Takes a secret key generated by C<Crypt::Ed25519::eddsa_secret_key>
93	returns the corresponding C<$public_key>.	166	and returns the corresponding C<$public_key>. The derivation is
		167	deterministic, i.e. the C<$public_key> generated for a specific
		168	C<$secret_key> is always the same.
94		169
95	This public key corresponds to the public key in the Ed25519 API above.	170	This public key corresponds to the public key in the Ed25519 API above.
96		171
97	=item $signature = Crypt::Ed25519::eddsa_sign $message, $public_key, $secret_key	172	=item $signature = Crypt::Ed25519::eddsa_sign $message, $public_key, $secret_key
98		173
99	Generates a signature for the given message using the public and secret	174	Generates a signature for the given message using the public and secret
100	keys.	175	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.
101		182
102	=item $valid = Crypt::Ed25519::eddsa_verify $message, $public_key, $signature	183	=item $valid = Crypt::Ed25519::eddsa_verify $message, $public_key, $signature
103		184
104	=item Crypt::Ed25519::eddsa_verify_croak $message, $public_key, $signature	185	=item Crypt::Ed25519::eddsa_verify_croak $message, $public_key, $signature
105		186
…		…
119	You can convert an EdDSA secret to an Ed25519 private/public key pair	200	You can convert an EdDSA secret to an Ed25519 private/public key pair
120	using C<Crypt::Ed25519::generate_keypair>:	201	using C<Crypt::Ed25519::generate_keypair>:
121		202
122	($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret	203	($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret
123		204
		205	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	=head1 Curve25519 Key Exchange
		212
		213	As an extension to Ed25519, this module implements a key exchange similar
		214	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
		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	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
		233	=back
		234
		235	=head1 SUPPORT FOR THE PERL MULTICORE SPECIFICATION
		236
		237	This module supports the perl multicore specification
		238	(L<http://perlmulticore.schmorp.de/>) for all operations, although it
		239	makes most sense to use it when signing or verifying longer messages.
		240
124	=head2 IMPLEMENTATIOIN	241	=head1 IMPLEMENTATION
125		242
126	This module currently uses "Nightcracker's Ed25519" implementation, but	243	This module currently uses "Nightcracker's Ed25519" implementation, which
		244	is unmodified except for some portability fixes and static delcarations,
127	the interface is kept implementation-agnostic to allow usage of other	245	but the interface is kept implementation-agnostic to allow usage of other
128	implementations in the future.	246	implementations in the future.
129		247
130	=head1 AUTHOR	248	=head1 AUTHOR
131		249
132	Marc Lehmann <schmorp@schmorp.de>	250	Marc Lehmann <schmorp@schmorp.de>
133	http://sfotware.schmorp.de/pkg/Crypt-Ed25519.html	251	http://software.schmorp.de/pkg/Crypt-Ed25519.html
134		252
135	=cut	253	=cut
136		254
137	1	255	1
138		256

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing Crypt-Ed25519/Ed25519.pm (file contents): Revision 1.2 by root, Sat Mar 28 19:42:35 2015 UTC vs. Revision 1.16 by root, Wed Aug 11 23:15:25 2021 UTC

Diff Legend

Comparing Crypt-Ed25519/Ed25519.pm (file contents):
Revision 1.2 by root, Sat Mar 28 19:42:35 2015 UTC vs.
Revision 1.16 by root, Wed Aug 11 23:15:25 2021 UTC