bzuccaro
2bf8da739b
CI / cargo fmt (push) Canceled after 0s
CI / cargo clippy (macos-latest) (push) Canceled after 0s
CI / cargo clippy (ubuntu-latest) (push) Canceled after 0s
CI / cargo clippy (windows-latest) (push) Canceled after 0s
CI / cargo test (macos-latest) (push) Canceled after 0s
CI / cargo test (ubuntu-latest) (push) Canceled after 0s
CI / cargo test (windows-latest) (push) Canceled after 0s
CI / cargo build (macos-latest) (push) Canceled after 0s
CI / cargo build (ubuntu-latest) (push) Canceled after 0s
CI / cargo build (windows-latest) (push) Canceled after 0s
CI / cargo build --release (macos-latest) (push) Canceled after 0s
CI / cargo build --release (ubuntu-latest) (push) Canceled after 0s
CI / cargo build --release (windows-latest) (push) Canceled after 0s
CI / CLI smoke (macos-latest) (push) Canceled after 0s
CI / CLI smoke (ubuntu-latest) (push) Canceled after 0s
CI / CLI smoke (windows-latest) (push) Canceled after 0s
CI / Minimal E2E (macos-latest) (push) Canceled after 0s
CI / Minimal E2E (ubuntu-latest) (push) Canceled after 0s
CI / Minimal E2E (windows-latest) (push) Canceled after 0s
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
88 lines
2.7 KiB
Markdown
88 lines
2.7 KiB
Markdown
# 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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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.
|