torctrlgo

package module
v0.0.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 29, 2024 License: MIT Imports: 17 Imported by: 0

README

torctrlgo - client to control your TOR instance

Go Reference build

Introduction

This is by far not a finished product.
My testing capabilities are quite limited, since I don't have a running relay and some features aren't activated.
Please report any bugs you encounter.

torctrlgo provides two different APIs.

Controller (high-level API)

The Controller API is under development. This most likely won't change any time soon. There are a wide variety of tasks, that could and should be implemented for ease of use.

If features aren't available using the Controller API, you can always access the LowController underneath.

I'm writing this mostly for fun. My use cases are limited and I have limited knowledge on which functions are needed and which functions are just too niche.
I'd love to get suggestions and submissions for new functions for the Controller API.

LowController (low-level API)

The LowController API is (for now) feature-complete. It implements all functions provided by the protocol. Future versions of TOR may change, how the protocol works and torctrlgo will need to be updated. TOR defines how the protocol will change and torctrlgo implements many compatibility conditions. In the foreseeable future, LowController shouldn't break easily.

For documentation see here.
To use this API I'd recommend looking at the control-spec documentation of TOR.

Documentation

Index

Constants

View Source 
const (
	GENERATE_BEST       = "BEST"
	GENERATE_RSA1024    = "RSA1024"
	GENERATE_ED25519_V3 = "ED25519-V3"
)
View Source 
const (
	FLAG_ADD_ONION_DISCARD_PK                = "DiscardPK"
	FLAG_ADD_ONION_DETACH                    = "Detach"
	FLAG_ADD_ONION_BASIC_AUTH                = "BasicAuth"
	FLAG_ADD_ONION_V3_AUTH                   = "V3Auth"
	FLAG_ADD_ONION_NON_ANONYMOUS             = "NonAnonymous"
	FLAG_ADD_ONION_MAX_STREAMS_CLOSE_CIRCUIT = "MaxStreamsCloseCircuit"
)
View Source 
const (
	FLAG_CLOSECIRCUIT_IFUNUSED = "IfUnused"
)

Variables

View Source 
var (
	ErrOperationUnnecessary        = errors.New("operation was unnecessary")
	ErrResourceExhausted           = errors.New("resource exhausted")
	ErrProtocolSyntaxError         = errors.New("syntax error: protocol")
	ErrUnrecognizedCommand         = errors.New("unrecognized command")
	ErrUnimplementedCommand        = errors.New("unimplemented command")
	ErrSyntaxCommandArgument       = errors.New("syntax error in command argument")
	ErrUnrecognizedCommandArgument = errors.New("unrecognized command argument")
	ErrAuthenticationRequired      = errors.New("authentication required")
	ErrBadAuthentication           = errors.New("bad authentication")
	ErrUnspecified                 = errors.New("unspecified Tor error")
	ErrInternal                    = errors.New("internal error")
	ErrUnrecognizedEntity          = errors.New("unrecognized entity")
	ErrInvalidConfigurationValue   = errors.New("invalid configuration value")
	ErrInvalidDescriptor           = errors.New("invalid descriptor")
	ErrUnmanagedEntity             = errors.New("unmanaged entity")

	ErrUnknown = errors.New("unknown status code")
)

Functions

func ParseStringDict added in v0.0.8 

func ParseStringDict(s string) map[string]string

func ReadQCString added in v0.0.8 

func ReadQCString(st string) (string, int)

func WriteQString added in v0.0.10 

func WriteQString(s string) string

Types

type AuthData 

type AuthData struct {
	Password   string
	CookieData []byte
}

AuthData declares the data passed for authentication.

  • Password may be declared for AUTH_HASHEDPASSWORD authentication.
  • CookieData may be declared to pass a cookie-file's contents manually. If CookieData is nil, AUTH_COOKIE and AUTH_SAFECOOKIE authentication will read the first available cookie-file's contents automatically.

type AuthMethod 

type AuthMethod string

AuthMethod declares the way of authentication on the ControlPort connection. 

const (
	// AUTH_NULL No authentication is required.
	//
	// To prevent cross-protocol attacks, calling authenticate is still required, even when all methods are disabled.
	AUTH_NULL AuthMethod = "NULL"
	// AUTH_HASHEDPASSWORD A password needs to be presented.
	//
	// The password's hash is defined in the configuration.
	AUTH_HASHEDPASSWORD AuthMethod = "HASHEDPASSWORD"
	// AUTH_COOKIE A cookie-file's contents must be provided.
	//
	// The Controller needs to prove its privileges to read one of them.
	AUTH_COOKIE AuthMethod = "COOKIE"
	// AUTH_SAFECOOKIE A Challenge must be completed
	//
	// The Controller needs to prove its knowledge of a cookie-file, similar to AUTH_COOKIE.
	AUTH_SAFECOOKIE AuthMethod = "SAFECOOKIE"
)

type Controller 

type Controller struct {
	VersionStatus string
	LowController *LowController
	// contains filtered or unexported fields
}

Controller provides a high-level API for communication over TOR's ControlPort protocol.

Certain functions may declare high concurrency-safety.

func NewController 

func NewController() *Controller

func (*Controller) Authenticate 

func (c *Controller) Authenticate(method AuthMethod, data AuthData) error

Authenticate the connection using the given AuthMethod and (if required) AuthData

This function is fully thread-safe, although there shouldn't be any scenario, where that's applicable

func (*Controller) AvailableConfigs added in v0.0.5 

func (c *Controller) AvailableConfigs() map[string][2]string

func (*Controller) AvailableEvents added in v0.0.5 

func (c *Controller) AvailableEvents() []string

func (*Controller) AvailableFeatures added in v0.0.5 

func (c *Controller) AvailableFeatures() []string

func (*Controller) AvailableInfos added in v0.0.5 

func (c *Controller) AvailableInfos() map[string]string

func (*Controller) AvailableSignals added in v0.0.5 

func (c *Controller) AvailableSignals() []string

func (*Controller) HSDescAvailable 

func (c *Controller) HSDescAvailable(addr string) (bool, error)

HSDescAvailable checks for the availability of the given hidden service on the hash-ring. This usually means, that the hidden service is reachable.

This function is fully thread-safe

func (*Controller) NewForwarder added in v0.0.6 

func (c *Controller) NewForwarder(ports []HSPortConfig, keyBlob string, auths []HSAuthConfig) (*HiddenService, error)

func (*Controller) NewIdentity 

func (c *Controller) NewIdentity() error

NewIdentity switches to new circuits, so that new requests don't share any circuits with old ones.

This function is fully thread-safe, although TOR might rate-limit its usage.

func (*Controller) NewListener added in v0.0.6 

func (c *Controller) NewListener(virtPort uint16, keyBlob string, auths []HSAuthConfig) (net.Listener, *HiddenService, error)

func (*Controller) Online added in v0.0.5 

func (c *Controller) Online() bool

func (*Controller) Open 

func (c *Controller) Open(addr string) error

func (*Controller) RegisterEvent 

func (c *Controller) RegisterEvent(code EventCode, callback func([]ReplyLine)) (int, error)

RegisterEvent adds a callback function for the given event.

This function is fully thread-safe.

func (*Controller) TorRCPath 

func (c *Controller) TorRCPath() string

func (*Controller) TorVersion 

func (c *Controller) TorVersion() string

func (*Controller) UnregisterEvent 

func (c *Controller) UnregisterEvent(code EventCode, id int) error

UnregisterEvent removes a set callback function for the given event.

This function is fully thread-safe.

type EventCode 

type EventCode string
const (
	EVENT_CIRC               EventCode = "CIRC"
	EVENT_STREAM             EventCode = "STREAM"
	EVENT_ORCONN             EventCode = "ORCONN"
	EVENT_BW                 EventCode = "BW"
	EVENT_DEBUG              EventCode = "DEBUG"
	EVENT_INFO               EventCode = "INFO"
	EVENT_NOTICE             EventCode = "NOTICE"
	EVENT_WARN               EventCode = "WARN"
	EVENT_ERR                EventCode = "ERR"
	EVENT_NEWDESC            EventCode = "NEWDESC"
	EVENT_ADDRMAP            EventCode = "ADDRMAP"
	EVENT_AUTHDIR_NEWDESCS   EventCode = "AUTHDIR_NEWDESCS"
	EVENT_DESCCHANGED        EventCode = "DESCCHANGED"
	EVENT_STATUS_GENERAL     EventCode = "STATUS_GENERAL"
	EVENT_STATUS_CLIENT      EventCode = "STATUS_CLIENT"
	EVENT_STATUS_SERVER      EventCode = "STATUS_SERVER"
	EVENT_GUARD              EventCode = "GUARD"
	EVENT_NS                 EventCode = "NS"
	EVENT_STREAM_BW          EventCode = "STREAM_BW"
	EVENT_CLIENTS_SEEN       EventCode = "CLIENTS_SEEN"
	EVENT_NEWCONSENSUS       EventCode = "NEWCONSENSUS"
	EVENT_BUILDTIMEOUT_SET   EventCode = "BUILDTIMEOUT_SET"
	EVENT_SIGNAL             EventCode = "SIGNAL"
	EVENT_CONF_CHANGED       EventCode = "CONF_CHANGED"
	EVENT_CIRC_MINOR         EventCode = "CIRC_MINOR"
	EVENT_TRANSPORT_LAUNCHED EventCode = "TRANSPORT_LAUNCHED"
	EVENT_CONN_BW            EventCode = "CONN_BW"
	EVENT_CIRC_BW            EventCode = "CIRC_BW"
	EVENT_CELL_STATS         EventCode = "CELL_STATS"
	EVENT_TB_EMPTY           EventCode = "TB_EMPTY"
	EVENT_HS_DESC            EventCode = "HS_DESC"
	EVENT_HS_DESC_CONTENT    EventCode = "HS_DESC_CONTENT"
	EVENT_NETWORK_LIVENESS   EventCode = "NETWORK_LIVENESS"
	EVENT_PT_LOG             EventCode = "PT_LOG"
	EVENT_PT_STATUS          EventCode = "PT_STATUS"
)

type HSAuthConfig added in v0.0.3 

type HSAuthConfig struct {
	ClientName string
	AuthBlob   string
}

type HSConfigReply added in v0.0.3 

type HSConfigReply struct {
	ServiceID string
	KeyType   KeyType
	KeyBlob   string
	Auths     []HSAuthConfig
}

type HSPortConfig added in v0.0.3 

type HSPortConfig struct {
	VirtPort uint16
	Target   string
}

type HiddenService added in v0.0.6 

type HiddenService struct {
	Config *HSConfigReply
	// contains filtered or unexported fields
}

type KeyType added in v0.0.3 

type KeyType string
const (
	// KEYTYPE_X25519 Only for use in OnionClientAuth
	KEYTYPE_X25519 KeyType = "x25519"
	// KEYTYPE_NEW pseudo-keytype, only for use in LowController.AddOnion
	KEYTYPE_NEW KeyType = "NEW"
	// KEYTYPE_RSA1024 Only for use in LowController.AddOnion
	KEYTYPE_RSA1024 KeyType = "RSA1024"
	// KEYTYPE_ED25519_V3 Only for use in LowController.AddOnion
	KEYTYPE_ED25519_V3 KeyType = "ED25519-V3"
)

type LowController 

type LowController struct {
	NotificationChan chan []ReplyLine

	Debug bool
	// contains filtered or unexported fields
}

LowController provides a low-level API for communication over TOR's ControlPort protocol.

All exported functions are concurrency-safe. Since TOR processes commands sequentially,

func NewLowController 

func NewLowController() *LowController

func (*LowController) AddOnion added in v0.0.3 

func (c *LowController) AddOnion(keyType KeyType, keyBlob string, flags []string, maxStreams uint16, ports []HSPortConfig, auths []HSAuthConfig) (*HSConfigReply, error)

func (*LowController) AttachStream added in v0.0.4 

func (c *LowController) AttachStream(streamID string, circuitID, hopNum int) error

func (*LowController) AuthChallenge 

func (c *LowController) AuthChallenge(chllngType string, clientNonce []byte) (serverHash []byte, serverNonce []byte, err error)

func (*LowController) AuthenticateBytes 

func (c *LowController) AuthenticateBytes(data []byte) error

func (*LowController) AuthenticateNull 

func (c *LowController) AuthenticateNull() error

func (*LowController) AuthenticateString 

func (c *LowController) AuthenticateString(data string) error

func (*LowController) CloseCircuit added in v0.0.4 

func (c *LowController) CloseCircuit(circuitID int, flags []string) error

func (*LowController) CloseStream added in v0.0.4 

func (c *LowController) CloseStream(streamID string, reason RelayEndReason, flags []string) error

func (*LowController) DelOnion added in v0.0.3 

func (c *LowController) DelOnion(HSAddr string) error

func (*LowController) DropGuards added in v0.0.4 

func (c *LowController) DropGuards() error

func (*LowController) DropOwnership added in v0.0.3 

func (c *LowController) DropOwnership() error

func (*LowController) DropTimeouts added in v0.0.3 

func (c *LowController) DropTimeouts() error

func (*LowController) ExtendCircuit added in v0.0.4 

func (c *LowController) ExtendCircuit(circuitID int, path []string, purpose string) (int, error)

func (*LowController) GetConf 

func (c *LowController) GetConf(names []string) (configs map[string][]string, defaults map[string]int, err error)

func (*LowController) GetInfo 

func (c *LowController) GetInfo(keywords []string) (map[string]string, error)

func (*LowController) GetProtocolInfo 

func (c *LowController) GetProtocolInfo(versions []string) (*ProtocolInfo, error)

func (*LowController) HSFetch 

func (c *LowController) HSFetch(addressOrDescriptorID string, servers []string) error

func (*LowController) HSPost added in v0.0.3 

func (c *LowController) HSPost(servers []string, HSAddr string, descriptor string) error

func (*LowController) LoadConf added in v0.0.4 

func (c *LowController) LoadConf(config string) error

func (*LowController) MapAddress added in v0.0.4 

func (c *LowController) MapAddress(addrs map[string]string) (map[string]string, error)

func (*LowController) OnionClientAuthAdd added in v0.0.3 

func (c *LowController) OnionClientAuthAdd(auth OnionClientAuth) error

func (*LowController) OnionClientAuthRemove added in v0.0.3 

func (c *LowController) OnionClientAuthRemove(HSAddr string) error

func (*LowController) OnionClientAuthView added in v0.0.3 

func (c *LowController) OnionClientAuthView(HSAddr string) ([]OnionClientAuth, error)

func (*LowController) Open 

func (c *LowController) Open(addr string) (err error)

func (*LowController) PostDescriptor added in v0.0.4 

func (c *LowController) PostDescriptor(purpose string, cache string, descriptor string) error

func (*LowController) Quit 

func (c *LowController) Quit() error

func (*LowController) RedirectStream added in v0.0.4 

func (c *LowController) RedirectStream(streamID string, address string, port uint16) error

func (*LowController) ResetConf 

func (c *LowController) ResetConf(confs map[string]string) error

func (*LowController) Resolve 

func (c *LowController) Resolve(addrs []string, reverse bool) error

func (*LowController) SaveConf 

func (c *LowController) SaveConf(force bool) error

func (*LowController) SendSignal 

func (c *LowController) SendSignal(signal Signal) error

func (*LowController) SetCircuitPurpose added in v0.0.4 

func (c *LowController) SetCircuitPurpose(circuitID int, purpose string) error

func (*LowController) SetConf 

func (c *LowController) SetConf(confs map[string]string) error

func (*LowController) SetEvents 

func (c *LowController) SetEvents(codes []string) error

func (*LowController) TakeOwnership added in v0.0.3 

func (c *LowController) TakeOwnership() error

func (*LowController) UseFeature added in v0.0.3 

func (c *LowController) UseFeature(features []string) error

type OnionClientAuth added in v0.0.3 

type OnionClientAuth struct {
	HSAddr     string
	KType      KeyType
	KeyBlob    []byte
	ClientName string
	Flags      []string
}

type ProtocolInfo 

type ProtocolInfo struct {
	PIVERSION   string
	TorVersion  string
	AuthMethods []string
	CookieFiles []string
	OtherLines  []string
}

type RelayEndReason added in v0.0.4 

type RelayEndReason byte
const (
	RELAY_END_REASON_MISC           RelayEndReason = 1
	RELAY_END_REASON_RESOLVEFAILED  RelayEndReason = 2
	RELAY_END_REASON_CONNECTREFUSED RelayEndReason = 3
	RELAY_END_REASON_EXITPOLICY     RelayEndReason = 4
	RELAY_END_REASON_DESTROY        RelayEndReason = 5
	RELAY_END_REASON_DONE           RelayEndReason = 6
	RELAY_END_REASON_TIMEOUT        RelayEndReason = 7
	RELAY_END_REASON_NOROUTE        RelayEndReason = 8
	RELAY_END_REASON_HIBERNATING    RelayEndReason = 9
	RELAY_END_REASON_INTERNAL       RelayEndReason = 10
	RELAY_END_REASON_RESOURCELIMIT  RelayEndReason = 11
	RELAY_END_REASON_CONNRESET      RelayEndReason = 12
	RELAY_END_REASON_TORPROTOCOL    RelayEndReason = 13
	RELAY_END_REASON_NOTDIRECTORY   RelayEndReason = 14
)

type ReplyLine 

type ReplyLine struct {
	StatusCode uint16
	Separator  byte
	Line       []byte
}

type Signal 

type Signal string
const (
	SIGNAL_RELOAD        Signal = "RELOAD"
	SIGNAL_HUP           Signal = "HUP" // Same as SIGNAL_RELOAD
	SIGNAL_SHUTDOWN      Signal = "SHUTDOWN"
	SIGNAL_INT           Signal = "INT" // Same as SIGNAL_SHUTDOWN
	SIGNAL_DUMP          Signal = "DUMP"
	SIGNAL_USR1          Signal = "USR1" // Same as SIGNAL_DUMP
	SIGNAL_DEBUG         Signal = "DEBUG"
	SIGNAL_USR2          Signal = "USR2" // Same as SIGNAL_DEBUG
	SIGNAL_HALT          Signal = "HALT"
	SIGNAL_TERM          Signal = "TERM" // Same as SIGNAL_HALT
	SIGNAL_CLEARDNSCACHE Signal = "CLEARDNSCACHE"
	SIGNAL_NEWNYM        Signal = "NEWNYM"
	SIGNAL_HEARTBEAT     Signal = "HEARTBEAT"
	SIGNAL_DORMANT       Signal = "DORMANT"
	SIGNAL_ACTIVE        Signal = "ACTIVE"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.