keychain

package
v0.3.0-rc2 Latest Latest
Warning

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

 Go to latest Published: Oct 30, 2020 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// KeyDerivationVersion is the version of the key derivation schema
	// defined below. We use a version as this means that we'll be able to
	// accept new seed in the future and be able to discern if the software
	// is compatible with the version of the seed.
	KeyDerivationVersion = 0

	// BIP0043Purpose is the "purpose" value that we'll use for the first
	// version or our key derivation scheme. All keys are expected to be
	// derived from this purpose, then the particular coin type of the
	// chain where the keys are to be used.  Slightly adhering to BIP0043
	// allows us to not deviate too far from a widely used standard, and
	// also fits into existing implementations of the BIP's template.
	//
	// NOTE: BRICK SQUUUUUAD.
	BIP0043Purpose = 1017
)
View Source 
const (
	// CoinTypeDecred specifies the BIP44 coin type for Decred key
	// derivation.
	CoinTypeDecred uint32 = 42

	// CoinTypeTestnet specifies the BIP44 coin
	// type for all testnet key derivation.
	CoinTypeTestnet = 1
)

Variables

View Source 
var (
	// MaxKeyRangeScan is the maximum number of keys that we'll attempt to
	// scan with if a caller knows the public key, but not the KeyLocator
	// and wishes to derive a private key.
	MaxKeyRangeScan = 100000

	// ErrCannotDerivePrivKey is returned when DerivePrivKey is unable to
	// derive a private key given only the public key and target key
	// family.
	ErrCannotDerivePrivKey = fmt.Errorf("unable to derive private key")
)

Functions

func CheckKeyRingImpl added in v0.2.0 

func CheckKeyRingImpl(t *testing.T, constructor KeyRingConstructor)

CheckKeyRingImpl tests that the provided KeyRing implementation properly adheres to the expected behavior of the set of interfaces.

func CheckSecretKeyRingImpl added in v0.2.0 

func CheckSecretKeyRingImpl(t *testing.T, constructor SecretKeyRingConstructor)

TestSecretKeyRingDerivation tests that each known SecretKeyRing implementation properly adheres to the expected behavior of the set of interface.

func DisableLog 

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.

func UseLogger 

func UseLogger(logger slog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using slog.

Types

type DigestSignerRing added in v0.3.0 

type DigestSignerRing interface {
	// SignDigest signs the given SHA256 message digest with the private key
	// described in the key descriptor.
	SignDigest(keyDesc KeyDescriptor, digest [32]byte) (*ecdsa.Signature,
		error)

	// SignDigestCompact signs the given SHA256 message digest with the
	// private key described in the key descriptor and returns the signature
	// in the compact, public key recoverable format.
	SignDigestCompact(keyDesc KeyDescriptor, digest [32]byte) ([]byte, error)
}

DigestSignerRing is an interface that abstracts away basic low-level ECDSA signing on keys within a key ring.

type ECDHRing added in v0.3.0 

type ECDHRing interface {
	// ECDH performs a scalar multiplication (ECDH-like operation) between
	// the target key descriptor and remote public key. The output
	// returned will be the sha256 of the resulting shared point serialized
	// in compressed format. If k is our private key, and P is the public
	// key, we perform the following operation:
	//
	//  sx := k*P
	//  s := sha256(sx.SerializeCompressed())
	ECDH(keyDesc KeyDescriptor, pubKey *secp256k1.PublicKey) ([32]byte, error)
}

ECDHRing is an interface that abstracts away basic low-level ECDH shared key generation on keys within a key ring.

type HDKeyRing added in v0.2.0 

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

HDKeyRing is an implementation of both the KeyRing and SecretKeyRing interfaces backed by a root master key pair. The master extended public keys (one for each required key family) is maintained in memory at all times, while the extended private key must be produred by a function (specified during struct setup) whenever requested.

func NewHDKeyRing added in v0.2.0 

func NewHDKeyRing(masterPubs map[KeyFamily]*hdkeychain.ExtendedKey,
	fetchMasterPriv func(KeyFamily) (*hdkeychain.ExtendedKey, error),
	nextIndex func(KeyFamily) (uint32, error)) *HDKeyRing

NewHDKeyRing creates a new implementation of the keychain.SecretKeyRing interface backed by a set of extended HD keys.

The passed fetchMasterPriv must be able to return the master private key for the keyring in a timely fashion, otherwise sign operations may be delayed. If this function is not specified, then the KeyRing cannot derive private keys.

The passed nextIndex must be able to return the next (unused) index for each existing KeyFamily used in ln operations. Indication that the index was returned should be persisted in some way, such that public key reuse is minimized and the same index is not returned twice. In other words, calling nextAddrIndex twice should return different values, otherwise key derivation might hang forever.

If either the set of master public keys (one for each family) or the next address index are not provided, the results from trying to use this function are undefined.

func (HDKeyRing) DeriveKey added in v0.2.0 

func (kr HDKeyRing) DeriveKey(keyLoc KeyLocator) (KeyDescriptor, error)

DeriveKey attempts to derive an arbitrary key specified by the passed KeyLocator. This may be used in several recovery scenarios, or when manually rotating something like our current default node key.

NOTE: This is part of the keychain.KeyRing interface.

func (*HDKeyRing) DeriveNextKey added in v0.2.0 

func (kr *HDKeyRing) DeriveNextKey(keyFam KeyFamily) (KeyDescriptor, error)

DeriveNextKey attempts to derive the *next* key within the key family (account in BIP43) specified. This method should return the next external child within this branch.

NOTE: This is part of the keychain.KeyRing interface.

func (*HDKeyRing) DerivePrivKey added in v0.2.0 

func (kr *HDKeyRing) DerivePrivKey(keyDesc KeyDescriptor) (*secp256k1.PrivateKey, error)

DerivePrivKey attempts to derive the private key that corresponds to the passed key descriptor.

NOTE: This is part of the keychain.SecretKeyRing interface.

func (*HDKeyRing) ECDH added in v0.3.0 

func (kr *HDKeyRing) ECDH(keyDesc KeyDescriptor,
	pub *secp256k1.PublicKey) ([32]byte, error)

ECDH performs a scalar multiplication (ECDH-like operation) between the target key descriptor and remote public key. The output returned will be the sha256 of the resulting shared point serialized in compressed format. If k is our private key, and P is the public key, we perform the following operation: 

sx := k*P
 s := sha256(sx.SerializeCompressed())

NOTE: This is part of the keychain.ECDHRing interface.

func (*HDKeyRing) SignDigest added in v0.3.0 

func (kr *HDKeyRing) SignDigest(keyDesc KeyDescriptor,
	digest [32]byte) (*ecdsa.Signature, error)

SignDigest signs the given SHA256 message digest with the private key described in the key descriptor.

NOTE: This is part of the keychain.DigestSignerRing interface.

func (*HDKeyRing) SignDigestCompact added in v0.3.0 

func (kr *HDKeyRing) SignDigestCompact(keyDesc KeyDescriptor,
	digest [32]byte) ([]byte, error)

SignDigestCompact signs the given SHA256 message digest with the private key described in the key descriptor and returns the signature in the compact, public key recoverable format.

NOTE: This is part of the keychain.DigestSignerRing interface.

type KeyDescriptor 

type KeyDescriptor struct {
	// KeyLocator is the internal KeyLocator of the descriptor.
	KeyLocator

	// PubKey is an optional public key that fully describes a target key.
	// If this is nil, the KeyLocator MUST NOT be empty.
	PubKey *secp256k1.PublicKey
}

KeyDescriptor wraps a KeyLocator and also optionally includes a public key. Either the KeyLocator must be non-empty, or the public key pointer be non-nil. This will be used by the KeyRing interface to lookup arbitrary private keys, and also within the SignDescriptor struct to locate precisely which keys should be used for signing.

type KeyFamily 

type KeyFamily uint32

KeyFamily represents a "family" of keys that will be used within various contracts created by lnd. These families are meant to be distinct branches within the HD key chain of the backing wallet. Usage of key families within the interface below are strict in order to promote integrability and the ability to restore all keys given a user master seed backup.

The key derivation in this file follows the following hierarchy based on BIP43:

  • m/1017'/coinType'/keyFamily'/0/index
const (
	// KeyFamilyMultiSig are keys to be used within multi-sig scripts.
	KeyFamilyMultiSig KeyFamily = 0

	// KeyFamilyRevocationBase are keys that are used within channels to
	// create revocation basepoints that the remote party will use to
	// create revocation keys for us.
	KeyFamilyRevocationBase = 1

	// KeyFamilyHtlcBase are keys used within channels that will be
	// combined with per-state randomness to produce public keys that will
	// be used in HTLC scripts.
	KeyFamilyHtlcBase KeyFamily = 2

	// KeyFamilyPaymentBase are keys used within channels that will be
	// combined with per-state randomness to produce public keys that will
	// be used in scripts that pay directly to us without any delay.
	KeyFamilyPaymentBase KeyFamily = 3

	// KeyFamilyDelayBase are keys used within channels that will be
	// combined with per-state randomness to produce public keys that will
	// be used in scripts that pay to us, but require a CSV delay before we
	// can sweep the funds.
	KeyFamilyDelayBase KeyFamily = 4

	// KeyFamilyRevocationRoot is a family of keys which will be used to
	// derive the root of a revocation tree for a particular channel.
	KeyFamilyRevocationRoot KeyFamily = 5

	// KeyFamilyNodeKey is a family of keys that will be used to derive
	// keys that will be advertised on the network to represent our current
	// "identity" within the network. Peers will need our latest node key
	// in order to establish a transport session with us on the Lightning
	// p2p level (BOLT-0008).
	KeyFamilyNodeKey KeyFamily = 6

	// KeyFamilyStaticBackup is the family of keys that will be used to
	// derive keys that we use to encrypt and decrypt our set of static
	// backups. These backups may either be stored within watch towers for
	// a payment, or self stored on disk in a single file containing all
	// the static channel backups.
	KeyFamilyStaticBackup KeyFamily = 7

	// KeyFamilyTowerSession is the family of keys that will be used to
	// derive session keys when negotiating sessions with watchtowers. The
	// session keys are limited to the lifetime of the session and are used
	// to increase privacy in the watchtower protocol.
	KeyFamilyTowerSession KeyFamily = 8

	// KeyFamilyTowerID is the family of keys used to derive the public key
	// of a watchtower. This made distinct from the node key to offer a form
	// of rudimentary whitelisting, i.e. via knowledge of the pubkey,
	// preventing others from having full access to the tower just as a
	// result of knowing the node key.
	KeyFamilyTowerID KeyFamily = 9

	// KeyFamilyLastKF holds the last defined key family.
	KeyFamilyLastKF = KeyFamilyTowerID
)

type KeyLocator 

type KeyLocator struct {

	// Family is the family of key being identified.
	Family KeyFamily

	// Index is the precise index of the key being identified.
	Index uint32
}

KeyLocator is a two-tuple that can be used to derive *any* key that has ever been used under the key derivation mechanisms described in this file. Version 0 of our key derivation schema uses the following BIP43-like derivation:

  • m/1017'/coinType'/keyFamily'/0/index

Our purpose is 1017 (chosen arbitrary for now), and the coin type will vary based on which coin/chain the channels are being created on. The key family are actually just individual "accounts" in the nomenclature of BIP43. By default we assume a branch of 0 (external). Finally, the key index (which will vary per channel and use case) is the final element which allows us to deterministically derive keys.

func (KeyLocator) IsEmpty 

func (k KeyLocator) IsEmpty() bool

IsEmpty returns true if a KeyLocator is "empty". This may be the case where we learn of a key from a remote party for a contract, but don't know the precise details of its derivation (as we don't know the private key!).

type KeyRing 

type KeyRing interface {
	// DeriveNextKey attempts to derive the *next* key within the key
	// family (account in BIP43) specified. This method should return the
	// next external child within this branch.
	DeriveNextKey(keyFam KeyFamily) (KeyDescriptor, error)

	// DeriveKey attempts to derive an arbitrary key specified by the
	// passed KeyLocator. This may be used in several recovery scenarios,
	// or when manually rotating something like our current default node
	// key.
	DeriveKey(keyLoc KeyLocator) (KeyDescriptor, error)
}

KeyRing is the primary interface that will be used to perform public derivation of various keys used within the peer-to-peer network, and also within any created contracts. All derivation required by the KeyRing is based off of public derivation, so a system with only an extended public key (for the particular purpose+family) can derive this set of keys.

type KeyRingConstructor added in v0.2.0 

type KeyRingConstructor func() (string, func(), KeyRing, error)

KeyRingConstructor is a function signature that's used as a generic constructor for various implementations of the KeyRing interface. A string naming the returned interface, a function closure that cleans up any resources, and the clean up interface itself are to be returned.

type PrivKeyDigestSigner added in v0.3.0 

type PrivKeyDigestSigner struct {
	PrivKey *secp256k1.PrivateKey
}

func (*PrivKeyDigestSigner) PubKey added in v0.3.0 

func (p *PrivKeyDigestSigner) PubKey() *secp256k1.PublicKey

func (*PrivKeyDigestSigner) SignDigest added in v0.3.0 

func (p *PrivKeyDigestSigner) SignDigest(digest [32]byte) (*ecdsa.Signature,
	error)

func (*PrivKeyDigestSigner) SignDigestCompact added in v0.3.0 

func (p *PrivKeyDigestSigner) SignDigestCompact(digest [32]byte) ([]byte,
	error)

type PrivKeyECDH added in v0.3.0 

type PrivKeyECDH struct {
	// PrivKey is the private key that is used for the ECDH operation.
	PrivKey *secp256k1.PrivateKey
}

PrivKeyECDH is an implementation of the SingleKeyECDH in which we do have the full private key. This can be used to wrap a temporary key to conform to the SingleKeyECDH interface.

func (*PrivKeyECDH) ECDH added in v0.3.0 

func (p *PrivKeyECDH) ECDH(pub *secp256k1.PublicKey) ([32]byte, error)

ECDH performs a scalar multiplication (ECDH-like operation) between the abstracted private key and a remote public key. The output returned will be the sha256 of the resulting shared point serialized in compressed format. If k is our private key, and P is the public key, we perform the following operation: 

sx := k*P
s := sha256(sx.SerializeCompressed())

NOTE: This is part of the SingleKeyECDH interface.

func (*PrivKeyECDH) PubKey added in v0.3.0 

func (p *PrivKeyECDH) PubKey() *secp256k1.PublicKey

PubKey returns the public key of the private key that is abstracted away by the interface.

NOTE: This is part of the SingleKeyECDH interface.

type PubKeyDigestSigner added in v0.3.0 

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

func NewPubKeyDigestSigner added in v0.3.0 

func NewPubKeyDigestSigner(keyDesc KeyDescriptor,
	signer DigestSignerRing) *PubKeyDigestSigner

func (*PubKeyDigestSigner) PubKey added in v0.3.0 

func (p *PubKeyDigestSigner) PubKey() *secp256k1.PublicKey

func (*PubKeyDigestSigner) SignDigest added in v0.3.0 

func (p *PubKeyDigestSigner) SignDigest(digest [32]byte) (*ecdsa.Signature,
	error)

func (*PubKeyDigestSigner) SignDigestCompact added in v0.3.0 

func (p *PubKeyDigestSigner) SignDigestCompact(digest [32]byte) ([]byte,
	error)

type PubKeyECDH added in v0.3.0 

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

PubKeyECDH is an implementation of the SingleKeyECDH interface. It wraps an ECDH key ring so it can perform ECDH shared key generation against a single abstracted away private key.

func NewPubKeyECDH added in v0.3.0 

func NewPubKeyECDH(keyDesc KeyDescriptor, ecdh ECDHRing) *PubKeyECDH

NewPubKeyECDH wraps the given key of the key ring so it adheres to the SingleKeyECDH interface.

func (*PubKeyECDH) ECDH added in v0.3.0 

func (p *PubKeyECDH) ECDH(pubKey *secp256k1.PublicKey) ([32]byte, error)

ECDH performs a scalar multiplication (ECDH-like operation) between the abstracted private key and a remote public key. The output returned will be the sha256 of the resulting shared point serialized in compressed format. If k is our private key, and P is the public key, we perform the following operation: 

sx := k*P
s := sha256(sx.SerializeCompressed())

NOTE: This is part of the SingleKeyECDH interface.

func (*PubKeyECDH) PubKey added in v0.3.0 

func (p *PubKeyECDH) PubKey() *secp256k1.PublicKey

PubKey returns the public key of the private key that is abstracted away by the interface.

NOTE: This is part of the SingleKeyECDH interface.

type SecretKeyRing 

type SecretKeyRing interface {
	KeyRing

	ECDHRing

	DigestSignerRing

	// DerivePrivKey attempts to derive the private key that corresponds to
	// the passed key descriptor.  If the public key is set, then this
	// method will perform an in-order scan over the key set, with a max of
	// MaxKeyRangeScan keys. In order for this to work, the caller MUST set
	// the KeyFamily within the partially populated KeyLocator.
	DerivePrivKey(keyDesc KeyDescriptor) (*secp256k1.PrivateKey, error)
}

SecretKeyRing is a ring similar to the regular KeyRing interface, but it is also able to derive *private keys*. As this is a super-set of the regular KeyRing, we also expect the SecretKeyRing to implement the fully KeyRing interface. The methods in this struct may be used to extract the node key in order to accept inbound network connections, or to do manual signing for recovery purposes.

type SecretKeyRingConstructor added in v0.2.0 

type SecretKeyRingConstructor func() (string, func(), SecretKeyRing, error)

SecretKeyRingConstructor is a function signature that's used as a generic constructor for various implementations of the SecretKeyRing interface. A string naming the returned interface, a function closure that cleans up any resources, and the clean up interface itself are to be returned.

type SingleKeyDigestSigner added in v0.3.0 

type SingleKeyDigestSigner interface {
	// PubKey returns the public key of the wrapped private key.
	PubKey() *secp256k1.PublicKey

	// SignDigest signs the given SHA256 message digest with the wrapped
	// private key.
	SignDigest(digest [32]byte) (*ecdsa.Signature, error)

	// SignDigestCompact signs the given SHA256 message digest with the
	// wrapped private key and returns the signature in the compact, public
	// key recoverable format.
	SignDigestCompact(digest [32]byte) ([]byte, error)
}

SingleKeyDigestSigner is an abstraction interface that hides the implementation of the low-level ECDSA signing operations by wrapping a single, specific private key.

type SingleKeyECDH added in v0.3.0 

type SingleKeyECDH interface {
	// PubKey returns the public key of the wrapped private key.
	PubKey() *secp256k1.PublicKey

	// ECDH performs a scalar multiplication (ECDH-like operation) between
	// the wrapped private key and remote public key. The output returned
	// will be the sha256 of the resulting shared point serialized in
	// compressed format.
	ECDH(pubKey *secp256k1.PublicKey) ([32]byte, error)
}

SingleKeyECDH is an abstraction interface that hides the implementation of an ECDH operation by wrapping a single, specific private key.

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.