more doc

Author: sammymu

bytes.go

@@ -1,5 +1,6 @@
 package bip32
 
+// ReverseCopy works in the opposite direction as the built-in copy()
 func ReverseCopy(dst, src []byte) {
 	for i, j := len(dst)-1, len(src)-1; i >= 0 && j >= 0; i, j = i-1, j-1 {
 		dst[i] = src[j]

conf.go

@@ -1,9 +1,5 @@
 package bip32
 
-// masterKey is the master key used along with a random seed used to generate
-// the master node in the hierarchical tree.
-var masterKey = []byte("Bitcoin seed")
-
 // masterHMACKey is the key used along with a random seed used to generate
 // the master key in the hierarchical tree.
 var masterHMACKey = []byte("Bitcoin seed")

constant.go

@@ -18,15 +18,6 @@ const (
 	// MaxSeedBytes is the maximum number of bytes allowed for a seed to
 	// a master node.
 	MaxSeedBytes = 64 // 512 bits
-
-	// serializedKeyLen is the length of a serialized public or private
-	// extended key.  It consists of 4 bytes version, 1 byte depth, 4 bytes
-	// fingerprint, 4 bytes child number, 32 bytes chain code, and 33 bytes
-	// public/private key data.
-	serializedKeyLen = 4 + 1 + 4 + 4 + 32 + 33 // 78 bytes
-
-	// maxUint8 is the max positive integer which can be serialized in a uint8
-	maxUint8 = 1<<8 - 1
 )
 
 // length constants about fields of key serialization
@@ -37,6 +28,10 @@ const (
 	ChildIndexLen  = 4
 	ChainCodeLen   = 32
 	KeyDataLen     = 33
-	KeyLen         = VersionLen + DepthLen + FingerprintLen +
+	// KeyLen is the length of a serialized public or private
+	// extended key.  It consists of 4 bytes version, 1 byte depth, 4 bytes
+	// fingerprint, 4 bytes child number, 32 bytes chain code, and 33 bytes
+	// public/private key data.
+	KeyLen = VersionLen + DepthLen + FingerprintLen +
 		ChildIndexLen + ChainCodeLen + KeyDataLen
 )

doc.go

@@ -1,3 +1,4 @@
+// Copyright (c) 2018 sammy00
 // Copyright (c) 2014 The btcsuite developers
 // Use of this source code is governed by an ISC
 // license that can be found in the LICENSE file.
@@ -12,39 +13,41 @@ The ability to implement hierarchical deterministic wallets depends on the
 ability to create and derive hierarchical deterministic extended keys.
 
 At a high level, this package provides support for those hierarchical
-deterministic extended keys by providing an ExtendedKey type and supporting
-functions.  Each extended key can either be a private or public extended key
-which itself is capable of deriving a child extended key.
+deterministic extended keys specified as the ExtendedKey interface, which is
+implemented by PrivateKey and PublicKey.Therefore, each extended key can either
+be a private or public extended key which itself is capable of deriving a child
+extended key.
 
 Determining the Extended Key Type
 
-Whether an extended key is a private or public extended key can be determined
-with the IsPrivate function.
+Whether an extended key is a private or public extended key can be type assertion against the PrivateKey type.
 
 Transaction Signing Keys and Payment Addresses
 
 In order to create and sign transactions, or provide others with addresses to
 send funds to, the underlying key and address material must be accessible.  This
-package provides the ECPubKey, ECPrivKey, and Address functions for this
-purpose.
+package provides the ECPubKey, ECPrivKey, and AddressPubKeyHash functions for
+this purpose.
 
 The Master Node
 
 As previously mentioned, the extended keys are hierarchical meaning they are
 used to form a tree.  The root of that tree is called the master node and this
-package provides the NewMaster function to create it from a cryptographically
-random seed.  The GenerateSeed function is provided as a convenient way to
-create a random seed for use with the NewMaster function.
+package provides the NewMasterKey function to create it from a cryptographically
+random seed.  The GenerateMasterKey function is provided as a convenient way to
+create a random extended private key for use where the seed would be read from
+the provided rand entropy reader.
 
 Deriving Children
 
 Once you have created a tree root (or have deserialized an extended key as
 discussed later), the child extended keys can be derived by using the Child
 function.  The Child function supports deriving both normal (non-hardened) and
 hardened child extended keys.  In order to derive a hardened extended key, use
-the HardenedKeyStart constant + the hardened key number as the index to the
-Child function.  This provides the ability to cascade the keys into a tree and
-hence generate the hierarchical deterministic key chains.
+the mapping function HardenIndex(i) to get the corresponding index for
+generating harden child to the Child function.  This provides the ability to
+cascade the keys into a tree and hence generate the hierarchical deterministic
+key chains.
 
 Normal vs Hardened Child Extended Keys
 
@@ -69,8 +72,8 @@ public extended keys.
 Serializing and Deserializing Extended Keys
 
 Extended keys are serialized and deserialized with the String and
-NewKeyFromString functions.  The serialized key is a Base58-encoded string which
-looks like the following:
+ParsePrivateKey/ParsePublicKey functions. The serialized key is a
+Base58-encoded string which looks like the following:
 	public key:   xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw
 	private key:  xprv9uHRZZhk6KAJC1avXpDAp4MDc3sQKNxDiPvvkX8Br5ngLNv1TxvUxt4cV1rGL5hj6KCesnDYUhd7oWgT11eZG7XnxHrnYeSvkzY7d2bhkJ7
 

errors.go

@@ -16,11 +16,6 @@ var (
 	ErrDeriveBeyondMaxDepth = errors.New("cannot derive a key with more than " +
 		"255 indices in its path")
 
-	// ErrNotPrivExtKey describes an error in which the caller attempted
-	// to extract a private key from a public extended key.
-	ErrNotPrivExtKey = errors.New("unable to create private keys from a " +
-		"public extended key")
-
 	// ErrInvalidChild describes an error in which the child at a specific
 	// index is invalid due to the derived key falling outside of the valid
 	// range for secp256k1 private keys.  This error indicates the caller
@@ -48,5 +43,6 @@ var (
 	ErrInvalidKeyLen = errors.New("the provided serialized extended key " +
 		"length is invalid")
 
+	// ErrNoEnoughEntropy signals more entropy is needed
 	ErrNoEnoughEntropy = errors.New("more entropy is needed")
 )

extended_key.go

@@ -2,15 +2,68 @@ package bip32
 
 import "github.com/btcsuite/btcd/btcec"
 
+// ExtendedKey specifies the basic api for a extended private or public key.
+// TODO: add the Zero method manually clears all fields and bytes in the
+// extended key. This can be used to explicitly clear key material from memory
+// for enhanced security against memory scraping. This function only clears
+// this particular key and not any children that have already been derived.
 type ExtendedKey interface {
+	// AddressPubKeyHash returns the public key hash (20 bytes) derived from the
+	// key, which would be itself for public keys and the extended public key
+	// bound to it for private keys
 	AddressPubKeyHash() []byte
+	// Child returns a derived child extended key at the given index.  When this
+	// extended key is a private extended key (as determined by the IsPrivate
+	// function), a private extended key will be derived.  Otherwise, the derived
+	// extended key will be also be a public extended key.
+	//
+	// When the index is greater to or equal than the HardenedKeyStart constant,
+	// the derived extended key will be a hardened extended key.  It is only
+	// possible to derive a hardended extended key from a private extended key.
+	// Consequently, this function will return ErrDeriveHardFromPublic if a
+	// hardened child extended key is requested from a public extended key.
+	//
+	// A hardened extended key is useful since, as previously mentioned, it
+	// requires a parent private extended key to derive. In other words, normal
+	// child extended public keys can be derived from a parent public extended
+	// key (no knowledge of the parent private key) whereas hardened extended
+	// keys may not be.
+	//
+	// NOTE: There is an extremely small chance (< 1 in 2^127) the specific child
+	// index does not derive to a usable child.  The ErrInvalidChild error should
+	// be returned if this should occur, and the caller is expected to ignore the
+	// invalid child and simply increment to the next index.
 	Child(i uint32) (ExtendedKey, error)
+	// Depth returns the current derivation level with respect to the root.
+	//
+	// The root key has depth zero, and the field has a maximum of 255 due to
+	// how depth is serialized.
 	Depth() uint8
+	// Hardened tells if the key of interest is hardened, whose index is greater
+	// than HardenedKeyStart.
 	Hardened() bool
+	// Index returns the index of the key seen from its parent.
 	Index() uint32
+	// IsForNet checks if this key is in use for a given net specified by keyID
 	IsForNet(keyID Magic) bool
+
+	// Neuter returns a new extended public key from a extended private key. The
+	// same extended key will be returned unaltered if it is already an extended
+	// public key.
+	//
+	// As the name implies, an extended public key does not have access to the
+	// private key, so it is not capable of signing transactions or deriving
+	// child extended private keys.  However, it is capable of deriving further
+	// child extended public keys.
+	Neuter() (*PublicKey, error)
+	// ParentFingerprint returns a fingerprint of the parent extended key from
+	// which this one was derived.
 	ParentFingerprint() uint32
+	// Public converts the extended key to a btcec public key and returns it.
 	Public() (*btcec.PublicKey, error)
+	// SetNet associates the extended key, and any child keys yet to be derived
+	// from it, with the passed network.
 	SetNet(keyID Magic)
+	// String returns the extended key as a human-readable base58-encoded string.
 	String() string
 }

golden.go

@@ -1,4 +1,7 @@
 // +build ignore
+// Package main is a utility to format the test vectors provided in
+// https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#test-vectors
+// into the golden file for testing.
 
 package main
 

goldie_test.go

@@ -8,8 +8,7 @@ import (
 )
 
 type childGoldie struct {
-	parent string
-	//index      uint32
+	parent     string
 	ChildIndex *bip32.ChildIndex
 	child      string // the expected child string
 }

internal.go

@@ -7,6 +7,9 @@ import (
 	"github.com/sammy00/base58"
 )
 
+// appendMeta serialize the meta part of the given public key
+// into bytes sequence and then append them to the buf, the address
+// of which will be return.
 func appendMeta(buf []byte, pub *PublicKey) []byte {
 	var childIndex [ChildIndexLen]byte
 	binary.BigEndian.PutUint32(childIndex[:], pub.ChildIndex)
@@ -69,6 +72,8 @@ func decodePublicKey(data58 string) (*PublicKey, error) {
 	return pub, nil
 }
 
+// derivePublicKey calculates the public key corresponding to the input
+// private key, and output the public key data in compressed form.
 func derivePublicKey(priv []byte) []byte {
 	// load the public key data eagerly
 	x, y := secp256k1Curve.ScalarBaseMult(priv)

magics.go

@@ -1,10 +1,14 @@
 package bip32
 
+// MagicLen is the length of magic bytes for generating human-readble prefix
+// of the base58-encoded key
 const MagicLen = 4
 
+// Magic represents the buffer to hold the magic bytes.
 type Magic [MagicLen]byte
 
-// magic bytes as version prefix for serialization
+// magic bytes as version prefix for serialization, and their application goes
+// as named.
 var (
 	MainNetPrivateKey = &Magic{0x04, 0x88, 0xad, 0xe4} // starts with xprv
 	MainNetPublicKey  = &Magic{0x04, 0x88, 0xb2, 0x1e} // starts with xpub

master_key.go

@@ -6,6 +6,10 @@ import (
 	"io"
 )
 
+// GenerateMasterKey is a more convinient implemenation w.r.t to
+// NewMasterKey. The seed needed is read from the given entropy source
+// rand, and the seed length is optional which would be RecommendedSeedLen
+// if omitted.
 func GenerateMasterKey(rand io.Reader, keyID Magic,
 	strength ...int) (*PrivateKey, error) {
 	seedLen := RecommendedSeedLen
@@ -43,45 +47,14 @@ func GenerateMasterKey(rand io.Reader, keyID Magic,
 	return newMaster(seed, keyID)
 }
 
-/*
-// NewMaster creates a new master node for use in creating a hierarchical
+// NewMasterKey creates a new master node for use in creating a hierarchical
 // deterministic key chain.  The seed must be between 128 and 512 bits and
 // should be generated by a cryptographically secure random generation source.
 //
 // NOTE: There is an extremely small chance (< 1 in 2^127) the provided seed
 // will derive to an unusable secret key.  The ErrUnusable error will be
 // returned if this should occur, so the caller must check for it and generate a
 // new seed accordingly.
-func NewMaster(seed []byte, net *chaincfg.Params) (*ExtendedKey, error) {
-	// Per [BIP32], the seed must be in range [MinSeedBytes, MaxSeedBytes].
-	if len(seed) < MinSeedBytes || len(seed) > MaxSeedBytes {
-		return nil, ErrInvalidSeedLen
-	}
-
-	// First take the HMAC-SHA512 of the master key and the seed data:
-	//   I = HMAC-SHA512(Key = "Bitcoin seed", Data = S)
-	hmac512 := hmac.New(sha512.New, masterKey)
-	hmac512.Write(seed)
-	lr := hmac512.Sum(nil)
-
-	// Split "I" into two 32-byte sequences Il and Ir where:
-	//   Il = master secret key
-	//   Ir = master chain code
-	secretKey := lr[:len(lr)/2]
-	chainCode := lr[len(lr)/2:]
-
-	// Ensure the key in usable.
-	secretKeyNum := new(big.Int).SetBytes(secretKey)
-	if secretKeyNum.Cmp(btcec.S256().N) >= 0 || secretKeyNum.Sign() == 0 {
-		return nil, ErrUnusableSeed
-	}
-
-	parentFP := []byte{0x00, 0x00, 0x00, 0x00}
-	return NewExtendedKey(net.HDPrivateKeyID[:], secretKey, chainCode,
-		parentFP, 0, 0, true), nil
-}
-*/
-
 func NewMasterKey(seed []byte, keyID Magic) (*PrivateKey, error) {
 	// Per [BIP32], the seed must be in range [MinSeedBytes, MaxSeedBytes].
 	if len(seed) < MinSeedBytes || len(seed) > MaxSeedBytes {
@@ -91,24 +64,22 @@ func NewMasterKey(seed []byte, keyID Magic) (*PrivateKey, error) {
 	return newMaster(seed, keyID)
 }
 
+// newMaster is helper function to derives a extended private key based on the
+// given valid seed and the provided keyID
 func newMaster(seed []byte, keyID Magic) (*PrivateKey, error) {
 	// I = HMAC-SHA512(Key = "Bitcoin seed", Data = S)
-	hmac512 := hmac.New(sha512.New, masterKey)
+	hmac512 := hmac.New(sha512.New, masterHMACKey)
 	hmac512.Write(seed)
 	I := hmac512.Sum(nil)
 
 	secretKey, chainCode := I[:len(I)/2], I[len(I)/2:]
 	// Ensure the key in usable.
 	if _, ok := ToUsableScalar(secretKey); !ok {
-		//if !ScalarUsable(secretKey) {
 		return nil, ErrUnusableSeed
 	}
 
 	// fingerprint of parent
 	parentFP := []byte{0x00, 0x00, 0x00, 0x00}
 
-	//return NewExtendedKey(keyID[:], secretKey, chainCode,
-	//	parentFP, 0, 0, true), nil
-
 	return NewPrivateKey(keyID[:], 0, parentFP, 0, chainCode, secretKey), nil
 }