Add comments to ed25519_vectors.inc

2 files changed, 67 insertions, 1 deletions

diff --git a/src/test/ed25519_exts_ref.py b/src/test/ed25519_exts_ref.py
index 0df5541d10..93dc49ee93 100644
--- a/src/test/ed25519_exts_ref.py
+++ b/src/test/ed25519_exts_ref.py
@@ -16,6 +16,7 @@ import random
 import slownacl_curve25519
 import unittest
 import binascii
+import textwrap
 
 #define a synonym that doesn't look like 1
 ell = l
@@ -138,7 +139,7 @@ RAND_INPUTS = [
   '4377c40431c30883c5fbd9bc92ae48d1ed8a47b81d13806beac5351739b5533d',
   'c6bbcce615839756aed2cc78b1de13884dd3618f48367a17597a16c1cd7a290b']
 
-# From pprint.pprint([ binascii.b2a_hex(os.urandom(16)) for _ in xrange(8) ])
+# From pprint.pprint([ binascii.b2a_hex(os.urandom(32)) for _ in xrange(8) ])
 BLINDING_PARAMS = [
   '54a513898b471d1d448a2f3c55c1de2c0ef718c447b04497eeb999ed32027823',
   '831e9b5325b5d31b7ae6197e9c7a7baf2ec361e08248bce055908971047a2347',
@@ -164,30 +165,57 @@ def writeArray(name, array):
             print '  "{0}",'.format(h)
     print "};\n"
 
+def comment(text, initial="/**"):
+    print initial
+    print textwrap.fill(text,initial_indent=" * ",subsequent_indent=" * ")
+    print " */"
+
 def makeTestVectors():
+    comment("""Test vectors for our ed25519 implementation and related
+               functions. These were automatically generated by the
+               ed25519_exts_ref.py script.""", initial="/*")
+
+
+    comment("""Secret key seeds used as inputs for the ed25519 test vectors.
+               Randomly generated. """)
     secretKeys = [ binascii.a2b_hex(r) for r in RAND_INPUTS ]
     writeArray("SECRET_KEYS", secretKeys)
 
+    comment("""Secret ed25519 keys after expansion from seeds. This is how Tor
+               represents them internally.""")
     expandedSecretKeys = [ expandSK(sk) for sk in secretKeys ]
     writeArray("EXPANDED_SECRET_KEYS", expandedSecretKeys)
 
+    comment("""Public keys derived from the above secret keys""")
     publicKeys = [ publickey(sk) for sk in secretKeys ]
     writeArray("PUBLIC_KEYS", publicKeys)
 
+    comment("""The curve25519 public keys from which the ed25519 keys can be
+               derived.  Used to test our 'derive ed25519 from curve25519'
+               code.""")
     writeArray("CURVE25519_PUBLIC_KEYS",
                (slownacl_curve25519.smult_curve25519_base(sk[:32])
                    for sk in expandedSecretKeys))
 
+    comment("""Parameters used for key blinding tests. Randomly generated.""")
     blindingParams =  [ binascii.a2b_hex(r) for r in BLINDING_PARAMS ]
     writeArray("BLINDING_PARAMS", blindingParams)
 
+    comment("""Blinded secret keys for testing key blinding.  The nth blinded
+               key corresponds to the nth secret key blidned with the nth
+               blinding parameter.""")
     writeArray("BLINDED_SECRET_KEYS",
                (blindESK(expandSK(sk), bp)
                 for sk,bp in zip(secretKeys,blindingParams)))
 
+    comment("""Blinded public keys for testing key blinding.  The nth blinded
+               key corresponds to the nth public key blidned with the nth
+               blinding parameter.""")
     writeArray("BLINDED_PUBLIC_KEYS",
                (blindPK(pk, bp) for pk,bp in zip(publicKeys,blindingParams)))
 
+    comment("""Signatures of the public keys, made with their corresponding
+               secret keys.""")
     writeArray("SELF_SIGNATURES",
                (signature(pk, sk, pk) for pk,sk in zip(publicKeys,secretKeys)))
 
diff --git a/src/test/ed25519_vectors.inc b/src/test/ed25519_vectors.inc
index ef0a20bb0d..760bafb971 100644
--- a/src/test/ed25519_vectors.inc
+++ b/src/test/ed25519_vectors.inc
@@ -1,3 +1,12 @@
+/*
+ * Test vectors for our ed25519 implementation and related
+ * functions. These were automatically generated by the
+ * ed25519_exts_ref.py script.
+ */
+/**
+ * Secret key seeds used as inputs for the ed25519 test vectors.
+ * Randomly generated.
+ */
 static const char *ED25519_SECRET_KEYS[] = {
   "26c76712d89d906e6672dafa614c42e5cb1caac8c6568e4d2493087db51f0d36",
   "fba7a5366b5cb98c2667a18783f5cf8f4f8d1a2ce939ad22a6e685edde85128d",
@@ -9,6 +18,10 @@ static const char *ED25519_SECRET_KEYS[] = {
   "c6bbcce615839756aed2cc78b1de13884dd3618f48367a17597a16c1cd7a290b",
 };
 
+/**
+ * Secret ed25519 keys after expansion from seeds. This is how Tor
+ * represents them internally.
+ */
 static const char *ED25519_EXPANDED_SECRET_KEYS[] = {
   "c0a4de23cc64392d85aa1da82b3defddbea946d13bb053bf8489fa9296281f495022f1"
       "f7ec0dcf52f07d4c7965c4eaed121d5d88d0a8ff546b06116a20e97755",
@@ -28,6 +41,9 @@ static const char *ED25519_EXPANDED_SECRET_KEYS[] = {
       "ff8dcd0c6c233f665a2e176324d92416bfcfcd1f787424c0c667452d86",
 };
 
+/**
+ * Public keys derived from the above secret keys
+ */
 static const char *ED25519_PUBLIC_KEYS[] = {
   "c2247870536a192d142d056abefca68d6193158e7c1a59c1654c954eccaff894",
   "1519a3b15816a1aafab0b213892026ebf5c0dc232c58b21088d88cb90e9b940d",
@@ -39,6 +55,11 @@ static const char *ED25519_PUBLIC_KEYS[] = {
   "95126f14d86494020665face03f2d42ee2b312a85bc729903eb17522954a1c4a",
 };
 
+/**
+ * The curve25519 public keys from which the ed25519 keys can be
+ * derived.  Used to test our 'derive ed25519 from curve25519'
+ * code.
+ */
 static const char *ED25519_CURVE25519_PUBLIC_KEYS[] = {
   "17ba77846e04c7ee5ca17cade774ac1884408f9701f439d4df32cbd8736c6a1f",
   "022be2124bc1899a78ba2b4167d191af3b59cadf94f0382bc31ce183a117f161",
@@ -50,6 +71,9 @@ static const char *ED25519_CURVE25519_PUBLIC_KEYS[] = {
   "861f33296cb57f8f01e4a5e8a7e5d5d7043a6247586ab36dea8a1a3c4403ee30",
 };
 
+/**
+ * Parameters used for key blinding tests. Randomly generated.
+ */
 static const char *ED25519_BLINDING_PARAMS[] = {
   "54a513898b471d1d448a2f3c55c1de2c0ef718c447b04497eeb999ed32027823",
   "831e9b5325b5d31b7ae6197e9c7a7baf2ec361e08248bce055908971047a2347",
@@ -61,6 +85,11 @@ static const char *ED25519_BLINDING_PARAMS[] = {
   "3f44f6a5a92cde816635dfc12ade70539871078d2ff097278be2a555c9859cd0",
 };
 
+/**
+ * Blinded secret keys for testing key blinding.  The nth blinded
+ * key corresponds to the nth secret key blidned with the nth
+ * blinding parameter.
+ */
 static const char *ED25519_BLINDED_SECRET_KEYS[] = {
   "014e83abadb2ca9a27e0ffe23920333d817729f48700e97656ec2823d694050e171d43"
       "f24e3f53e70ec7ac280044ac77d4942dee5d6807118a59bdf3ee647e89",
@@ -80,6 +109,11 @@ static const char *ED25519_BLINDED_SECRET_KEYS[] = {
       "00c81e1331c06ab50087be8cfc7dc11691b132614474f1aa9c2503cccd",
 };
 
+/**
+ * Blinded public keys for testing key blinding.  The nth blinded
+ * key corresponds to the nth public key blidned with the nth
+ * blinding parameter.
+ */
 static const char *ED25519_BLINDED_PUBLIC_KEYS[] = {
   "722d6da6348e618967ef782e71061e27163a8b35f21856475d9d2023f65b6495",
   "1dffa0586da6cbfcff2024eedf4fc6c818242d9a82dbbe635d6da1b975a1160d",
@@ -91,6 +125,10 @@ static const char *ED25519_BLINDED_PUBLIC_KEYS[] = {
   "9f297ff0aa2ceda91c5ab1b6446f12533d145940de6d850dc323417afde0cb78",
 };
 
+/**
+ * Signatures of the public keys, made with their corresponding
+ * secret keys.
+ */
 static const char *ED25519_SELF_SIGNATURES[] = {
   "d23188eac3773a316d46006fa59c095060be8b1a23582a0dd99002a82a0662bd246d84"
       "49e172e04c5f46ac0d1404cebe4aabd8a75a1457aa06cae41f3334f104",