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
- type Config
- type Peer
Constants ¶
This section is empty.
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 ¶
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 ¶
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 ¶
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 ¶ added in v0.4.0
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 ¶
RandomGarbage returns a base64 encoded string of n bytes of entropy.
func SpawnTor ¶
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 ¶
ValidateOnionAddress checks if the given string is a valid Tor v3 Hidden service address. Returns error if not.
func ValidateOnionInternal ¶
ValidateOnionInternal takes someunlikelyname.onion:port as a parameter and validates its format.
func ValidatePortmap ¶
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 ¶
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 ¶
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.
Source Files
Directories