checkpoint: integrate authenticated transports
This commit is contained in:
h3cx committed
1 parent
313ab00765
commit
586ff8f223
42 files changed
+6277
-771
No files matched your search
@@ -1,98 +1,99 @@
|
||||
# wgcloak
|
||||
|
||||
wgcloak is a Linux userspace relay for opaque UDP datagrams. It is intended to
|
||||
carry WireGuard traffic, but does not configure, inspect, or depend on
|
||||
WireGuard: the same relay can carry any UDP application.
|
||||
wgcloak relays opaque UDP datagrams between a local UDP application and a
|
||||
remote UDP backend. It does not inspect WireGuard or other application
|
||||
protocols and does not configure interfaces, routes, or firewalls.
|
||||
|
||||
The design keeps four concerns separate:
|
||||
|
||||
```text
|
||||
local UDP application -> tunnel core -> selected transport -> tunnel core
|
||||
-> backend UDP application
|
||||
```
|
||||
|
||||
The server gives each authenticated client its own backend UDP socket. The
|
||||
application payload is not decoded or rewritten.
|
||||
|
||||
## Status
|
||||
|
||||
This checkout is specification-first and under active implementation. The
|
||||
milestone and v1 acceptance checklist is in
|
||||
[`docs/IMPLEMENTATION_CHECKLIST.md`](docs/IMPLEMENTATION_CHECKLIST.md). A
|
||||
transport is available only when its code, tests, and integration criteria are
|
||||
verified; the documentation intentionally does not imply that all four
|
||||
transports are already present.
|
||||
|
||||
Target v1 transport order:
|
||||
|
||||
1. direct UDP (Milestone 1)
|
||||
2. QUIC DATAGRAM (Milestone 2)
|
||||
3. HTTP/3 CONNECT-UDP (Milestone 4)
|
||||
4. TLS/TCP framed fallback (Milestone 5)
|
||||
The current runtime implements authenticated direct UDP, QUIC DATAGRAM,
|
||||
HTTP/3 CONNECT-UDP, and TLS/TCP framed fallback. Client `mode = "auto"` probes
|
||||
the configured transport order; authentication rejection stops fallback.
|
||||
See [`docs/IMPLEMENTATION_CHECKLIST.md`](docs/IMPLEMENTATION_CHECKLIST.md) for
|
||||
acceptance evidence and remaining v1 work.
|
||||
|
||||
## Build and install
|
||||
|
||||
Rust and Cargo are required. From the repository root:
|
||||
Install Rust and Cargo, then run from the repository root:
|
||||
|
||||
```bash
|
||||
cargo test
|
||||
cargo test --all-targets
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
For a host installation (choose a reviewed release artifact):
|
||||
For a local host installation:
|
||||
|
||||
```bash
|
||||
sudo install -Dm755 target/release/wgcloak /usr/local/bin/wgcloak
|
||||
sudo install -d -m0750 /etc/wgcloak
|
||||
sudo install -d -o root -g wgcloak -m0750 /etc/wgcloak/clients
|
||||
```
|
||||
|
||||
The binary name and subcommands are the intended interface from `spec.md`:
|
||||
The CLI supports:
|
||||
|
||||
```bash
|
||||
wgcloak client --config /etc/wgcloak/client.toml
|
||||
wgcloak server --config /etc/wgcloak/server.toml
|
||||
wgcloak check-config --config /etc/wgcloak/client.toml
|
||||
wgcloak generate-secret
|
||||
wgcloak status
|
||||
wgcloak stats
|
||||
wgcloak reconnect
|
||||
wgcloak reload
|
||||
wgcloak shutdown
|
||||
```
|
||||
|
||||
Run `wgcloak --help` against the built binary to confirm the commands in the
|
||||
current build. QUIC, HTTP/3, control commands, and certificate reload are
|
||||
milestone-gated; see the checklist before deploying them.
|
||||
`reload` is retained as a CLI/control command but currently returns an explicit
|
||||
unsupported response. Configuration and certificate hot reload are not
|
||||
implemented. `reconnect` applies to the client; the server rejects it.
|
||||
|
||||
## Configuration
|
||||
## Configure and run
|
||||
|
||||
Copy and edit one of the safe, placeholder-only examples:
|
||||
Copy a placeholder-only example and adjust it for the selected transport:
|
||||
|
||||
- [`examples/client.minimal.toml`](examples/client.minimal.toml)
|
||||
- [`examples/client.advanced.toml`](examples/client.advanced.toml)
|
||||
- [`examples/server.minimal.toml`](examples/server.minimal.toml)
|
||||
- [`examples/server.advanced.toml`](examples/server.advanced.toml)
|
||||
|
||||
Put real secrets in separate files, owned by the service account, mode `0600`.
|
||||
Do not commit them. See [`docs/OPERATIONS.md`](docs/OPERATIONS.md) and
|
||||
[`docs/SECURITY.md`](docs/SECURITY.md).
|
||||
Store each secret in a separate file owned by the service account with mode
|
||||
`0600`. Keep configuration and key files out of version control. TLS-capable
|
||||
transports require a certificate and private key on the server; clients use
|
||||
normal certificate-chain and hostname verification.
|
||||
|
||||
## Run with systemd
|
||||
Run in the foreground first:
|
||||
|
||||
The templates in [`packaging/systemd/`](packaging/systemd/) assume a dedicated
|
||||
```bash
|
||||
wgcloak check-config --config /etc/wgcloak/client.toml
|
||||
wgcloak client --config /etc/wgcloak/client.toml
|
||||
```
|
||||
|
||||
See [`docs/OPERATIONS.md`](docs/OPERATIONS.md) for control commands, systemd
|
||||
deployment, shutdown behavior, and troubleshooting pointers.
|
||||
|
||||
## systemd
|
||||
|
||||
The units in [`packaging/systemd/`](packaging/systemd/) assume a dedicated
|
||||
`wgcloak` user, `/usr/bin/wgcloak`, and configuration under `/etc/wgcloak/`.
|
||||
Review paths and transport support before installing them. The server template
|
||||
includes hardening and a commented optional `CAP_NET_BIND_SERVICE` setting for
|
||||
ports below 1024; normal operation does not require `CAP_NET_ADMIN` or
|
||||
`CAP_SYS_ADMIN`.
|
||||
Review the paths and enabled listeners before installing. The server unit
|
||||
contains an optional, commented `CAP_NET_BIND_SERVICE` setting for ports below
|
||||
1024. Normal operation needs neither `CAP_NET_ADMIN` nor `CAP_SYS_ADMIN`.
|
||||
|
||||
## Security boundaries
|
||||
|
||||
TLS transports authenticate the server with normal X.509 verification and
|
||||
authenticate clients with the configured shared secret. Direct UDP provides
|
||||
message integrity and replay protection but no outer confidentiality. The
|
||||
control socket is local, stored in a private runtime directory, and mode
|
||||
`0600`.
|
||||
|
||||
wgcloak does not configure WireGuard, create TUN/TAP devices, change routes or
|
||||
firewalls, fragment application datagrams, spoof browser fingerprints,
|
||||
cluster servers, or provide multiple simultaneous local client tunnels.
|
||||
|
||||
## Documentation
|
||||
|
||||
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md): process, data path, and ownership boundaries.
|
||||
- [`docs/PROTOCOL.md`](docs/PROTOCOL.md): direct packet model and transport contracts.
|
||||
- [`docs/OPERATIONS.md`](docs/OPERATIONS.md): files, control socket, lifecycle, and deployment.
|
||||
- [`docs/SECURITY.md`](docs/SECURITY.md): threat model, secrets, privileges, and non-goals.
|
||||
- [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md): checks for common startup and connectivity failures.
|
||||
- [`docs/IMPLEMENTATION_CHECKLIST.md`](docs/IMPLEMENTATION_CHECKLIST.md): milestones 1–6 and all 17 v1 criteria.
|
||||
|
||||
## Explicit non-goals
|
||||
|
||||
wgcloak does not configure WireGuard, create TUN/TAP devices, change routes or
|
||||
firewalls, fragment application datagrams, spoof browser/TLS fingerprints, or
|
||||
provide clustering, roaming, a GUI, Windows/macOS support, or multiple client
|
||||
tunnels in v1.
|
||||
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md): runtime roles and ownership.
|
||||
- [`docs/PROTOCOL.md`](docs/PROTOCOL.md): wire protocol and transport behavior.
|
||||
- [`docs/OPERATIONS.md`](docs/OPERATIONS.md): setup, control, and systemd.
|
||||
- [`docs/SECURITY.md`](docs/SECURITY.md): threat model and permissions.
|
||||
- [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md): common failures.
|
||||
- [`docs/IMPLEMENTATION_CHECKLIST.md`](docs/IMPLEMENTATION_CHECKLIST.md):
|
||||
milestones 1–6 and all 17 v1 criteria.
|
||||
Reference in new issue
Block a user