control

Documentation

Overview

Package control implements part of the 'Tor control protocol (Version 1)'. See https://gitweb.torproject.org/torspec.git/tree/control-spec.txt.

Index

• Constants
• type Cmd
• type Conn
  • func Client(conn net.Conn) *Conn
  • func Dial(addr string) (*Conn, error)
  • func (c Conn) Auth(passwd string) (err error)
  • func (c Conn) AuthCookie(cookie []byte) (err error)
  • func (c Conn) GetInfo(key string) (*Reply, error)
  • func (c Conn) Receive() (*Reply, error)
  • func (c Conn) ReceiveSync() (*Reply, error)
  • func (c Conn) ReceiveToChan() error
  • func (c Conn) Resolve(addr string) error
  • func (c Conn) Send(cmd Cmd) (*Reply, error)
  • func (c Conn) SetEvents(keys []string) error
  • func (c Conn) Signal(s string) error
• type Demux
  • func NewDemux(c *Conn) *Demux
  • func (m *Demux) Handle(event string, f Handler) Handler
  • func (m *Demux) Serve()
• type Handler
• type Reply
  • func (r Reply) IsAsync() bool
  • func (r Reply) IsSync() bool
  • func (r Reply) String() string
• type ReplyLine
  • func (rl ReplyLine) String() string

Constants

const (
	StatusOK                   = 250
	StatusOperationUnnecessary = 251

	StatusResourceExhausted = 451

	StatusProtocolSyntaxError = 500

	StatusUnrecognizedCommand    = 510
	StatusUnimplementedCommand   = 511
	StatusArgumentSyntaxError    = 512
	StatusUnrecognizedArgument   = 513
	StatusAuthenticationRequired = 514
	StatusBadAuthentication      = 515

	StatusUnspecifiedError   = 550
	StatusInternalError      = 551
	StatusUnrecognizedEntity = 552

	StatusInvalidConfigurationValue = 553
	StatusInvalidDescriptor         = 554

	StatusUnmanagedEntity = 555

	StatusAsyncEventNotification = 650
)

Status codes of replies from the onion router.

const (
	SignalReload        = "RELOAD"        // Reload config items.
	SignalShutdown      = "SHUTDOWN"      // Controlled shutdown.
	SignalDump          = "DUMP"          // Dump log information about open connections and circuits.
	SignalDebug         = "DEBUG"         // Switch all open logs to loglevel debug.
	SignalHalt          = "HALT"          // Immediate shutdown: clean up and exit now.
	SignalClearDNSCache = "CLEARDNSCACHE" // Forget the client-side cached IPs for all hostnames.
	SignalNewNym        = "NEWNYM"        // Switch to clean circuits, so new application requests don't share any circuits with old ones.
	SignalHeartbeat     = "HEARTBEAT"     // Dump an unscheduled Heartbeat message to log.
)

Types

type Cmd

type Cmd struct {
	Keyword   string
	Arguments []string // optional list of arguments; may be nil
	Data      string   // will be dot escaped by Send
}

Cmd represents a command send from the client to the server.

type Conn

type Conn struct {
	Replies chan *Reply
	*Demux
	// contains filtered or unexported fields
}

Conn represents a Tor Control Protocol connection to a Tor server.

func Client

func Client(conn net.Conn) *Conn

Client returns a new Tor Control Protocol connection using conn as the underlying transport.

func Dial

func Dial(addr string) (*Conn, error)

Dial connects to the given network address using net.Dial and then starts and returns a new Tor Control Protocol connection.

func (Conn) Auth

func (c Conn) Auth(passwd string) (err error)

Auth authenticates a connection using the hashed password mechanism. Pass an empty string to authenticate without password.

func (Conn) AuthCookie

func (c Conn) AuthCookie(cookie []byte) (err error)

AuthCookie authenticates a connection using the control auth cookie.

func (Conn) GetInfo

func (c Conn) GetInfo(key string) (*Reply, error)

GetInfo sends a GETINFO command to the server.

func (Conn) Receive

func (c Conn) Receive() (*Reply, error)

Receive reads and returns a single reply from the Tor server. It makes no distinction between synchronous and asynchronous replies.

func (Conn) ReceiveSync

func (c Conn) ReceiveSync() (*Reply, error)

ReceiveSync reads replies from the Tor server. It returns the first synchronous reply; replies read before that are send to the connections Replies channel. ReceiveSync blocks until the replies are read from that channel.

func (Conn) ReceiveToChan

func (c Conn) ReceiveToChan() error

ReceiveToChan reads a single reply from the Tor server and sends it to the connections Replies channel. ReceiveToChan blocks until the reply is read from the channel.

func (Conn) Resolve

func (c Conn) Resolve(addr string) error

Resolve launches a remote hostname lookup for addr.

func (Conn) Send

func (c Conn) Send(cmd Cmd) (*Reply, error)

Send sends a command to the Tor server.

func (Conn) SetEvents

func (c Conn) SetEvents(keys []string) error

SetEvents sends a SETEVENTS command to the server.

func (Conn) Signal

func (c Conn) Signal(s string) error

Signal sends a SIGNAL command to the server.

type Demux

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

Demux is a simple demultiplexer for asynchronous replies. It matches the type of a reply against a list of registered events and calls the corresponding Handler function.

func NewDemux

func NewDemux(c *Conn) *Demux

NewMux allocates and returns a new Demux.

func (*Demux) Handle

func (m *Demux) Handle(event string, f Handler) Handler

Handle registers f to handle replies of type event. The different events are listed in section 4.1 of the control-spec.

func (*Demux) Serve

func (m *Demux) Serve()

Serve reads replies from the Replies channel of m's Conn and launches the corresponding Handler functions in new goroutines.

type Handler

type Handler func(r *Reply)

A Handler can be registered to handle asynchronous replies send by an Tor router. It is customary for Handler to communicate back using channels.

type Reply

type Reply struct {
	Status int         // the StatusCode of the reply
	Text   string      // ReplyText of the EndReplyLine
	Lines  []ReplyLine // MidReplyLines and DataReplyLines
}

Reply represents a reply send from the server to the client.

func (Reply) IsAsync

func (r Reply) IsAsync() bool

IsAsync returns true if r is an asynchronous reply and false otherwise.

func (Reply) IsSync

func (r Reply) IsSync() bool

IsSync returns true if r is an synchronous reply and false otherwise.

func (Reply) String

func (r Reply) String() string

type ReplyLine

type ReplyLine struct {
	Status int
	Text   string
	// Data is the empty string for MidReplyLines and the CmdData with
	// dot encoding removed for DataReplyLines.
	Data string
}

ReplyLine represents a MidReplyLine or DataReplyLine read from the server.

func (ReplyLine) String

func (rl ReplyLine) String() string