diff --git a/README.md b/README.md index 201b516..9ac7605 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ Most VPNs treat TCP as a fallback. Konduit is designed for TCP from the ground u - **QR code provisioning** — scan once, connect instantly - **Cross-platform** — Linux, Windows, Android (macOS and iOS coming soon) - **Modern cryptography** — X25519 key exchange, ChaCha20-Poly1305 data channel -- **Stealth mode** — port 443 deployment with decoy proxy for hostile network environments +- **SOCKS5 chaining** — egress-dial (`use_proxy`) to reach the server through your own proxy, or a post-tunnel listener (`listen_socks`) for per-app routing — see [SOCKS Modes](docs/socks-modes.md) - **Memory safe** — written entirely in Rust ## Download @@ -95,7 +95,8 @@ Coming soon. **CLI & server** - [Client Quickstart](docs/client-quickstart.md) — download, configure, connect, run as a systemd service - [Server Quickstart](docs/server-quickstart.md) — install, provision, NAT setup for iptables and firewalld -- [Stealth Mode Setup](docs/stealth-setup.md) — HAProxy TCP passthrough + camouflage configuration +- [SOCKS5 Modes](docs/socks-modes.md) — reach the server through a proxy, or expose a local SOCKS5 listener +- [Connection Tuning](docs/connection-tuning.md) — opt-in connection pooling for unstable links - [systemd units](docs/systemd/) — service files for konduit-server, konduit (client), and konduit-admin-ui ## Architecture @@ -124,7 +125,7 @@ Konduit engine (Rust) The [`konduit-platform`](./konduit-platform) crate is published here for transparency and security audit. It contains the cryptographic primitives, connection statistics, and platform networking layer (TUN device, DNS, routes) — everything an auditor needs to verify what runs on your machine. It is licensed under the [PolyForm Noncommercial License 1.0.0](LICENSE) — free to read, study, and use for noncommercial purposes. -The VPN server, management UI, and stealth-mode protocol are proprietary. Keeping stealth mechanisms private makes automated DPI fingerprinting significantly harder. Source review under NDA is available for enterprise partners. +The VPN server and management UI are proprietary. Source review under NDA is available for enterprise partners. ## Security @@ -132,8 +133,6 @@ The VPN server, management UI, and stealth-mode protocol are proprietary. Keepin **Key storage:** Private keys are stored in the OS secure enclave on every platform (iOS Keychain, macOS Keychain, Android Keystore). They are never written to disk in plaintext. -**Stealth mode:** On port 443, failed or unrecognized handshakes are proxied transparently to a configurable decoy service. From the outside, the server is indistinguishable from a standard HTTPS endpoint. - ## Support **Bug reports:** Use the in-app reporting feature or open an issue in this repository. diff --git a/docs/client-quickstart.md b/docs/client-quickstart.md index ce3be81..04425f7 100644 --- a/docs/client-quickstart.md +++ b/docs/client-quickstart.md @@ -18,8 +18,6 @@ sudo cp client.toml /opt/konduit/client.toml sudo chmod 600 /opt/konduit/client.toml ``` -If your server runs in stealth mode, the config already points to port 443. No additional client-side configuration is needed. - ## 3. Connect ```bash diff --git a/docs/connection-tuning.md b/docs/connection-tuning.md new file mode 100644 index 0000000..2c9b7fd --- /dev/null +++ b/docs/connection-tuning.md @@ -0,0 +1,20 @@ +# Connection Tuning + +Konduit is a TCP-native VPN. On stable networks, a single TCP connection works fine. On unstable links (spotty Wi-Fi, mobile data, satellite), you can opt into a small pool of pre-warmed connections so a failing connection can be replaced without a full reconnect cascade. + +## Config + +```toml +[connection] +pool_enabled = false # default off; opt in for unstable links +pool_size = 3 # pre-warmed idle connections when enabled +carry_duration = 1.0 # seconds an active connection carries traffic before handoff +``` + +- `pool_enabled` — when `true`, the client keeps `pool_size` extra pre-authenticated connections warm, so an in-use connection can fail over instantly instead of paying a fresh TCP-plus-handshake cost. +- `pool_size` — number of pre-warmed idle connections to keep, in addition to the active one. Only used when `pool_enabled = true`. +- `carry_duration` — how long (in seconds) an active connection carries traffic before handoff to a pre-warmed one. Only used when `pool_enabled = true`. + +This is a resilience feature, not a stealth feature — it exists purely to make konduit more tolerant of flaky links, and has no effect on how konduit's traffic looks to a network observer. + +Server-side, sticky DL-target routing keeps your active connection selected until it actually fails (detected via a write timeout), rather than rotating on a fixed timer. This needs no client-side configuration. diff --git a/docs/privacy-policy.md b/docs/privacy-policy.md index 3438b4f..ecac873 100644 --- a/docs/privacy-policy.md +++ b/docs/privacy-policy.md @@ -51,7 +51,6 @@ Server-side connection logs are retained for a limited period for operational pu - All traffic between client and server is encrypted using **X25519** key exchange and **ChaCha20-Poly1305** AEAD. - The pre-shared key (PSK) is stored in the local config file with permissions restricted to the current user. -- Stealth mode wraps the tunnel in a protocol that is indistinguishable from HTTPS, preventing deep-packet inspection from identifying Konduit traffic. ## Children diff --git a/docs/server-quickstart.md b/docs/server-quickstart.md index 5a7c235..e8f578d 100644 --- a/docs/server-quickstart.md +++ b/docs/server-quickstart.md @@ -34,7 +34,7 @@ echo "your secret mantra phrase here" | ./konduit-ctl bootstrap -l vpn.example.c echo "your secret mantra phrase here" | ./konduit-ctl bootstrap -l vpn.example.com:8443 --public-port 443 -p - ``` -`--public-port` sets the port written into client configs, so they connect to 443 even though konduit listens on 8443. See [stealth-setup.md](stealth-setup.md) for the full HAProxy configuration. +`--public-port` sets the port written into client configs, so they connect to 443 even though konduit listens on 8443 — useful when running behind any TCP-passthrough reverse proxy (e.g. HAProxy, nginx `stream` module). ## 3. Add a Client @@ -102,8 +102,8 @@ sudo apt install iptables-persistent && sudo netfilter-persistent save ## 7. Verify ```bash -# Should return your website (camouflage) not an error -curl -sk https://your-server/ +# Connect a client and confirm the tunnel comes up +./konduit --config client.toml # Check konduit logs journalctl -u konduit-server -f diff --git a/docs/socks-modes.md b/docs/socks-modes.md new file mode 100644 index 0000000..53f266e --- /dev/null +++ b/docs/socks-modes.md @@ -0,0 +1,50 @@ +# SOCKS5 Modes + +Konduit is a VPN for reaching your own resources over the public internet — it is not a censorship-circumvention tool, and it doesn't try to disguise its traffic. If you need to get through a network that's actively blocking or fingerprinting VPN traffic, that's a job for a dedicated, purpose-built tool — an SSH SOCKS proxy (`ssh -D`), Xray, sing-box, or similar — not something konduit reimplements. + +What konduit does provide is standard SOCKS5 support on both sides of the connection, so you can chain it with whichever of those tools you already trust. + +## Egress-dial: reaching the server through a proxy (`use_proxy`) + +If you already have a SOCKS5 proxy that gets you out of a restrictive network (for example `ssh -D 1080 jumphost`), point konduit at it instead of dialing the server directly: + +```toml +[client] +server_endpoint = "vpn.example.com:443" +use_proxy = "socks5://127.0.0.1:1080" +``` + +Or via the CLI: + +```bash +./konduit connect --config client.toml --use-proxy socks5://127.0.0.1:1080 +``` + +Konduit dials the SOCKS5 proxy, asks it to `CONNECT` to your server, and then runs its normal protocol over that connection — the proxy is otherwise transparent to it. If the proxy is unreachable, or requires authentication konduit doesn't support, the connection attempt fails immediately; there is no silent fallback to a direct connection. + +## Listener: exposing a SOCKS5 proxy after the tunnel is up (`listen_socks`) + +Once connected, konduit can also expose a local SOCKS5 listener so other tools (browsers, curl, Xray outbounds) can route traffic through the tunnel without needing their own TUN-level integration: + +```toml +[client] +listen_socks = "127.0.0.1:1080" +``` + +Or via the CLI: + +```bash +./konduit connect --config client.toml --listen-socks 127.0.0.1:1080 +``` + +Connections accepted by the listener are plain outbound TCP connections, routed through the tunnel by the kernel's routing table — the same routes any other tunnelled traffic uses. The SOCKS code itself has no VPN-specific logic. + +Notes: + +- SOCKS5 only, `CONNECT` command only — no `BIND`, no `UDP ASSOCIATE`. +- No authentication — bind it to localhost (the default) unless you understand the exposure of doing otherwise. +- If no address is given, konduit falls back to `127.0.0.1:1080`. Override the fallback itself with the `KONDUIT_SOCKS_LISTEN_ADDR` environment variable. + +## Using both together + +`use_proxy` and `listen_socks` are independent and can be combined — for example, dial out through an SSH SOCKS proxy to reach your server, and also expose a local SOCKS5 listener once connected for other apps to use. diff --git a/docs/stealth-setup.md b/docs/stealth-setup.md deleted file mode 100644 index 4b1fafa..0000000 --- a/docs/stealth-setup.md +++ /dev/null @@ -1,102 +0,0 @@ -# Stealth Mode Setup - -Stealth mode makes VPN traffic look like normal HTTPS to deep packet inspection systems. -The client opens a real TLS 1.3 connection, performs a WebSocket upgrade, and then carries -the konduit protocol inside WebSocket binary frames — identical in appearance to any -browser-based web app. - -``` -Client ──TLS 1.3──▶ HAProxy :443 (TCP passthrough) ──▶ Konduit :8443 - HTTP/1.1 GET /ws → 101 Switching Protocols - WebSocket binary frames (konduit protocol inside) -``` - -## Server Requirements - -- A domain with a valid TLS certificate (Let's Encrypt / certbot) -- HAProxy 2.4+ -- Konduit server on a non-public port (e.g. `8443`) - -## HAProxy Configuration - -HAProxy acts as a pure TCP proxy — it passes TLS through to the konduit server unchanged. - -```haproxy -frontend https-ingress - bind *:443 - mode tcp - default_backend konduit-vpn - -backend konduit-vpn - mode tcp - timeout tunnel 0 - server konduit 127.0.0.1:8443 -``` - -`timeout tunnel 0` prevents HAProxy from dropping idle connections. - -Reload after changes: - -```bash -haproxy -c -f /etc/haproxy/haproxy.cfg # validate first -systemctl reload haproxy -``` - -## Konduit Server (`server.toml`) - -```toml -[server] -listen_addr = "0.0.0.0" -listen_port = 8443 -public_addr = "your-domain.com" -public_port = 443 -tls_cert = "/etc/letsencrypt/live/your-domain.com/fullchain.pem" -tls_key = "/etc/letsencrypt/live/your-domain.com/privkey.pem" -websocket = true -``` - -## Client Configuration (`client.toml`) - -```toml -[client] -server_endpoint = "your-domain.com:443" -peer_id = "..." -identity_key = "..." -server_public_key = "..." - -[stealth] -enabled = true -``` - -That's it — `stealth = true` activates TLS and WebSocket camouflage automatically. - -## Flutter / Mobile App - -Enable **Stealth Mode** in the app settings. The toggle maps to `[stealth] enabled = true` -in the connection config and activates TLS + WebSocket camouflage on all platforms -(Linux, Android, Windows). - -For QR-code-based provisioning, the `t: true` field in the QR payload enables stealth. - -## Verify - -```bash -# TLS cert must be valid — browser must reach your site -curl -s https://your-domain.com/ | head -5 - -# Connect the VPN client -sudo ./konduit --config client.toml - -# Watch HAProxy — you should see the tunnel established -journalctl -u haproxy -f -``` - -## Common Mistakes - -| Mistake | Effect | Fix | -|---------|--------|-----| -| HAProxy terminating TLS (`bind *:443 ssl crt ...`) | konduit receives plain TCP, WebSocket handshake fails | Use `bind *:443` (no `ssl`) — TCP passthrough | -| Missing `timeout tunnel 0` | Connection drops after 30 s of silence | Add `timeout tunnel 0` to backend | -| Port 8443 exposed to internet | Bypass HAProxy entirely | Firewall port 8443 to localhost only | -| Expired/self-signed cert | TLS error on client | Use Let's Encrypt; renew via certbot | -| `stealth = false` on client | Plain TCP connection, DPI detects VPN | Set `[stealth] enabled = true` |