torctrlgo

package module
v0.0.4 Latest Latest
Warning

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

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

README

torctrlgo - client to control your TOR instance

Go Reference build

under development...

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

This section is empty.

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 {
	TorVersion    string
	TorRCPath     string
	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) 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) 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) Open

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

func (*Controller) RegisterEvent

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

RegisterEvent sets the callback function for the given event.

This function is fully thread-safe.

func (*Controller) UnregisterEvent

func (c *Controller) UnregisterEvent(code EventCode) error

UnregisterEvent removes the 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
	// contains filtered or unexported fields
}

type HSPortConfig added in v0.0.3

type HSPortConfig struct {
	VirtPort uint16
	Target   string
}

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
	// 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"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL