torgo

README ¶

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 ¶

func NewClient(addr string) (*http.Client, error)
func ServiceIDFromEd25519(pub ed25519.PublicKey) (string, error)
func ServiceIDFromRSA(pub *rsa.PublicKey) (string, error)
type Controller
- func NewController(addr string) (*Controller, error)
type Onion
- func OnionFromEd25519(pri ed25519.PrivateKey) (*Onion, error)
- func OnionFromRSA(pri *rsa.PrivateKey) (*Onion, error)

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.

package main

import (
	"io"
	"log"
	"os"

	"github.com/wybiral/torgo"
)

func main() {
	// Create client from SOCKS proxy address
	client, err := torgo.NewClient("127.0.0.1:9050")
	if err != nil {
		log.Fatal(err)
	}
	// Perform HTTP GET request
	resp, err := client.Get("http://httpbin.org/ip")
	if err != nil {
		log.Fatal(err)
	}
	// Copy response to Stdout
	io.Copy(os.Stdout, resp.Body)
}

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.

package main

import (
	"fmt"
	"log"

	"github.com/wybiral/torgo"
	"golang.org/x/crypto/ed25519"
)

var publicKeyEd25519 ed25519.PublicKey

func main() {
	// Calculate service ID
	serviceID, err := torgo.ServiceIDFromEd25519(publicKeyEd25519)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(serviceID)
}

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.

package main

import (
	"crypto/rsa"
	"fmt"
	"log"

	"github.com/wybiral/torgo"
)

var publicKeyRSA *rsa.PublicKey

func main() {
	// Calculate service ID
	serviceID, err := torgo.ServiceIDFromRSA(publicKeyRSA)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(serviceID)
}

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.

package main

import (
	"fmt"
	"log"

	"github.com/wybiral/torgo"
)

func main() {
	// Address of control port
	addr := "127.0.0.1:9051"
	controller, err := torgo.NewController(addr)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(controller)
}

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.

package main

import (
	"fmt"
	"log"

	"github.com/wybiral/torgo"
)

var controller *torgo.Controller

func main() {
	// Define onion that maps virtual port 80 to local port 8080
	onion := &torgo.Onion{Ports: map[int]string{
		80: "127.0.0.1:8080",
	}}
	// Add onion to controller
	err := controller.AddOnion(onion)
	if err != nil {
		log.Fatal(err)
	}
	// Print onion ID (address without ".onion" ending)
	fmt.Println(onion.ServiceID)
}

Output:

Example (Ed25519) ¶

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

package main

import (
	"fmt"
	"log"

	"github.com/wybiral/torgo"
)

var controller *torgo.Controller

func main() {
	// Define onion that maps virtual port 80 to local port 8080
	onion := &torgo.Onion{
		Ports: map[int]string{
			80: "127.0.0.1:8080",
		},
		PrivateKeyType: "NEW",
		PrivateKey:     "ED25519-V3",
	}
	// Add onion to controller
	err := controller.AddOnion(onion)
	if err != nil {
		log.Fatal(err)
	}
	// Print onion ID (address without ".onion" ending)
	fmt.Println(onion.ServiceID)
}

Output:

func (*Controller) AuthenticateCookie ¶

func (c *Controller) AuthenticateCookie() error

AuthenticateCookie authenticate to controller with cookie from current CookieFile path.

Example ¶

Authenticate with cookie file.

package main

import (
	"log"

	"github.com/wybiral/torgo"
)

var controller *torgo.Controller

func main() {
	err := controller.AuthenticateCookie()
	if err != nil {
		log.Fatal(err)
	}
}

Output:

func (*Controller) AuthenticateNone ¶

func (c *Controller) AuthenticateNone() error

AuthenticateNone authenticate to controller without password or cookie.

Example ¶

Authenticate without password or cookie file.

package main

import (
	"log"

	"github.com/wybiral/torgo"
)

var controller *torgo.Controller

func main() {
	err := controller.AuthenticateNone()
	if err != nil {
		log.Fatal(err)
	}
}

Output:

func (*Controller) AuthenticatePassword ¶

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

AuthenticatePassword authenticate to controller with password.

Example ¶

Authenticate with password.

package main

import (
	"log"

	"github.com/wybiral/torgo"
)

var controller *torgo.Controller

func main() {
	err := controller.AuthenticatePassword("pa55w0rd")
	if err != nil {
		log.Fatal(err)
	}
}

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

package main

import (
	"log"

	"github.com/wybiral/torgo"
)

var onion *torgo.Onion
var controller *torgo.Controller

func main() {
	err := controller.DeleteOnion(onion.ServiceID)
	if err != nil {
		log.Fatal(err)
	}
}

Output:

func (*Controller) GetAddress ¶

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

GetAddress returns the current external IP address.

Example ¶

Print external IP address.

package main

import (
	"fmt"
	"log"

	"github.com/wybiral/torgo"
)

var controller *torgo.Controller

func main() {
	address, err := controller.GetAddress()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(address)
}

Output:

func (*Controller) GetBytesRead ¶

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

GetBytesRead returns total bytes downloaded.

Example ¶

Print total bytes read (downloaded).

package main

import (
	"fmt"
	"log"

	"github.com/wybiral/torgo"
)

var controller *torgo.Controller

func main() {
	n, err := controller.GetBytesRead()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(n)
}

Output:

func (*Controller) GetBytesWritten ¶

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

GetBytesWritten returns total bytes uploaded.

Example ¶

Print total bytes written (uploaded).

package main

import (
	"fmt"
	"log"

	"github.com/wybiral/torgo"
)

var controller *torgo.Controller

func main() {
	n, err := controller.GetBytesWritten()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(n)
}

Output:

func (*Controller) GetConfigFile ¶

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

GetConfigFile return path to Tor config file.

Example ¶

Print path to Tor configuration file.

package main

import (
	"fmt"
	"log"

	"github.com/wybiral/torgo"
)

var controller *torgo.Controller

func main() {
	config, err := controller.GetConfigFile()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(config)
}

Output:

func (*Controller) GetTorPid ¶

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

GetTorPid returns PID for current Tor process.

Example ¶

Print PID of Tor process.

package main

import (
	"fmt"
	"log"

	"github.com/wybiral/torgo"
)

var controller *torgo.Controller

func main() {
	pid, err := controller.GetTorPid()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(pid)
}

Output:

func (*Controller) GetVersion ¶

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

GetVersion returns version of Tor server.

Example ¶

Return version of Tor server.

package main

import (
	"fmt"
	"log"

	"github.com/wybiral/torgo"
)

var controller *torgo.Controller

func main() {
	version, err := controller.GetVersion()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(version)
}

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.

package main

import (
	"log"

	"github.com/wybiral/torgo"
)

var controller *torgo.Controller

func main() {
	err := controller.Signal("NEWNYM")
	if err != nil {
		log.Fatal(err)
	}
}

Output:

Example (Reload) ¶

Send signal to reload configuration.

package main

import (
	"log"

	"github.com/wybiral/torgo"
)

var controller *torgo.Controller

func main() {
	err := controller.Signal("RELOAD")
	if err != nil {
		log.Fatal(err)
	}
}

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.

package main

import (
	"fmt"
	"log"

	"github.com/wybiral/torgo"
	"golang.org/x/crypto/ed25519"
)

var controller *torgo.Controller

var privateKeyEd25519 ed25519.PrivateKey

func main() {
	// Create Onion from private key (does not start hidden service)
	onion, err := torgo.OnionFromEd25519(privateKeyEd25519)
	if err != nil {
		log.Fatal(err)
	}
	// Set port mapping from hidden service 80 to localhost:8080
	onion.Ports[80] = "localhost:8080"
	// Print service ID for Onion
	fmt.Println(onion.ServiceID)
	// Start hidden service
	controller.AddOnion(onion)
}

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.

package main

import (
	"crypto/rsa"
	"fmt"
	"log"

	"github.com/wybiral/torgo"
)

var controller *torgo.Controller
var privateKeyRSA *rsa.PrivateKey

func main() {
	// Create Onion from private key (does not start hidden service)
	onion, err := torgo.OnionFromRSA(privateKeyRSA)
	if err != nil {
		log.Fatal(err)
	}
	// Set port mapping from hidden service 80 to localhost:8080
	onion.Ports[80] = "localhost:8080"
	// Print service ID for Onion
	fmt.Println(onion.ServiceID)
	// Start hidden service
	controller.AddOnion(onion)
}

Output:

Source Files ¶

View all

Directories ¶

Path	Synopsis
examples
hello-world

?	: This menu
/	: Search site
f or F	: Jump to

torgo

README ¶

torgo

Examples

Documentation ¶

Overview ¶

Index ¶

Examples ¶

Constants ¶

Variables ¶

Functions ¶

func NewClient ¶

func ServiceIDFromEd25519 ¶

func ServiceIDFromRSA ¶

Types ¶

type Controller ¶

func NewController ¶

func (*Controller) AddOnion ¶

func (*Controller) AuthenticateCookie ¶

func (*Controller) AuthenticateNone ¶

func (*Controller) AuthenticatePassword ¶

func (*Controller) DeleteOnion ¶

func (*Controller) GetAddress ¶

func (*Controller) GetBytesRead ¶

func (*Controller) GetBytesWritten ¶

func (*Controller) GetConfigFile ¶

func (*Controller) GetTorPid ¶

func (*Controller) GetVersion ¶

func (*Controller) SetConf ¶

func (*Controller) Signal ¶

type Onion ¶

func OnionFromEd25519 ¶

func OnionFromRSA ¶

Source Files ¶

Directories ¶

Details

Repository

Jump to

Keyboard shortcuts