Client Core Architecture: TUN Interface & Split Tunneling Specs

1. Overview & Client Core Philosophy #

The BEX Cross-Platform Client Core serves as the high-performance network engine embedded across all supported end-user platforms (Windows, macOS, Linux, Android, and iOS). Built using Rust for memory safety, concurrency, and cross-compilation capability, the engine abstracts OS-specific network stack interfaces into a unified event-driven pipeline. It establishes low-latency virtual TUN interfaces, manages encrypted packet encapsulation, and executes intelligent split-tunneling routing directly on the client device without degrading system performance or battery life.

2. Virtual TUN Interface Driver & Packet Processing #

The client core interfaces directly with native operating system virtual network adapters to achieve near-wire-speed packet processing:

• OS Adapter Abstraction Layer:
  • Windows: Utilizes high-performance Wintun ring-buffer driver for ultra-low latency packet ring-buffer transfers.
  • macOS & iOS: Integrates with utun and NetworkExtension (NEPacketTunnelProvider) APIs.
  • Linux & Android: Binds directly to the kernel /dev/net/tun interface with native file descriptor polling.
• Zero-Copy Memory Allocation: Ingress and egress packets are read directly into pre-allocated memory pools, avoiding costly kernel-to-userland memory copy operations.
• Dynamic MTU & MSS Clamping: Automatically calculates optimal Maximum Transmission Unit (MTU 1420–1460 bytes) and performs TCP Maximum Segment Size (MSS) clamping to prevent IP packet fragmentation over unstable cellular or Wi-Fi links.

3. Split Tunneling Mechanics & Traffic Filtering Engine #

BEX provides granular split-tunneling capabilities, allowing users to direct specific application traffic, domain queries, or IP ranges through the BEX encrypted tunnel while routing local traffic directly to the local ISP interface:

• App-Based Split Tunneling:
  • Windows: Uses Windows Filtering Platform (WFP) driver hooks to inspect process IDs (PIDs) and executable paths.
  • Android: Leverages VpnService API uid-binding to route selected app package IDs through or around the tunnel.
  • macOS: Applies NetworkExtension content filter rules to intercept application socket bindings.
• IP/CIDR & Domain-Based Routing: Features a high-speed Trie-based routing table inside the client core that evaluates destination IP ranges (e.g., bypassing local LAN 192.168.0.0/16 or domestic IP subnets) and domain rules in under 50 microseconds.
• Dynamic Route Table Injection: Intercepts system routing table changes and re-injects high-priority route metrics to maintain rule enforcement during network state transitions (e.g., switching from Wi-Fi to cellular data).

4. DNS Leak Prevention, IPv6 Handling & Kill-Switch #

To protect user privacy and prevent metadata exposure, the client core enforces hard security boundaries around all system socket activity:

• Embedded DNS Proxy (DoH/DoT): Intercepts all system Port 53 UDP/TCP DNS requests and redirects them to an embedded DNS proxy running inside the client core, which resolves queries over encrypted DNS-over-HTTPS (DoH) or DNS-over-TLS (DoT).
• Dual-Stack IPv4 / IPv6 Tunneling: Captures and encapsulates IPv6 traffic alongside IPv4. On networks without native IPv6 connectivity, the core blocks or blackholes outbound IPv6 packets to prevent unencrypted IPv6 fallback leaks.
• Hardware & Software Kill-Switch: Implements an OS-level firewall filter rule (WFP on Windows, nftables/iptables on Linux, pf on macOS) that instantly blocks all non-TUN internet traffic if the VPN tunnel disconnects unexpectedly or during server re-handshakes.

5. Key Strategic Benefits #

• Cross-Platform Parity: Single shared Rust core guarantees consistent routing behavior, security standards, and feature parity across desktop and mobile.
• Maximum Battery Efficiency: Zero-copy packet pipeline and asynchronous event loops minimize CPU cycles and thermal throttling on mobile devices.
• Ironclad Leak Protection: Total mitigation against DNS leaks, IPv6 bypass, and WebRTC address disclosures.