--- Crypt-Ed25519/Ed25519.pm 2015/03/28 19:43:19 1.3 +++ Crypt-Ed25519/Ed25519.pm 2015/06/29 12:33:37 1.11 @@ -6,10 +6,13 @@ 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 messages + # sign a message $signature = Crypt::Ed25519::sign $message, $pubkey, $privkey; # verify message @@ -18,6 +21,24 @@ # 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; + =head1 DESCRIPTION This module implements Ed25519 public key generation, message signing and @@ -37,12 +58,25 @@ More detailed praise and other info can be found at L. +=head1 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. + +=head1 CONVENTIONS + +Public/private/secret keys, messages and signatures are all opaque and +architecture-independent octet strings, and, except for the message, have +fixed lengths. + =cut package Crypt::Ed25519; BEGIN { - $VERSION = '0.9'; + $VERSION = 1.03; require XSLoader; XSLoader::load Crypt::Ed25519::, $VERSION; @@ -57,9 +91,24 @@ 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 ($public_key, $private_key) = Crypt::Ed25519::generate_keypair $secret_key + +Instead of generating a random keypair, generate them from the given +C<$secret_key> (e.g. as returned by C. +The derivation is deterministic, i.e. a specific C<$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. + =item $signature = Crypt::Ed25519::sign $message, $public_key, $private_key -Generates a signature for the given message using the public and private keys. +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 C<$message>, C<$public_key> +and C<$private_key>, i.e. no external source of randomness is required for +signing. =item $valid = Crypt::Ed25519::verify $message, $public_key, $signature @@ -87,17 +136,29 @@ C 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. + =item $public_key = Crypt::Ed25519::eddsa_public_key $secret_key -Takes a secret key generated by C and -returns the corresponding C<$public_key>. +Takes a secret key generated by C +and returns the corresponding C<$public_key>. The derivation ios +deterministic, i.e. the C<$public_key> generated for a specific +C<$secret_key> is always the same. 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. +keys. Apart from specifying the C<$secret_key>, this function is identical +to C, so everything said about it is true for this +function as well. + +Internally, C derives the corresponding +private key first and then calls C, so it is always +slower. =item $valid = Crypt::Ed25519::eddsa_verify $message, $public_key, $signature @@ -121,10 +182,23 @@ ($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 +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. + +=head1 SUPPORT FOR THE PERL MULTICORE SPECIFICATION + +This module supports the perl multicore specification +(L) for key generation (usually the +slowest operation), and all signing and verification functions. + +=head1 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. =head1 AUTHOR