baalvpn/README.md

baalvpn

A hub-and-spoke VPN for IPv6

Features

• Post-quantum security: Uses HPKE(XWingMLKEM768X25519, HKDF-SHA-256) + XChaCha20-Poly1305 for encryption and ML-DSA-44 for signatures.
• NAT-resistant architecture: Any device with Internet access can easily join the network.
• Cross-platform: Tested on Linux, Windows and macOS.

Protocol

See proto.go for details

Known limitations

• A compromised server could give out fake pubkeys allowing a MITM attack and decrypting the peer-to-peer traffic
• The keys are rotated only on client and server restart
• The protocol is vulnerable to replay attacks

Setup

Prerequisites

• Go 1.26.3+

Building

go build -o baalvpn-server ./server

CGO_ENABLED=0 go build -o baalvpn-client ./client

Server

1. Generate a keypair:

./baalvpn-server keygen

This creates server.conf and client.conf.

2. Run:

sudo ./baalvpn-server server.conf

Client

1. Copy client.conf (generated by keygen) and ensure SERVER_ADDR points to the server.

2. Run:

sudo ./baalvpn-client client.conf

The client will be assigned an IPv6 address from the fd00:baa1::/32 range.

Third-party dependencies

• github.com/songgao/water - wrapper around TUN interfaces for *nix
• golang.zx2c4.com/wintun - wrapper around wintun.dll
• github.com/cloudflare/circl - used for ML-DSA, but only until next Go release