From d825e6a31bf980dde8afd94fba61614523e60f09 Mon Sep 17 00:00:00 2001
From: Pieter Wuille <pieter.wuille@gmail.com>
Date: Mon, 7 Nov 2011 00:05:42 +0100
Subject: Some extra comments

---
 src/key.h | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

(limited to 'src/key.h')

diff --git a/src/key.h b/src/key.h
index 5ffd7b9ccc..df5cfeb32c 100644
--- a/src/key.h
+++ b/src/key.h
@@ -39,6 +39,7 @@
 // see www.keylength.com
 // script supports up to 75 for single byte push
 
+// Generate a private key from just the secret parameter
 int static inline EC_KEY_regenerate_key(EC_KEY *eckey, BIGNUM *priv_key)
 {
     int ok = 0;
@@ -75,6 +76,9 @@ err:
     return(ok);
 }
 
+// Perform ECDSA key recovery (see SEC1 4.1.6) for curves over (mod p)-fields
+// recid selects which key is recovered
+// if check is nonzero, additional checks are performed
 int static inline ECDSA_SIG_recover_key_GFp(EC_KEY *eckey, ECDSA_SIG *ecsig, const unsigned char *msg, int msglen, int recid, int check)
 {
     if (!eckey) return 0;
@@ -154,7 +158,9 @@ public:
 
 
 // secure_allocator is defined in serialize.h
+// CPrivKey is a serialized private key, with all parameters included (279 bytes)
 typedef std::vector<unsigned char, secure_allocator<unsigned char> > CPrivKey;
+// CSecret is a serialization of just the secret parameter (32 bytes)
 typedef std::vector<unsigned char, secure_allocator<unsigned char> > CSecret;
 
 class CKey
@@ -292,6 +298,9 @@ public:
     }
 
     // create a compact signature (65 bytes), which allows reconstructing the used public key
+    // The format is one header byte, followed by two times 32 bytes for the serialized r and s values.
+    // The header byte: 0x1B = first key with even y, 0x1C = first key with odd y,
+    //                  0x1D = second key with even y, 0x1E = second key with odd y
     bool SignCompact(uint256 hash, std::vector<unsigned char>& vchSig)
     {
         bool fOk = false;
@@ -318,7 +327,7 @@ public:
             }
 
             if (nRecId == -1)
-                throw key_error("CKEy::SignCompact() : unable to construct recoverable key");
+                throw key_error("CKey::SignCompact() : unable to construct recoverable key");
 
             vchSig[0] = nRecId+27;
             BN_bn2bin(sig->r,&vchSig[33-(nBitsR+7)/8]);
@@ -330,6 +339,9 @@ public:
     }
 
     // reconstruct public key from a compact signature
+    // This is only slightly more CPU intensive than just verifying it.
+    // If this function succeeds, the recovered public key is guaranteed to be valid
+    // (the signature is a valid signature of the given data for that key)
     bool SetCompactSignature(uint256 hash, const std::vector<unsigned char>& vchSig)
     {
         if (vchSig.size() != 65)
@@ -359,6 +371,7 @@ public:
         return true;
     }
 
+    // Verify a compact signature
     bool VerifyCompact(uint256 hash, const std::vector<unsigned char>& vchSig)
     {
         CKey key;
@@ -369,6 +382,7 @@ public:
         return true;
     }
 
+    // Get the address corresponding to this key
     CBitcoinAddress GetAddress() const
     {
         return CBitcoinAddress(GetPubKey());
-- 
cgit v1.2.3