Add comments to ed25519_vectors.inc

1 files changed, 29 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)))