bine

package module
Version: v0.2.0 Latest Latest
Warning

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

Go to latest
Published: May 31, 2021 License: MIT Imports: 0 Imported by: 0

README

GoDoc

Bine is a Go API for using and controlling Tor. It is similar to Stem.

Features:

  • Full support for the Tor controller API
  • Support for net.Conn and net.Listen style APIs
  • Supports statically compiled Tor to embed Tor into the binary
  • Supports both v2 and v3 onion services
  • Support for embedded control socket in Tor >= 0.3.5 (non-Windows)

See info below, the API docs, and the examples. The project is MIT licensed. The Tor docs/specs and https://github.com/yawning/bulb were great helps when building this.

Example

It is really easy to create an onion service. For example, assuming tor is on the PATH, this bit of code will show a directory server of the current directory:

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"time"

	"github.com/cretz/bine/tor"
)

func main() {
	// Start tor with default config (can set start conf's DebugWriter to os.Stdout for debug logs)
	fmt.Println("Starting and registering onion service, please wait a couple of minutes...")
	t, err := tor.Start(nil, nil)
	if err != nil {
		log.Panicf("Unable to start Tor: %v", err)
	}
	defer t.Close()
	// Wait at most a few minutes to publish the service
	listenCtx, listenCancel := context.WithTimeout(context.Background(), 3*time.Minute)
	defer listenCancel()
	// Create a v3 onion service to listen on any port but show as 80
	onion, err := t.Listen(listenCtx, &tor.ListenConf{Version3: true, RemotePorts: []int{80}})
	if err != nil {
		log.Panicf("Unable to create onion service: %v", err)
	}
	defer onion.Close()
	fmt.Printf("Open Tor browser and navigate to http://%v.onion\n", onion.ID)
	fmt.Println("Press enter to exit")
	// Serve the current folder from HTTP
	errCh := make(chan error, 1)
	go func() { errCh <- http.Serve(onion, http.FileServer(http.Dir("."))) }()
	// End when enter is pressed
	go func() {
		fmt.Scanln()
		errCh <- nil
	}()
	if err = <-errCh; err != nil {
		log.Panicf("Failed serving: %v", err)
	}
}

If in main.go it can simply be run with go run main.go. Of course this uses a separate tor process. To embed Tor statically in the binary, follow the embedded package docs which will require building Tor statically. Then with github.com/cretz/bine/process/embedded imported, change the start line above to:

t, err := tor.Start(nil, &tor.StartConf{ProcessCreator: embedded.NewCreator()})

This defaults to Tor 0.3.5.x versions but others can be used from different packages. In non-Windows environments, the UseEmbeddedControlConn field in StartConf can be set to true to use an embedded socket that does not open a control port.

Tested on Windows, the original exe file is ~7MB. With Tor statically linked it comes to ~24MB, but Tor does not have to be distributed separately. Of course take notice of all licenses in accompanying projects.

Testing

To test, a simple go test ./... from the base of the repository will work (add in a -v in there to see the tests). The integration tests in tests however will be skipped. To execute those tests, -tor must be passed to the test. Also, tor must be on the PATH or -tor.path must be set to the path of the tor executable. Even with those flags, only the integration tests that do not connect to the Tor network are run. To also include the tests that use the Tor network, add the -tor.network flag. For details Tor logs during any of the integration tests, use the -tor.verbose flag.

Documentation

Overview

Bine is a toolkit to assist in creating Tor clients and servers. Features:

* Full support for the Tor controller API

* Support for `net.Conn` and `net.Listen` style APIs

* Supports statically compiled Tor to embed Tor into the binary

* Supports both v2 and v3 onion services

* Support for embedded control socket in Tor >= 0.3.5 (non-Windows)

Users of this library will usually use the high-level tor package. See README at https://github.com/cretz/bine for more info.

Source Files

Directories

Path Synopsis
Package control implements a low-level client for the Tor control spec version 1.
Package control implements a low-level client for the Tor control spec version 1.
examples module
Package process is the low-level abstraction for a Tor instance.
Package process is the low-level abstraction for a Tor instance.
embedded
Package embedded implements process interfaces for statically linked, embedded Tor.
Package embedded implements process interfaces for statically linked, embedded Tor.
embedded/tor-0.3.3
Package tor033 implements process interfaces for statically linked Tor 0.3.3.x versions.
Package tor033 implements process interfaces for statically linked Tor 0.3.3.x versions.
embedded/tor-0.3.5
Package tor035 implements process interfaces for statically linked Tor 0.3.5.x versions.
Package tor035 implements process interfaces for statically linked Tor 0.3.5.x versions.
Package tests contains integration tests.
Package tests contains integration tests.
Package tor is the high-level client for Tor.
Package tor is the high-level client for Tor.
Package torutil has generic utilities shared across the library.
Package torutil has generic utilities shared across the library.
ed25519
Package ed25519 implements Tor/BitTorrent-like ed25519 keys.
Package ed25519 implements Tor/BitTorrent-like ed25519 keys.
geoipembed
Package geoipembed contains embedded db files for GeoIP.
Package geoipembed contains embedded db files for GeoIP.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL