Garlic autonomous routing

.gitignore

@@ -0,0 +1,2 @@
+
+.worktrees/

README.md

@@ -10,6 +10,46 @@ allows pretty much any IPv6-capable application to communicate securely with
 other Yggdrasil nodes. Yggdrasil does not require you to have IPv6 Internet
 connectivity - it also works over IPv4.
 
+## Garlic Routing Overlay (experimental, this branch)
+
+This branch adds an experimental, optional privacy-enhanced routing layer on
+top of Yggdrasil: onion/garlic-style circuits, capability negotiation,
+per-hop packet-size and timing randomization, gossip-based peer discovery,
+topologically diverse hop selection, multipath circuits, and cover-traffic
+bundling. It is fully backward compatible - a node with `Garlic.Enabled:
+false` (the default) behaves exactly like vanilla Yggdrasil, and ordinary
+Yggdrasil nodes transparently carry Garlic traffic without needing to know
+it exists or upgrading anything.
+
+Start here:
+
+- [docs/garlic-architecture.md](docs/garlic-architecture.md) - design and integration rationale
+- [docs/garlic-protocol.md](docs/garlic-protocol.md) - wire format, what's actually implemented
+- [docs/garlic-threat-model.md](docs/garlic-threat-model.md) - what this does and does not protect against (read before relying on it for anything)
+- [docs/garlic-security.md](docs/garlic-security.md) - self-review of the implementation
+- [docs/garlic-compatibility.md](docs/garlic-compatibility.md) - why old and new nodes keep interoperating
+- [docs/garlic-testing.md](docs/garlic-testing.md) - manual walkthrough via `yggdrasilctl`
+
+### Quick install for testing
+
+To build, package, install, and enable Garlic on a Linux server in one
+step (auto-detects Debian/Ubuntu-family `apt`/`.deb` vs Fedora/RHEL/CentOS-family
+`dnf`/`yum`/`.rpm`):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/luisakrivonogih/yggdrasil-go/develop/install.sh | sudo sh
+```
+
+This builds an actual `.deb` or `.rpm` from source, installs it the same
+way the official packages install (systemd service,
+`/etc/yggdrasil/yggdrasil.conf`), sets `Garlic.Enabled: true` in the
+generated config, restarts the service, and prints the resulting Garlic
+identity and stats so you can confirm it actually started. See
+[install.sh](install.sh) for the environment variables it honors
+(`REPO_URL`, `REPO_BRANCH`, `WORKDIR`, `ENABLE_GARLIC`), and
+[docs/garlic-testing.md](docs/garlic-testing.md) for how to build a circuit
+and send traffic through it once the service is running.
+
 ## Supported Platforms
 
 Yggdrasil works on a number of platforms, including Linux, macOS, Ubiquiti

cmd/yggdrasil/main.go

@@ -13,6 +13,7 @@ import (
 	"regexp"
 	"strings"
 	"syscall"
+	"time"
 
 	"suah.dev/protect"
 
@@ -24,9 +25,11 @@ import (
 	"github.com/yggdrasil-network/yggdrasil-go/src/address"
 	"github.com/yggdrasil-network/yggdrasil-go/src/admin"
 	"github.com/yggdrasil-network/yggdrasil-go/src/config"
+	"github.com/yggdrasil-network/yggdrasil-go/src/garlic"
 	"github.com/yggdrasil-network/yggdrasil-go/src/ipv6rwc"
 
 	"github.com/yggdrasil-network/yggdrasil-go/src/core"
+	"github.com/yggdrasil-network/yggdrasil-go/src/dashboard"
 	"github.com/yggdrasil-network/yggdrasil-go/src/multicast"
 	"github.com/yggdrasil-network/yggdrasil-go/src/tun"
 	"github.com/yggdrasil-network/yggdrasil-go/src/version"
@@ -37,6 +40,8 @@ type node struct {
 	tun       *tun.TunAdapter
 	multicast *multicast.Multicast
 	admin     *admin.AdminSocket
+	garlic    *garlic.Garlic
+	dashboard *dashboard.Process
 }
 
 // The main function is responsible for configuring and starting Yggdrasil.
@@ -286,6 +291,93 @@ func main() {
 		}
 	}
 
+	// Set up the Garlic Routing Overlay (experimental, optional). When
+	// cfg.Garlic.Enabled is false (the default), this block does nothing
+	// and n.garlic stays nil - behavior is identical to a build with no
+	// Garlic support at all. See docs/garlic-architecture.md.
+	{
+		if cfg.Garlic.Enabled {
+			var identity *garlic.Identity
+			switch {
+			case len(cfg.Garlic.PrivateKey) > 0 && len(cfg.Garlic.SigningPrivateKey) > 0:
+				if identity, err = garlic.LoadIdentityFromPrivateKeys(cfg.Garlic.PrivateKey, cfg.Garlic.SigningPrivateKey); err != nil {
+					panic(err)
+				}
+			case len(cfg.Garlic.PrivateKey) > 0:
+				// Upgrade path: a node that was already running Garlic
+				// before Garlic.SigningPrivateKey existed has
+				// Garlic.PrivateKey configured but not the new signing
+				// key. Keep the existing X25519 identity stable and
+				// generate only a fresh signing identity for this run -
+				// regenerating both would silently reset an already-
+				// stable Garlic identity on every restart, not just add
+				// a new one.
+				if identity, err = garlic.LoadIdentityFromPrivateKey(cfg.Garlic.PrivateKey); err != nil {
+					panic(err)
+				}
+				logger.Warnln("Garlic.PrivateKey configured but no Garlic.SigningPrivateKey - generated a fresh signing identity for this run only; your Garlic X25519 identity remains stable")
+			default:
+				if identity, err = garlic.NewIdentity(); err != nil {
+					panic(err)
+				}
+				logger.Warnln("No Garlic.PrivateKey/SigningPrivateKey configured - generated ephemeral Garlic identity keys for this run only")
+			}
+			lifetime, err := time.ParseDuration(cfg.Garlic.CircuitLifetime)
+			if err != nil {
+				panic(fmt.Sprintf("invalid Garlic.CircuitLifetime %q: %v", cfg.Garlic.CircuitLifetime, err))
+			}
+			gcfg := garlic.DefaultConfig()
+			gcfg.PathLength = cfg.Garlic.PathLength
+			gcfg.CircuitLifetime = lifetime
+			gcfg.MaxCircuits = cfg.Garlic.MaxCircuits
+			gcfg.MaxCircuitsPerPeer = cfg.Garlic.MaxCircuitsPerPeer
+			gcfg.MaxRelayCircuits = cfg.Garlic.MaxRelayCircuits
+			gcfg.PaddingEnabled = cfg.Garlic.Padding.Enabled
+			gcfg.MinPaddedSize = cfg.Garlic.Padding.MinSize
+			gcfg.MaxPaddedSize = cfg.Garlic.Padding.MaxSize
+			gcfg.JitterEnabled = cfg.Garlic.Jitter.Enabled
+			if gcfg.MinJitter, err = time.ParseDuration(cfg.Garlic.Jitter.MinDelay); err != nil {
+				panic(fmt.Sprintf("invalid Garlic.Jitter.MinDelay %q: %v", cfg.Garlic.Jitter.MinDelay, err))
+			}
+			if gcfg.MaxJitter, err = time.ParseDuration(cfg.Garlic.Jitter.MaxDelay); err != nil {
+				panic(fmt.Sprintf("invalid Garlic.Jitter.MaxDelay %q: %v", cfg.Garlic.Jitter.MaxDelay, err))
+			}
+			gcfg.MaxDiscoveredPeers = cfg.Garlic.MaxDiscoveredPeers
+			gcfg.MinHopCount = cfg.Garlic.MinHopCount
+			gcfg.BootstrapPeers = cfg.Garlic.BootstrapPeers
+			gcfg.AutoPoolEnabled = cfg.Garlic.AutoPoolEnabled
+			gcfg.AutoPoolSize = cfg.Garlic.AutoPoolSize
+			if gcfg.AutoRotationInterval, err = time.ParseDuration(cfg.Garlic.AutoRotationInterval); err != nil {
+				panic(fmt.Sprintf("invalid Garlic.AutoRotationInterval %q: %v", cfg.Garlic.AutoRotationInterval, err))
+			}
+			gcfg.CoverTrafficEnabled = cfg.Garlic.CoverTrafficEnabled
+			if gcfg.CoverTrafficInterval, err = time.ParseDuration(cfg.Garlic.CoverTrafficInterval); err != nil {
+				panic(fmt.Sprintf("invalid Garlic.CoverTrafficInterval %q: %v", cfg.Garlic.CoverTrafficInterval, err))
+			}
+			n.garlic = garlic.New(n.core, identity, gcfg, garlic.NewStaticRendezvous())
+			logger.Printf("Your Garlic public key is %s", hex.EncodeToString(identity.PublicKey))
+			if n.admin != nil {
+				n.garlic.SetupAdminHandlers(n.admin)
+			}
+		}
+	}
+
+	// Set up the local operator dashboard (optional, disabled by
+	// default). A failure here is always a warning, never fatal - the
+	// dashboard must never be the reason yggdrasil itself won't start.
+	{
+		if cfg.Dashboard.Enabled {
+			dcfg := dashboard.Config{
+				Listen:      cfg.Dashboard.Listen,
+				Path:        cfg.Dashboard.Path,
+				AdminListen: cfg.AdminListen,
+			}
+			if n.dashboard, err = dashboard.Start(dcfg, logger); err != nil {
+				logger.Warnln("Dashboard not started:", err)
+			}
+		}
+	}
+
 	//Windows service shutdown
 	minwinsvc.SetOnExit(func() {
 		logger.Infof("Shutting down service ...")
@@ -313,6 +405,14 @@ func main() {
 	if len(cfg.MulticastInterfaces) > 0 {
 		promises = append(promises, "mcast")
 	}
+	if cfg.Dashboard.Enabled {
+		// Only relevant on OpenBSD, where protect.Pledge actually
+		// enforces this - "proc" is needed to signal/wait on the
+		// already-spawned dashboard child process at shutdown. The
+		// exec() itself already happened above, before this pledge
+		// call, so "exec" doesn't need to be a standing promise.
+		promises = append(promises, "proc")
+	}
 	if err := protect.Pledge(strings.Join(promises, " ")); err != nil {
 		panic(fmt.Sprintf("pledge: %v: %v", promises, err))
 	}
@@ -327,6 +427,12 @@ func main() {
 	<-ctx.Done()
 
 	// Shut down the node.
+	if n.dashboard != nil {
+		_ = n.dashboard.Stop()
+	}
+	if n.garlic != nil {
+		n.garlic.Close()
+	}
 	_ = n.admin.Stop()
 	_ = n.multicast.Stop()
 	_ = n.tun.Stop()

contrib/deb/generate.sh

@@ -11,8 +11,8 @@ then
 fi
 
 PKGBRANCH=$(basename `git name-rev --name-only HEAD`)
-PKGNAME=$(sh contrib/semver/name.sh)
-PKGVERSION=$(sh contrib/semver/version.sh --bare)
+PKGNAME=${PKGNAME:-$(sh contrib/semver/name.sh)}
+PKGVERSION=${PKGVERSION:-$(sh contrib/semver/version.sh --bare)}
 PKGARCH=${PKGARCH-amd64}
 PKGFILE=$PKGNAME-$PKGVERSION-$PKGARCH.deb
 PKGREPLACES=yggdrasil

contrib/rpm/generate.sh

@@ -0,0 +1,149 @@
+#!/bin/sh
+
+# This is a lazy script to create an .rpm for Fedora/RHEL/CentOS and other
+# rpm-based distributions. It installs yggdrasil and enables it in systemd.
+# Mirrors contrib/deb/generate.sh - same build, same /etc/yggdrasil layout,
+# same systemd units - just packaged as an rpm instead of a deb. You can
+# give it the PKGARCH= argument, using the same values as the deb script,
+# i.e. PKGARCH=arm64 sh contrib/rpm/generate.sh
+#
+# Requires rpmbuild (the "rpm-build" package on Fedora/RHEL/CentOS).
+
+if [ `pwd` != `git rev-parse --show-toplevel` ]
+then
+  echo "You should run this script from the top-level directory of the git repo"
+  exit 1
+fi
+
+if ! command -v rpmbuild >/dev/null 2>&1; then
+  echo "rpmbuild not found - install it first, e.g.:"
+  echo "  dnf install -y rpm-build   (Fedora/RHEL/CentOS)"
+  echo "  zypper install -y rpm-build   (openSUSE)"
+  exit 1
+fi
+
+PKGNAME=${PKGNAME:-$(sh contrib/semver/name.sh)}
+PKGVERSION=${PKGVERSION:-$(sh contrib/semver/version.sh --bare)}
+PKGARCH=${PKGARCH-amd64}
+
+# RPM's Version/Release fields can't contain "-". git describe --bare gives
+# e.g. "0.5.14-29-g36c42ec" for a dev build (29 commits past tag v0.5.14) or
+# just "0.5.14" on an exact tag - split that into a valid Version+Release.
+RPMVERSION=$(echo "$PKGVERSION" | cut -d- -f1)
+RPMRELEASE=$(echo "$PKGVERSION" | sed "s/^$RPMVERSION-\{0,1\}//" | sed 's/-/./g')
+if [ -z "$RPMRELEASE" ]; then RPMRELEASE=1; fi
+
+GOLDFLAGS="-X github.com/yggdrasil-network/yggdrasil-go/src/config.defaultConfig=/etc/yggdrasil/yggdrasil.conf"
+GOLDFLAGS="${GOLDFLAGS} -X github.com/yggdrasil-network/yggdrasil-go/src/config.defaultAdminListen=unix:///var/run/yggdrasil/yggdrasil.sock"
+
+# Same PKGARCH vocabulary as contrib/deb/generate.sh; translated to the
+# native rpm arch name for the package metadata/filename below.
+if [ $PKGARCH = "amd64" ]; then GOARCH=amd64 GOOS=linux ./build -l "${GOLDFLAGS}"; RPMARCH=x86_64
+elif [ $PKGARCH = "i386" ]; then GOARCH=386 GOOS=linux ./build -l "${GOLDFLAGS}"; RPMARCH=i686
+elif [ $PKGARCH = "mipsel" ]; then GOARCH=mipsle GOOS=linux ./build -l "${GOLDFLAGS}"; RPMARCH=mipsel
+elif [ $PKGARCH = "mips" ]; then GOARCH=mips64 GOOS=linux ./build -l "${GOLDFLAGS}"; RPMARCH=mips64
+elif [ $PKGARCH = "armhf" ]; then GOARCH=arm GOOS=linux GOARM=6 ./build -l "${GOLDFLAGS}"; RPMARCH=armv6hl
+elif [ $PKGARCH = "arm64" ]; then GOARCH=arm64 GOOS=linux ./build -l "${GOLDFLAGS}"; RPMARCH=aarch64
+elif [ $PKGARCH = "armel" ]; then GOARCH=arm GOOS=linux GOARM=5 ./build -l "${GOLDFLAGS}"; RPMARCH=armv5tel
+else
+  echo "Specify PKGARCH=amd64,i386,mips,mipsel,armhf,arm64,armel"
+  exit 1
+fi
+
+PKGFILE=$PKGNAME-$RPMVERSION-$RPMRELEASE.$RPMARCH.rpm
+echo "Building $PKGFILE"
+
+TOPDIR=/tmp/$PKGNAME-rpmbuild
+rm -rf $TOPDIR
+mkdir -p $TOPDIR/BUILD $TOPDIR/RPMS $TOPDIR/SOURCES $TOPDIR/SPECS $TOPDIR/SRPMS $TOPDIR/BUILDROOT
+
+# Binaries and units already built above - this spec only packages them, it
+# does not compile anything itself (rpmbuild has no Go toolchain dependency
+# this way, same philosophy as the deb script's hand-rolled data.tar.gz).
+cat > $TOPDIR/SPECS/$PKGNAME.spec << EOF
+Name: $PKGNAME
+Version: $RPMVERSION
+Release: $RPMRELEASE
+Summary: Yggdrasil Network
+License: LGPLv3
+URL: https://github.com/yggdrasil-network/yggdrasil-go/
+Requires: systemd
+# Statically-linked-ish Go binary - rpm's automatic dependency scanner has
+# nothing useful to add here and can misfire on Go's ELF metadata.
+AutoReqProv: no
+
+%description
+Yggdrasil is an early-stage implementation of a fully end-to-end encrypted IPv6
+network. It is lightweight, self-arranging, supported on multiple platforms and
+allows pretty much any IPv6-capable application to communicate securely with
+other Yggdrasil nodes.
+
+%install
+mkdir -p %{buildroot}/usr/bin
+mkdir -p %{buildroot}/usr/lib/systemd/system
+install -m 0755 $PWD/yggdrasil %{buildroot}/usr/bin/yggdrasil
+install -m 0755 $PWD/yggdrasilctl %{buildroot}/usr/bin/yggdrasilctl
+install -m 0644 $PWD/contrib/systemd/yggdrasil.service.debian %{buildroot}/usr/lib/systemd/system/yggdrasil.service
+install -m 0644 $PWD/contrib/systemd/yggdrasil-default-config.service.debian %{buildroot}/usr/lib/systemd/system/yggdrasil-default-config.service
+
+%files
+/usr/bin/yggdrasil
+/usr/bin/yggdrasilctl
+/usr/lib/systemd/system/yggdrasil.service
+/usr/lib/systemd/system/yggdrasil-default-config.service
+
+%pre
+getent group yggdrasil >/dev/null || groupadd --system yggdrasil || true
+exit 0
+
+%post
+systemctl daemon-reload >/dev/null 2>&1 || true
+
+if [ ! -d /etc/yggdrasil ]; then
+    mkdir -p /etc/yggdrasil
+    chown root:yggdrasil /etc/yggdrasil
+    chmod 750 /etc/yggdrasil
+fi
+
+if [ -f /etc/yggdrasil/yggdrasil.conf ]; then
+  mkdir -p /var/backups
+  echo "Backing up configuration file to /var/backups/yggdrasil.conf.\`date +%Y%m%d\`"
+  cp /etc/yggdrasil/yggdrasil.conf /var/backups/yggdrasil.conf.\`date +%Y%m%d\`
+
+  echo "Normalising and updating /etc/yggdrasil/yggdrasil.conf"
+  /usr/bin/yggdrasil -useconf -normaliseconf < /var/backups/yggdrasil.conf.\`date +%Y%m%d\` > /etc/yggdrasil/yggdrasil.conf
+
+  chown root:yggdrasil /etc/yggdrasil/yggdrasil.conf
+  chmod 640 /etc/yggdrasil/yggdrasil.conf
+else
+  echo "Generating initial configuration file /etc/yggdrasil/yggdrasil.conf"
+  (umask 037 && /usr/bin/yggdrasil -genconf > /etc/yggdrasil/yggdrasil.conf)
+
+  chown root:yggdrasil /etc/yggdrasil/yggdrasil.conf
+  chmod 640 /etc/yggdrasil/yggdrasil.conf
+fi
+
+systemctl enable yggdrasil >/dev/null 2>&1 || true
+systemctl restart yggdrasil >/dev/null 2>&1 || true
+exit 0
+
+%preun
+if [ "\$1" = "0" ]; then
+  if command -v systemctl >/dev/null; then
+    systemctl stop yggdrasil >/dev/null 2>&1 || true
+    systemctl disable yggdrasil >/dev/null 2>&1 || true
+  fi
+fi
+exit 0
+
+%changelog
+* $(date "+%a %b %d %Y") Yggdrasil <noreply@yggdrasil-network.github.io> - $RPMVERSION-$RPMRELEASE
+- See https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/CHANGELOG.md
+EOF
+
+rpmbuild --define "_topdir $TOPDIR" --target "$RPMARCH" -bb "$TOPDIR/SPECS/$PKGNAME.spec"
+
+find $TOPDIR/RPMS -name '*.rpm' -exec cp {} "./$PKGFILE" \;
+rm -rf $TOPDIR
+
+echo "Built $PKGFILE"