Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 32 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -156,13 +156,43 @@ opts := desync.Options{
}
```

- `TTL` must expire after the filter and before the server. It depends on the route; 4 is an example, not a default.
- `TTL` must expire after the filter and before the server. It depends on the route; 4 is an example, not a default. `AutoTTL` derives it per connection where that can be observed, `FakeTTLCandidates` covers the rest (see [automatic TTL](#automatic-ttl)).
- `Prefix` is measured after record fragmentation. Negative values count from the end; `-1` leaves the last byte for a normal write.
- `Payload` replaces the bytes of the first transmission; by default an embedded TLS template is used, padded or truncated to the prefix.
- `Timeout` (default 3 s) bounds the native waits. Write deadlines on the wrapper bound normal writes; `Close` interrupts both.

Windows sends the prefix with `TransmitFile` from a delete-on-close temporary file, then puts the original bytes in the file cache for the retransmission and restores the socket's hop limits; native resources are kept until the operation completes or is cancelled. Linux and Android `vmsplice` a shared page holding the fake bytes into a pipe and `splice` it to the socket, so the send queue references the page instead of a copy; once `SIOCOUTQNSD` reports the prefix transmitted, the page is overwritten with the original bytes, then the hop limit is restored. This needs a route whose device supports scatter-gather (loopback, Ethernet, Wi-Fi, tun and WireGuard do); otherwise the kernel copies the spliced bytes and the server receives the fake, which fails the handshake. An error after a transformed send is terminal for the connection. Fake can be combined with `TLSRec`, not with `Split`, `Disorder` or `OOB`. macOS reports it unsupported (`Capabilities.Unsupported["fake-tcp"]`).

### Automatic TTL

```go
dialer := net.Dialer{Control: desync.ControlAutoTTL} // before connect; no-op where unobservable
raw, err := dialer.Dial("tcp", "[2001:db8::1]:443")
if err != nil {
return err
}
conn := desync.WrapConn(raw, desync.Options{
Fake: &desync.FakeOptions{
AutoTTL: &desync.AutoTTL{}, // Delta 1, Min 3, Max 20
TTL: 4, // fallback where the path cannot be observed; 0: fail instead
},
})
// after the first Write: ttl, auto := conn.(*desync.Conn).FakeTTL()
```

- The client reads the TTL of the server's SYN-ACK, guesses its initial value (64, 128 or 255; `EstimateHops`) and so the number of routers, and sends the fake with `hops - Delta`, clamped to `Min`..`Max` (zapret's `--dpi-desync-autottl`). A result that does not stay below the hop count is rejected: the fallback `TTL` is used, or the write fails with `ErrAutoTTLUnobserved` before anything is sent.
- Only **Linux/Android over IPv6** can observe it without privileges (`IPV6_RECVHOPLIMIT`, enabled by `ControlAutoTTL` before connect). Linux IPv4, Windows and macOS keep no received TTL for a TCP socket; `PlatformCapabilities().AutoTTL` and `Unsupported["auto-ttl-ipv4"]`/`["auto-ttl-ipv6"]` say why. There `AutoTTL` without a fallback `TTL` fails `Validate` (Windows) or the write (`ErrAutoTTLUnsupported`, Linux IPv4).
- `ObserveHops(conn)` returns the observed TTL and hops without changing anything, for diagnostics or to set `UDPOptions.TTL` with `AutoTTL{}.TTL(hops)`. The UDP burst itself has no automatic TTL: it precedes the peer's first reply.
- Where nothing can be observed, probe a range instead. `FakeTTLCandidates(base, 2, 8)` (and `UDPTTLCandidates`) return one option set per TTL, each with a stable, distinct `Key()`; register them as controller candidates and let discovery keep the one that verifies:

```go
candidates, err := desync.FakeTTLCandidates(desync.Options{Fake: &desync.FakeOptions{Prefix: -1}}, 2, 8)
// one strategy ID per candidate, e.g. "fake-ttl-" + strconv.Itoa(c.Fake.TTL);
// derive the controller's PolicyVersion from the candidates' Key() values
```

The estimate assumes that the return path is as long as the forward path and that the server uses a standard initial TTL; a CDN or middlebox answering with its own TTL, or an asymmetric route, makes it wrong. See [connection I/O](docs/connection-io.md#automatic-ttl).

### Low-TTL UDP burst (Windows, Linux, macOS)

```go
Expand Down Expand Up @@ -221,4 +251,4 @@ Fuzz targets, benchmarks and what has been verified are listed in [validation](d

## License

MIT, see [LICENSE](LICENSE). The default fake TLS template and the fake, disorder and out-of-band mechanisms come from ByeDPI (MIT); what was taken is listed in [third_party/NOTICE](third_party/NOTICE).
MIT, see [LICENSE](LICENSE). The default fake TLS template and the fake, disorder and out-of-band mechanisms come from ByeDPI (MIT), the automatic TTL estimate from zapret (MIT); what was taken is listed in [third_party/NOTICE](third_party/NOTICE).
245 changes: 245 additions & 0 deletions autottl.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,245 @@
package desync

import (
"errors"
"fmt"
"net"
"strconv"
"strings"
"syscall"
)

var (
// ErrAutoTTLUnsupported reports that this platform, or the connection's
// address family, gives an unprivileged TCP socket no way to read the TTL
// or hop limit of the packets it received. PlatformCapabilities().AutoTTL
// and Unsupported["auto-ttl-ipv4"/"auto-ttl-ipv6"] say why.
ErrAutoTTLUnsupported = errors.New("desync: auto TTL cannot observe the server's TTL here")
// ErrAutoTTLUnobserved reports that the server's TTL was not observed or
// does not yield a usable hop count, so no TTL could be derived.
ErrAutoTTLUnobserved = errors.New("desync: auto TTL could not derive a TTL from the observed path")
)

// Defaults of AutoTTL, those of zapret's --dpi-desync-autottl (-1:3-20).
const (
defaultAutoTTLDelta = 1
defaultAutoTTLMin = 3
defaultAutoTTLMax = 20
// maxGuessedHops bounds the path lengths EstimateHops accepts.
maxGuessedHops = 32
)

// AutoTTL derives a low TTL from the observed length of the path to the
// server: TTL = hops - Delta, clamped to Min..Max. A result that is not below
// the hop count would reach the server, so it is rejected instead. The hop
// count comes from the TTL of the server's packets (see EstimateHops), which
// assumes the return path is as long as the forward path.
//
// Zero fields select the defaults (Delta 1, Min 3, Max 20, zapret's
// --dpi-desync-autottl default), so &AutoTTL{} is a complete policy.
type AutoTTL struct {
// Delta is subtracted from the hop count, 1..254 (0 means 1). It is the
// margin between the fake's last hop and the server.
Delta int
// Min and Max bound the TTL, 1..255 (0 means 3 and 20). A path so short
// that hops-Delta is below Min still uses Min, unless Min reaches the
// server; then no TTL is derived.
Min, Max int
}

func (a AutoTTL) normalized() AutoTTL {
if a.Delta == 0 {
a.Delta = defaultAutoTTLDelta
}
if a.Min == 0 {
a.Min = defaultAutoTTLMin
}
if a.Max == 0 {
a.Max = defaultAutoTTLMax
}
return a
}

// Validate checks the policy after applying defaults.
func (a AutoTTL) Validate() error {
if a.Delta < 0 || a.Delta > 254 {
return fmt.Errorf("desync: auto TTL delta must be between 1 and 254 (or zero for default)")
}
if a.Min < 0 || a.Min > 255 || a.Max < 0 || a.Max > 255 {
return fmt.Errorf("desync: auto TTL bounds must be between 1 and 255 (or zero for default)")
}
if n := a.normalized(); n.Min > n.Max {
return fmt.Errorf("desync: auto TTL minimum %d exceeds maximum %d", n.Min, n.Max)
}
return nil
}

// TTL returns the TTL for a path of hops routers, or false when no TTL in
// Min..Max stays below the hop count. The policy must be valid.
func (a AutoTTL) TTL(hops int) (int, bool) {
a = a.normalized()
ttl := hops - a.Delta
if ttl < a.Min {
ttl = a.Min
}
if ttl > a.Max {
ttl = a.Max
}
if ttl >= hops || ttl < 1 {
return 0, false
}
return ttl, true
}

// EstimateHops guesses how many routers decremented a packet that arrived
// with the given TTL (or IPv6 hop limit). Senders start at one of the common
// initial values 64 (Linux, macOS, most network gear), 128 (Windows) or 255;
// paths are assumed shorter than 32 hops, so 33..64 is read as starting at
// 64, 97..128 at 128 and 224..255 at 255. Any other value is ambiguous and
// returns false. The guess is zapret's hop_count_guess (MIT, see
// third_party/NOTICE), except that 64 and 128 count as zero hops.
func EstimateHops(ttl int) (int, bool) {
for _, initial := range [...]int{64, 128, 255} {
if ttl <= initial && ttl > initial-maxGuessedHops {
return initial - ttl, true
}
}
return 0, false
}

// HopObservation is what ObserveHops read from a connection.
type HopObservation struct {
// TTL is the TTL or hop limit of the last in-order segment received
// from the server, normally its SYN-ACK.
TTL int
// Hops is EstimateHops(TTL).
Hops int
}

// ObserveHops reads the TTL of the packets the server sent on c (unwrapping
// *Conn and other NetConn wrappers) and estimates the path length. It works
// only where PlatformCapabilities().AutoTTL reports the connection's family,
// and only for a socket created with ControlAutoTTL; otherwise the error
// wraps ErrAutoTTLUnsupported or ErrAutoTTLUnobserved. It changes nothing;
// call it before the first Write of a *Conn with AutoTTL, which turns the
// observation off once it used it.
func ObserveHops(c net.Conn) (HopObservation, error) {
raw, err := socketOf(c)
if err != nil {
return HopObservation{}, err
}
return observeHops(raw, false)
}

func observeHops(raw syscall.RawConn, stop bool) (HopObservation, error) {
var ttl int
var opErr error
err := raw.Control(func(fd uintptr) { ttl, opErr = observeTTL(fd, stop) })
if err == nil {
err = opErr
}
if err != nil {
return HopObservation{}, err
}
hops, ok := EstimateHops(ttl)
if !ok {
return HopObservation{TTL: ttl}, fmt.Errorf("%w: received TTL %d does not follow an initial TTL of 64, 128 or 255 within %d hops", ErrAutoTTLUnobserved, ttl, maxGuessedHops)
}
return HopObservation{TTL: ttl, Hops: hops}, nil
}

// ControlAutoTTL prepares a socket before it connects, so that ObserveHops
// and FakeOptions.AutoTTL can later read the TTL of the server's SYN-ACK. Use
// it as (or call it from) net.Dialer.Control. Where the platform or family
// cannot observe the TTL it does nothing and returns nil, so a dialer can use
// it everywhere; the failure is reported when the TTL is needed.
//
// On Linux it enables IPV6_RECVHOPLIMIT on IPv6 sockets. The kernel then
// clones every in-order segment to record its hop limit; the *Conn wrapper
// disables the option again once it read the value for the fake.
func ControlAutoTTL(network, address string, c syscall.RawConn) error {
var opErr error
err := c.Control(func(fd uintptr) { opErr = prepareTTLObservation(fd, network) })
if err != nil {
return err
}
return opErr
}

// AutoTTLCapability describes how the package observes the server's TTL.
type AutoTTLCapability struct {
// Mechanism names the kernel interface, empty when there is none.
Mechanism string
// IPv4 and IPv6 report the peer families that can be observed.
IPv4, IPv6 bool
}

// validateTTL checks Fake.TTL and Fake.AutoTTL.
func (f *FakeOptions) validateTTL() error {
if f.AutoTTL == nil {
if f.TTL < 1 || f.TTL > 255 {
return fmt.Errorf("desync: fake TTL must be between 1 and 255")
}
return nil
}
if f.TTL < 0 || f.TTL > 255 {
return fmt.Errorf("desync: fake TTL must be between 1 and 255 (or zero with AutoTTL)")
}
if err := f.AutoTTL.Validate(); err != nil {
return err
}
// Without a fallback TTL the fake needs an observable family. A platform
// without the fake reports ErrFakeUnsupported instead.
if f.TTL == 0 && supportsFake && !platformAutoTTL.IPv4 && !platformAutoTTL.IPv6 {
return ErrAutoTTLUnsupported
}
return nil
}

// fakeTTL selects the TTL of the fake prefix before anything is sent. With
// AutoTTL it observes the path; when that fails it uses Fake.TTL as the
// fallback, or fails without a fallback.
func (c *Conn) fakeTTL(raw syscall.RawConn) (int, error) {
f := c.opts.Fake
if f.AutoTTL == nil {
c.usedTTL.Store(int32(f.TTL))
return f.TTL, nil
}
obs, err := observeHops(raw, true)
if err == nil {
if ttl, ok := f.AutoTTL.TTL(obs.Hops); ok {
c.usedTTL.Store(int32(ttl) | autoTTLFlag)
return ttl, nil
}
n := f.AutoTTL.normalized()
err = fmt.Errorf("%w: %d hops (received TTL %d) leave no TTL in %d..%d below the server with delta %d", ErrAutoTTLUnobserved, obs.Hops, obs.TTL, n.Min, n.Max, n.Delta)
}
if f.TTL != 0 {
c.usedTTL.Store(int32(f.TTL))
return f.TTL, nil
}
return 0, err
}

const autoTTLFlag = 1 << 8

// FakeTTL reports the TTL the fake prefix was sent with, and whether AutoTTL
// derived it (false: the fixed or fallback Fake.TTL). It is 0 until the fake
// was attempted.
func (c *Conn) FakeTTL() (ttl int, auto bool) {
v := c.usedTTL.Load()
return int(v &^ autoTTLFlag), v&autoTTLFlag != 0
}

func writeAutoTTL(b *strings.Builder, a *AutoTTL) {
if a == nil {
return
}
n := a.normalized()
b.WriteString(",auto:")
b.WriteString(strconv.Itoa(n.Delta))
b.WriteByte(':')
b.WriteString(strconv.Itoa(n.Min))
b.WriteByte('-')
b.WriteString(strconv.Itoa(n.Max))
}
8 changes: 8 additions & 0 deletions autottl_darwin.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
//go:build darwin

package desync

// xnu's tcp_input never saves received IP control data (no ip_savecontrol or
// ip6_savecontrol call), and ip6_ctloutput answers getsockopt
// IPV6_2292PKTOPTIONS with empty data.
const autoTTLReason = "xnu TCP keeps no received IP control data (tcp_input saves none, and getsockopt IPV6_2292PKTOPTIONS always returns empty data)"
Loading
Loading