Repository files navigation

WireHub (in a shell,wh) builds decentralized, peer-to-peer and secure overlaynetworks. It is small (<10KLOC) and tends to be simple-to-use and easilyextendable.

It is built uponWireGuard tunnels and provides distributed peerdiscovery & routing capabilities, NAT trasversal, extendable name resolving, ...

⚠️Not ready for production! This is still a work-in-progress. It stillrequires some work to be clean and secure. The current code is provided fortesting only.

• Single file network description: a configuration of a network is a listof the public key, private IPs and hostnames for each node.

• Decentralized peer discovery: WireHub peers form a authentifiedKademiliaDHT network, which is the by-default discovery mechanism to findnew peers.Sybil attack is mitigated with a configurableProof-of-Work parameter (seeworkbits);

• Peer-to-peer and relayed communication: WireHub goes through NATs, usingUPnP IGD to map new ports on compatible routers, or usingUDP HolePunching techniques. If a P2P communication cannot beestablished, network traffic is relayed through the DHT.

Run a minimal environment with WireHub installed.

docker run -it --cap-add NET_ADMIN wirehub/wh /bin/sh

Run a testing environment with auto-completion enabled, testing scripts anddebug tools installed, ...

docker run -it --cap-add NET_ADMIN wirehub/sandbox /bin/bash

If you want to compile the Docker images from source,

git clone --recursive https://github.com/gawen/wirehubcd wirehubmake docker docker-sandbox

First, generate two keys, one for each node.

$ wh genkey| tee node_a.sk| wh pubkey| tee node_a.kzW-1lBeQ7IkT6NW6hL_NsV4eOPOwJi_rt1vO-omOEmQ$ wh genkey| tee node_b.sk| wh pubkey| tee node_b.kg878Bf9ZDc4IzFSUhWFTO1VYFVmHD5XfvEsVn83Dsho

The private keys are stored in the.sk files. The public keys are stored inthe.k files.

Generate a WireHub configuration

echo"name tutorialsubnet 10.0.42.0/24boot P17zMwXJFbBdJEn05RFIMADw9TX5_m2xgf31OgNKX3w bootstrap.wirehub.iotrust node_a`cat node_a.k`trust node_b`cat node_b.k`"> config

Fileconfig should be like this:

name tutorial           # name of networksubnet 10.0.42.0/24     # private subnetwork# one DHT bootstrap nodeboot P17zMwXJFbBdJEn05RFIMADw9TX5_m2xgf31OgNKX3w bootstrap.wirehub.io# two nodes, node_a & node_btrust node_a zW-1lBeQ7IkT6NW6hL_NsV4eOPOwJi_rt1vO-omOEmQtrust node_b g878Bf9ZDc4IzFSUhWFTO1VYFVmHD5XfvEsVn83Dsho

To start the network, run onnode_a ...

wh up ./config private-key ./node_a.sk

... and onnode_b ...

wh up ./config private-key ./node_b.sk

After some time, each node should be able to ping themselves.

# ping node_bPING 10.0.42.3 (10.0.42.3): 56 data bytes64 bytes from 10.0.42.2: seq=0 ttl=64 time=106.801 ms64 bytes from 10.0.42.2: seq=1 ttl=64 time=49.778 ms

You can check the overlay network status

# whinterface wh-zW-1lBeQ7, network tutorial, node node_a <NAT>  public key: zW-1lBeQ7IkT6NW6hL_NsV4eOPOwJi_rt1vO-omOEmQ  peers     node_b

While the daemon is running, you can modify the network configuration and reloadit.

# echo "trust node_c 9OtorxsAqPqZkJ-fAYNRAPr9piMWKMLnGqOVVpMUvXY" >> ./config# wh reload wh-zW-1lBeQ7

You may stop the WireHub node as so:

wh down wh-zW-1lBeQ7

Advise: use auto-completion to avoid writing wirehub interface, peer's keys orother arguments. For example,

# wh do<TAB>  wh down <TAB>  wh down wh-zW-1lBeQ7

Zero Netcat, or0nc, is a modified version ofNetcat which runs overWireHub. It has the nice property to be secure, peer-to-peer and agnostic of thenetwork topology.

On one node, run the WireHub sandbox.

$ docker run -it --cap-add NET_ADMIN wirehub/sandbox /bin/bash

Run0nc.

node_a # 0nc.luaznc invitation: ncuJonSJOS1DlFtb3HdgDJczPilrs0oPR9pwRpa_7WXwO0z-xioe_g9cdcMZkpV2b5lN7j3eLILjplBffvjdcw

Copy the znc invitation. Run another WireHub sandbox, call0nc with theinvitation as argument.

node_b # 0nc.lua ncuJonSJOS1DlFtb3HdgDJczPilrs0oPR9pwRpa_7WXwO0z-xioe_g9cdcMZkpV2b5lN7j3eLILjplBffvjdcw

STDIN ofnode_a is now pipe-d intoSTDOUT ofnode_b, and vice-versa.

The minimal configuration for a node is something like this,

name publicworkbit 8boot P17zMwXJFbBdJEn05RFIMADw9TX5_m2xgf31OgNKX3w bootstrap.wirehub.io

Only a bootstrap node is listed, but no trusted nodes. A node with thisconfiguration will join the WireHub DHT and only provide support for discoverypeers and relaying data (which is a good thing for the DHT's health).

Start a public node,

curl https://raw.githubusercontent.com/gawen/wirehub/master/config/public> ./configwh up ./config

Check the neighbour peers in the DHT,

# wh show wh-gOVQwCSUxK allinterface wh-gOVQwCSUxK, network public, node <>  public key: gOVQwCSUxKUhUrkUSF0aDvssDfWVrrnm47ZMp5GJtDg  peers  ◒  BB_O_4Qxzw: 1.2.3.4:55329 (bucket:1)  ◒  C4mfi1ltU9: 1.2.3.4:46276 (bucket:1)  ◒  Dng_TaMHei: 1.2.3.4:6465 (bucket:1)  ◒  GjIX1RdmDj: 1.2.3.4:53850 (bucket:1)  ◒  G9qk6znNL5: 1.2.3.4:4523 (bucket:1)  ◒  J_RXehMJiw: 1.2.3.4:13962 (bucket:1)  ◒  PgjYqFfsyS: 1.2.3.4:39582 (bucket:1)  ●  P17zMwXJFb: 51.15.227.165:62096 (bucket:1)  [...]

• Libpcap
• Libsodium
• Lua
• miniupnpc
• WireGuard
• optionally,Docker

• Linux or Docker
• WireGuard

• Untrusted cryptography: even if WireHub basics cryptographic routines arebased on the trustedLibsodium, the WireHub cryptographicarchitecture has not been audited yet. If you're interested to contribute onthis part, help is very welcome!

• Automatic testing: a lot of work needs to be done to make real automatictesting possible with WireHub. Current efforts are on branchdev-testbed andmicronet.

• Still panic: still quite rough to use. Do not expect the daemon to be stable;

• Poor documentation: WireHub was a side project and still lacksdocumentation.

• For a relayed peer, only one relay is used: the traffic is not distributedyet between several relays, which makes a single point of failure of WireHubrelay mechanisms;

• Only IPv4 private addresses: implemeting IPv6 private addresses requiressome additional work;

• and related to WireGuard, which is still under active development.

• Zero-configuration IP6 networking with IPv6ORCHID addresses, toautomatically allocate each peer a default private IP (seewh orchid);

WireHub's source code is stored insrc/.wh.lua is the main Lua module toimport WireHub's engine.

The source code of the CLI toolwh is stored insrc/tools/. Its entry point issrc/tools/cli.lua.

The core of WireHub is written in C and stored insrc/core/. It is a nativeLua module calledwhcore, defined insrc/core/whcorelib.c.

Please refer to the documentation in each files for more info.