SMTP Tunnel Proxy – A High‑Speed, DPI‑Evasive SOCKS5 Tunnel

## Overview SMTP Tunnel Proxy disguises unrestricted TCP traffic as legitimate SMTP communication on port 587, allowing the data to slip past sophisticated Deep Packet Inspection (DPI) systems that filter by protocol. Once the connection is established, the client negotiates TLS 1.2+ via STARTTLS, and the protocol switches to a lightweight binary streaming mode that transfers any payload with minimal overhead. The design mirrors a typical SMTP server handshake, including the standard EHLO/STARTTLS sequence, which makes the tunnel indistinguishable from a genuine mail server to an external observer. After authentication—performed with per‑user pre‑shared secrets and HMAC‑SHA256 signatures—traffic is forwarded through a configurable SOCKS5 proxy listening on localhost. ## Architecture ``` Browser (TCP) → Client SOCKS5:1080 → SMTP Tunnel Server (port 587) → Internet ``` The tunnel is bidirectional and supports multiplexing of multiple logical connections over a single physical SMTP stream. IP whitelisting, per‑user logging, and a built‑in alerting system provide operational flexibility. ## Key Features | Feature | Description | |---------|-------------| | TLS Encryption | All data is wrapped in TLS 1.2+ after the STARTTLS handshake. | | DPI Evasion | The SMTP session imitates a real Postfix server to hide the tunnel. | | High Performance | The protocol uses a binary streaming format that keeps latency low. | | Multi‑User | Separate credentials, secrets, and IP restrictions per user. | | SOCKS5 Proxy | Works natively with any application that supports SOCKS5. | | Auto‑Reconnect | Clients automatically re‑establish the tunnel when the connection drops. | | Package Delivery | The server generates a ZIP package containing client configuration and certificates for each user. | | Easy Management | Systemd integration on the server, command‑line utilities for user administration. | ## Installation – Server Side 1. **Prepare the host** – A Linux VPS with Python 3.8+ and an open TCP port 587. 2. **Acquire a domain** – SMTP verification requires a valid hostname. Services such as DuckDNS, No‑IP, or FreeDNS provide free subdomains. 3. **Run the installer** ```bash curl -sSL https://raw.githubusercontent.com/x011/smtp-tunnel-proxy/main/install.sh | sudo bash ``` The script: * Downloads the repository to `/opt/smtp-tunnel`. * Prompts for the domain name and generates a self‑signed TLS bundle. * Offers to create the first administrative user. * Configures UFW or the local firewall to allow traffic on port 587. * Starts a systemd unit `smtp-tunnel`. ### Managing Users ```bash # Add a user and create a client ZIP tty@srv:~$ smtp-tunnel-adduser alice # List existing users $ smtp-tunnel-listusers # Delete a user $ smtp-tunnel-deluser alice # Update the server in‑place $ smtp-tunnel-update ``` ## Client Setup The client can be installed on Windows, macOS, or Linux. | Platform | Launch Method | |----------|---------------| | Windows | Double‑click `start.bat` | | Linux | `./start.sh` | | macOS | `./start.sh` | When started, the launcher installs required Python packages and connects to the server. On a successful connection you should see: ``` SMTP Tunnel Proxy Client User: alice [INFO] Connecting to myserver.duckdns.org:587 [INFO] TLS established – binary mode active [INFO] SOCKS5 proxy listening on 127.0.0.1:1080 ``` **Alternate manual mode** – place the ZIP contents in a directory, run `pip install -r requirements.txt` and then `python client.py`. For custom configurations (e.g., different ports or a separate CA certificate) supply a YAML file like: ```yaml config.yaml: server_host: myserver.duckdns.org server_port: 587 socks_port: 1080 username: alice secret: your‑generated‑secret ca_cert: ca.crt ``` ```bash python client.py -c config.yaml ``` ## Using the Proxy 1. Configure your applications to use `127.0.0.1:1080` as a SOCKS5 interface and enable “Proxy DNS when using SOCKS v5”. 2. Test connectivity: ```bash curl -x socks5h://127.0.0.1:1080 https://ifconfig.me ``` You should see the public IP of the VPS. Windows system‑wide settings, macOS `Advanced > Proxies`, macOS terminal `export ALL_PROXY=socks5://127.0.0.1:1080`, and the `curl` or `git` examples all demonstrate how the proxy can be leveraged. ## Configuration Details Server and client configuration files are YAML and reside under `/etc/smtp-tunnel` for the server and inside the client ZIP for a client. ```yaml config.yaml: host: 0.0.0.0 port: 587 hostname: mail.example.com cert_file: server.crt key_file: server.key users_file: users.yaml log_users: true ``` ```yaml users.yaml: alice: secret: automatically‑generated‑value # whitelist: [ "192.168.1.100", "10.0.0.0/8" ] # logging: true bob: secret: another‑value whitelist: [ "203.0.113.50" ] logging: false ``` On the client side: ```yaml config.yaml: server_host: myserver.duckdns.org server_port: 587 socks_host: 127.0.0.1 socks_port: 1080 username: alice secret: automatically‑generated‑value ca_cert: ca.crt ``` ## Service Management The server runs under systemd: ```bash sudo systemctl status smtp-tunnel sudo systemctl restart smtp-tunnel sudo journalctl -u smtp-tunnel -n 100 ``` Uninstall by executing the `uninstall.sh` script shipped in `/opt/smtp-tunnel`. ## Troubleshooting | Symptom | Likely Cause | Fix | |---------|--------------|-----| | `Connection refused` | Service not running | `sudo systemctl start smtp-tunnel` or check `netstat -tlnp | grep 587`. | | `Auth failed` | Credentials mismatch | Verify `username` and `secret` in `users.yaml`; re‑generate if necessary. | | `IP not whitelisted` | Current IP not listed | Add your current IP or CIDR to the user’s `whitelist` entry. | | `Certificate verify failed` | Domain mismatch or missing CA | Ensure `server_host` matches the TLS cert’s Common Name, and distribute the correct `ca.crt`. | Run the client or server with `-d` to view verbose logging, or tail systemd logs with `journalctl -u smtp-tunnel -f`. ## Security Considerations * Always use a fully‑qualified domain name for TLS verification. * Keep the `ca.crt` confidential to prevent man‑in‑the‑middle attacks. * `users.yaml` contains user secrets; set `chmod 600` on this file. * Disable per‑user logging (`logging: false`) for sensitive workloads. * The TCP payload is encapsulated inside a TLS session; ensure the server’s private key remains secure. ## Legal Notice This software is intended for legitimate privacy and censorship circumvention. It should be deployed in compliance with your jurisdiction’s laws and regulations. Misuse may violate local statutes or service‑provider agreements. ## License The code is released under an educational‑use license and may be executed in controlled, authorized environments only.