--- Crypt-Ed25519/README 2015/03/27 20:23:12 1.1 +++ Crypt-Ed25519/README 2015/06/24 12:18:02 1.4 @@ -5,10 +5,13 @@ 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 messages + # sign a message $signature = Crypt::Ed25519::sign $message, $pubkey, $privkey; # verify message @@ -17,16 +20,35 @@ # 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. + 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 signaturer algorithms are: - small public/private key and signature sizes (<= 64 octets), good key + 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. @@ -34,10 +56,113 @@ More detailed praise and other info can be found at . - 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. +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