keychain

Documentation

Index

• Constants
• Variables
• type ExtendedKey
  • func NewKeyFromString(key string) (*ExtendedKey, error)
  • func NewMaster(seed []byte, cryptography uint8) (*ExtendedKey, error)
  • func (k *ExtendedKey) Address() (string, error)
  • func (k *ExtendedKey) Child(i uint32) (*ExtendedKey, error)
  • func (k *ExtendedKey) CorrespondingPrivateChild(childPublicKey *ExtendedKey) (*ExtendedKey, error)
  • func (k *ExtendedKey) ECPrivateKey() (*ecdsa.PrivateKey, error)
  • func (k *ExtendedKey) ECPublicKey() (*ecdsa.PublicKey, error)
  • func (k *ExtendedKey) Neuter() (*ExtendedKey, error)
  • func (k *ExtendedKey) ToString() string

Constants

const (
	// HardenedKeyStart is the index at which a hardended key starts.
	// Each extended key has 2^31 normal child keys, and 2^31 hardned child keys.
	// Each of these child keys has an index.
	// The range for normal child keys is [0, 2^31 - 1]
	// The range for hardened child keys is [2^31, 2^32 - 1].
	HardenedKeyStart = 0x80000000 // 2^31 -- 16进制

	// maxUint8 is the max positive integer which can be serialized in a uint8
	MaxUint8 = 1<<8 - 1

	PubKeyBytesLenUncompressed = 65
)

Hierarchical Deterministic Wallets - child drivation function 相关常量定义 Reference - https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki

Variables

var (
	// BIP32 hierarchical deterministic extended key magics
	// (i.e. for BTC, mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
	HDPrivateKeyID = []byte{0x04, 0x20, 0xb9, 0x00} // starts with sprv
	HDPublicKeyID  = []byte{0x04, 0x20, 0xbd, 0x3a} // starts with spub

	// Prefix used when derive the hardened child private key.
	// I = HMAC-SHA512(Key = cpar, Data = 0x00 || ser256(kpar) || ser32(i)).
	// Note: The 0x00 pads the private key to make it 33 bytes long.
	PrefixDeriveHardenedPrivateKey = []byte{0x00}

	// masterKey is the master key used along with a random seed used to
	// generate the master node in the hierarchical tree.
	MasterKey = []byte("XuperCrypto seed")
)

var (
	// The caller should simply ignore the invalid index for generateing a child extended key at this time.
	// Just move to the next index. (increase the old index by 1)
	ErrInvalidIndexForGenerateChildKey = errors.New("this index is invalid for generating a child key.")

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

	// Seed length must between 128 and 512 bits. Which means between 16 and 64 bytes.
	ErrInvalidSeedLength = errors.New("invalid seed length, must between 128 and 512 bits")

	// 密码学算法暂未被支持
	// Cryptography required for generating Mnemonic has not been supported yet.
	ErrCryptographyNotSupported = fmt.Errorf("this cryptography has not been supported yet.")

	// A hardened child extended key cannot be derived from a public extended key.
	ErrDeriveHardenKeyFromPublicKey = errors.New("cannot derive a hardened child extended key from a public extended key")

	// Cannot derive a key with more than 255 depth from a root key.
	ErrDeriveBeyondMaxDepth = errors.New("cannot derive a key with more than 255 depth in its path from a root key")

	// Cannot create a private ecdsa key from a public extended key.
	ErrNotPrivExtKey = errors.New("cannot to create a private ecdsa key from a public extended key")

	// The checksum contained in the 58-encoded string(a serialized extended key) is not right.
	ErrWrongChecksum = errors.New("wrong extended key checksum")

	// The pubKeyStr contained in the extended key is not right.
	ErrWrongPubKeyStr = errors.New("wrong PubKeyStr")

	// Wrong param for deriving corresponding private child key from child public key.
	ErrWrongParamForDerivingPrivateChildKey = errors.New("wrong param when trying to derive child private key from child public key.")
)

错误相关定义

Types

type ExtendedKey

type ExtendedKey struct {
	Version   []byte // version bytes (i.e. for BTC, mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
	Depth     uint8  // depth: 0x00 for master nodes, 0x01 for level-1 derived keys, ....
	ParentFP  []byte // the fingerprint of the parent's key (0x00000000 if master key)
	ChildNum  uint32 // child number. This is ser32(i) for i in xi = xpar/i, with xi the key being serialized. (0x00000000 if master key)
	ChainCode []byte // the chain code
	Key       []byte // the public key or private key data (serP(K) for public keys, 0x00 || ser256(k) for private keys)
	PubKey    []byte // this will only be set for extended priv keys

	AccountNum map[uint8]uint32 // shows the bloodline of this key

	Cryptography uint8 // the cryptography type: 1 for Nist P-256, 2 for Gm SM-2, ...

	IsPrivate bool // Whether an extended key is a private or public extended key can be determined with the isPrivate
}

ExtendedKey has all the information needed to support a hierarchical deterministic extended key. <key format> Extended public and private keys have follow contents: 4 byte: version bytes (i.e. for BTC, mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private) 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 derived keys, .... 4 bytes: the fingerprint of the parent's key (0x00000000 if master key) 4 bytes: child number. This is ser32(i) for i in xi = xpar/i, with xi the key being serialized. (0x00000000 if master key) 32 bytes: the chain code 33 bytes: the public key or private key data (serP(K) for public keys, 0x00 || ser256(k) for private keys)

func NewKeyFromString

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

Retrieve an extended key from a base58-encoded String.

func NewMaster

func NewMaster(seed []byte, cryptography uint8) (*ExtendedKey, error)

NewMaster creates a new master node. The seed must be between 128 and 512 bits and should be generated by a cryptographically secure random generation source.

NOTE: Here rand.GenerateSeedWithStrengthAndKeyLen(strength int, keyLength int) ([]byte, error) should be used to generate the seed.

NOTE: There is an extremely small chance (< 1 in 2^127) the provided seed will derive to an unusable secret key. The ErrUnusableSeed error will be returned if this happens. The caller must check the error and generate a new seed if necessary.

BIP32: Master key generation: 1. Generate a seed byte sequence S of a chosen length (between 128 and 512 bits; 256 bits is advised) from a (P)RNG. 2. Calculate I = HMAC-SHA512(Key = "Bitcoin seed", Data = S) 3. Split I into two 32-byte sequences, IL and IR. 4. Use parse256(IL) as master secret key, and IR as master chain code.

func (*ExtendedKey) Address

func (k *ExtendedKey) Address() (string, error)

Return the address of an extended Key.

func (*ExtendedKey) Child

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

Child key derivation (CKD) functions This function returns a derived child extended key at the given index. A new private extended key will be derived from a private extended key. And a new public extended key will be derived from a public extended key.

When the index is between [0, 2^31 - 1], normal child extended keys will be derived. When the index is between [2^31, 2^32 - 1], hardended child extended keys will be derived.

A hardended extended key can only be derived from a private extended key.

NOTE: There is an extremely small chance (< 1 in 2^127) the specific child index faild to derive a valid 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.

Given a parent extended key and an index i, it is possible to compute the corresponding child extended key. The algorithm to do so depends on whether the child is a hardened key or not (or, equivalently, whether i ≥ 2^31), and whether we're talking about private or public keys.

1. Private parent key → private child key. 2. Public parent key → public child key. Note: It is only defined for non-hardened child keys. i.e. i < HardenedKeyStart. 3. Private parent key → public child key. Use Neuter func instead. No need to consider in this func. 4. Public parent key → private child key. Note: This is impossible! No need to consider in this func.

func (*ExtendedKey) CorrespondingPrivateChild

func (k *ExtendedKey) CorrespondingPrivateChild(childPublicKey *ExtendedKey) (*ExtendedKey, error)

Derive corresponding(the same depth and childNum) private child key from child public key

func (*ExtendedKey) ECPrivateKey

func (k *ExtendedKey) ECPrivateKey() (*ecdsa.PrivateKey, error)

ECPrivateKey converts the extended key to a ecdsa private key and returns it. This is only possible if the extended key is a private extended key.

func (*ExtendedKey) ECPublicKey

func (k *ExtendedKey) ECPublicKey() (*ecdsa.PublicKey, error)

ECPublicKey converts the extended key to a ecdsa public key and returns it.

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) ToString

func (k *ExtendedKey) ToString() string

Convert an extended key to a base58-encoded String.