tor

README

tor

The tor package contains utility functions that allow for interacting with the Tor daemon. So far, supported functions include:

• Routing all traffic over Tor's exposed SOCKS5 proxy.
• Routing DNS queries over Tor (A, AAAA, SRV).
• Limited Tor Control functionality (synchronous messages only). So far, this includes:
  • Support for SAFECOOKIE authentication only as a sane default.
  • Creating v2 onion services.

In the future, the Tor Control functionality will be extended to support v3 onion services, asynchronous messages, etc.

Installation and Updating

$ go get -u github.com/lightningnetwork/lnd/tor

Documentation

Index

• Constants
• Variables
• func Dial(address, socksAddr string, streamIsolation bool) (net.Conn, error)
• func IsOnionHost(host string) bool
• func LookupHost(host, socksAddr string) ([]string, error)
• func LookupSRV(service, proto, name, socksAddr, dnsServer string, streamIsolation bool) (string, []*net.SRV, error)
• func ParseAddr(address, socksAddr string) (net.Addr, error)
• func ResolveTCPAddr(address, socksAddr string) (*net.TCPAddr, error)
• type AddOnionConfig
• type ClearNet
  • func (r *ClearNet) Dial(network, address string) (net.Conn, error)
  • func (r *ClearNet) LookupHost(host string) ([]string, error)
  • func (r *ClearNet) LookupSRV(service, proto, name string) (string, []*net.SRV, error)
  • func (r *ClearNet) ResolveTCPAddr(network, address string) (*net.TCPAddr, error)
• type Controller
  • func NewController(controlAddr string, targetIPAddress string) *Controller
  • func (c *Controller) AddOnion(cfg AddOnionConfig) (*OnionAddr, error)
  • func (c *Controller) ProtocolInfo() ([]string, string, string, error)
  • func (c *Controller) Start() error
  • func (c *Controller) Stop() error
• type Net
• type OnionAddr
  • func (o *OnionAddr) Network() string
  • func (o *OnionAddr) String() string
• type OnionType
• type ProxyNet
  • func (p *ProxyNet) Dial(network, address string) (net.Conn, error)
  • func (p *ProxyNet) LookupHost(host string) ([]string, error)
  • func (p *ProxyNet) LookupSRV(service, proto, name string) (string, []*net.SRV, error)
  • func (p *ProxyNet) ResolveTCPAddr(network, address string) (*net.TCPAddr, error)

Constants

const (

	// ProtocolInfoVersion is the `protocolinfo` version currently supported
	// by the Tor server.
	ProtocolInfoVersion = 1

	// MinTorVersion is the minimum supported version that the Tor server
	// must be running on. This is needed in order to create v3 onion
	// services through Tor's control port.
	MinTorVersion = "0.3.3.6"
)

const (

	// OnionSuffix is the ".onion" suffix for v2 and v3 onion addresses.
	OnionSuffix = ".onion"

	// OnionSuffixLen is the length of the ".onion" suffix.
	OnionSuffixLen = len(OnionSuffix)

	// V2DecodedLen is the length of a decoded v2 onion service.
	V2DecodedLen = 10

	// V2Len is the length of a v2 onion service including the ".onion"
	// suffix.
	V2Len = 22

	// V3DecodedLen is the length of a decoded v3 onion service.
	V3DecodedLen = 35

	// V3Len is the length of a v2 onion service including the ".onion"
	// suffix.
	V3Len = 62
)

Variables

var (
	// Base32Encoding represents the Tor's base32-encoding scheme for v2 and
	// v3 onion addresses.
	Base32Encoding = base32.NewEncoding(base32Alphabet)
)

Functions

func Dial

func Dial(address, socksAddr string, streamIsolation bool) (net.Conn, error)

Dial is a wrapper over the non-exported dial function that returns a wrapper around net.Conn in order to expose the actual remote address we're dialing, rather than the proxy's address.

func IsOnionHost

func IsOnionHost(host string) bool

IsOnionHost determines whether a host is part of an onion address.

func LookupHost

func LookupHost(host, socksAddr string) ([]string, error)

LookupHost performs DNS resolution on a given host via Tor's native resolver. Only IPv4 addresses are returned.

func LookupSRV

func LookupSRV(service, proto, name, socksAddr, dnsServer string,
	streamIsolation bool) (string, []*net.SRV, error)

LookupSRV uses Tor's SOCKS proxy to route DNS SRV queries. Tor does not natively support SRV queries so we must route all SRV queries through the proxy by connecting directly to a DNS server and querying it. The DNS server must have TCP resolution enabled for the given port.

func ParseAddr

func ParseAddr(address, socksAddr string) (net.Addr, error)

ParseAddr parses an address from its string format to a net.Addr.

func ResolveTCPAddr

func ResolveTCPAddr(address, socksAddr string) (*net.TCPAddr, error)

ResolveTCPAddr uses Tor's proxy to resolve TCP addresses instead of the standard system resolver provided in the `net` package.

Types

type AddOnionConfig

type AddOnionConfig struct {
	// Type denotes the type of the onion service that should be created.
	Type OnionType

	// VirtualPort is the externally reachable port of the onion address.
	VirtualPort int

	// TargetPorts is the set of ports that the service will be listening on
	// locally. The Tor server will use choose a random port from this set
	// to forward the traffic from the virtual port.
	//
	// NOTE: If nil/empty, the virtual port will be used as the only target
	// port.
	TargetPorts []int

	// PrivateKeyPath is the full path to where the onion service's private
	// key is stored. This can be used to restore an existing onion service.
	PrivateKeyPath string
}

AddOnionConfig houses all of the required parameters in order to successfully create a new onion service or restore an existing one.

type ClearNet

type ClearNet struct{}

ClearNet is an implementation of the Net interface that defines behaviour for regular network connections.

func (*ClearNet) Dial

func (r *ClearNet) Dial(network, address string) (net.Conn, error)

Dial on the regular network uses net.Dial

func (*ClearNet) LookupHost

func (r *ClearNet) LookupHost(host string) ([]string, error)

LookupHost for regular network uses the net.LookupHost function

func (*ClearNet) LookupSRV

func (r *ClearNet) LookupSRV(service, proto, name string) (string, []*net.SRV, error)

LookupSRV for regular network uses net.LookupSRV function

func (*ClearNet) ResolveTCPAddr

func (r *ClearNet) ResolveTCPAddr(network, address string) (*net.TCPAddr, error)

ResolveTCPAddr for regular network uses net.ResolveTCPAddr function

type Controller

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

Controller is an implementation of the Tor Control protocol. This is used in order to communicate with a Tor server. Its only supported method of authentication is the SAFECOOKIE method.

NOTE: The connection to the Tor server must be authenticated before proceeding to send commands. Otherwise, the connection will be closed.

TODO:

• if adding support for more commands, extend this with a command queue?
• place under sub-package?
• support async replies from the server

func NewController

func NewController(controlAddr string, targetIPAddress string) *Controller

NewController returns a new Tor controller that will be able to interact with a Tor server.

func (*Controller) AddOnion

func (c *Controller) AddOnion(cfg AddOnionConfig) (*OnionAddr, error)

AddOnion creates an onion service and returns its onion address. Once created, the new onion service will remain active until the connection between the controller and the Tor server is closed.

func (*Controller) ProtocolInfo

func (c *Controller) ProtocolInfo() ([]string, string, string, error)

ProtocolInfo returns the different authentication methods supported by the Tor server and the version of the Tor server.

func (*Controller) Start

func (c *Controller) Start() error

Start establishes and authenticates the connection between the controller and a Tor server. Once done, the controller will be able to send commands and expect responses.

func (*Controller) Stop

func (c *Controller) Stop() error

Stop closes the connection between the controller and the Tor server.

type Net

type Net interface {
	// Dial connects to the address on the named network.
	Dial(network, address string) (net.Conn, error)

	// LookupHost performs DNS resolution on a given host and returns its
	// addresses.
	LookupHost(host string) ([]string, error)

	// LookupSRV tries to resolve an SRV query of the given service,
	// protocol, and domain name.
	LookupSRV(service, proto, name string) (string, []*net.SRV, error)

	// ResolveTCPAddr resolves TCP addresses.
	ResolveTCPAddr(network, address string) (*net.TCPAddr, error)
}

Net is an interface housing a Dial function and several DNS functions that allows us to abstract the implementations of these functions over different networks, e.g. clearnet, Tor net, etc.

type OnionAddr

type OnionAddr struct {
	// OnionService is the host of the onion address.
	OnionService string

	// Port is the port of the onion address.
	Port int
}

OnionAddr represents a Tor network end point onion address.

func (*OnionAddr) Network

func (o *OnionAddr) Network() string

Network returns the network that this implementation of net.Addr will use. In this case, because Tor only allows TCP connections, the network is "tcp".

func (*OnionAddr) String

func (o *OnionAddr) String() string

String returns the string representation of an onion address.

type OnionType

type OnionType int

OnionType denotes the type of the onion service.

const (
	// V2 denotes that the onion service is V2.
	V2 OnionType = iota

	// V3 denotes that the onion service is V3.
	V3
)

type ProxyNet

type ProxyNet struct {
	// SOCKS is the host:port which Tor's exposed SOCKS5 proxy is listening
	// on.
	SOCKS string

	// DNS is the host:port of the DNS server for Tor to use for SRV
	// queries.
	DNS string

	// StreamIsolation is a bool that determines if we should force the
	// creation of a new circuit for this connection. If true, then this
	// means that our traffic may be harder to correlate as each connection
	// will now use a distinct circuit.
	StreamIsolation bool
}

ProxyNet is an implementation of the Net interface that defines behaviour for Tor network connections.

func (*ProxyNet) Dial

func (p *ProxyNet) Dial(network, address string) (net.Conn, error)

Dial uses the Tor Dial function in order to establish connections through Tor. Since Tor only supports TCP connections, only TCP networks are allowed.

func (*ProxyNet) LookupHost

func (p *ProxyNet) LookupHost(host string) ([]string, error)

LookupHost uses the Tor LookupHost function in order to resolve hosts over Tor.

func (*ProxyNet) LookupSRV

func (p *ProxyNet) LookupSRV(service, proto, name string) (string, []*net.SRV, error)

LookupSRV uses the Tor LookupSRV function in order to resolve SRV DNS queries over Tor.

func (*ProxyNet) ResolveTCPAddr

func (p *ProxyNet) ResolveTCPAddr(network, address string) (*net.TCPAddr, error)

ResolveTCPAddr uses the Tor ResolveTCPAddr function in order to resolve TCP addresses over Tor.