[tor-commits] [torspec/master] Specify the ED25519-V3 private key format, and explain why it is so.

[dgoulet at torproject.org]

commit 3c34000c9c28b6a55e2c4333a5ad0ccf99bd4026
Author: Taylor R Campbell <campbell+tor at mumble.net>
Date:   Fri Oct 19 17:43:17 2018 +0000

    Specify the ED25519-V3 private key format, and explain why it is so.
---
 control-spec.txt | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/control-spec.txt b/control-spec.txt
index 6f0a543..6a04b65 100644
--- a/control-spec.txt
+++ b/control-spec.txt
@@ -1671,8 +1671,18 @@
 
   (The KeyBlob format is left intentionally opaque, however for "RSA1024"
   keys it is currently the Base64 encoded DER representation of a PKCS#1
-  RSAPrivateKey, with all newlines removed. For a "ED25519-V3" key is a Base64
-  encoded ed25519 private key.)
+  RSAPrivateKey, with all newlines removed. For a "ED25519-V3" key is
+  the Base64 encoding of the concatenation of the 32-byte ed25519 secret
+  scalar in little-endian and the 32-byte ed25519 PRF secret.)
+
+  [Note: The ED25519-V3 format is not the same as, e.g., SUPERCOP
+  ed25519/ref, which stores the concatenation of the 32-byte ed25519
+  hash seed concatenated with the 32-byte public key, and which derives
+  the secret scalar and PRF secret by expanding the hash seed with
+  SHA-512.  Our key blinding scheme is incompatible with storing
+  private keys as seeds, so we store the secret scalar alongside the
+  PRF secret, and just pay the cost of recomputing the public key when
+  importing an ED25519-V3 key.]
 
   (The "NEW:BEST" option obeys the HiddenServiceVersion torrc option default
   value. Currently it is 2.)