--- Crypt-Ed25519/README	2015/03/27 20:23:12	1.1
+++ Crypt-Ed25519/README	2015/03/27 20:24:14	1.2
@@ -20,13 +20,14 @@
 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,6 +35,65 @@
     More detailed praise and other info can be found at
     <http://ed25519.cr.yp.to/index.html>.
 
+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.
+
+    $signature = Crypt::Ed25519::sign $message, $public_key, $private_key
+        Generates a signature for the given message using the public and
+        private keys.
+
+    $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.
+
+    $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.
+
+        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.
+
+    $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
+
   IMPLEMENTATIOIN
     This module currently uses "Nightcracker's Ed25519" implementation, but
     the interface is kept implementation-agnostic to allow usage of other