bulb

README

bulb - Is not stem

Yawning Angel (yawning at torproject dot org)

bulb is a Go language interface to the Tor control port. It is considerably lighter in functionality than stem and other controller libraries, and is intended to be used in combination withcontrol-spec.txt.

It was written primarily as a not-invented-here hack, and the base interface is more than likely to stay fairly low level, though useful helpers will be added as I need them.

Things you should probably use instead:

• stem
• txtorcon
• orc

Bugs:

• bulb does not send the 'QUIT' command before closing the connection.

Documentation

Overview

Package bulb is a Go language interface to a Tor control port.

Index

• Constants
• Variables
• type Conn
  • func Dial(network, addr string) (*Conn, error)
  • func NewConn(c io.ReadWriteCloser) *Conn
  • func (c *Conn) AddOnion(ports []OnionPortSpec, key crypto.PrivateKey, oneshot bool) (*OnionInfo, error)
  • func (c *Conn) Authenticate(password string) error
  • func (c *Conn) Close() error
  • func (c *Conn) Debug(enable bool)
  • func (c *Conn) DeleteOnion(serviceID string) error
  • func (c *Conn) Dialer(auth *proxy.Auth) (proxy.Dialer, error)
  • func (c *Conn) Listener(port uint16, key crypto.PrivateKey) (net.Listener, error)
  • func (c *Conn) NewListener(config *NewOnionConfig, vports ...uint16) (net.Listener, error)
  • func (c *Conn) NewOnion(config *NewOnionConfig) (*OnionInfo, error)
  • func (c *Conn) NextEvent() (*Response, error)
  • func (c *Conn) ProtocolInfo() (*ProtocolInfo, error)
  • func (c *Conn) Read(p []byte) (int, error)
  • func (c *Conn) ReadResponse() (*Response, error)
  • func (c *Conn) Request(fmt string, args ...interface{}) (*Response, error)
  • func (c *Conn) StartAsyncReader()
  • func (c *Conn) Write(p []byte) (int, error)
• type NewOnionConfig
• type OnionInfo
• type OnionPortSpec
• type OnionPrivateKey
• type ProtocolInfo
• type Response
  • func (r *Response) IsAsync() bool
  • func (r *Response) IsOk() bool

Constants

const (
	StatusOk            = 250
	StatusOkUnneccecary = 251

	StatusErrResourceExhausted      = 451
	StatusErrSyntaxError            = 500
	StatusErrUnrecognizedCmd        = 510
	StatusErrUnimplementedCmd       = 511
	StatusErrSyntaxErrorArg         = 512
	StatusErrUnrecognizedCmdArg     = 513
	StatusErrAuthenticationRequired = 514
	StatusErrBadAuthentication      = 515
	StatusErrUnspecifiedTorError    = 550
	StatusErrInternalError          = 551
	StatusErrUnrecognizedEntity     = 552
	StatusErrInvalidConfigValue     = 553
	StatusErrInvalidDescriptor      = 554
	StatusErrUnmanagedEntity        = 555

	StatusAsyncEvent = 650
)

The various control port StatusCode constants.

Variables

var ErrNoAsyncReader = errors.New("event requested without an async reader")

ErrNoAsyncReader is the error returned when the asynchronous event handling is requested, but the helper go routine has not been started.

Types

type Conn

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

Conn is a control port connection instance.

func Dial

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

Dial connects to a given network/address and returns a new Conn for the connection.

func NewConn

func NewConn(c io.ReadWriteCloser) *Conn

NewConn returns a new Conn using c for I/O.

func (*Conn) AddOnion

func (c *Conn) AddOnion(ports []OnionPortSpec, key crypto.PrivateKey, oneshot bool) (*OnionInfo, error)

[DEPRECATED] AddOnion issues an ADD_ONION command and returns the parsed response.

func (*Conn) Authenticate

func (c *Conn) Authenticate(password string) error

Authenticate authenticates with the Tor instance using the "best" possible authentication method. The password argument is entirely optional, and will only be used if the "SAFECOOKE" and "NULL" authentication methods are not available and "HASHEDPASSWORD" is.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection.

func (*Conn) Debug

func (c *Conn) Debug(enable bool)

Debug enables/disables debug logging of control port chatter.

func (*Conn) DeleteOnion

func (c *Conn) DeleteOnion(serviceID string) error

DeleteOnion issues a DEL_ONION command and returns the parsed response.

func (*Conn) Dialer

func (c *Conn) Dialer(auth *proxy.Auth) (proxy.Dialer, error)

Dialer returns a proxy.Dialer for the given Tor instance.

func (*Conn) Listener

func (c *Conn) Listener(port uint16, key crypto.PrivateKey) (net.Listener, error)

[DEPRECATED] Listener returns a net.Listener backed by an Onion Service.

func (*Conn) NewListener

func (c *Conn) NewListener(config *NewOnionConfig, vports ...uint16) (net.Listener, error)

NewListener returns a net.Listener backed by an Onion Service using configuration config, optionally having Tor generate an ephemeral private key (config is nil or config.PrivateKey is nil). All of virtual ports specified in vports will be mapped to the port to which the underlying TCP listener binded. PortSpecs in config will be ignored since there is only one mapping for a vports set is possible.

func (*Conn) NewOnion

func (c *Conn) NewOnion(config *NewOnionConfig) (*OnionInfo, error)

NewOnion issues an ADD_ONION command using configuration config and returns the parsed response.

func (*Conn) NextEvent

func (c *Conn) NextEvent() (*Response, error)

NextEvent returns the next asynchronous event received, blocking if neccecary. In order to enable asynchronous event handling, StartAsyncReader must be called first.

func (*Conn) ProtocolInfo

func (c *Conn) ProtocolInfo() (*ProtocolInfo, error)

ProtocolInfo issues a PROTOCOLINFO command and returns the parsed response.

func (*Conn) Read

func (c *Conn) Read(p []byte) (int, error)

Read reads directly from the control port connection. Mixing this call with Request, ReadResponse, or asynchronous events will lead to undefined behavior.

func (*Conn) ReadResponse

func (c *Conn) ReadResponse() (*Response, error)

ReadResponse returns the next response object. Calling this simultaniously with Read, Request, or StartAsyncReader will lead to undefined behavior

func (*Conn) Request

func (c *Conn) Request(fmt string, args ...interface{}) (*Response, error)

Request sends a raw control port request and returns the response. If the async. reader is not currently running, events received while waiting for the response will be silently dropped. Calling Request simultaniously with StartAsyncReader, Read, Write, or ReadResponse will lead to undefined behavior.

func (*Conn) StartAsyncReader

func (c *Conn) StartAsyncReader()

StartAsyncReader starts the asynchronous reader go routine that allows asynchronous events to be handled. It must not be called simultaniously with Read, Request, or ReadResponse or undefined behavior will occur.

func (*Conn) Write

func (c *Conn) Write(p []byte) (int, error)

Write writes directly from the control port connection. Mixing this call with Request will lead to undefined behavior.

type NewOnionConfig

type NewOnionConfig struct {
	PortSpecs    []OnionPortSpec
	PrivateKey   crypto.PrivateKey
	DiscardPK    bool
	Detach       bool
	BasicAuth    bool
	NonAnonymous bool
}

NewOnionConfig is a configuration for NewOnion command.

type OnionInfo

type OnionInfo struct {
	OnionID    string
	PrivateKey crypto.PrivateKey

	RawResponse *Response
}

OnionInfo is the result of the AddOnion command.

type OnionPortSpec

type OnionPortSpec struct {
	VirtPort uint16
	Target   string
}

OnionPortSpec is a Onion VirtPort/Target pair.

type OnionPrivateKey

type OnionPrivateKey struct {
	KeyType string
	Key     string
}

OnionPrivateKey is a unknown Onion private key (crypto.PublicKey).

type ProtocolInfo

type ProtocolInfo struct {
	AuthMethods map[string]bool
	CookieFile  string
	TorVersion  string

	RawResponse *Response
}

ProtocolInfo is the result of the ProtocolInfo command.

type Response

type Response struct {
	// Err is the status code and string representation associated with a
	// response.  Responses that have completed successfully will also have
	// Err set to indicate such.
	Err *textproto.Error

	// Reply is the text on the EndReplyLine of the response.
	Reply string

	// Data is the MidReplyLines/DataReplyLines of the response.  Dot encoded
	// data is "decoded" and presented as a single string (terminal ".CRLF"
	// removed, all intervening CRs stripped).
	Data []string

	// RawLines is all of the lines of a response, without CRLFs.
	RawLines []string
}

Response is a response to a control port command, or an asyncrhonous event.

func (*Response) IsAsync

func (r *Response) IsAsync() bool

IsAsync returns true if the response is an asyncrhonous event.

func (*Response) IsOk

func (r *Response) IsOk() bool

IsOk returns true if the response status code indicates success or an asynchronous event.