bulb: github.com/Yawning/bulb Index | Files | Directories

package bulb

import "github.com/Yawning/bulb"

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


Package Files

cmd_authenticate.go cmd_onion.go cmd_protocolinfo.go conn.go dialer.go listener.go response.go status.go


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.


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.

type Conn Uses

type Conn struct {
    // contains filtered or unexported fields

Conn is a control port connection instance.

func Dial Uses

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

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

func NewConn Uses

func NewConn(c io.ReadWriteCloser) *Conn

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

func (*Conn) AddOnion Uses

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 Uses

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 Uses

func (c *Conn) Close() error

Close closes the connection.

func (*Conn) Debug Uses

func (c *Conn) Debug(enable bool)

Debug enables/disables debug logging of control port chatter.

func (*Conn) DeleteOnion Uses

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

DeleteOnion issues a DEL_ONION command and returns the parsed response.

func (*Conn) Dialer Uses

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

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

func (*Conn) Listener Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

ProtocolInfo issues a PROTOCOLINFO command and returns the parsed response.

func (*Conn) Read Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

type OnionInfo struct {
    OnionID    string
    PrivateKey crypto.PrivateKey

    RawResponse *Response

OnionInfo is the result of the AddOnion command.

type OnionPortSpec Uses

type OnionPortSpec struct {
    VirtPort uint16
    Target   string

OnionPortSpec is a Onion VirtPort/Target pair.

type OnionPrivateKey Uses

type OnionPrivateKey struct {
    KeyType string
    Key     string

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

type ProtocolInfo Uses

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

    RawResponse *Response

ProtocolInfo is the result of the ProtocolInfo command.

type Response Uses

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 Uses

func (r *Response) IsAsync() bool

IsAsync returns true if the response is an asyncrhonous event.

func (*Response) IsOk Uses

func (r *Response) IsOk() bool

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


utilsPackage utils implements useful utilities for dealing with Tor and it's control port.
utils/pkcs1Package pkcs1 implements PKCS#1 RSA key marshalling/unmarshalling, compatibile with Tor's usage.

Package bulb imports 20 packages (graph) and is imported by 4 packages. Updated 2017-12-23. Refresh now. Tools for package owners.