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
17 changes: 17 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,23 @@ func connect(ctx context.Context, address, serverName string) (*tls.Conn, error)

SNI-relative positions skip existing record headers. Positions without an SNI, outside the ClientHello, or on an existing record boundary are ignored. `TLSRec` positions choose record boundaries; `Split` positions choose write boundaries.

### Random cuts

`Options.Random` adds bounded random record and write cuts on top of the fixed positions; nil keeps a strategy fully deterministic. Each `RandomCut` draws `Count` cuts uniformly from the inclusive range `From`..`To` (both absolute or both SNI-relative), at least `MinPiece` bytes apart:

```go
opts := desync.Options{
TLSRec: []desync.Pos{{Offset: 1, FromSNI: true}},
Random: &desync.RandomOptions{
TLSRec: []desync.RandomCut{{From: desync.Pos{Offset: -8, FromSNI: true}, To: desync.Pos{Offset: 8, FromSNI: true}, Count: 2, MinPiece: 2}},
Split: []desync.RandomCut{{From: desync.Pos{Offset: 1}, To: desync.Pos{Offset: 120}}},
Seed: 0, // 0: a new seed per connection; nonzero: the same cuts on every connection
},
}
```

Random cuts never change handshake bytes, create empty records or writes, or add delays beyond `SplitDelay`. A nonzero `Seed` reproduces a test or a bug report. `opts.Key()` is a stable description of every option, the random policy and seed included: derive cached strategy IDs from it so an ID never silently changes meaning.

A ClientHello may arrive across several records and `Write` calls. Assembly is bounded by default to a 64 KiB handshake, 256 records and a 5-second timeout for incomplete input; `Options.ClientHello` changes these limits. A complete ClientHello written at once starts no timer.

### Low-TTL fake prefix (Windows)
Expand Down
36 changes: 32 additions & 4 deletions conn.go
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,21 @@ type Options struct {
Split []Pos
// SplitDelay is a pause between the TCP pieces; 0 sends them back to back.
SplitDelay time.Duration
// Random adds bounded random record/write cuts; nil keeps the strategy
// deterministic. Include Key() in a strategy ID so it is never reused for
// a different randomization policy or seed.
Random *RandomOptions
}

// Enabled reports whether the options change anything.
func (o Options) Enabled() bool { return o.Fake != nil || len(o.TLSRec) > 0 || len(o.Split) > 0 }
func (o Options) Enabled() bool {
return o.Fake != nil || len(o.TLSRec) > 0 || len(o.Split) > 0 || o.Random.enabled()
}

// splits reports whether the hello can be sent in more than one TCP write.
func (o Options) splits() bool {
return len(o.Split) > 0 || (o.Random != nil && len(o.Random.Split) > 0)
}

// Conn applies Options to the first ClientHello written to an underlying conn.
type Conn struct {
Expand All @@ -54,6 +65,7 @@ func WrapConn(c net.Conn, opts Options) net.Conn {
}
opts.TLSRec = append([]Pos(nil), opts.TLSRec...)
opts.Split = append([]Pos(nil), opts.Split...)
opts.Random = opts.Random.clone()
if opts.ClientHello != nil {
limits := *opts.ClientHello
opts.ClientHello = &limits
Expand All @@ -64,7 +76,7 @@ func WrapConn(c net.Conn, opts Options) net.Conn {
opts.Fake = &fake
}
w := &Conn{Conn: c, opts: opts, closed: make(chan struct{}), err: opts.Validate()}
if len(opts.Split) > 0 && opts.SplitDelay > 0 {
if opts.splits() && opts.SplitDelay > 0 {
w.deadlineChanged = make(chan struct{})
}
return w
Expand Down Expand Up @@ -245,7 +257,20 @@ func (c *Conn) Write(p []byte) (int, error) {
// retaining existing input record headers and any coalesced tail payload.
func (c *Conn) sendHello(rec []byte, frame helloFrame) (int, error) {
out := rec
recCuts := frame.cuts(c.opts.TLSRec, true)
var recCuts, splitCuts []int
if r := c.opts.Random; r.enabled() {
// Draw record ranges first, then write ranges, so a seed reproduces.
// One bounded allocation holds both cut lists.
rng := c.newCutRand()
nRec := len(c.opts.TLSRec) + randomCutCapacity(r.TLSRec)
buf := make([]int, 0, nRec+len(c.opts.Split)+randomCutCapacity(r.Split))
recCuts = frame.randomCuts(frame.positionCuts(buf[:0:nRec], c.opts.TLSRec), r.TLSRec, &rng)
recCuts = frame.normalizeCuts(recCuts, true)
splitCuts = frame.randomCuts(frame.positionCuts(buf[nRec:nRec], c.opts.Split), r.Split, &rng)
splitCuts = frame.normalizeCuts(splitCuts, false)
} else {
recCuts = frame.cuts(c.opts.TLSRec, true)
}
if len(recCuts) > 0 {
out = fragmentHello(rec, frame, recCuts)
}
Expand All @@ -264,7 +289,10 @@ func (c *Conn) sendHello(rec []byte, frame helloFrame) (int, error) {
}
return len(rec), nil
}
tcpCuts := mapCuts(frame.cuts(c.opts.Split, false), recCuts)
if !c.opts.Random.enabled() {
splitCuts = frame.cuts(c.opts.Split, false)
}
tcpCuts := mapCuts(splitCuts, recCuts)
written := 0
for i, end := range append(tcpCuts, len(out)) {
if end <= start || end > len(out) {
Expand Down
2 changes: 1 addition & 1 deletion docs/connection-io.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Record lengths and the 24-bit handshake length are parsed independently. SNI can

`ParseHello` now requires the complete first handshake and returns `ErrIncompleteClientHello` when only its first fragment is available. `Hello.RecordLen` retains its original meaning: the length of the first input record. `Hello.SNIOffset` is the start in the original wire input; the hostname may cross headers, so use `Hello.SNI` rather than assuming its wire bytes are contiguous. This deliberately replaces the old false success with missing SNI for incomplete input.

Absolute positions count original wire bytes. SNI-relative positions count logical handshake bytes and skip existing headers. Missing-SNI/out-of-range cuts remain ignored. TLS record cuts cannot create an empty record or split an existing header. There is no randomization or automatic strategy substitution in this path.
Absolute positions count original wire bytes. SNI-relative positions count logical handshake bytes and skip existing headers. Missing-SNI/out-of-range cuts remain ignored. TLS record cuts cannot create an empty record or split an existing header. Optional `Options.Random` ranges add cuts drawn once per connection among logical handshake byte boundaries, under the same framing rules; a nil policy keeps the path deterministic. There is no automatic strategy substitution in this path.

```go
opts := desync.Options{
Expand Down
7 changes: 7 additions & 0 deletions docs/controller.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,13 @@ rejected. The caller must supply a new network identity when its relevant route
changes, and a new `PolicyVersion` when options or probe semantics change. The
candidate slice is copied; corresponding option values remain caller-owned.

IDs are purely consumer-defined, so derive each ID (or the `PolicyVersion`) from
`desync.Options.Key()`. The key covers every transformation field, including the
randomization policy and seed, and carries a version prefix that changes if an
unchanged value would behave differently, so a cached ID never silently changes
meaning. An unseeded random policy is one strategy: its key identifies the
distribution, not one connection's cuts.

## Defaults and bounds

| Setting | Default | Hard limit |
Expand Down
5 changes: 4 additions & 1 deletion docs/validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ Fuzz one target at a time:
```sh
go test -run '^$' -fuzz '^FuzzClientHelloFraming$' -fuzztime=30s -fuzzminimizetime=1s -parallel=2
go test -run '^$' -fuzz '^FuzzClientHelloAssembly$' -fuzztime=30s -fuzzminimizetime=1s -parallel=2
go test -run '^$' -fuzz '^FuzzRandomCuts$' -fuzztime=30s -fuzzminimizetime=1s -parallel=2
go test ./controller -run '^$' -fuzz '^FuzzControllerTarget$' -fuzztime=15s -fuzzminimizetime=1s -parallel=2
```

Expand Down Expand Up @@ -98,5 +99,7 @@ requires comparable connection p50/p95/p99 and real application outcomes.
report zero even after transmission started; never infer replay safety from that.
- The controller only returns IDs and proofs; consumers must supply their catalog,
application contracts and persistence. Manual choices are unverified.
- No ACK timing heuristic, randomization, new named Mihomo outbound, subscriber
- Randomization is opt-in through `Options.Random`; `Options.Key()` identifies a
strategy including its policy and seed. Seeded draws are tied to the key version.
- No ACK timing heuristic, new named Mihomo outbound, subscriber
reserve implementation or client migration was added by these library stages.
15 changes: 15 additions & 0 deletions docs/vnext.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ application probe and real application tests; a successful TCP dial is insuffici
| Windows UDP | Existing bounded fake bursts, source-socket preservation, option restoration and counters; the earlier UDP branch is included |
| Optional controller | Destination/network/probe-contract cache, negative cache, singleflight, finite attempts/deadlines, bounded callbacks, LKG/ranking, manual/off modes, optional stale/background checks |
| Controller lifecycle | Independent waiter cancellation, late-result rejection, generation invalidation, close/shutdown, bounded diagnostics and caller-owned versioned snapshots |
| Bounded randomization | Opt-in `Options.Random` record/write cut ranges with count/minimum-piece bounds, optional reproducible seed (per-connection crypto/rand seed otherwise) and `Options.Key()` strategy identity; deterministic options unchanged |
| Examples and tests | Owned HTTPS application probe, fragmented/malformed TLS, concurrency, deadlines, IPv4/IPv6 and native Windows regressions |

The controller is available as an API. It is **not yet connected to SlothClash or
Expand Down Expand Up @@ -81,6 +82,20 @@ and documented limitations. TCP packet segmentation remains OS-controlled.

### 2. Bounded reproducible splitting/randomization

Status: implemented in the library (`Options.Random`, `RandomOptions`,
`RandomCut`, `Options.Key`). Ranges reuse `Pos` anchors; cuts are drawn among
logical handshake byte boundaries, clipped to the ClientHello, at most 16 ranges
of 64 cuts per list. A nonzero `Seed` reproduces the same cuts on every
connection; zero reads one crypto/rand seed per connection and draws with
splitmix64, so a consumer's global `math/rand.Seed` cannot make connections
alike. Covered by regression tests, the `FuzzRandomCuts` target (byte
preservation, framing, non-empty writes, bounds, seed reproduction), a seed
golden test tied to the `desync/v1` key version, a verified loopback TLS
handshake and first-write benchmarks. On the local i7-14700K benchmark, a
deterministic first write is 936 B / 9 allocations (928 B / 10 before) and a
randomized one is 1104 B / 9 allocations; later writes stay allocation-free.
Consumer wiring (Mihomo/SlothClash) is not part of this milestone.

- Keep deterministic strategies available.
- Introduce an explicit randomization policy, safe configurable ranges and an
optional deterministic seed for tests.
Expand Down
5 changes: 4 additions & 1 deletion fake.go
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,9 @@ func (o Options) Validate() error {
if err := o.ClientHello.validate(); err != nil {
return err
}
if err := o.Random.validate(o.ClientHello.limits()); err != nil {
return err
}
if o.Fake == nil {
return nil
}
Expand All @@ -50,7 +53,7 @@ func (o Options) Validate() error {
if o.Fake.Timeout < 0 {
return fmt.Errorf("desync: fake timeout must not be negative")
}
if len(o.Split) > 0 {
if o.splits() {
return fmt.Errorf("desync: fake and TCP split cannot be combined yet")
}
if !SupportsFake() {
Expand Down
102 changes: 102 additions & 0 deletions key.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
package desync

import (
"crypto/sha256"
"encoding/hex"
"strconv"
"strings"
)

// keyVersion changes whenever the meaning of an unchanged Options value
// changes, including how a seed maps to random cuts.
const keyVersion = "desync/v1"

// Key returns a stable, canonical description of every field that affects
// the transformation, including the randomization policy and seed. Consumers
// that cache strategies by ID (for example with the controller package) should
// derive the ID or PolicyVersion from Key, so a cached ID never silently
// changes meaning. Equal keys mean identical behavior for this library version
// prefix; different keys may still behave alike (for example a nil
// ClientHello and its explicit defaults). The fake payload is represented by
// its SHA-256 digest rather than its bytes.
func (o Options) Key() string {
var b strings.Builder
b.WriteString(keyVersion)
b.WriteString(";tlsrec=")
writePosList(&b, o.TLSRec)
b.WriteString(";split=")
writePosList(&b, o.Split)
b.WriteString(";delay=")
b.WriteString(strconv.FormatInt(int64(o.SplitDelay), 10))
b.WriteString(";hello=")
if h := o.ClientHello; h == nil {
b.WriteString("default")
} else {
b.WriteString(strconv.Itoa(h.MaxSize))
b.WriteByte(',')
b.WriteString(strconv.Itoa(h.MaxRecords))
b.WriteByte(',')
b.WriteString(strconv.FormatInt(int64(h.Timeout), 10))
}
b.WriteString(";fake=")
if f := o.Fake; f == nil {
b.WriteString("off")
} else {
b.WriteString("ttl:")
b.WriteString(strconv.Itoa(f.TTL))
b.WriteString(",prefix:")
b.WriteString(strconv.Itoa(f.Prefix))
b.WriteString(",timeout:")
b.WriteString(strconv.FormatInt(int64(f.Timeout), 10))
b.WriteString(",payload:")
if len(f.Payload) == 0 {
b.WriteString("default")
} else {
sum := sha256.Sum256(f.Payload)
b.WriteString(hex.EncodeToString(sum[:]))
}
}
b.WriteString(";random=")
if r := o.Random; r == nil {
b.WriteString("off")
} else {
b.WriteString("seed:")
if r.Seed == 0 {
b.WriteString("crypto")
} else {
b.WriteString(strconv.FormatUint(r.Seed, 10))
}
b.WriteString(",tlsrec:")
writeRandomList(&b, r.TLSRec)
b.WriteString(",split:")
writeRandomList(&b, r.Split)
}
return b.String()
}

func writePosList(b *strings.Builder, ps []Pos) {
for i, p := range ps {
if i > 0 {
b.WriteByte(',')
}
b.WriteString(p.String())
}
}

// writeRandomList writes "[from..to*count/minpiece ...]".
func writeRandomList(b *strings.Builder, cuts []RandomCut) {
b.WriteByte('[')
for i, c := range cuts {
if i > 0 {
b.WriteByte(' ')
}
b.WriteString(c.From.String())
b.WriteString("..")
b.WriteString(c.To.String())
b.WriteByte('*')
b.WriteString(strconv.Itoa(c.Count))
b.WriteByte('/')
b.WriteString(strconv.Itoa(c.MinPiece))
}
b.WriteByte(']')
}
Loading
Loading