tordam

README

tor-dam (Tor Distributed Announce Mechanism)

A library for peer discovery inside the Tor network.

Installation

go get github.com/parazyd/tordam

Documentation

https://pkg.go.dev/github.com/parazyd/tordam

tor-dam is a small library that can be used to facilitate peer to peer services in the Tor network with simple mechanisms.

An integration example can be found and reviewed in the form of a single go file: cmd/tor-dam/tor-dam.go. It is procedural and well-documented so it should serve well for learning how to integrate the library into a Go program.

Most of the library's code is documented in the source, along with godoc.

Feature list

• Anonymous peer mapping in the Tor network
• Launching Tor and Hidden Services
• Port mapping to launched hidden service for easy anonymous services
• Exporting available peers through any marshaling interface (think peer list as JSON)

Documentation

Index

• Variables
• func Announce(onionaddr string) error
• func AppendPeers(p []string) error
• func GetAvailableListener() (*net.TCPAddr, error)
• func LogInit(f *os.File)
• func RandomGarbage(n int) (string, error)
• func SpawnTor(listener *net.TCPAddr, portmap []string, datadir string) (*exec.Cmd, error)
• func ValidateOnionAddress(addr string) error
• func ValidateOnionInternal(onionaddr string) error
• func ValidatePortmap(pm []string) error
• type Ann
  • func (Ann) Init(ctx context.Context, vals []string) ([]string, error)
  • func (Ann) Validate(ctx context.Context, vals []string) ([]string, error)
• type Config
• type Peer

Variables

var Cfg = Config{}

Cfg is the global config structure, to be filled by library user.

var Onion string

Onion is the library user's something.onion:port identifier. It can be read from the datadir once Tor is spawned.

var Peers = map[string]Peer{}

Peers is the global map of peers

var SignKey ed25519.PrivateKey

SignKey is an ed25519 private key, to be assigned by library user.

Functions

func Announce

func Announce(onionaddr string) error

Announce is a function that announces to a certain onion address. Upon success, it appends the peers received from the endpoint to the global Peers map, which in turn also writes it to the peers db file.

func AppendPeers

func AppendPeers(p []string) error

AppendPeers appends given []string peers to the global Peers map. Usually received by validating ourself to a peer and them replying with a list of their valid peers. If a peer is not in format of "unlikelyname.onion:port", they will not be appended. As a placeholder, this function can return an error, but it has no reason to do so right now.

func GetAvailableListener

func GetAvailableListener() (*net.TCPAddr, error)

GetAvailableListener is a helper function to return a *net.TCPAddr on some port that is available for listening on the system. It uses the :0 port which the kernel utilizes to return a random available port.

func LogInit

func LogInit(f *os.File)

LogInit is the initializer for the internal tordam logging functions. It should be called from programs using the library, with something like:

tordam.LogInit(os.Stdout)

func RandomGarbage

func RandomGarbage(n int) (string, error)

RandomGarbage returns a base64 encoded string of n bytes of entropy.

func SpawnTor

func SpawnTor(listener *net.TCPAddr, portmap []string, datadir string) (*exec.Cmd, error)

SpawnTor runs the system's Tor binary with the torrc created by newtorrc. It takes listener (which is the local JSON-RPC server net.TCPAddr), portmap (to map HiddenServicePort entries) and datadir (to store Tor files) as parameters. Returns exec.Cmd pointer and/or error.

func ValidateOnionAddress

func ValidateOnionAddress(addr string) error

ValidateOnionAddress checks if the given string is a valid Tor v3 Hidden service address. Returns error if not.

func ValidateOnionInternal

func ValidateOnionInternal(onionaddr string) error

ValidateOnionInternal takes someunlikelyname.onion:port as a parameter and validates its format.

func ValidatePortmap

func ValidatePortmap(pm []string) error

ValidatePortmap checks if the given []string holds valid portmaps in the form of port:port (e.g. 1234:48372). Returns error if any of the found portmaps are invalid.

Types

type Ann

type Ann struct{}

Ann is the struct for the JSON-RPC announce endpoint.

func (Ann) Init

func (Ann) Init(ctx context.Context, vals []string) ([]string, error)

Init takes three parameters:

• onion: onionaddress:port where the peer and tordam can be reached
• pubkey: ed25519 public signing key in base64
• portmap: List of ports available for communication
• (optional) revoke: Revocation key for updating peer info { "jsonrpc":"2.0", "id": 1, "method": "ann.Init", "params": ["unlikelynameforan.onion:49371", "214=", "69:420,323:2354"] }

Returns:

• nonce: A random nonce which is to be signed by the client
• revoke: A key which can be used to revoke key and portmap and reannounce the peer { "jsonrpc":"2.0", "id":1, "result": ["somenonce", "somerevokekey"] }

On any kind of failure returns an error and the reason.

func (Ann) Validate

func (Ann) Validate(ctx context.Context, vals []string) ([]string, error)

Validate takes two parameters:

• onion: onionaddress:port where the peer and tordam can be reached
• signature: base64 signature of the previously obtained nonce { "jsonrpc":"2.0", "id":2, "method": "ann.Announce", "params": ["unlikelynameforan.onion:49371", "deadbeef=="] }

Returns:

• peers: A list of known validated peers (max. 50) { "jsonrpc":"2.0", "id":2, "result": ["unlikelynameforan.onion:69", "yetanother.onion:420"] }

On any kind of failure returns an error and the reason.

type Config

type Config struct {
	Listen  *net.TCPAddr // Local listen address for the JSON-RPC server
	TorAddr *net.TCPAddr // Tor SOCKS5 proxy address, filled by SpawnTor()
	Datadir string       // Path to data directory
	Portmap []string     // The peer's portmap, to be mapped in the Tor HS
}

Config is the configuration structure, to be filled by library user.

type Peer

type Peer struct {
	Pubkey     ed25519.PublicKey `json:"pubkey"`     // Peer's ed25519 public key
	Portmap    []string          `json:"portmap"`    // Peer's port map in Tor
	Nonce      string            `json:"nonce"`      // The nonce to be signed after announce init
	SelfRevoke string            `json:"selfrevoke"` // Our revoke key we use to update our data
	PeerRevoke string            `json:"peerrevoke"` // Peer's revoke key if they wish to update their data
	LastSeen   int64             `json:"lastseen"`   // Timestamp of last announce
	Trusted    int               `json:"trusted"`    // Trusted is int because of possible levels of trust
}

Peer is the base struct for any peer in the network.