From b0f9a19e29530f84578405dadb01ca1e2d212f2a Mon Sep 17 00:00:00 2001 From: Igor Lins e Silva <4753812+igorls@users.noreply.github.com> Date: Sun, 7 Jun 2026 20:41:55 -0300 Subject: [PATCH 1/3] ci: add no-sodium Linux build+test lane (#102) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds and tests with -Dno-sodium=true on ubuntu WITHOUT installing libsodium-dev — a regression guard that the std.crypto path stays buildable on Linux with no libsodium present. --- .github/workflows/ci.yml | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 580a926..b0830b3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -50,3 +50,27 @@ jobs: - name: Test run: zig build test + + no-sodium-linux: + name: Build + Test (ubuntu, std.crypto / no libsodium) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + # Deliberately do NOT install libsodium-dev — this lane proves the + # std.crypto path builds and tests on Linux with no libsodium present + # (regression guard for the optional-libsodium work, meshguard#102). + + - name: Setup Zig + uses: mlugg/setup-zig@v2 + with: + version: 0.16.0 + + - name: Build (std.crypto, no libsodium) + run: zig build -Dno-sodium=true + + - name: Build ReleaseFast (std.crypto, no libsodium) + run: zig build -Dno-sodium=true -Doptimize=ReleaseFast + + - name: Test (std.crypto, no libsodium) + run: zig build test -Dno-sodium=true From 9f78e99b25f000d03d6cc7481d5a11e578631238 Mon Sep 17 00:00:00 2001 From: Igor Lins e Silva <4753812+igorls@users.noreply.github.com> Date: Sun, 7 Jun 2026 20:41:55 -0300 Subject: [PATCH 2/3] docs(crypto): describe libsodium as optional acceleration, not a requirement (#102) - README: reframe the Linux requirement; add a Crypto backend section distinguishing required primitives (ChaCha20-Poly1305/Ed25519/X25519, always via std.crypto) from the optional libsodium AVX2 accelerator, with the -Dcrypto-backend / -Dno-sodium flag table. - getting-started: mark libsodium optional. - macos-support: update the stale use_libsodium snippet (now read from build_options, not builtin.os.tag). --- README.md | 33 ++++++++++++++++++++++++++++++++- docs/guide/getting-started.md | 2 +- docs/guide/macos-support.md | 10 +++++++--- 3 files changed, 40 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index eb0d5fd..8626b25 100644 --- a/README.md +++ b/README.md @@ -272,7 +272,10 @@ docker compose -f docker-compose.bench.yml up - **Zig 0.16+** - **Linux** (kernel WireGuard module _or_ TUN device support) -- **libsodium** (`libsodium-dev` for building, `libsodium23` at runtime) +- **libsodium** — _optional_ AVX2 accelerator, on by default on Linux + (`libsodium-dev` to build, `libsodium23` at runtime). Build with + `-Dno-sodium` / `-Dcrypto-backend=std` to use `std.crypto` instead and drop + the dependency entirely (see [Crypto backend](#crypto-backend)). - `sudo` or `CAP_NET_ADMIN` for interface creation ### macOS @@ -336,6 +339,34 @@ zig build -Dtarget=aarch64-ios -Doptimize=ReleaseFast Windows builds automatically bundle `wintun.dll` alongside `meshguard.exe`. Android builds produce only `libmeshguard-ffi.so` — the CLI binary, static library, and unit tests are excluded. +### Crypto backend + +MeshGuard's **required** crypto primitives — ChaCha20-Poly1305 (AEAD), Ed25519 +(signatures), X25519 (key exchange) — are always available via Zig's `std.crypto`. +**libsodium is an optional implementation accelerator**, not a dependency: its +hand-written AVX2 ChaCha20-Poly1305 is ~2× faster than `std.crypto` at MTU/bulk +sizes on Linux x86_64, so it is auto-selected there. Everywhere else +(macOS/FreeBSD/Windows/Android/iOS) `std.crypto` is used. + +Select the backend with `-Dcrypto-backend` (or the `-Dno-sodium` alias): + +| Build flag | Backend | +|---|---| +| _(default)_ / `-Dcrypto-backend=auto` | libsodium on Linux desktop, `std.crypto` elsewhere | +| `-Dno-sodium` / `-Dcrypto-backend=std` | `std.crypto` everywhere — **no libsodium**, no `libsodium-dev` | +| `-Dcrypto-backend=sodium` | force libsodium (link must be available for the target) | + +```bash +# Build + test on Linux with zero libsodium dependency: +zig build -Dno-sodium=true +zig build test -Dno-sodium=true +``` + +The choice is resolved in `build.zig` and passed to the source via `build_options`, +so the compiled code and the linker always agree. Downstream packages that embed +MeshGuard from source can pass the same `use_libsodium` option through and never +touch system libsodium. + ## Status Core functionality is implemented and under active benchmarking: diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 39e47ab..fa22289 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -38,7 +38,7 @@ Alternatively, build from source with [Zig](https://ziglang.org/download/) 0.15+ | Requirement | Linux | Windows | | --------------- | ------------------------------------------------ | ---------------------------------- | | **Zig** | 0.15 or later | 0.15 or later | -| **libsodium** | `libsodium-dev` for building | Not required | +| **libsodium** | _optional_ — `libsodium-dev` for the AVX2 accelerator (default); build `-Dno-sodium` to use `std.crypto` and skip it | Not required | | **OS** | Kernel WireGuard module _or_ TUN support | Windows 10+ with Wintun | | **Permissions** | `sudo` or `CAP_NET_ADMIN` for interface creation | Administrator for `meshguard up` | diff --git a/docs/guide/macos-support.md b/docs/guide/macos-support.md index 35760db..4d10ee3 100644 --- a/docs/guide/macos-support.md +++ b/docs/guide/macos-support.md @@ -27,14 +27,18 @@ macOS shares most of Linux's POSIX API surface. The gap is much smaller than Win ### Phase 1: AEAD Backend (Already Done) -The `use_libsodium` flag already handles this: +The `use_libsodium` flag already handles this. It is resolved in `build.zig` +(from `-Dcrypto-backend` / `-Dno-sodium`) and read by the source via +`build_options`: ```zig // src/wireguard/tunnel.zig -const use_libsodium = (builtin.os.tag == .linux and builtin.target.abi != .android); +const use_libsodium = @import("build_options").use_libsodium; ``` -For macOS, this evaluates to `false` → uses `std.crypto.aead.chacha_poly.ChaCha20Poly1305`. No changes needed. +For macOS this is `false` → uses `std.crypto.aead.chacha_poly.ChaCha20Poly1305`. +No changes needed. (On Linux it defaults to `true`; `-Dno-sodium` forces `false` +there too.) ### Phase 2: utun Device From f9c65e46dafb8c0ea9318a0c68b5220b1a2cdc0b Mon Sep 17 00:00:00 2001 From: Igor Lins e Silva <4753812+igorls@users.noreply.github.com> Date: Sun, 7 Jun 2026 21:04:48 -0300 Subject: [PATCH 3/3] =?UTF-8?q?docs(crypto):=20use=20-Dno-sodium=3Dtrue=20?= =?UTF-8?q?consistently=20+=20correct=20Zig=20version=20to=200.16=20(PR=20?= =?UTF-8?q?#104=20review=20=E2=80=94=20Copilot)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 6 +++--- docs/guide/getting-started.md | 6 +++--- docs/guide/macos-support.md | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 8626b25..6a014f9 100644 --- a/README.md +++ b/README.md @@ -274,7 +274,7 @@ docker compose -f docker-compose.bench.yml up - **Linux** (kernel WireGuard module _or_ TUN device support) - **libsodium** — _optional_ AVX2 accelerator, on by default on Linux (`libsodium-dev` to build, `libsodium23` at runtime). Build with - `-Dno-sodium` / `-Dcrypto-backend=std` to use `std.crypto` instead and drop + `-Dno-sodium=true` / `-Dcrypto-backend=std` to use `std.crypto` instead and drop the dependency entirely (see [Crypto backend](#crypto-backend)). - `sudo` or `CAP_NET_ADMIN` for interface creation @@ -348,12 +348,12 @@ hand-written AVX2 ChaCha20-Poly1305 is ~2× faster than `std.crypto` at MTU/bulk sizes on Linux x86_64, so it is auto-selected there. Everywhere else (macOS/FreeBSD/Windows/Android/iOS) `std.crypto` is used. -Select the backend with `-Dcrypto-backend` (or the `-Dno-sodium` alias): +Select the backend with `-Dcrypto-backend` (or the `-Dno-sodium=true` alias): | Build flag | Backend | |---|---| | _(default)_ / `-Dcrypto-backend=auto` | libsodium on Linux desktop, `std.crypto` elsewhere | -| `-Dno-sodium` / `-Dcrypto-backend=std` | `std.crypto` everywhere — **no libsodium**, no `libsodium-dev` | +| `-Dno-sodium=true` / `-Dcrypto-backend=std` | `std.crypto` everywhere — **no libsodium**, no `libsodium-dev` | | `-Dcrypto-backend=sodium` | force libsodium (link must be available for the target) | ```bash diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index fa22289..1ad23ca 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -33,12 +33,12 @@ You can also download binaries directly from the [releases page](https://github. ## Building from source -Alternatively, build from source with [Zig](https://ziglang.org/download/) 0.15+: +Alternatively, build from source with [Zig](https://ziglang.org/download/) 0.16+: | Requirement | Linux | Windows | | --------------- | ------------------------------------------------ | ---------------------------------- | -| **Zig** | 0.15 or later | 0.15 or later | -| **libsodium** | _optional_ — `libsodium-dev` for the AVX2 accelerator (default); build `-Dno-sodium` to use `std.crypto` and skip it | Not required | +| **Zig** | 0.16 or later | 0.16 or later | +| **libsodium** | _optional_ — `libsodium-dev` for the AVX2 accelerator (default); build `-Dno-sodium=true` to use `std.crypto` and skip it | Not required | | **OS** | Kernel WireGuard module _or_ TUN support | Windows 10+ with Wintun | | **Permissions** | `sudo` or `CAP_NET_ADMIN` for interface creation | Administrator for `meshguard up` | diff --git a/docs/guide/macos-support.md b/docs/guide/macos-support.md index 4d10ee3..03b6ebd 100644 --- a/docs/guide/macos-support.md +++ b/docs/guide/macos-support.md @@ -28,7 +28,7 @@ macOS shares most of Linux's POSIX API surface. The gap is much smaller than Win ### Phase 1: AEAD Backend (Already Done) The `use_libsodium` flag already handles this. It is resolved in `build.zig` -(from `-Dcrypto-backend` / `-Dno-sodium`) and read by the source via +(from `-Dcrypto-backend` / `-Dno-sodium=true`) and read by the source via `build_options`: ```zig @@ -37,8 +37,8 @@ const use_libsodium = @import("build_options").use_libsodium; ``` For macOS this is `false` → uses `std.crypto.aead.chacha_poly.ChaCha20Poly1305`. -No changes needed. (On Linux it defaults to `true`; `-Dno-sodium` forces `false` -there too.) +No changes needed. (On Linux it defaults to `true`; `-Dno-sodium=true` forces +`false` there too.) ### Phase 2: utun Device