--- Crypt-Ed25519/README	2015/03/27 20:24:14	1.2
+++ 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,6 +20,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;
+
 DESCRIPTION
     This module implements Ed25519 public key generation, message signing
     and verification. It is a pretty bare-bones implementation that
@@ -35,15 +56,40 @@
     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.
+        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
@@ -65,9 +111,15 @@
         "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.
+        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.
@@ -75,7 +127,13 @@
     $signature = Crypt::Ed25519::eddsa_sign $message, $public_key,
     $secret_key
         Generates a signature for the given message using the public and
-        secret keys.
+        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
@@ -94,10 +152,17 @@
 
        ($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
-    implementations in the future.
+    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 <schmorp@schmorp.de>