key

Documentation

Index

• Constants
• Variables
• func GenerateSeed(length uint8) ([]byte, error)
• type ExtendedKey
  • func FromOldSerialization(key string) (*ExtendedKey, error)
  • func FromSignatureKey(key signature.Key) (ek *ExtendedKey, err error)
  • func NewExtendedKey(key, chainCode, parentFP []byte, depth uint8, childNum uint32, isPrivate bool) *ExtendedKey
  • func NewMaster(seed []byte) (*ExtendedKey, error)
  • func (k ExtendedKey) AsSignatureKey() (signature.Key, error)
  • func (k *ExtendedKey) Bytes() []byte
  • func (k *ExtendedKey) Child(i uint32) (*ExtendedKey, error)
  • func (k *ExtendedKey) Depth() uint8
  • func (k *ExtendedKey) DeriveFrom(parentPath, childPath string) (*ExtendedKey, error)
  • func (k *ExtendedKey) ECPrivKey() (*btcec.PrivateKey, error)
  • func (k *ExtendedKey) ECPubKey() (*btcec.PublicKey, error)
  • func (k *ExtendedKey) FromSignatureKey(key signature.Key) (err error)
  • func (k *ExtendedKey) HardenedChild(n uint32) (*ExtendedKey, error)
  • func (k *ExtendedKey) IsPrivate() bool
  • func (k ExtendedKey) MarshalText() ([]byte, error)
  • func (k *ExtendedKey) ParentFingerprint() uint32
  • func (k *ExtendedKey) PubKeyBytes() []byte
  • func (k *ExtendedKey) Public() (*ExtendedKey, error)
  • func (k *ExtendedKey) SPrivKey() (*signature.PrivateKey, error)
  • func (k *ExtendedKey) SPubKey() (*signature.PublicKey, error)
  • func (k *ExtendedKey) UnmarshalText(text []byte) (err error)
  • func (k *ExtendedKey) Zero()

Constants

const (
	RecommendedSeedLen = bip32.RecommendedSeedLen
	HardenedKeyStart   = bip32.HardenedKeyStart
	MinSeedBytes       = bip32.MinSeedBytes
	MaxSeedBytes       = bip32.MaxSeedBytes
)

bip32 constants are described in bip32 documentation

Variables

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 = bip32.ErrUnusableSeed

	// ErrInvalidSeedLen describes an error in which the provided seed or
	// seed length is not in the allowed range.
	ErrInvalidSeedLen = bip32.ErrInvalidSeedLen

	// 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")

	// ErrUnknownHDKeyID describes an error where the provided id which
	// is intended to identify the network for a hierarchical deterministic
	// private extended key is not registered.
	ErrUnknownHDKeyID = errors.New("unknown hd private extended key bytes")

	// ErrInvalidKeyEncoding describes an error where the provided key
	// is not properly formatted in base32 encoding
	ErrInvalidKeyEncoding = errors.New("invalid key encoding")

	// NdauPrivateKeyID is the special prefix we use for ndau private keys
	NdauPrivateKeyID = [3]byte{99, 103, 31} // npvt
	// NdauPublicKeyID is another special prefix
	NdauPublicKeyID = [3]byte{99, 100, 16} // npub
	// TestPrivateKeyID is another special prefix
	TestPrivateKeyID = [3]byte{139, 103, 31} // tpvt
	// TestPublicKeyID is another special prefix
	TestPublicKeyID = [3]byte{139, 100, 16} // tpub
)

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 FromOldSerialization

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

FromOldSerialization attempts to produce an ExtendedKey from the old (pre-october-2018) format.

If successful, it produces an ExtendedKey object whose MarshalText method will produce the new serialization.

func FromSignatureKey

func FromSignatureKey(key signature.Key) (ek *ExtendedKey, err error)

FromSignatureKey attempts to construct an ExtendedKey from a signature.Key instance

func NewExtendedKey

func NewExtendedKey(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 by used by applications that need to create custom ExtendedKeys. All other applications should just use NewMaster, Child, or Public.

func NewMaster

func NewMaster(seed []byte) (*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.

func (ExtendedKey) AsSignatureKey

func (k ExtendedKey) AsSignatureKey() (signature.Key, error)

AsSignatureKey converts this ExtendedKey into a signature.Key instance

func (*ExtendedKey) Bytes

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

Bytes returns the bytes of the key

func (*ExtendedKey) Child

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

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

func (k *ExtendedKey) DeriveFrom(parentPath, childPath string) (*ExtendedKey, error)

DeriveFrom accepts a parent key and its known path, plus a desired child path and derives the child key from the parent according to the path info.

Note that the parent's known path is simply believed -- we have no mechanism to check that it's true.

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

func (k *ExtendedKey) FromSignatureKey(key signature.Key) (err error)

FromSignatureKey attempts to construct an ExtendedKey from a signature.Key instance

func (*ExtendedKey) HardenedChild

func (k *ExtendedKey) HardenedChild(n uint32) (*ExtendedKey, error)

HardenedChild returns the n'th hardened child of the given extended key.

The parent key must be a private key. A HardenedChild is guaranteed to have been derived from a private key. It is an error if the given key is already a hardened key.

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

func (k ExtendedKey) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler

func (*ExtendedKey) ParentFingerprint

func (k *ExtendedKey) ParentFingerprint() uint32

ParentFingerprint returns a fingerprint of the parent extended key from which this one was derived. Since the fingerprint is 3 bytes, we set the high byte to 0 before returning it as a uint32

func (*ExtendedKey) PubKeyBytes

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

PubKeyBytes returns bytes for the serialized compressed public key associated with this extended key in an efficient manner including memoization as necessary.

When the extended key is already a public key, the key is simply returned as is since it's already in the correct form. However, when the extended key is a private key, the public key will be calculated and memoized so future accesses can simply return the cached result.

func (*ExtendedKey) Public

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

Public 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) SPrivKey

func (k *ExtendedKey) SPrivKey() (*signature.PrivateKey, error)

SPrivKey converts the extended key to a signature.PrivateKey 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) SPubKey

func (k *ExtendedKey) SPubKey() (*signature.PublicKey, error)

SPubKey converts the extended key to a signature.PublicKey and returns it.

func (*ExtendedKey) UnmarshalText

func (k *ExtendedKey) UnmarshalText(text []byte) (err error)

UnmarshalText implements encoding.TextUnmarshaler

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.