Add opt-in fd protection for upstream UDP sockets (Android VpnService)

[hawkff]

Summary

Adds opt-in fd protection for the client's upstream UDP sockets, for use when the client runs inside an Android VpnService host.

When FD_CONTROL_UNIX_SOCKET is set, the client sends the fd of every new upstream UDP socket to that Unix socket before connect/bind, so the host can call VpnService.protect(fd). Without this, resolver traffic from a client running inside the VPN process loops back into the tunnel. When the key is empty (the default), socket creation is unchanged.

Configuration

FD_CONTROL_UNIX_SOCKET = "/path/to/protect.sock"

The key is also available as -fd-control-unix-socket and in JSON configs, like every other client option.

Which sockets

Sent to the protect server:

• pooled UDP resolver sockets
• UDP query transports used for session setup, MTU probes and resolver health checks
• the RX/TX worker sockets

Never sent, because they face local apps and must stay on the VPN side:

• the local TCP/SOCKS5 listener
• the SOCKS5 UDP ASSOCIATE relay socket
• the optional local DNS listener

Wire protocol

The client connects to the Unix SOCK_STREAM path, sends one fd via SCM_RIGHTS with a single 0x01 payload byte, and reads one status byte. 0x01 means success. Any other status, a short read, a timeout or a connect/send error fails socket creation; there is no fallback to an unprotected socket. One deadline of 5 seconds bounds the whole handshake. This is the framing used by libneko/Matsuri protect servers.

Also in this PR

ENCRYPTION_KEY is now required only when DATA_ENCRYPTION_METHOD is not 0. With method 0 the codec does not use the key, but config loading still rejected an empty value.

Compatibility

Default-off. Desktop and server setups see no change. On platforms without Unix fd passing (Windows), setting the key makes upstream socket creation fail with a clear error.

[hawkff]

Pushed an additional fix (d481d72): propagate context through the protected UDP resolver dial.

dialUDPResolver previously hardcoded context.Background(), so callers holding a live context (probeConnectionMTU, recheckInactiveResolver) couldn't cancel or time out socket creation — in the protected path a cancelled probe could hold a goroutine for up to the protect timeout (~15s). It now takes ctx (threaded via getUDPConn/newUDPQueryTransport), and the MTU probe/recheck paths pass their live context. Callers without one pass context.Background() (no behavior change); the unprotected path also switched to DialContext so it honors cancellation.

go build/vet/go test ./internal/client/ all clean.

[Copilot]

Pull request overview

This PR adds optional Android VpnService-style FD protection for upstream UDP resolver sockets by sending newly-created UDP socket file descriptors to a Unix-domain “protect” server before connect/bind, controlled via FD_CONTROL_UNIX_SOCKET (or MASTERDNSVPN_PROTECT_PATH env override).

Changes:

• Introduces internal/sockprotect with a Unix fd-passing client (SCM_RIGHTS) plus time-bounded connect/send/read handshake and platform stubs.
• Wires FD protection into upstream UDP socket creation paths (resolver UDP pool, UDP query transports, async runtime worker sockets).
• Adds config support + documentation + tests for the new setting; also refines ENCRYPTION_KEY validation to only require it when encryption is enabled.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
internal/sockprotect/protect_unix.go	Unix-domain protect handshake implementation (connect + SCM_RIGHTS + status byte).
internal/sockprotect/protect_unix_test.go	Verifies fd passing and failure status handling for the protect protocol.
internal/sockprotect/protect_other.go	Non-unix stub that errors when protection is configured.
internal/sockprotect/cloexec_flag_supported.go	Uses SOCK_CLOEXEC on platforms that support it.
internal/sockprotect/cloexec_flag_fallback.go	Fallback when SOCK_CLOEXEC isn’t available.
internal/config/client.go	Adds FD_CONTROL_UNIX_SOCKET + env override; adjusts encryption-key requirement logic.
internal/config/client_test.go	Tests FD control config parsing/override and updated encryption-key requirement behavior.
internal/client/protected_socket.go	Adds protected UDP dial/listen helpers and net.Dialer/ListenConfig wiring.
internal/client/protected_socket_unix_test.go	Validates that protected socket creation sends fds and fails when protection fails.
internal/client/tunnel_runtime.go	Threads context into UDP resolver pooling + uses protected resolver dialing.
internal/client/mtu.go	Uses protected UDP query transport creation for MTU/recheck flows.
internal/client/async_runtime.go	Uses protected UDP listener for async RX/TX worker sockets.
internal/client/tcp_listener.go	Clarifying comment that local listener sockets are not protected.
internal/client/socks_manager.go	Clarifying comment that SOCKS UDP associate sockets are not protected.
internal/client/dns_listener.go	Clarifying comment that local DNS listener sockets are not protected.
client_config.toml.simple	Documents FD_CONTROL_UNIX_SOCKET and env override behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

🔵 Needs a closer look

Android VpnService interoperability and cross-platform socket behavior still require human validation beyond the supplied stub tests.

No open issues 🎉

3 resolved since last review

• protectControl runs sockprotect.ProtectFD inside syscall.RawConn.Control. RawConn.Control callbacks…
• In connectWithTimeout, the poll timeout uses remaining.Milliseconds(), which truncates…
• When the protect server returns a non-success status, the error message drops the actual status…

_{Review effort: Balanced}