Documentation
¶
Overview ¶
Package tor is the high-level client for Tor.
The Tor type is a combination of a Tor instance and a connection to it. Use Start to create Tor. Then Dialer or Listener can be used.
Some of this code is lifted from https://github.com/yawning/bulb with thanks.
Index ¶
- type DialConf
- type Dialer
- type ForwardConf
- type ListenConf
- type OnionForward
- type OnionService
- type StartConf
- type Tor
- func (t *Tor) Close() error
- func (t *Tor) DebugEnabled() bool
- func (t *Tor) Debugf(format string, args ...interface{})
- func (t *Tor) Dialer(ctx context.Context, conf *DialConf) (*Dialer, error)
- func (t *Tor) EnableNetwork(ctx context.Context, wait bool) error
- func (t *Tor) Forward(ctx context.Context, conf *ForwardConf) (*OnionForward, error)
- func (t *Tor) Listen(ctx context.Context, conf *ListenConf) (*OnionService, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DialConf ¶
type DialConf struct {
// ProxyAddress is the address for the SOCKS5 proxy. If empty, it is looked
// up.
ProxyAddress string
// ProxyNetwork is the network for the SOCKS5 proxy. If ProxyAddress is
// empty, this value is ignored and overridden by what is looked up. If this
// is empty and ProxyAddress is not empty, it defaults to "tcp".
ProxyNetwork string
// ProxyAuth is the auth for the proxy. Since Tor's SOCKS5 proxy is
// unauthenticated, this is rarely needed. It can be used when
// IsolateSOCKSAuth is set to ensure separate circuits.
//
// This should not be confused with downstream SOCKS proxy authentication
// which is set via Tor values for Socks5ProxyUsername and
// Socks5ProxyPassword when Socks5Proxy is set.
ProxyAuth *proxy.Auth
// SkipEnableNetwork, if true, will skip the enable network step in Dialer.
SkipEnableNetwork bool
// Forward is the dialer to forward to. If nil, just uses normal net dialer.
Forward proxy.Dialer
}
DialConf is the configuration used for Dialer.
type ForwardConf ¶
type ForwardConf struct {
// PortForwards defines the ports that will be forwarded to the onion
// service.
PortForwards map[string][]int
// Key is the private key to use. If not present, a key is generated. If
// present, it must be an instance of
// github.com/cretz/bine/torutil/ed25519.KeyPair, a
// golang.org/x/crypto/ed25519.PrivateKey, or a
// github.com/cretz/bine/control.Key.
Key crypto.PrivateKey
// ClientAuths is the credential set for clients. The values are
// base32-encoded ed25519 public keys.
ClientAuths []string
// MaxStreams is the maximum number of streams the service will accept. 0
// means unlimited.
MaxStreams int
// DiscardKey, if true and Key is nil (meaning a private key is generated),
// tells Tor not to return the generated private key. This value is ignored
// if Key is not nil.
DiscardKey bool
// Detach, if true, prevents the default behavior of the onion service being
// deleted when this controller connection is closed.
Detach bool
// NonAnonymous must be true if Tor options HiddenServiceSingleHopMode and
// HiddenServiceNonAnonymousMode are set. Otherwise, it must be false.
NonAnonymous bool
// MaxStreamsCloseCircuit determines whether to close the circuit when the
// maximum number of streams is exceeded. If true, the circuit is closed. If
// false, the stream is simply not connected but the circuit stays open.
MaxStreamsCloseCircuit bool
// NoWait if true will not wait until the onion service is published. If
// false, the network will be enabled if it's not and then we will wait
// until the onion service is published.
NoWait bool
}
ForwardConf is the configuration for Forward calls.
type ListenConf ¶
type ListenConf struct {
// LocalPort is the local port to create a TCP listener on. If the port is
// 0, it is automatically chosen. This is ignored if LocalListener is set.
LocalPort int
// LocalListener is the specific local listener to back the onion service.
// If this is nil (the default), then a listener is created with LocalPort.
LocalListener net.Listener
// RemotePorts are the remote ports to serve the onion service on. If empty,
// it is the same as the local port or local listener. This must have at
// least one value if the local listener is not a *net.TCPListener.
RemotePorts []int
// Key is the private key to use. If not present, a key is generated. If
// present, it must be an instance of
// github.com/cretz/bine/torutil/ed25519.KeyPair, a
// golang.org/x/crypto/ed25519.PrivateKey, or a
// github.com/cretz/bine/control.Key.
Key crypto.PrivateKey
// ClientAuths is the credential set for clients. The values are
// base32-encoded ed25519 public keys.
ClientAuths []string
// MaxStreams is the maximum number of streams the service will accept. 0
// means unlimited.
MaxStreams int
// DiscardKey, if true and Key is nil (meaning a private key is generated),
// tells Tor not to return the generated private key. This value is ignored
// if Key is not nil.
DiscardKey bool
// Detach, if true, prevents the default behavior of the onion service being
// deleted when this controller connection is closed.
Detach bool
// NonAnonymous must be true if Tor options HiddenServiceSingleHopMode and
// HiddenServiceNonAnonymousMode are set. Otherwise, it must be false.
NonAnonymous bool
// MaxStreamsCloseCircuit determines whether to close the circuit when the
// maximum number of streams is exceeded. If true, the circuit is closed. If
// false, the stream is simply not connected but the circuit stays open.
MaxStreamsCloseCircuit bool
// NoWait if true will not wait until the onion service is published. If
// false, the network will be enabled if it's not and then we will wait
// until the onion service is published.
NoWait bool
}
ListenConf is the configuration for Listen calls.
type OnionForward ¶
type OnionForward struct {
// ID is the service ID for this onion service.
ID string
// Key is the private key for this service. It is either the set key, the
// generated key, or nil if asked to discard the key. If present, it is an
// instance of github.com/cretz/bine/torutil/ed25519.KeyPair.
Key crypto.PrivateKey
// PortForwards defines the ports that will be forwarded to the onion
// service.
PortForwards map[string][]int
// The Tor object that created this. Needed for Close.
Tor *Tor
}
OnionForward describes a port forward to an onion service.
func (*OnionForward) Close ¶
func (o *OnionForward) Close() (err error)
Close deletes the onion service.
type OnionService ¶
type OnionService struct {
// ID is the service ID for this onion service.
ID string
// Key is the private key for this service. It is either the set key, the
// generated key, or nil if asked to discard the key. If present, it is an
// instance of github.com/cretz/bine/torutil/ed25519.KeyPair.
Key crypto.PrivateKey
// LocalListener is the local TCP listener. This is always present.
LocalListener net.Listener
// RemotePorts is the set of remote ports that are forwarded to the local
// listener. This will always have at least one value.
RemotePorts []int
// CloseLocalListenerOnClose is true if the local listener should be closed
// on Close. This is set to true if a listener was created by Listen and set
// to false of an existing LocalListener was provided to Listen.
CloseLocalListenerOnClose bool
// The Tor object that created this. Needed for Close.
Tor *Tor
}
OnionService implements net.Listener and net.Addr for an onion service.
func (*OnionService) Accept ¶
func (o *OnionService) Accept() (net.Conn, error)
Accept implements net.Listener.Accept.
func (*OnionService) Addr ¶
func (o *OnionService) Addr() net.Addr
Addr implements net.Listener.Addr just returning this object.
func (*OnionService) Close ¶
func (o *OnionService) Close() (err error)
Close implements net.Listener.Close and deletes the onion service and closes the LocalListener if CloseLocalListenerOnClose is true.
func (*OnionService) Network ¶
func (o *OnionService) Network() string
Network implements net.Addr.Network always returning "tcp".
func (*OnionService) String ¶
func (o *OnionService) String() string
String implements net.Addr.String and returns "<serviceID>.onion:<virtport>".
type StartConf ¶
type StartConf struct {
// ExePath is the path to the Tor executable. If it is not present, "tor" is
// used either locally or on the PATH. This is ignored if ProcessCreator is
// set.
ExePath string
// ProcessCreator is the override to use a specific process creator. If set,
// ExePath is ignored.
ProcessCreator process.Creator
// UseEmbeddedControlConn can be set to true to use
// process.Process.EmbeddedControlConn() instead of creating a connection
// via ControlPort. Note, this only works when ProcessCreator is an
// embedded Tor creator with version >= 0.3.5.x.
UseEmbeddedControlConn bool
// ControlPort is the port to use for the Tor controller. If it is 0, Tor
// picks a port for use. This is ignored if UseEmbeddedControlConn is true.
ControlPort int
// DataDir is the directory used by Tor. If it is empty, a temporary
// directory is created in TempDataDirBase.
DataDir string
// TempDataDirBase is the parent directory that a temporary data directory
// will be created under for use by Tor. This is ignored if DataDir is not
// empty. If empty it is assumed to be the current working directory.
TempDataDirBase string
// RetainTempDataDir, if true, will not set the created temporary data
// directory to be deleted on close. This is ignored if DataDir is not
// empty.
RetainTempDataDir bool
// DisableCookieAuth, if true, will not use the default SAFECOOKIE
// authentication mechanism for the Tor controller.
DisableCookieAuth bool
// DisableEagerAuth, if true, will not authenticate on Start.
DisableEagerAuth bool
// EnableNetwork, if true, will connect to the wider Tor network on start.
EnableNetwork bool
// ExtraArgs is the set of extra args passed to the Tor instance when
// started.
ExtraArgs []string
// TorrcFile is the torrc file to set on start. If empty, a blank torrc is
// created in the data directory and is used instead.
TorrcFile string
// DebugWriter is the writer to use for debug logs, or nil for no debug
// logs.
DebugWriter io.Writer
// NoHush if true does not set --hush. By default --hush is set.
NoHush bool
// NoAutoSocksPort if true does not set "--SocksPort auto" as is done by
// default. This means the caller could set their own or just let it
// default to 9050.
NoAutoSocksPort bool
// GeoIPReader, if present, is called before start to copy geo IP files to
// the data directory. Errors are propagated. If the ReadCloser is present,
// it is copied to the data dir, overwriting as necessary, and then closed
// and the appropriate command line argument is added to reference it. If
// both the ReadCloser and error are nil, no copy or command line argument
// is used for that version. This is called twice, once with false and once
// with true for ipv6.
//
// This can be set to torutil/geoipembed.GeoIPReader to use an embedded
// source.
GeoIPFileReader func(ipv6 bool) (io.ReadCloser, error)
}
StartConf is the configuration used for Start when starting a Tor instance. A default instance with no fields set is the default used for Start.
type Tor ¶
type Tor struct {
// Process is the Tor instance that is running.
Process process.Process
// Control is the Tor controller connection.
Control *control.Conn
// ProcessCancelFunc is the context cancellation func for the Tor process.
// It is used by Close and should not be called directly. This can be nil.
ProcessCancelFunc context.CancelFunc
// ControlPort is the port that Control is connected on. It is 0 if the
// connection is an embedded control connection.
ControlPort int
// DataDir is the path to the data directory that Tor is using.
DataDir string
// DeleteDataDirOnClose is true if, when Close is invoked, the entire
// directory will be deleted.
DeleteDataDirOnClose bool
// DebugWriter is the writer used for debug logs, or nil if debug logs
// should not be emitted.
DebugWriter io.Writer
// StopProcessOnClose, if true, will attempt to halt the process on close.
StopProcessOnClose bool
// GeoIPCreatedFile is the path, relative to DataDir, that was created from
// StartConf.GeoIPFileReader. It is empty if no file was created.
GeoIPCreatedFile string
// GeoIPv6CreatedFile is the path, relative to DataDir, that was created
// from StartConf.GeoIPFileReader. It is empty if no file was created.
GeoIPv6CreatedFile string
}
Tor is the wrapper around the Tor process and control port connection. It should be created with Start and developers should always call Close when done.
func Start ¶
Start a Tor instance and connect to it. If ctx is nil, context.Background() is used. If conf is nil, a default instance is used.
func (*Tor) Close ¶
Close sends a halt to the Tor process if it can, closes the controller connection, and stops the process.
func (*Tor) DebugEnabled ¶
DebugEnabled returns true if there is a DebugWriter.
func (*Tor) Debugf ¶
Debugf writes the formatted string with a newline appended to the DebugWriter if present.
func (*Tor) Dialer ¶
Dialer creates a new Dialer for the given configuration. Context can be nil. If conf is nil, a default is used.
func (*Tor) EnableNetwork ¶
EnableNetwork sets DisableNetwork to 0 and optionally waits for bootstrap to complete. The context can be nil. If DisableNetwork isnt 1, this does nothing.
func (*Tor) Forward ¶
func (t *Tor) Forward(ctx context.Context, conf *ForwardConf) (*OnionForward, error)
Forward creates an onion service which forwards to local ports. The context can be nil. conf is required and cannot be nil.
func (*Tor) Listen ¶
func (t *Tor) Listen(ctx context.Context, conf *ListenConf) (*OnionService, error)
Listen creates an onion service and local listener. The context can be nil. If conf is nil, the default struct value is used. Note, if this errors, any listeners created here are closed but if a LocalListener is provided it may remain open.
Source Files
Click to show internal directories.
Click to hide internal directories.