More documentation for ed25519 stuff.

2 files changed, 45 insertions, 4 deletions

diff --git a/src/common/crypto_ed25519.c b/src/common/crypto_ed25519.c
index 15fc626fa2..a545cad9f5 100644
--- a/src/common/crypto_ed25519.c
+++ b/src/common/crypto_ed25519.c
@@ -19,6 +19,11 @@
 
 #include <openssl/sha.h>
 
+/**
+ * Initialize a new ed25519 secret key in <b>seckey_out</b>.  If
+ * <b>extra_strong</b>, take the RNG inputs directly from the operating
+ * system.  Return 0 on success, -1 on failure.
+ */
 int
 ed25519_secret_key_generate(ed25519_secret_key_t *seckey_out,
                         int extra_strong)
@@ -34,6 +39,10 @@ ed25519_secret_key_generate(ed25519_secret_key_t *seckey_out,
   return r < 0 ? -1 : 0;
 }
 
+/**
+ * Given a 32-byte random seed in <b>seed</b>, expand it into an ed25519
+ * secret key in <b>seckey_out</b>.  Return 0 on success, -1 on failure.
+ */
 int
 ed25519_secret_key_from_seed(ed25519_secret_key_t *seckey_out,
                              const uint8_t *seed)
@@ -43,6 +52,10 @@ ed25519_secret_key_from_seed(ed25519_secret_key_t *seckey_out,
   return 0;
 }
 
+/**
+ * Given a secret key in <b>seckey</b>, expand it into an
+ * ed25519 public key.  Return 0 on success, -1 on failure.
+ */
 int
 ed25519_public_key_generate(ed25519_public_key_t *pubkey_out,
                         const ed25519_secret_key_t *seckey)
@@ -224,6 +237,10 @@ ed25519_public_key_from_curve25519_public_key(ed25519_public_key_t *pubkey,
  * ed25519 keypair in <b>out</b>, blinded by the corresponding 32-byte input
  * in 'param'.
  *
+ * Tor uses key blinding for the "next-generation" hidden services design:
+ * service descriptors are encrypted with a key derived from the service's
+ * long-term public key, and then signed with (and stored at a position
+ * indexed by) a short-term key derived by blinding the long-term keys.
  */
 int
 ed25519_keypair_blind(ed25519_keypair_t *out,
@@ -245,6 +262,11 @@ ed25519_keypair_blind(ed25519_keypair_t *out,
   return 0;
 }
 
+/**
+ * Given an ed25519 public key in <b>inp</b>, generate a corresponding blinded
+ * public key in <b>out</b>, blinded with the 32-byte parameter in
+ * <b>param</b>.  Return 0 on sucess, -1 on railure.
+ */
 int
 ed25519_public_blind(ed25519_public_key_t *out,
                      const ed25519_public_key_t *inp,
@@ -254,7 +276,10 @@ ed25519_public_blind(ed25519_public_key_t *out,
   return 0;
 }
 
-/** DOCDOC */
+/**
+ * Store seckey unencrypted to <b>filename</b>, marking it with <b>tag</b>.
+ * Return 0 on success, -1 on failure.
+ */
 int
 ed25519_seckey_write_to_file(const ed25519_secret_key_t *seckey,
                              const char *filename,
@@ -267,7 +292,11 @@ ed25519_seckey_write_to_file(const ed25519_secret_key_t *seckey,
                                               sizeof(seckey->seckey));
 }
 
-/** DOCDOC */
+/**
+ * Read seckey unencrypted from <b>filename</b>, storing it into
+ * <b>seckey_out</b>.  Set *<b>tag_out</> to the tag it was marked with.
+ * Return 0 on success, -1 on failure.
+ */
 int
 ed25519_seckey_read_from_file(ed25519_secret_key_t *seckey_out,
                               char **tag_out,
@@ -284,7 +313,10 @@ ed25519_seckey_read_from_file(ed25519_secret_key_t *seckey_out,
   return 0;
 }
 
-/** DOCDOC */
+/**
+ * Store pubkey unencrypted to <b>filename</b>, marking it with <b>tag</b>.
+ * Return 0 on success, -1 on failure.
+ */
 int
 ed25519_pubkey_write_to_file(const ed25519_public_key_t *pubkey,
                              const char *filename,
@@ -297,7 +329,10 @@ ed25519_pubkey_write_to_file(const ed25519_public_key_t *pubkey,
                                               sizeof(pubkey->pubkey));
 }
 
-/** DOCDOC */
+/**
+ * Store pubkey unencrypted to <b>filename</b>, marking it with <b>tag</b>.
+ * Return 0 on success, -1 on failure.
+ */
 int
 ed25519_pubkey_read_from_file(ed25519_public_key_t *pubkey_out,
                               char **tag_out,
diff --git a/src/common/crypto_ed25519.h b/src/common/crypto_ed25519.h
index 1271312dfe..13b05c7c1e 100644
--- a/src/common/crypto_ed25519.h
+++ b/src/common/crypto_ed25519.h
@@ -24,6 +24,12 @@ typedef struct {
 
 /** An Ed25519 secret key */
 typedef struct {
+  /** Note that we store secret keys in an expanded format that doesn't match
+   * the format from standard ed25519.  Ed25519 stores a 32-byte value k and
+   * expands it into a 64-byte H(k), using the first 32 bytes for a multiplier
+   * of the base point, and second 32 bytes as an input to a hash function
+   * for deriving r.  But because we implement key blinding, we need to store
+   * keys in the 64-byte expanded form. */
   uint8_t seckey[ED25519_SECKEY_LEN];
 } ed25519_secret_key_t;