Update README
This commit is contained in:
parent
dba7e8856b
commit
c11e3bb90d
79
README.md
79
README.md
|
@ -1,9 +1,76 @@
|
|||
# Bine
|
||||
|
||||
Under development. Goals:
|
||||
[![GoDoc](https://godoc.org/github.com/cretz/bine?status.svg)](https://godoc.org/github.com/cretz/bine)
|
||||
|
||||
* Golang equivalent of https://stem.torproject.org/ (e.g. a maintained https://github.com/yawning/bulb)
|
||||
* Support everything Stem supports
|
||||
* Provide Golang abstractions (net.Conn, net.Listener) on onion services
|
||||
* Key generation utilities
|
||||
* Support statically compiled Tor (akin to how I did https://github.com/cretz/rtsw-poc)
|
||||
Bine is a Go API for using and controlling Tor. It is similar to [Stem](https://stem.torproject.org/).
|
||||
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
```go
|
||||
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 an onion service to listen on any port but show as 80
|
||||
onion, err := t.Listen(listenCtx, &tor.ListenConf{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](https://godoc.org/github.com/cretz/bine/process/embedded)
|
||||
which will require [building Tor statically](https://github.com/cretz/tor-static). Then with
|
||||
`github.com/cretz/bine/process/embedded` imported, change the start line above to:
|
||||
|
||||
```go
|
||||
t, err := tor.Start(nil, &tor.StartConf{ProcessCreator: embedded.NewCreator()})
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
Also take a look at the [API docs](http://godoc.org/github.com/cretz/bine) and the [examples](examples). The project is
|
||||
MIT licensed. The Tor docs/specs and https://github.com/yawning/bulb were great helps when building this.
|
|
@ -0,0 +1,8 @@
|
|||
### Bine Examples
|
||||
|
||||
The following examples are in this directory:
|
||||
|
||||
* [simpleclient](simpleclient) - A simple Tor client for connecting to the web or other onion services
|
||||
* [simpleserver](simpleserver) - Hosting simple "hello world" Tor onion service
|
||||
* [embeddedversion](embeddedversion) - Example showing how to dump the version of Tor embedded in the binary
|
||||
* [embeddedfileserver](embeddedfileserver) - Example showing a file server using Tor embedded in the binary
|
Loading…
Reference in New Issue