From ffd8eddab540a9692bef681f2637f757d84e28a2 Mon Sep 17 00:00:00 2001 From: Michael Ford Date: Sun, 26 Oct 2014 16:33:52 +0800 Subject: [PATCH] Update comments in key to be doxygen compatible --- src/key.cpp | 8 +-- src/key.h | 139 +++++++++++++++++++++++++++++----------------------- 2 files changed, 82 insertions(+), 65 deletions(-) diff --git a/src/key.cpp b/src/key.cpp index 0f4bc6652..48431f3dc 100644 --- a/src/key.cpp +++ b/src/key.cpp @@ -1,5 +1,5 @@ // Copyright (c) 2009-2014 The Bitcoin developers -// Distributed under the MIT/X11 software license, see the accompanying +// Distributed under the MIT software license, see the accompanying // file COPYING or http://www.opensource.org/licenses/mit-license.php. #include "key.h" @@ -13,7 +13,7 @@ #include "ecwrapper.h" #endif -// anonymous namespace +//! anonymous namespace with local implementation code (OpenSSL interaction) namespace { #ifdef USE_SECP256K1 @@ -56,7 +56,7 @@ int CompareBigEndian(const unsigned char *c1, size_t c1len, const unsigned char return 0; } -// Order of secp256k1's generator minus 1. +/** Order of secp256k1's generator minus 1. */ const unsigned char vchMaxModOrder[32] = { 0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF, 0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFE, @@ -64,7 +64,7 @@ const unsigned char vchMaxModOrder[32] = { 0xBF,0xD2,0x5E,0x8C,0xD0,0x36,0x41,0x40 }; -// Half of the order of secp256k1's generator minus 1. +/** Half of the order of secp256k1's generator minus 1. */ const unsigned char vchMaxModHalfOrder[32] = { 0x7F,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF, 0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF, diff --git a/src/key.h b/src/key.h index 48b165253..b4cb64768 100644 --- a/src/key.h +++ b/src/key.h @@ -1,6 +1,6 @@ // Copyright (c) 2009-2010 Satoshi Nakamoto -// Copyright (c) 2009-2013 The Bitcoin developers -// Distributed under the MIT/X11 software license, see the accompanying +// Copyright (c) 2009-2014 The Bitcoin developers +// Distributed under the MIT software license, see the accompanying // file COPYING or http://www.opensource.org/licenses/mit-license.php. #ifndef BITCOIN_KEY_H @@ -14,13 +14,15 @@ #include #include -// secp256k1: -// const unsigned int PRIVATE_KEY_SIZE = 279; -// const unsigned int PUBLIC_KEY_SIZE = 65; -// const unsigned int SIGNATURE_SIZE = 72; -// -// see www.keylength.com -// script supports up to 75 for single byte push +/** + * secp256k1: + * const unsigned int PRIVATE_KEY_SIZE = 279; + * const unsigned int PUBLIC_KEY_SIZE = 65; + * const unsigned int SIGNATURE_SIZE = 72; + * + * see www.keylength.com + * script supports up to 75 for single byte push + */ /** A reference to a CKey: the Hash160 of its serialized public key */ class CKeyID : public uint160 @@ -34,11 +36,14 @@ public: class CPubKey { private: - // Just store the serialized data. - // Its length can very cheaply be computed from the first byte. + + /** + * Just store the serialized data. + * Its length can very cheaply be computed from the first byte. + */ unsigned char vch[65]; - // Compute the length of a pubkey with a given first byte. + //! Compute the length of a pubkey with a given first byte. unsigned int static GetLen(unsigned char chHeader) { if (chHeader == 2 || chHeader == 3) @@ -48,20 +53,20 @@ private: return 0; } - // Set this key data to be invalid + //! Set this key data to be invalid void Invalidate() { vch[0] = 0xFF; } public: - // Construct an invalid public key. + //! Construct an invalid public key. CPubKey() { Invalidate(); } - // Initialize a public key using begin/end iterators to byte data. + //! Initialize a public key using begin/end iterators to byte data. template void Set(const T pbegin, const T pend) { @@ -72,26 +77,26 @@ public: Invalidate(); } - // Construct a public key using begin/end iterators to byte data. + //! Construct a public key using begin/end iterators to byte data. template CPubKey(const T pbegin, const T pend) { Set(pbegin, pend); } - // Construct a public key from a byte vector. + //! Construct a public key from a byte vector. CPubKey(const std::vector& vch) { Set(vch.begin(), vch.end()); } - // Simple read-only vector-like interface to the pubkey data. + //! Simple read-only vector-like interface to the pubkey data. unsigned int size() const { return GetLen(vch[0]); } const unsigned char* begin() const { return vch; } const unsigned char* end() const { return vch + size(); } const unsigned char& operator[](unsigned int pos) const { return vch[pos]; } - // Comparator implementation. + //! Comparator implementation. friend bool operator==(const CPubKey& a, const CPubKey& b) { return a.vch[0] == b.vch[0] && @@ -107,7 +112,7 @@ public: (a.vch[0] == b.vch[0] && memcmp(a.vch, b.vch, a.size()) < 0); } - // Implement serialization, as if this was a byte vector. + //! Implement serialization, as if this was a byte vector. unsigned int GetSerializeSize(int nType, int nVersion) const { return size() + 1; @@ -134,86 +139,92 @@ public: } } - // Get the KeyID of this public key (hash of its serialization) + //! Get the KeyID of this public key (hash of its serialization) CKeyID GetID() const { return CKeyID(Hash160(vch, vch + size())); } - // Get the 256-bit hash of this public key. + //! Get the 256-bit hash of this public key. uint256 GetHash() const { return Hash(vch, vch + size()); } - // Check syntactic correctness. - // - // Note that this is consensus critical as CheckSig() calls it! + /* + * Check syntactic correctness. + * + * Note that this is consensus critical as CheckSig() calls it! + */ bool IsValid() const { return size() > 0; } - // fully validate whether this is a valid public key (more expensive than IsValid()) + //! fully validate whether this is a valid public key (more expensive than IsValid()) bool IsFullyValid() const; - // Check whether this is a compressed public key. + //! Check whether this is a compressed public key. bool IsCompressed() const { return size() == 33; } - // Verify a DER signature (~72 bytes). - // If this public key is not fully valid, the return value will be false. + /** + * Verify a DER signature (~72 bytes). + * If this public key is not fully valid, the return value will be false. + */ bool Verify(const uint256& hash, const std::vector& vchSig) const; - // Recover a public key from a compact signature. + //! Recover a public key from a compact signature. bool RecoverCompact(const uint256& hash, const std::vector& vchSig); - // Turn this public key into an uncompressed public key. + //! Turn this public key into an uncompressed public key. bool Decompress(); - // Derive BIP32 child pubkey. + //! Derive BIP32 child pubkey. bool Derive(CPubKey& pubkeyChild, unsigned char ccChild[32], unsigned int nChild, const unsigned char cc[32]) const; }; -// secure_allocator is defined in allocators.h -// CPrivKey is a serialized private key, with all parameters included (279 bytes) +/** + * secure_allocator is defined in allocators.h + * CPrivKey is a serialized private key, with all parameters included (279 bytes) + */ typedef std::vector > CPrivKey; /** An encapsulated private key. */ class CKey { private: - // Whether this private key is valid. We check for correctness when modifying the key - // data, so fValid should always correspond to the actual state. + //! Whether this private key is valid. We check for correctness when modifying the key + //! data, so fValid should always correspond to the actual state. bool fValid; - // Whether the public key corresponding to this private key is (to be) compressed. + //! Whether the public key corresponding to this private key is (to be) compressed. bool fCompressed; - // The actual byte data + //! The actual byte data unsigned char vch[32]; - // Check whether the 32-byte array pointed to be vch is valid keydata. + //! Check whether the 32-byte array pointed to be vch is valid keydata. bool static Check(const unsigned char* vch); public: - // Construct an invalid private key. + //! Construct an invalid private key. CKey() : fValid(false), fCompressed(false) { LockObject(vch); } - // Copy constructor. This is necessary because of memlocking. + //! Copy constructor. This is necessary because of memlocking. CKey(const CKey& secret) : fValid(secret.fValid), fCompressed(secret.fCompressed) { LockObject(vch); memcpy(vch, secret.vch, sizeof(vch)); } - // Destructor (again necessary because of memlocking). + //! Destructor (again necessary because of memlocking). ~CKey() { UnlockObject(vch); @@ -225,7 +236,7 @@ public: memcmp(&a.vch[0], &b.vch[0], a.size()) == 0; } - // Initialize using begin and end iterators to byte data. + //! Initialize using begin and end iterators to byte data. template void Set(const T pbegin, const T pend, bool fCompressedIn) { @@ -242,48 +253,54 @@ public: } } - // Simple read-only vector-like interface. + //! Simple read-only vector-like interface. unsigned int size() const { return (fValid ? 32 : 0); } const unsigned char* begin() const { return vch; } const unsigned char* end() const { return vch + size(); } - // Check whether this private key is valid. + //! Check whether this private key is valid. bool IsValid() const { return fValid; } - // Check whether the public key corresponding to this private key is (to be) compressed. + //! Check whether the public key corresponding to this private key is (to be) compressed. bool IsCompressed() const { return fCompressed; } - // Initialize from a CPrivKey (serialized OpenSSL private key data). + //! Initialize from a CPrivKey (serialized OpenSSL private key data). bool SetPrivKey(const CPrivKey& vchPrivKey, bool fCompressed); - // Generate a new private key using a cryptographic PRNG. + //! Generate a new private key using a cryptographic PRNG. void MakeNewKey(bool fCompressed); - // Convert the private key to a CPrivKey (serialized OpenSSL private key data). - // This is expensive. + /** + * Convert the private key to a CPrivKey (serialized OpenSSL private key data). + * This is expensive. + */ CPrivKey GetPrivKey() const; - // Compute the public key from a private key. - // This is expensive. + /** + * Compute the public key from a private key. + * This is expensive. + */ CPubKey GetPubKey() const; - // Create a DER-serialized signature. + //! Create a DER-serialized signature. bool Sign(const uint256& hash, std::vector& vchSig, bool lowS = true) const; - // 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, - // add 0x04 for compressed keys. + /** + * 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, + * add 0x04 for compressed keys. + */ bool SignCompact(const uint256& hash, std::vector& vchSig) const; - // Derive BIP32 child key. + //! Derive BIP32 child key. bool Derive(CKey& keyChild, unsigned char ccChild[32], unsigned int nChild, const unsigned char cc[32]) const; - // Load private key and check that public key matches. + //! Load private key and check that public key matches. bool Load(CPrivKey& privkey, CPubKey& vchPubKey, bool fSkipCheck); - // Check whether an element of a signature (r or s) is valid. + //! Check whether an element of a signature (r or s) is valid. static bool CheckSignatureElement(const unsigned char* vch, int len, bool half); };