torgo

package module
v0.0.0-...-5fd9910 Latest Latest
Warning

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

 Go to latest Published: Dec 9, 2020 License: GPL-3.0 Imports: 20 Imported by: 10

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

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. 

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 Source files

Directories

Path Synopsis
examples
hello-world

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.