onionmsg

Documentation

Index

• Constants
• Variables
• func DisableLog()
• func UseLogger(logger btclog.Logger)
• type LndOnionMsg
• type LndOnionSigner
• type Messenger
  • func NewOnionMessenger(lnd LndOnionMsg, nodeKeyECDH sphinx.SingleKeyECDH, shutdown func(error)) *Messenger
  • func (m *Messenger) DeregisterHandler(tlvType tlv.Type) error
  • func (m *Messenger) RegisterHandler(tlvType tlv.Type, handler OnionMessageHandler) error
  • func (m *Messenger) SendMessage(ctx context.Context, req *SendMessageRequest) error
  • func (m *Messenger) Start() error
  • func (m *Messenger) Stop() error
• type NodeECDH
  • func NewNodeECDH(lnd LndOnionMsg, signer LndOnionSigner) (*NodeECDH, error)
  • func (r *NodeECDH) ECDH(pubkey *btcec.PublicKey) ([32]byte, error)
  • func (r *NodeECDH) PubKey() *btcec.PublicKey
• type OnionMessageHandler
• type OnionMessenger
• type SendMessageRequest
  • func NewSendMessageRequest(destination *btcec.PublicKey, blindedDestination, replyPath *lnwire.ReplyPath, ...) *SendMessageRequest
  • func (s *SendMessageRequest) Validate() error

Constants

const Subsystem = "B12-OMS"

Subsystem defines the logging code for this subsystem.

Variables

var (
	// ErrNotStarted is returned if the messenger hasn't been started yet
	// and can't perform an operation.
	ErrNotStarted = errors.New("messenger not started")

	// ErrHandlerNotFound is returned when we try to de-register a handler
	// that isn't currently registered.
	ErrHandlerNotFound = errors.New("handler not found")

	// ErrHandlerRegistered is returned when we try to register a handler
	// for a type that already exists.
	ErrHandlerRegistered = errors.New("handler already registered")

	// ErrNoAddresses is returned when we can't find a node's address in the
	// public graph.
	ErrNoAddresses = errors.New("no advertised addresses")

	// ErrNoConnection is returned if we don't successfully connect to our
	// peer within our set number of retries.
	ErrNoConnection = errors.New("peer not connected within wait period")

	// ErrNoPath is returned when we can't find a path to a peer to deliver
	// an onion message.
	ErrNoPath = errors.New("path not found to peer")

	// ErrFinalPayload is returned if an intermediate hop in an onion
	// message chain contains fields that are reserved for the last hop.
	ErrFinalPayload = errors.New("intermediate hop has final hop payloads")

	// ErrBadMessage is returned when we can't process an onion message.
	ErrBadMessage = errors.New("onion message processing failed")

	// ErrBadOnionMsg is returned when we receive a bad onion message.
	ErrBadOnionMsg = errors.New("invalid onion message")

	// ErrBadOnionBlob is returned when we receive a bad onion blob within
	// our onion message.
	ErrBadOnionBlob = errors.New("invalid onion blob")

	// ErrNilPubkeyInRoute is returned when we query lnd for a route and
	// do not get a node pubkey alongside a channel.
	ErrNilPubkeyInRoute = errors.New("nil pubkey in route")

	// ErrNoForwardingOnion is returned when we try to forward an onion
	// message but no next onion is provided.
	ErrNoForwardingOnion = errors.New("no next onion provided to forward")

	// ErrNoNextNodeID is returned when we require a next node id in our
	// encrypted data blob and one was not provided.
	ErrNoNextNodeID = errors.New("next node ID required")

	// ErrBothDest is returned when a message request sets more than one
	// destination type.
	ErrBothDest = errors.New("cannot set blinded and un-blinded " +
		"destination")

	// ErrNoDest is returned when no destination for an onion message
	// is provided.
	ErrNoDest = errors.New("clear or blinded destination required")

	// ErrNoBlindedHops is returned when we try to send an onion message
	// to a blinded route with no hops.
	ErrNoBlindedHops = errors.New("at least one blinded hop required")

	// ErrShuttingDown is returned when the messenger exits.
	ErrShuttingDown = errors.New("messenger shutting down")

	// ErrLNDShutdown is returned when lnd shuts down one of our streams.
	ErrLNDShutdown = errors.New("lnd shutting down")
)

var (
	// ErrNoEncryptedData is returned when the encrypted data TLV is not
	// present when it is required.
	ErrNoEncryptedData = errors.New("encrypted data blob required")

	// ErrNoForwardingPayload is returned when no onion message payload
	// is provided to allow forwarding messages.
	ErrNoForwardingPayload = errors.New("no payload provided for " +
		"forwarding")
)

Functions

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

Types

type LndOnionMsg

type LndOnionMsg interface {
	// SendCustomMessage sends a custom message to a peer.
	SendCustomMessage(ctx context.Context, msg lndclient.CustomMessage) error

	// SubscribeCustomMessages subscribes to custom messages received by
	// lnd.
	SubscribeCustomMessages(ctx context.Context) (
		<-chan lndclient.CustomMessage, <-chan error, error)

	// GetNodeInfo looks up a node in the public ln graph.
	GetNodeInfo(ctx context.Context, pubkey route.Vertex,
		includeChannels bool) (*lndclient.NodeInfo, error)

	// ListPeers returns lnd's current set of peers.
	ListPeers(ctx context.Context) ([]lndclient.Peer, error)

	// Connect makes a connection to the peer provided.
	Connect(ctx context.Context, peer route.Vertex, host string,
		permanent bool) error

	// GetInfo returns information about the lnd node.
	GetInfo(ctx context.Context) (*lndclient.Info, error)

	// QueryRoutes queries lnd for a route to a destination peer.
	QueryRoutes(ctx context.Context, req lndclient.QueryRoutesRequest) (
		*lndclient.QueryRoutesResponse, error)
}

LndOnionMsg is an interface describing the lnd dependencies that the onionmsg package required.

type LndOnionSigner

type LndOnionSigner interface {
	// DeriveSharedKey returns a shared secret key by performing
	// Diffie-Hellman key derivation between the ephemeral public key and
	// the key specified by the key locator (or the node's identity private
	// key if no key locator is specified)
	DeriveSharedKey(ctx context.Context, ephemeralPubKey *btcec.PublicKey,
		keyLocator *keychain.KeyLocator) ([32]byte, error)
}

LndOnionSigner is an interface describing the lnd dependencies required for the onion messenger's cryptographic operations.

type Messenger

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

Messenger houses the functionality to send and receive onion messages.

func NewOnionMessenger

func NewOnionMessenger(lnd LndOnionMsg,
	nodeKeyECDH sphinx.SingleKeyECDH,
	shutdown func(error)) *Messenger

NewOnionMessenger creates a new onion messenger.

func (*Messenger) DeregisterHandler

func (m *Messenger) DeregisterHandler(tlvType tlv.Type) error

Deregister removes the handler for a specific tlv type.

func (*Messenger) RegisterHandler

func (m *Messenger) RegisterHandler(tlvType tlv.Type,
	handler OnionMessageHandler) error

RegisterHandler connects the handler provided to a tlv type in the final hop payload range in onion messages. This function would block if the messenger is not yet started, so we fail any calls before startup.

func (*Messenger) SendMessage

func (m *Messenger) SendMessage(ctx context.Context,
	req *SendMessageRequest) error

SendMessage sends an onion message to the peer provided. The message can optionally include a reply path for the recipient to use for replies and payloads for the final hop. If we cannot find a path to the peer and the direct connect param is true, we will make a direct connection to the peer to send the message.

func (*Messenger) Start

func (m *Messenger) Start() error

Start the messenger, running all goroutines required.

func (*Messenger) Stop

func (m *Messenger) Stop() error

Stop shuts down the messenger and waits for all goroutines to exit.

type NodeECDH

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

NodeECDH provides the functionality required for an onion router's cryptographic operations, specifically ECDH operations with the node's pubkey, using lnd's public apis to perform the operations.

func NewNodeECDH

func NewNodeECDH(lnd LndOnionMsg, signer LndOnionSigner) (*NodeECDH,
	error)

NewNodeECDH creates a new node key ecdh which uses lnd's external apis to perform the operations required.

func (*NodeECDH) ECDH

func (r *NodeECDH) ECDH(pubkey *btcec.PublicKey) ([32]byte, error)

ECDH performs ECDH operations with the node's public key, returning the SHA256 hash of the shared secret.

func (*NodeECDH) PubKey

func (r *NodeECDH) PubKey() *btcec.PublicKey

PubKey returns the lnd node's public key.

type OnionMessageHandler

type OnionMessageHandler func(*lnwire.ReplyPath, []byte, []byte) error

OnionMessageHandler is the function signature for handlers used to manage final hop payloads included in onion messages. It takes the reply path, encrypted data and value of the final hop's tlv as arguments.

type OnionMessenger

type OnionMessenger interface {
	// Start the onion messenger.
	Start() error

	// Stop the onion messenger, blocking until all goroutines exit.
	Stop() error

	// SendMessage sends an onion message to the peer specified. A set of
	// optional TLVs for the target peer can be included in final payloads.
	SendMessage(ctx context.Context, req *SendMessageRequest) error

	// RegisterHandler adds a handler onion message payloads delivered to
	// our node for the tlv type provided.
	// Note: this function will fail if the messenger has not been started.
	RegisterHandler(tlvType tlv.Type, handler OnionMessageHandler) error

	// DeregisterHandler removes a handler for onion message payloads for
	// the tlv type provided.
	// Note: this function will fail if the messenger has not been started.
	DeregisterHandler(tlvType tlv.Type) error
}

OnionMessenger is an interface implemented by objects that can send and receive onion messages.

type SendMessageRequest

type SendMessageRequest struct {
	// Peer is the destination that we are sending the message to. This
	// field and blinded destination are mutually exclusive.
	Peer *btcec.PublicKey

	// BlindedDestination is a blinded path to the peer that we are sending
	// the message to. This field and peer are mutually exclusive.
	BlindedDestination *lnwire.ReplyPath

	// ReplyPath is an optional reply path to our own node, included to
	// allow the recipient to reply to the message.
	ReplyPath *lnwire.ReplyPath

	// FinalHopPayloads is a set of tlv types / values to include in the
	// payload for the final hop.
	FinalPayloads []*lnwire.FinalHopPayload

	// DirectConnect indicates whether we should make a direct p2p
	// connection to the target node.
	DirectConnect bool
}

SendMessageRequest contains the request parameters for sending an onion message.

func NewSendMessageRequest

func NewSendMessageRequest(destination *btcec.PublicKey, blindedDestination,
	replyPath *lnwire.ReplyPath, finalPayloads []*lnwire.FinalHopPayload,
	directConnect bool) *SendMessageRequest

NewSendMessageRequest creates an onion message request.

func (*SendMessageRequest) Validate

func (s *SendMessageRequest) Validate() error

Validate performs validation on send message requests.