README

torgo GoDoc

This is a Go library for interacting with Tor over the standard controller interface. It simplifies tasks like creating ephemeral hidden services, working with private keys, and making SOCKS proxied client requests on the Tor network.

Examples

Expand ▾ Collapse ▴

Documentation

Overview

    Package torgo provides a Golang controller interface for Tor.

    Index

    Examples

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func NewClient

    func NewClient(addr string) (*http.Client, error)

      NewClient return new HTTP client that uses a Tor SOCKS proxy. `addr` is the host:port address of SOCKS proxy (usually "127.0.0.1:9050")

      Example (Httpget)

        Create a new Tor SOCKS HTTP client and request current IP from httpbin.org.

        Output:
        
        

        func ServiceIDFromEd25519

        func ServiceIDFromEd25519(pub ed25519.PublicKey) (string, error)

          ServiceIDFromEd25519 calculates a Tor service ID from an ed25519.PublicKey.

          Example

            Calculate Tor service ID from ed25519.PublicKey.

            Output:
            
            

            func ServiceIDFromRSA

            func ServiceIDFromRSA(pub *rsa.PublicKey) (string, error)

              ServiceIDFromRSA calculates a Tor service ID from an *rsa.PublicKey.

              Example

                Calculate Tor service ID from *rsa.PublicKey.

                Output:
                
                

                Types

                type Controller

                type Controller struct {
                	// Array of available authentication methods.
                	AuthMethods []string
                	// Cookie file path (empty if not available).
                	CookieFile string
                	// Text is a textproto.Conn to the control port.
                	Text *textproto.Conn
                }

                  A Controller instance is a control port connection that provides methods for communicating with Tor.

                  func NewController

                  func NewController(addr string) (*Controller, error)

                    NewController returns a new Controller instance connecting to the control port at addr.

                    Example

                      Return a new Controller interface.

                      Output:
                      
                      

                      func (*Controller) AddOnion

                      func (c *Controller) AddOnion(onion *Onion) error

                        AddOnion adds Onion hidden service. If no private key is supplied one will be generated and the PrivateKeyType and PrivateKey properties will be set with the newly generated one. The hidden service will use port mapping contained in Ports map supplied. ServiceID will be assigned based on the private key and will be the address of this hidden service (without the ".onion" ending).

                        Example

                          Add onion and generate private key.

                          Output:
                          
                          
                          Example (Ed25519)

                            Add onion and generate private key (using ED25519-V3 key if supported).

                            Output:
                            
                            

                            func (*Controller) AuthenticateCookie

                            func (c *Controller) AuthenticateCookie() error

                              AuthenticateCookie authenticate to controller with cookie from current CookieFile path.

                              Example

                                Authenticate with cookie file.

                                Output:
                                
                                

                                func (*Controller) AuthenticateNone

                                func (c *Controller) AuthenticateNone() error

                                  AuthenticateNone authenticate to controller without password or cookie.

                                  Example

                                    Authenticate without password or cookie file.

                                    Output:
                                    
                                    

                                    func (*Controller) AuthenticatePassword

                                    func (c *Controller) AuthenticatePassword(password string) error

                                      AuthenticatePassword authenticate to controller with password.

                                      Example

                                        Authenticate with password.

                                        Output:
                                        
                                        

                                        func (*Controller) DeleteOnion

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

                                          DeleteOnion deletes an onion by its serviceID (stop hidden service created by this controller).

                                          Example

                                            Delete an onion by its ServiceID

                                            Output:
                                            
                                            

                                            func (*Controller) GetAddress

                                            func (c *Controller) GetAddress() (string, error)

                                              GetAddress returns the current external IP address.

                                              Example

                                                Print external IP address.

                                                Output:
                                                
                                                

                                                func (*Controller) GetBytesRead

                                                func (c *Controller) GetBytesRead() (int, error)

                                                  GetBytesRead returns total bytes downloaded.

                                                  Example

                                                    Print total bytes read (downloaded).

                                                    Output:
                                                    
                                                    

                                                    func (*Controller) GetBytesWritten

                                                    func (c *Controller) GetBytesWritten() (int, error)

                                                      GetBytesWritten returns total bytes uploaded.

                                                      Example

                                                        Print total bytes written (uploaded).

                                                        Output:
                                                        
                                                        

                                                        func (*Controller) GetConfigFile

                                                        func (c *Controller) GetConfigFile() (string, error)

                                                          GetConfigFile return path to Tor config file.

                                                          Example

                                                            Print path to Tor configuration file.

                                                            Output:
                                                            
                                                            

                                                            func (*Controller) GetTorPid

                                                            func (c *Controller) GetTorPid() (int, error)

                                                              GetTorPid returns PID for current Tor process.

                                                              Example

                                                                Print PID of Tor process.

                                                                Output:
                                                                
                                                                

                                                                func (*Controller) GetVersion

                                                                func (c *Controller) GetVersion() (string, error)

                                                                  GetVersion returns version of Tor server.

                                                                  Example

                                                                    Return version of Tor server.

                                                                    Output:
                                                                    
                                                                    

                                                                    func (*Controller) SetConf

                                                                    func (c *Controller) SetConf(param, value string) error

                                                                    func (*Controller) Signal

                                                                    func (c *Controller) Signal(signal string) error

                                                                      Signal sends a signal to the server. Tor documentations defines the following signals :

                                                                      * RELOAD
                                                                      * SHUTDOWN
                                                                      * DUMP
                                                                      * DEBUG
                                                                      * HALT
                                                                      * CLEARDNSCACHE
                                                                      * NEWNYM
                                                                      * HEARTBEAT
                                                                      * DORMANT
                                                                      * ACTIVE
                                                                      
                                                                      Example (Newnym)

                                                                        Send NEWSYM signal to switch to new clean circuits.

                                                                        Output:
                                                                        
                                                                        
                                                                        Example (Reload)

                                                                          Send signal to reload configuration.

                                                                          Output:
                                                                          
                                                                          

                                                                          type Onion

                                                                          type Onion struct {
                                                                          	// Ports maps virtual ports for the hidden service to local addresses.
                                                                          	Ports map[int]string
                                                                          	// ServiceID is the unique hidden service address (without ".onion" ending).
                                                                          	ServiceID string
                                                                          	// Base64 encoded private key for the hidden service.
                                                                          	PrivateKey string
                                                                          	// Type of private key (RSA1024 or ED25519-V3).
                                                                          	PrivateKeyType string
                                                                          }

                                                                            Onion represents a hidden service.

                                                                            func OnionFromEd25519

                                                                            func OnionFromEd25519(pri ed25519.PrivateKey) (*Onion, error)

                                                                              OnionFromEd25519 returns an Onion instance from an ED25519 private key which can be used to start a hidden service with controller.AddOnion.

                                                                              Example

                                                                                Create an Onion and start hidden service from an ed25519.PrivateKey.

                                                                                Output:
                                                                                
                                                                                

                                                                                func OnionFromRSA

                                                                                func OnionFromRSA(pri *rsa.PrivateKey) (*Onion, error)

                                                                                  OnionFromRSA returns an Onion instance from a 1024 bit RSA private key which can be used to start a hidden service with controller.AddOnion.

                                                                                  Example

                                                                                    Create an Onion and start hidden service from an rsa.PrivateKey.

                                                                                    Output:
                                                                                    
                                                                                    

                                                                                    Directories

                                                                                    Path Synopsis
                                                                                    examples