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
- type Controller
- type Net
- type OnionAddr
- type OnionType
- type ProxyNet
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 ¶
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 ¶
IsOnionHost determines whether a host is part of an onion address.
func LookupHost ¶
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.
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) LookupHost ¶
LookupHost for regular network uses the net.LookupHost 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.
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 ¶
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 ¶
LookupHost uses the Tor LookupHost function in order to resolve hosts over Tor.
Source Files