bzuccaro
2bf8da739b
Connection keys are now a ~49-char seed (rtun3.) instead of a bundled ~1740-char certificate blob. Both endpoints deterministically derive an identical Ed25519 CA from the seed and mint ephemeral server/client leaves at startup (keyderive.rs); the app-layer auth token is derived from the seed. Target is passed separately on connect (resocks-style). - connkey.rs: rtun3 seed parse/format - keyderive.rs: CA/server/client/token derivation - keygen takes no args; connect requires --target - remove miniz_oxide; TLS layer unchanged - add determinism + key-based e2e + wrong-seed-rejected tests - update wiki, README, design spec, CI smoke
2.7 KiB
rustunnel
rustunnel is a cross-platform Rust tool for lab and development tunneling over HTTPS with mutual TLS and an application auth token. It exposes a local SOCKS5 proxy on the connector side and forwards traffic only after the HTTPS, certificate, and auth checks succeed.
Legitimate use
Use rustunnel for local labs, development environments, and controlled testing where you own or are authorized to operate both endpoints. Do not use it to access systems without permission.
Build and test
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo check
cargo test --all-targets
cargo build
Generate credentials
Generate local certificate and auth material into an explicit directory:
rustunnel generate --out ./creds
This creates ca.pem, ca.key, server.crt, server.key, client.crt, client.key, token.txt, and config.json.
Run a tunnel
Start the HTTPS listener:
rustunnel listen \
--listen 127.0.0.1:4180 \
--cert ./creds/server.crt \
--key ./creds/server.key \
--ca-cert ./creds/ca.pem \
--auth-token-file ./creds/token.txt
Start the connector and local SOCKS5 proxy:
rustunnel connect \
--target 127.0.0.1:4180 \
--socks 127.0.0.1:1180 \
--cert ./creds/client.crt \
--key ./creds/client.key \
--ca-cert ./creds/ca.pem \
--auth-token-file ./creds/token.txt
Use the SOCKS5 proxy from a local client:
curl --proxy socks5h://127.0.0.1:1180 http://127.0.0.1:4181/
Connection keys
Instead of certificate files you can use a short connection key, from which both endpoints derive identical TLS material on the spot:
rustunnel keygen # prints a ~49-char rtun3. key
rustunnel listen --listen 0.0.0.0:4180 --connection-key '<key>' # server side
rustunnel connect --target 127.0.0.1:4180 '<key>' # each client
The key is a random 32-byte seed; no certificates are ever shipped in it. The target
address is passed separately on connect.
Defaults and custom ports
- HTTPS listener:
127.0.0.1:4180 - SOCKS5 proxy:
127.0.0.1:1180
Override ports with --listen, --target, and --socks, as shown above.
Security posture
HTTPS is the default tunnel carrier. The listener requires a trusted client certificate and a valid auth token; the connector validates the server certificate before establishing the tunnel. Private keys and auth tokens are treated as sensitive and are redacted from normal logs.
Cross-platform CI
CI runs on Linux, macOS, and Windows. It checks formatting, Clippy, tests, builds, CLI smoke commands, release artifacts, and a minimal local generate/listen/connect/SOCKS5 end-to-end flow.