[tor-commits] [tor/master] More documentation for ed25519 stuff.
nickm at torproject.org
nickm at torproject.org
Thu Sep 25 19:12:41 UTC 2014
commit f0eb7ae79f54781bc00e51ff5e9630b2103e4df0
Author: Nick Mathewson <nickm at torproject.org>
Date: Fri Aug 29 09:24:27 2014 -0400
More documentation for ed25519 stuff.
---
src/common/crypto_ed25519.c | 43 ++++++++++++++++++++++++++++++++++----
src/common/crypto_ed25519.h | 6 ++++++
src/ext/ed25519/ref10/README.tor | 23 ++++++++++++++++++++
src/ext/ed25519/ref10/blinding.c | 2 +-
4 files changed, 69 insertions(+), 5 deletions(-)
diff --git a/src/common/crypto_ed25519.c b/src/common/crypto_ed25519.c
index 15fc626..a545cad 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 1271312..13b05c7 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;
diff --git a/src/ext/ed25519/ref10/README.tor b/src/ext/ed25519/ref10/README.tor
new file mode 100644
index 0000000..38ed97b
--- /dev/null
+++ b/src/ext/ed25519/ref10/README.tor
@@ -0,0 +1,23 @@
+
+We've made the following changes to the stock ed25519_ref10 from
+supercop-20140622:
+
+ * We added the necessary glue to provide integers of fixed bit
+ sizes, SHA512, and to compile without warnings everywhere we need
+ to build.
+
+ * Secret keys are stored in expanded format. There are functions
+ to expand them from the 32-byte seed.
+
+ * Signatures are made and processed detached from the messages that
+ they sign. (In other words, we support "make signature" and
+ "check signature", not "create signed message" and "check and
+ unpack signed message".)
+
+ * There's an implementation of 'convert a curve25519 key to an
+ ed25519 key' so we can do cross-certification with curve25519 keys.
+ (keyconv.c)
+
+ * There's an implementation of multiplicative key blinding so we
+ can use it for next-gen hidden srevice descriptors. (blinding.c)
+
diff --git a/src/ext/ed25519/ref10/blinding.c b/src/ext/ed25519/ref10/blinding.c
index a17dbcd..f0154e0 100644
--- a/src/ext/ed25519/ref10/blinding.c
+++ b/src/ext/ed25519/ref10/blinding.c
@@ -14,7 +14,7 @@ gettweak(unsigned char *out, const unsigned char *param)
{
const char str[] = "Derive temporary signing key";
crypto_hash_sha512_2(out, (const unsigned char*)str, strlen(str), param, 32);
- out[0] &= 248; /* Necessary ? */
+ out[0] &= 248; /* Is this necessary necessary ? */
out[31] &= 63;
out[31] |= 64;
}
More information about the tor-commits
mailing list