hdkeychain

package
v1.1.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 15, 2024 License: ISC Imports: 13 Imported by: 284

README

hdkeychain

Build Status ISC License GoDoc

Package hdkeychain provides an API for bitcoin hierarchical deterministic extended keys (BIP0032).

A comprehensive suite of tests is provided to ensure proper functionality. See test_coverage.txt for the gocov coverage report. Alternatively, if you are running a POSIX OS, you can run the cov_report.sh script for a real-time report.

Feature Overview

  • Full BIP0032 implementation
  • Single type for private and public extended keys
  • Convenient cryptographically secure seed generation
  • Simple creation of master nodes
  • Support for multi-layer derivation
  • Easy serialization and deserialization for both private and public extended keys
  • Support for custom networks by registering them with chaincfg
  • Obtaining the underlying EC pubkeys, EC privkeys, and associated bitcoin addresses ties in seamlessly with existing btcec and btcutil types which provide powerful tools for working with them to do things like sign transactions and generate payment scripts
  • Uses the btcec package which is highly optimized for secp256k1
  • Code examples including:
    • Generating a cryptographically secure random seed and deriving a master node from it
    • Default HD wallet layout as described by BIP0032
    • Audits use case as described by BIP0032
  • Comprehensive test coverage including the BIP0032 test vectors
  • Benchmarks

Installation and Updating

$ go get -u github.com/btcsuite/btcd/btcutil/hdkeychain

Examples

License

Package hdkeychain is licensed under the copyfree ISC License.

Documentation

Overview

Package hdkeychain provides an API for bitcoin hierarchical deterministic extended keys (BIP0032).

Overview

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.

Determining the Extended Key Type

Whether an extended key is a private or public extended key can be determined with the IsPrivate function.

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.

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.

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 Derive function. The Derive 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 Derive function. This provides the ability to cascade the keys into a tree and hence generate the hierarchical deterministic key chains.

Normal vs Hardened Derived Extended Keys

A private extended key can be used to derive both hardened and non-hardened (normal) child private and public extended keys. A public extended key can only be used to derive non-hardened child public extended keys. As enumerated in BIP0032 "knowledge of the extended public key plus any non-hardened private key descending from it is equivalent to knowing the extended private key (and thus every private and public key descending from it). This means that extended public keys must be treated more carefully than regular public keys. It is also the reason for the existence of hardened keys, and why they are used for the account level in the tree. This way, a leak of an account-specific (or below) private key never risks compromising the master or other accounts."

Neutering a Private Extended Key

A private extended key can be converted to a new instance of the corresponding public extended key with the Neuter function. The original extended key is not modified. A public extended key is still capable of deriving non-hardened child 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: 

public key:   xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw
private key:  xprv9uHRZZhk6KAJC1avXpDAp4MDc3sQKNxDiPvvkX8Br5ngLNv1TxvUxt4cV1rGL5hj6KCesnDYUhd7oWgT11eZG7XnxHrnYeSvkzY7d2bhkJ7

Network

Extended keys are much like normal Bitcoin addresses in that they have version bytes which tie them to a specific network. The SetNet and IsForNet functions are provided to set and determinine which network an extended key is associated with.

Example (Audits)

This example demonstrates the audits use case in BIP0032. 

package main

import (
	"fmt"

	"github.com/btcsuite/btcd/btcutil/hdkeychain"
)

func main() {
	// The audits use case described in BIP0032 is:
	//
	// In case an auditor needs full access to the list of incoming and
	// outgoing payments, one can share all account public extended keys.
	// This will allow the auditor to see all transactions from and to the
	// wallet, in all accounts, but not a single secret key.
	//
	//   * N(m/*)
	//   corresponds to the neutered master extended key (also called
	//   the master public extended key)

	// Ordinarily this would either be read from some encrypted source
	// and be decrypted or generated as the NewMaster example shows, but
	// for the purposes of this example, the private extended key for the
	// master node is being hard coded here.
	master := "xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jP" +
		"PqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi"

	// Start by getting an extended key instance for the master node.
	// This gives the path:
	//   m
	masterKey, err := hdkeychain.NewKeyFromString(master)
	if err != nil {
		fmt.Println(err)
		return
	}

	// Neuter the master key to generate a master public extended key.  This
	// gives the path:
	//   N(m/*)
	masterPubKey, err := masterKey.Neuter()
	if err != nil {
		fmt.Println(err)
		return
	}

	// Share the master public extended key with the auditor.
	fmt.Println("Audit key N(m/*):", masterPubKey)

}

Output:

Audit key N(m/*): xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8
Example (DefaultWalletLayout)

This example demonstrates the default hierarchical deterministic wallet layout as described in BIP0032. 

package main

import (
	"fmt"

	"github.com/btcsuite/btcd/btcutil/hdkeychain"
	"github.com/btcsuite/btcd/chaincfg"
)

func main() {
	// The default wallet layout described in BIP0032 is:
	//
	// Each account is composed of two keypair chains: an internal and an
	// external one. The external keychain is used to generate new public
	// addresses, while the internal keychain is used for all other
	// operations (change addresses, generation addresses, ..., anything
	// that doesn't need to be communicated).
	//
	//   * m/iH/0/k
	//     corresponds to the k'th keypair of the external chain of account
	//     number i of the HDW derived from master m.
	//   * m/iH/1/k
	//     corresponds to the k'th keypair of the internal chain of account
	//     number i of the HDW derived from master m.

	// Ordinarily this would either be read from some encrypted source
	// and be decrypted or generated as the NewMaster example shows, but
	// for the purposes of this example, the private extended key for the
	// master node is being hard coded here.
	master := "xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jP" +
		"PqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi"

	// Start by getting an extended key instance for the master node.
	// This gives the path:
	//   m
	masterKey, err := hdkeychain.NewKeyFromString(master)
	if err != nil {
		fmt.Println(err)
		return
	}

	// Derive the extended key for account 0.  This gives the path:
	//   m/0H
	acct0, err := masterKey.Derive(hdkeychain.HardenedKeyStart + 0)
	if err != nil {
		fmt.Println(err)
		return
	}

	// Derive the extended key for the account 0 external chain.  This
	// gives the path:
	//   m/0H/0
	acct0Ext, err := acct0.Derive(0)
	if err != nil {
		fmt.Println(err)
		return
	}

	// Derive the extended key for the account 0 internal chain.  This gives
	// the path:
	//   m/0H/1
	acct0Int, err := acct0.Derive(1)
	if err != nil {
		fmt.Println(err)
		return
	}

	// At this point, acct0Ext and acct0Int are ready to derive the keys for
	// the external and internal wallet chains.

	// Derive the 10th extended key for the account 0 external chain.  This
	// gives the path:
	//   m/0H/0/10
	acct0Ext10, err := acct0Ext.Derive(10)
	if err != nil {
		fmt.Println(err)
		return
	}

	// Derive the 1st extended key for the account 0 internal chain.  This
	// gives the path:
	//   m/0H/1/0
	acct0Int0, err := acct0Int.Derive(0)
	if err != nil {
		fmt.Println(err)
		return
	}

	// Get and show the address associated with the extended keys for the
	// main bitcoin	network.
	acct0ExtAddr, err := acct0Ext10.Address(&chaincfg.MainNetParams)
	if err != nil {
		fmt.Println(err)
		return
	}
	acct0IntAddr, err := acct0Int0.Address(&chaincfg.MainNetParams)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println("Account 0 External Address 10:", acct0ExtAddr)
	fmt.Println("Account 0 Internal Address 0:", acct0IntAddr)

}

Output:

Account 0 External Address 10: 1HVccubUT8iKTapMJ5AnNA4sLRN27xzQ4F
Account 0 Internal Address 0: 1J5rebbkQaunJTUoNVREDbeB49DqMNFFXk

Index

Examples

Constants

View Source 
const (
	// RecommendedSeedLen is the recommended length in bytes for a seed
	// to a master node.
	RecommendedSeedLen = 32 // 256 bits

	// HardenedKeyStart is the index at which a hardened key starts.  Each
	// extended key has 2^31 normal child keys and 2^31 hardened child keys.
	// Thus the range for normal child keys is [0, 2^31 - 1] and the range
	// for hardened child keys is [2^31, 2^32 - 1].
	HardenedKeyStart = 0x80000000 // 2^31

	// MinSeedBytes is the minimum number of bytes allowed for a seed to
	// a master node.
	MinSeedBytes = 16 // 128 bits

	// MaxSeedBytes is the maximum number of bytes allowed for a seed to
	// a master node.
	MaxSeedBytes = 64 // 512 bits

)

Variables

View Source 
var (
	// ErrDeriveHardFromPublic describes an error in which the caller
	// attempted to derive a hardened extended key from a public key.
	ErrDeriveHardFromPublic = errors.New("cannot derive a hardened key " +
		"from a public key")

	// ErrDeriveBeyondMaxDepth describes an error in which the caller
	// has attempted to derive more than 255 keys from a root key.
	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
	// should simply ignore the invalid child extended key at this index and
	// increment to the next index.
	ErrInvalidChild = errors.New("the extended key at this index is invalid")

	// ErrUnusableSeed describes an error in which the provided seed is not
	// usable due to the derived key falling outside of the valid range for
	// secp256k1 private keys.  This error indicates the caller must choose
	// another seed.
	ErrUnusableSeed = errors.New("unusable seed")

	// ErrInvalidSeedLen describes an error in which the provided seed or
	// seed length is not in the allowed range.
	ErrInvalidSeedLen = fmt.Errorf("seed length must be between %d and %d "+
		"bits", MinSeedBytes*8, MaxSeedBytes*8)

	// ErrBadChecksum describes an error in which the checksum encoded with
	// a serialized extended key does not match the calculated value.
	ErrBadChecksum = errors.New("bad extended key checksum")

	// ErrInvalidKeyLen describes an error in which the provided serialized
	// key is not the expected length.
	ErrInvalidKeyLen = errors.New("the provided serialized extended key " +
		"length is invalid")
)

Functions

func GenerateSeed 

func GenerateSeed(length uint8) ([]byte, error)

GenerateSeed returns a cryptographically secure random seed that can be used as the input for the NewMaster function to generate a new master node.

The length is in bytes and it must be between 16 and 64 (128 to 512 bits). The recommended length is 32 (256 bits) as defined by the RecommendedSeedLen constant.

Types

type ExtendedKey 

type ExtendedKey struct {
	// contains filtered or unexported fields
}

ExtendedKey houses all the information needed to support a hierarchical deterministic extended key. See the package overview documentation for more details on how to use extended keys.

func NewExtendedKey 

func NewExtendedKey(version, key, chainCode, parentFP []byte, depth uint8,
	childNum uint32, isPrivate bool) *ExtendedKey

NewExtendedKey returns a new instance of an extended key with the given fields. No error checking is performed here as it's only intended to be a convenience method used to create a populated struct. This function should only be used by applications that need to create custom ExtendedKeys. All other applications should just use NewMaster, Derive, or Neuter.

func NewKeyFromString 

func NewKeyFromString(key string) (*ExtendedKey, error)

NewKeyFromString returns a new extended key instance from a base58-encoded extended key.

func NewMaster 

func NewMaster(seed []byte, net *chaincfg.Params) (*ExtendedKey, error)

NewMaster 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.

Example

This example demonstrates how to generate a cryptographically random seed then use it to create a new master node (extended key). 

package main

import (
	"fmt"

	"github.com/btcsuite/btcd/btcutil/hdkeychain"
	"github.com/btcsuite/btcd/chaincfg"
)

func main() {
	// Generate a random seed at the recommended length.
	seed, err := hdkeychain.GenerateSeed(hdkeychain.RecommendedSeedLen)
	if err != nil {
		fmt.Println(err)
		return
	}

	// Generate a new master node using the seed.
	key, err := hdkeychain.NewMaster(seed, &chaincfg.MainNetParams)
	if err != nil {
		fmt.Println(err)
		return
	}

	// Show that the generated master node extended key is private.
	fmt.Println("Private Extended Key?:", key.IsPrivate())

}

Output:

Private Extended Key?: true

func (*ExtendedKey) Address 

func (k *ExtendedKey) Address(net *chaincfg.Params) (*btcutil.AddressPubKeyHash, error)

Address converts the extended key to a standard bitcoin pay-to-pubkey-hash address for the passed network.

func (*ExtendedKey) ChainCode 

func (k *ExtendedKey) ChainCode() []byte

ChainCode returns the chain code part of this extended key.

It is identical for both public and private extended keys.

func (*ExtendedKey) ChildIndex 

func (k *ExtendedKey) ChildIndex() uint32

ChildIndex returns the index at which the child extended key was derived.

Extended keys with ChildNum value between 0 and 2^31-1 are normal child keys, and those with a value between 2^31 and 2^32-1 are hardened keys.

func (*ExtendedKey) CloneWithVersion 

func (k *ExtendedKey) CloneWithVersion(version []byte) (*ExtendedKey, error)

CloneWithVersion returns a new extended key cloned from this extended key, but using the provided HD version bytes. The version must be a private HD key ID for an extended private key, and a public HD key ID for an extended public key.

This method creates a new copy and therefore does not mutate the original extended key instance.

Unlike Neuter(), this does NOT convert an extended private key to an extended public key. It is particularly useful for converting between standard BIP0032 extended keys (serializable to xprv/xpub) and keys based on the SLIP132 standard (serializable to yprv/ypub, zprv/zpub, etc.).

References: 

[SLIP132]: SLIP-0132 - Registered HD version bytes for BIP-0032
https://github.com/satoshilabs/slips/blob/master/slip-0132.md

func (*ExtendedKey) Depth 

func (k *ExtendedKey) Depth() uint8

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.

func (*ExtendedKey) Derive 

func (k *ExtendedKey) Derive(i uint32) (*ExtendedKey, error)

Derive returns a derived child extended key at the given index.

IMPORTANT: if you were previously using the Child method, this method is incompatible. The Child method had a BIP-32 standard compatibility issue. You have to check whether any hardened derivations in your derivation path are affected by this issue, via the IsAffectedByIssue172 method and migrate the wallet if so. This method does conform to the standard. If you need the old behavior, use DeriveNonStandard.

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 hardened 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 will be returned if this should occur, and the caller is expected to ignore the invalid child and simply increment to the next index.

func (*ExtendedKey) DeriveNonStandard deprecated 

func (k *ExtendedKey) DeriveNonStandard(i uint32) (*ExtendedKey, error)

Deprecated: This is a non-standard derivation that is affected by issue #172. 1-of-256 hardened derivations will be wrong. See note in the Derive method and IsAffectedByIssue172.

func (*ExtendedKey) ECPrivKey 

func (k *ExtendedKey) ECPrivKey() (*btcec.PrivateKey, error)

ECPrivKey converts the extended key to a btcec private key and returns it. As you might imagine this is only possible if the extended key is a private extended key (as determined by the IsPrivate function). The ErrNotPrivExtKey error will be returned if this function is called on a public extended key.

func (*ExtendedKey) ECPubKey 

func (k *ExtendedKey) ECPubKey() (*btcec.PublicKey, error)

ECPubKey converts the extended key to a btcec public key and returns it.

func (*ExtendedKey) IsAffectedByIssue172 

func (k *ExtendedKey) IsAffectedByIssue172() bool

Returns true if this key was affected by the BIP-32 issue in the Child method (since renamed to DeriveNonStandard).

func (*ExtendedKey) IsForNet 

func (k *ExtendedKey) IsForNet(net *chaincfg.Params) bool

IsForNet returns whether or not the extended key is associated with the passed bitcoin network.

func (*ExtendedKey) IsPrivate 

func (k *ExtendedKey) IsPrivate() bool

IsPrivate returns whether or not the extended key is a private extended key.

A private extended key can be used to derive both hardened and non-hardened child private and public extended keys. A public extended key can only be used to derive non-hardened child public extended keys.

func (*ExtendedKey) Neuter 

func (k *ExtendedKey) Neuter() (*ExtendedKey, error)

Neuter returns a new extended public key from this 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.

func (*ExtendedKey) ParentFingerprint 

func (k *ExtendedKey) ParentFingerprint() uint32

ParentFingerprint returns a fingerprint of the parent extended key from which this one was derived.

func (*ExtendedKey) SetNet 

func (k *ExtendedKey) SetNet(net *chaincfg.Params)

SetNet associates the extended key, and any child keys yet to be derived from it, with the passed network.

func (*ExtendedKey) String 

func (k *ExtendedKey) String() string

String returns the extended key as a human-readable base58-encoded string.

func (*ExtendedKey) Version 

func (k *ExtendedKey) Version() []byte

Version returns the extended key's hardened derivation version. This can be used to identify the extended key's type.

func (*ExtendedKey) Zero 

func (k *ExtendedKey) Zero()

Zero 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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.