From 4180c4794b053ae03c59a580a8a833f7722c0ed7 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Wed, 28 Oct 2026 20:47:00 +0300 Subject: [PATCH 1/2] feat: add bounded reproducible random record and write cuts Options.Random adds opt-in RandomCut ranges for TLS record cuts and TCP write cuts, anchored like Pos (absolute or SNI-relative), with a bounded count and minimum piece size. A nonzero seed reproduces the cuts exactly; otherwise one crypto/rand seed per connection drives splitmix64. Deterministic options keep their meaning byte for byte. Options.Key returns a versioned canonical description, including the randomization policy and seed, for use in cached strategy IDs. Adds regression, golden, TLS round-trip and FuzzRandomCuts tests and first-write benchmarks. --- conn.go | 36 ++- fake.go | 5 +- key.go | 102 +++++++ random.go | 230 ++++++++++++++++ random_bench_test.go | 51 ++++ random_test.go | 633 +++++++++++++++++++++++++++++++++++++++++++ tlsrec.go | 12 +- 7 files changed, 1063 insertions(+), 6 deletions(-) create mode 100644 key.go create mode 100644 random.go create mode 100644 random_bench_test.go create mode 100644 random_test.go diff --git a/conn.go b/conn.go index 03061c3..0a142a5 100644 --- a/conn.go +++ b/conn.go @@ -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 { @@ -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 @@ -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 @@ -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) } @@ -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) { diff --git a/fake.go b/fake.go index 4d6d452..d2662a1 100644 --- a/fake.go +++ b/fake.go @@ -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 } @@ -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() { diff --git a/key.go b/key.go new file mode 100644 index 0000000..f1cc8a8 --- /dev/null +++ b/key.go @@ -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(']') +} diff --git a/random.go b/random.go new file mode 100644 index 0000000..55e40c7 --- /dev/null +++ b/random.go @@ -0,0 +1,230 @@ +package desync + +import ( + crand "crypto/rand" + "encoding/binary" + "fmt" + mrand "math/rand" +) + +const ( + // MaxRandomRanges bounds RandomOptions.TLSRec and RandomOptions.Split each. + MaxRandomRanges = 16 + // MaxRandomCount bounds RandomCut.Count, the cuts drawn from one range. + MaxRandomCount = 64 +) + +// RandomOptions adds bounded random cuts to the deterministic TLSRec/Split +// positions. It is opt-in: a nil Options.Random keeps a strategy fully +// deterministic, and the deterministic positions keep their exact meaning +// when randomization is enabled; random cuts are only added to them. +// +// Random cuts are drawn once per connection, for its first ClientHello. They +// never change logical handshake bytes, never create an empty TLS record or an +// empty write, and add no delay beyond an explicitly configured SplitDelay. +type RandomOptions struct { + // TLSRec ranges add TLS record boundaries (randomized --tlsrec). + TLSRec []RandomCut + // Split ranges add TCP write boundaries (randomized --split). Like Split, + // they cannot be combined with Fake yet. + Split []RandomCut + // Seed makes the draws reproducible: every connection wrapped with the + // same nonzero Seed and options cuts the same ClientHello identically, + // which is meant for tests and bug reports. Zero (the default) draws an + // independent seed from crypto/rand for every connection. + Seed uint64 +} + +// RandomCut draws Count cut positions uniformly from the inclusive range +// [From, To]. Both ends use one anchor: absolute (wire offsets, like Pos) or +// SNI-relative (logical handshake bytes from the server name, like "+s"). +// +// Cuts are chosen among logical handshake byte boundaries, so an absolute +// range never places a cut inside an existing record header; a wire offset in +// a header means the start of that record's payload. The range is clipped to +// the ClientHello; an SNI-relative range is ignored without an SNI, like Pos. +// +// MinPiece is the minimum distance between two cuts of this range and from +// either end of the handshake. When the clipped range cannot hold Count cuts +// at that spacing, as many as fit are drawn. A random cut that coincides with +// another cut or an existing record boundary adds nothing. +type RandomCut struct { + From, To Pos + // Count is 1..MaxRandomCount; zero means one cut. + Count int + // MinPiece is 1..ClientHello max size bytes; zero means one byte. + MinPiece int +} + +func (r *RandomOptions) enabled() bool { + return r != nil && (len(r.TLSRec) > 0 || len(r.Split) > 0) +} + +func (r *RandomOptions) clone() *RandomOptions { + if r == nil { + return nil + } + c := *r + c.TLSRec = append([]RandomCut(nil), r.TLSRec...) + c.Split = append([]RandomCut(nil), r.Split...) + return &c +} + +func (r *RandomOptions) validate(limits helloLimits) error { + if r == nil { + return nil + } + for _, list := range [...]struct { + name string + cuts []RandomCut + }{{"TLSRec", r.TLSRec}, {"Split", r.Split}} { + if len(list.cuts) > MaxRandomRanges { + return fmt.Errorf("desync: at most %d random %s ranges", MaxRandomRanges, list.name) + } + for _, c := range list.cuts { + if c.From.FromSNI != c.To.FromSNI { + return fmt.Errorf("desync: random %s range %s..%s mixes absolute and SNI-relative ends", list.name, c.From, c.To) + } + if c.From.Offset > c.To.Offset { + return fmt.Errorf("desync: random %s range %s..%s is reversed", list.name, c.From, c.To) + } + if c.Count < 0 || c.Count > MaxRandomCount { + return fmt.Errorf("desync: random %s count must be between 1 and %d", list.name, MaxRandomCount) + } + if c.MinPiece < 0 || c.MinPiece > limits.size { + return fmt.Errorf("desync: random %s minimum piece must be between 1 and %d", list.name, limits.size) + } + } + } + return nil +} + +// cutRand is splitmix64: tiny, allocation-free and fully determined by its +// 64-bit state, so a Seed reproduces the same draws on every platform. +type cutRand struct{ state uint64 } + +func (r *cutRand) next() uint64 { + r.state += 0x9e3779b97f4a7c15 + z := r.state + z = (z ^ (z >> 30)) * 0xbf58476d1ce4e5b9 + z = (z ^ (z >> 27)) * 0x94d049bb133111eb + return z ^ (z >> 31) +} + +// intn returns an unbiased value in [0, n) for n > 0. +func (r *cutRand) intn(n int) int { + bound := uint64(n) + threshold := -bound % bound + for { + if x := r.next(); x >= threshold { + return int(x % bound) + } + } +} + +// newCutRand seeds one connection's draws. Unseeded policies read a 64-bit +// seed from crypto/rand once per connection, so a consumer calling the global +// math/rand.Seed cannot make all connections alike; the draws themselves then +// use the cheap generator above. A failing system source falls back to the +// auto-seeded global math/rand source. +func (c *Conn) newCutRand() cutRand { + if seed := c.opts.Random.Seed; seed != 0 { + return cutRand{seed} + } + var b [8]byte + if _, err := crand.Read(b[:]); err == nil { + return cutRand{binary.LittleEndian.Uint64(b[:])} + } + return cutRand{mrand.Uint64()} +} + +// randomCutCapacity is the most cuts the ranges can draw. +func randomCutCapacity(ranges []RandomCut) int { + n := 0 + for _, rc := range ranges { + if rc.Count < 1 { + n++ + } else { + n += rc.Count + } + } + return n +} + +// logicalAt maps an absolute wire offset to a logical handshake boundary. An +// offset inside a record header becomes the start of that record's payload. +func (f helloFrame) logicalAt(wire int) int { + logical := 0 + for i := 0; i < f.records.count; i++ { + r := f.records.at(i) + payload := r.start + recordHeaderLen + if wire < payload { + return logical + } + if wire < r.end { + return logical + wire - payload + } + logical += r.end - payload + } + return logical +} + +// randomCuts appends original wire offsets for every range to cuts. The +// caller sorts, deduplicates and filters them with the deterministic cuts. +func (f helloFrame) randomCuts(cuts []int, ranges []RandomCut, rng *cutRand) []int { + var picks [MaxRandomCount]int + for _, rc := range ranges { + var lo, hi int + if rc.From.FromSNI { + if f.sniLogical < 0 { + continue + } + lo, hi = f.sniLogical+rc.From.Offset, f.sniLogical+rc.To.Offset + } else { + lo, hi = f.logicalAt(rc.From.Offset), f.logicalAt(rc.To.Offset) + } + gap := rc.MinPiece + if gap < 1 { + gap = 1 + } + if lo < gap { + lo = gap + } + if hi > f.size-gap { + hi = f.size - gap + } + if hi < lo { + continue + } + n := rc.Count + if n < 1 { + n = 1 + } + if fit := (hi-lo)/gap + 1; n > fit { + n = fit + } + // Choosing n distinct values from [0, slots) and spreading the sorted + // values by gap-1 gives a uniform choice among all spaced cut sets. + slots := hi - lo + 1 - (n-1)*(gap-1) + chosen := picks[:0] + for j := slots - n; j < slots; j++ { // Floyd's subset sampling. + v := rng.intn(j + 1) + for _, p := range chosen { + if p == v { + v = j + break + } + } + chosen = append(chosen, v) + } + for i := 1; i < len(chosen); i++ { // insertion sort; n is small. + for k := i; k > 0 && chosen[k] < chosen[k-1]; k-- { + chosen[k], chosen[k-1] = chosen[k-1], chosen[k] + } + } + for i, v := range chosen { + cuts = append(cuts, f.byteOffset(lo+v+i*(gap-1))) + } + } + return cuts +} diff --git a/random_bench_test.go b/random_bench_test.go new file mode 100644 index 0000000..dc2c7b5 --- /dev/null +++ b/random_bench_test.go @@ -0,0 +1,51 @@ +package desync + +import ( + "net" + "testing" +) + +func benchmarkFirstWrite(b *testing.B, opts Options) { + a, peer := net.Pipe() + defer a.Close() + defer peer.Close() + sink := &framingDiscard{a} + rec := framingHello("fragment.example", 420) + b.ReportAllocs() + b.SetBytes(int64(len(rec))) + b.ResetTimer() + for i := 0; i < b.N; i++ { + w := WrapConn(sink, opts) + if _, err := w.Write(rec); err != nil { + b.Fatal(err) + } + // A later write is the warm path and must stay allocation-free. + if _, err := w.Write(rec[:16]); err != nil { + b.Fatal(err) + } + } +} + +func BenchmarkFirstWriteDeterministic(b *testing.B) { + benchmarkFirstWrite(b, Options{ + TLSRec: []Pos{{Offset: 1, FromSNI: true}, {Offset: 40}}, + Split: []Pos{{Offset: 3, FromSNI: true}}, + }) +} + +var benchRandomCuts = []RandomCut{{From: Pos{-4, true}, To: Pos{12, true}, Count: 2, MinPiece: 2}} +var benchRandomSplit = []RandomCut{{From: Pos{0, true}, To: Pos{8, true}}} + +func BenchmarkFirstWriteRandomSeeded(b *testing.B) { + benchmarkFirstWrite(b, Options{ + TLSRec: []Pos{{Offset: 40}}, + Random: &RandomOptions{TLSRec: benchRandomCuts, Split: benchRandomSplit, Seed: 1}, + }) +} + +func BenchmarkFirstWriteRandomUnseeded(b *testing.B) { + benchmarkFirstWrite(b, Options{ + TLSRec: []Pos{{Offset: 40}}, + Random: &RandomOptions{TLSRec: benchRandomCuts, Split: benchRandomSplit}, + }) +} diff --git a/random_test.go b/random_test.go new file mode 100644 index 0000000..fc1a370 --- /dev/null +++ b/random_test.go @@ -0,0 +1,633 @@ +package desync + +import ( + "bytes" + "crypto/tls" + "crypto/x509" + "errors" + "fmt" + "io" + "net" + "os" + "strings" + "sync" + "testing" + "time" +) + +// segmentSink records every Write call as one segment and accepts it whole. +type segmentSink struct { + net.Conn + mu sync.Mutex + segs [][]byte +} + +func (s *segmentSink) Write(p []byte) (int, error) { + s.mu.Lock() + s.segs = append(s.segs, append([]byte(nil), p...)) + s.mu.Unlock() + return len(p), nil +} + +func (s *segmentSink) data() []byte { + s.mu.Lock() + defer s.mu.Unlock() + return bytes.Join(s.segs, nil) +} + +func newSegmentSink(t testing.TB) *segmentSink { + a, b := net.Pipe() + t.Cleanup(func() { a.Close(); b.Close() }) + return &segmentSink{Conn: a} +} + +// randomRun writes input in chunks through a wrapper and returns the sink. +func randomRun(t testing.TB, opts Options, input []byte, chunk int) *segmentSink { + t.Helper() + sink := newSegmentSink(t) + w := WrapConn(sink, opts) + defer w.Close() + for at := 0; at < len(input); { + end := at + chunk + if end > len(input) { + end = len(input) + } + if n, err := w.Write(input[at:end]); n != end-at || err != nil { + t.Fatalf("write: %d %v", n, err) + } + at = end + } + return sink +} + +// checkRandomOutput validates framing of the transformed hello independently +// of the implementation and returns its logical record boundaries. Every output +// record must be non-empty, within the TLS limit and carry the type/version of +// the input record its first byte came from; logical bytes and the tail must +// be unchanged. +func checkRandomOutput(t *testing.T, wire, out []byte) []int { + t.Helper() + var scanner helloScanner + frame, err := scanner.scan(wire, (*ClientHelloOptions)(nil).limits()) + if err != nil { + t.Fatalf("input is not a complete hello: %v", err) + } + var headerAt []int // logical offset -> index of input record + for i := 0; i < frame.records.count; i++ { + r := frame.records.at(i) + for j := r.start + recordHeaderLen; j < r.end; j++ { + headerAt = append(headerAt, r.start) + } + } + var payload, bounds []int + end, logical := 0, 0 + for logical < frame.size { + if len(out)-end < recordHeaderLen { + t.Fatal("incomplete output header") + } + n := int(out[end+3])<<8 | int(out[end+4]) + if n == 0 || n > maxRecordPayload || n > len(out)-end-recordHeaderLen { + t.Fatalf("invalid output record length %d", n) + } + src := headerAt[logical] + if !bytes.Equal(out[end:end+3], wire[src:src+3]) { + t.Fatalf("record type/version % x, want % x", out[end:end+3], wire[src:src+3]) + } + if logical > 0 { + bounds = append(bounds, logical) + } + payload = append(payload, n) + logical += n + end += recordHeaderLen + n + } + if !bytes.Equal(framingPayload(t, out[:end]), framingPayload(t, wire[:frame.wireLen])) { + t.Fatal("logical handshake bytes changed") + } + if !bytes.Equal(out[end:], wire[frame.wireLen:]) { + t.Fatal("trailing bytes changed") + } + return bounds +} + +func checkSegments(t testing.TB, segs [][]byte) { + t.Helper() + for i, s := range segs { + if len(s) == 0 { + t.Fatalf("empty write %d", i) + } + } +} + +func TestRandomRecordCutsStayInRangeWithMinPiece(t *testing.T) { + rec := framingHello("random.example", 300) + h, _ := ParseHello(rec) + sni := h.SNIOffset - recordHeaderLen + cut := RandomCut{From: Pos{-5, true}, To: Pos{20, true}, Count: 3, MinPiece: 4} + seen := map[int]bool{} + for seed := uint64(1); seed <= 500; seed++ { + opts := Options{Random: &RandomOptions{TLSRec: []RandomCut{cut}, Seed: seed}} + sink := randomRun(t, opts, rec, len(rec)) + checkSegments(t, sink.segs) + bounds := checkRandomOutput(t, rec, sink.data()) + if len(bounds) != 3 { + t.Fatalf("seed=%d: %d cuts, want 3", seed, len(bounds)) + } + for i, b := range bounds { + if b < sni-5 || b > sni+20 { + t.Fatalf("seed=%d: cut %d outside range", seed, b) + } + if i > 0 && b-bounds[i-1] < 4 { + t.Fatalf("seed=%d: pieces %v below minimum", seed, bounds) + } + seen[b-sni] = true + } + } + // 500 seeds draw every allowed position of the 26-byte range. + for off := -5; off <= 20; off++ { + if !seen[off] { + t.Fatalf("position %d+s never drawn", off) + } + } +} + +func TestRandomAbsoluteRangeAcrossInputRecords(t *testing.T) { + rec := framingHello("random.example", 300) + wire := reframeInput(rec, 10, 60) + wire[2] = 1 // the first input record keeps its legacy version + wire = append(wire, []byte("trailing application bytes")...) + cut := RandomCut{From: Pos{Offset: 0}, To: Pos{Offset: 200}, Count: 12, MinPiece: 2} + for seed := uint64(1); seed <= 200; seed++ { + opts := Options{Random: &RandomOptions{TLSRec: []RandomCut{cut}, Seed: seed}} + for _, chunk := range []int{1, 13, len(wire)} { + sink := randomRun(t, opts, wire, chunk) + checkSegments(t, sink.segs) + bounds := checkRandomOutput(t, wire, sink.data()) + // Two existing boundaries plus at most 12 drawn cuts, all in range. + if len(bounds) < 2 || len(bounds) > 14 { + t.Fatalf("seed=%d: %d boundaries", seed, len(bounds)) + } + for _, b := range bounds { + if b > 200-3*recordHeaderLen { + t.Fatalf("seed=%d: cut %d past range end", seed, b) + } + } + } + } +} + +func TestRandomSeedReproducesAcrossConnectionsAndChunking(t *testing.T) { + rec := framingHello("random.example", 300) + wire := append(reframeInput(rec, 77), framingRecord([]byte{1, 2, 3})...) + policy := &RandomOptions{ + TLSRec: []RandomCut{{From: Pos{-10, true}, To: Pos{14, true}, Count: 3, MinPiece: 2}}, + Split: []RandomCut{{From: Pos{Offset: 1}, To: Pos{Offset: 300}, Count: 4, MinPiece: 16}}, + Seed: 0x5eed, + } + opts := Options{TLSRec: []Pos{{Offset: 1, FromSNI: true}}, Random: policy} + want := randomRun(t, opts, wire, len(wire)) + checkSegments(t, want.segs) + checkRandomOutput(t, wire, want.data()) + for _, chunk := range []int{1, 5, 64, len(wire)} { + // The hello writes match exactly; later input passes through per chunk. + got := randomRun(t, opts, wire, chunk) + hello := len(want.segs) - 1 + if len(got.segs) < hello || !bytes.Equal(got.data(), want.data()) { + t.Fatalf("chunk=%d: output differs for the same seed", chunk) + } + for i := 0; i < hello; i++ { + if !bytes.Equal(got.segs[i], want.segs[i]) { + t.Fatalf("chunk=%d: write %d differs for the same seed", chunk, i) + } + } + } + // The hello plus one tail write: four random write cuts give five pieces. + if len(want.segs) != 6 { + t.Fatalf("%d writes, want 6", len(want.segs)) + } + distinct := map[string]bool{} + for seed := uint64(1); seed <= 32; seed++ { + p := *policy + p.Seed = seed + distinct[string(bytes.Join(randomRun(t, Options{Random: &p}, wire, len(wire)).segs, []byte{0}))] = true + } + if len(distinct) < 16 { + t.Fatalf("only %d distinct outputs for 32 seeds", len(distinct)) + } +} + +// The draw sequence is a compatibility promise of keyVersion. If this golden +// output changes, bump keyVersion so cached seeded strategy IDs change too. +func TestRandomSeedGolden(t *testing.T) { + rec := framingHello("random.example", 0) + opts := Options{Random: &RandomOptions{ + TLSRec: []RandomCut{{From: Pos{Offset: 0}, To: Pos{Offset: 60}, Count: 3}}, + Split: []RandomCut{{From: Pos{0, true}, To: Pos{13, true}, Count: 2}}, + Seed: 42, + }} + sink := randomRun(t, opts, rec, len(rec)) + bounds := checkRandomOutput(t, rec, sink.data()) + var sizes []int + for _, seg := range sink.segs { + sizes = append(sizes, len(seg)) + } + if got := fmt.Sprint(bounds, sizes); got != goldenSeed42 { + t.Fatalf("seed 42 draws changed: %s (want %s); bump keyVersion", got, goldenSeed42) + } +} + +const goldenSeed42 = "[14 20 51] [79 3 8]" + +func TestRandomUnseededVariesPerConnection(t *testing.T) { + rec := framingHello("random.example", 300) + opts := Options{Random: &RandomOptions{ + TLSRec: []RandomCut{{From: Pos{Offset: 6}, To: Pos{Offset: 300}, Count: 2}}, + Split: []RandomCut{{From: Pos{0, true}, To: Pos{13, true}}}, + }} + distinct := map[string]bool{} + for i := 0; i < 64; i++ { + sink := randomRun(t, opts, rec, len(rec)) + checkSegments(t, sink.segs) + if len(sink.segs) != 2 { + t.Fatalf("%d writes, want 2", len(sink.segs)) + } + if b := checkRandomOutput(t, rec, sink.data()); len(b) != 2 { + t.Fatalf("%d record cuts, want 2", len(b)) + } + distinct[string(bytes.Join(sink.segs, []byte{0}))] = true + } + if len(distinct) < 32 { + t.Fatalf("unseeded policy produced only %d distinct outputs", len(distinct)) + } +} + +func TestRandomIgnoredRangesKeepDeterministicOutput(t *testing.T) { + rec := framingHello("random.example", 300) + noSNI := framingHello("random.example", 0) + noSNI[6], noSNI[7], noSNI[8] = 0, 0, 41 // minimal TLS 1.2 body, no extensions + noSNI = noSNI[:5+45] + noSNI[3], noSNI[4] = 0, 45 + if h, err := ParseHello(noSNI); err != nil || h.SNIOffset != -1 { + t.Fatalf("fixture: %+v %v", h, err) + } + det := Options{TLSRec: []Pos{{Offset: 12}, {Offset: 1, FromSNI: true}}, Split: []Pos{{Offset: 30}}} + ignored := &RandomOptions{ + // Beyond the hello, before it, without SNI, or too small for MinPiece. + TLSRec: []RandomCut{{From: Pos{Offset: 5000}, To: Pos{Offset: 6000}}, {From: Pos{Offset: -9}, To: Pos{Offset: 0}}}, + Split: []RandomCut{{From: Pos{0, true}, To: Pos{5, true}, MinPiece: 1 << 15}}, + Seed: 7, + } + for _, input := range [][]byte{rec, noSNI} { + want := randomRun(t, det, input, len(input)) + withRandom := det + withRandom.Random = ignored + got := randomRun(t, withRandom, input, len(input)) + if len(got.segs) != len(want.segs) || !bytes.Equal(got.data(), want.data()) { + t.Fatal("ignored random ranges changed deterministic output") + } + } + sniOnly := Options{Random: &RandomOptions{TLSRec: []RandomCut{{From: Pos{0, true}, To: Pos{3, true}}}}} + if got := randomRun(t, sniOnly, noSNI, len(noSNI)); !bytes.Equal(got.data(), noSNI) { + t.Fatal("SNI-relative random range changed a hello without SNI") + } + raw := newSegmentSink(t) + if WrapConn(raw, Options{Random: &RandomOptions{Seed: 3}}) != net.Conn(raw) { + t.Fatal("a seed without ranges enabled the wrapper") + } +} + +func TestRandomPartialWriteCounts(t *testing.T) { + rec := framingHello("random.example", 300) + opts := Options{Random: &RandomOptions{ + TLSRec: []RandomCut{{From: Pos{-20, true}, To: Pos{40, true}, Count: 4, MinPiece: 3}}, + Seed: 99, + }} + ok := randomRun(t, opts, rec, len(rec)) + out := ok.data() + rs := records(t, out) + if len(rs) != 5 { + t.Fatalf("%d records", len(rs)) + } + for _, buffered := range []int{0, 9} { + for fail := 0; fail < len(out); fail++ { + // Generated headers are those of every output record but the first. + want, at := fail, 0 + for i, r := range rs { + if i > 0 { + overlap := fail - at + if overlap > recordHeaderLen { + overlap = recordHeaderLen + } + if overlap > 0 { + want -= overlap + } + } + at += len(r) + } + raw := lifecycleStream(t) + raw.failCall, raw.failAfter = 1, fail + w := WrapConn(raw, opts) + if buffered > 0 { + if _, err := w.Write(rec[:buffered]); err != nil { + t.Fatal(err) + } + } + n, err := w.Write(rec[buffered:]) + want -= buffered + if want < 0 { + want = 0 + } + if n != want || !errors.Is(err, io.ErrUnexpectedEOF) { + t.Fatalf("buffered=%d fail=%d: n=%d want=%d err=%v", buffered, fail, n, want, err) + } + w.Close() + } + } +} + +func TestRandomSplitDelayIsInterruptible(t *testing.T) { + rec := framingHello("random.example", 0) + raw := lifecycleStream(t) + opts := Options{ + Random: &RandomOptions{Split: []RandomCut{{From: Pos{0, true}, To: Pos{10, true}}}, Seed: 1}, + SplitDelay: time.Hour, + } + w := WrapConn(raw, opts) + defer w.Close() + done := make(chan error, 1) + go func() { _, err := w.Write(rec); done <- err }() + time.Sleep(20 * time.Millisecond) + if err := w.SetWriteDeadline(time.Now()); err != nil { + t.Fatal(err) + } + select { + case err := <-done: + if !errors.Is(err, os.ErrDeadlineExceeded) { + t.Fatalf("delay error: %v", err) + } + case <-time.After(2 * time.Second): + t.Fatal("random split delay ignored a deadline change") + } +} + +func TestRandomValidation(t *testing.T) { + ok := []RandomOptions{ + {TLSRec: []RandomCut{{From: Pos{-3, true}, To: Pos{3, true}, Count: MaxRandomCount, MinPiece: 1}}}, + {Split: []RandomCut{{From: Pos{Offset: 1}, To: Pos{Offset: 1}}}, Seed: 1}, + {TLSRec: make([]RandomCut, MaxRandomRanges)}, + } + for i, r := range ok { + r := r + if err := (Options{Random: &r}).Validate(); err != nil { + t.Fatalf("valid %d: %v", i, err) + } + } + bad := []RandomOptions{ + {TLSRec: []RandomCut{{From: Pos{Offset: 1}, To: Pos{2, true}}}}, + {Split: []RandomCut{{From: Pos{Offset: 9}, To: Pos{Offset: 2}}}}, + {TLSRec: []RandomCut{{Count: -1}}}, + {TLSRec: []RandomCut{{Count: MaxRandomCount + 1}}}, + {Split: []RandomCut{{MinPiece: -1}}}, + {Split: []RandomCut{{MinPiece: DefaultMaxClientHelloSize + 1}}}, + {Split: make([]RandomCut, MaxRandomRanges+1)}, + } + for i, r := range bad { + r := r + err := (Options{Random: &r}).Validate() + if err == nil || !strings.HasPrefix(err.Error(), "desync: ") { + t.Fatalf("invalid %d accepted: %v", i, err) + } + // An invalid policy is terminal on the first write, never ignored. + raw := newSegmentSink(t) + r.TLSRec = append(r.TLSRec, RandomCut{}) + w := WrapConn(raw, Options{Random: &r}) + if _, err := w.Write(framingHello("random.example", 0)); err == nil || len(raw.segs) != 0 { + t.Fatalf("invalid %d was transmitted: %v", i, err) + } + } + fake := Options{Fake: &FakeOptions{TTL: 4}, Random: &RandomOptions{Split: []RandomCut{{}}}} + if err := fake.Validate(); err == nil || !strings.Contains(err.Error(), "split") { + t.Fatalf("fake with random split accepted: %v", err) + } +} + +func TestRandomOptionsAreCopied(t *testing.T) { + rec := framingHello("random.example", 300) + policy := RandomOptions{TLSRec: []RandomCut{{From: Pos{-8, true}, To: Pos{8, true}, Count: 2}}, Seed: 11} + opts := Options{Random: &policy} + want := randomRun(t, Options{Random: policy.clone()}, rec, len(rec)).data() + sink := newSegmentSink(t) + w := WrapConn(sink, opts) + defer w.Close() + policy.Seed = 12 + policy.TLSRec[0].Count = 9 + policy.TLSRec = append(policy.TLSRec, RandomCut{From: Pos{Offset: 1}, To: Pos{Offset: 100}}) + if _, err := w.Write(rec); err != nil { + t.Fatal(err) + } + if !bytes.Equal(sink.data(), want) { + t.Fatal("caller changes altered an existing wrapper") + } +} + +func TestOptionsKey(t *testing.T) { + base := Options{ + TLSRec: []Pos{{1, true}, {3, false}}, + Split: []Pos{{-2, true}}, + SplitDelay: time.Millisecond, + ClientHello: &ClientHelloOptions{MaxSize: 1024, MaxRecords: 8, Timeout: time.Second}, + Fake: &FakeOptions{TTL: 4, Prefix: -1, Payload: []byte{1, 2}, Timeout: time.Second}, + Random: &RandomOptions{ + TLSRec: []RandomCut{{From: Pos{-4, true}, To: Pos{4, true}, Count: 2, MinPiece: 3}}, + Split: []RandomCut{{From: Pos{Offset: 1}, To: Pos{Offset: 9}}}, + Seed: 5, + }, + } + const want = "desync/v1;tlsrec=1+s,3;split=-2+s;delay=1000000;hello=1024,8,1000000000;" + + "fake=ttl:4,prefix:-1,timeout:1000000000,payload:a12871fee210fb8619291eaea194581cbd2531e4b23759d225f6806923f63222;" + + "random=seed:5,tlsrec:[-4+s..4+s*2/3],split:[1..9*0/0]" + if got := base.Key(); got != want { + t.Fatalf("key changed:\n got %s\nwant %s", got, want) + } + if got := (Options{}).Key(); got != "desync/v1;tlsrec=;split=;delay=0;hello=default;fake=off;random=off" { + t.Fatalf("empty key: %s", got) + } + clone := func() Options { + o := base + o.TLSRec = append([]Pos(nil), base.TLSRec...) + o.Split = append([]Pos(nil), base.Split...) + h, f := *base.ClientHello, *base.Fake + o.ClientHello, o.Fake, o.Random = &h, &f, base.Random.clone() + return o + } + mutations := []func(*Options){ + func(o *Options) { o.TLSRec[0].Offset = 2 }, + func(o *Options) { o.TLSRec[1].FromSNI = true }, + func(o *Options) { o.Split = nil }, + func(o *Options) { o.SplitDelay = 0 }, + func(o *Options) { o.ClientHello = nil }, + func(o *Options) { o.ClientHello.MaxRecords = 9 }, + func(o *Options) { o.Fake.TTL = 5 }, + func(o *Options) { o.Fake.Payload = []byte{1, 3} }, + func(o *Options) { o.Fake.Payload = nil }, + func(o *Options) { o.Fake = nil }, + func(o *Options) { o.Random = nil }, + func(o *Options) { o.Random.Seed = 0 }, + func(o *Options) { o.Random.Seed = 6 }, + func(o *Options) { o.Random.TLSRec[0].Count = 3 }, + func(o *Options) { o.Random.TLSRec[0].MinPiece = 0 }, + func(o *Options) { o.Random.TLSRec[0].To.Offset = 5 }, + func(o *Options) { o.Random.TLSRec, o.Random.Split = o.Random.Split, o.Random.TLSRec }, + func(o *Options) { o.Random.Split = nil }, + } + seen := map[string]int{want: -1} + for i, m := range mutations { + o := clone() + m(&o) + k := o.Key() + if j, dup := seen[k]; dup { + t.Fatalf("mutation %d has the key of %d: %s", i, j, k) + } + seen[k] = i + } + if base.Key() != want { + t.Fatal("mutations altered the base options") + } +} + +func TestRandomVerifiedTLSHandshake(t *testing.T) { + ln, err := net.Listen("tcp4", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + defer ln.Close() + cert := selfSigned(t) + parsed, err := x509.ParseCertificate(cert.Certificate[0]) + if err != nil { + t.Fatal(err) + } + roots := x509.NewCertPool() + roots.AddCert(parsed) + policies := []*RandomOptions{ + {TLSRec: []RandomCut{{From: Pos{-30, true}, To: Pos{10, true}, Count: 6, MinPiece: 2}}, + Split: []RandomCut{{From: Pos{Offset: 1}, To: Pos{Offset: 400}, Count: 5, MinPiece: 20}}}, + {TLSRec: []RandomCut{{From: Pos{Offset: 0}, To: Pos{Offset: 1 << 14}, Count: MaxRandomCount}}, Seed: 77}, + } + go func() { + for { + raw, err := ln.Accept() + if err != nil { + return + } + go func() { + defer raw.Close() + raw.SetDeadline(time.Now().Add(5 * time.Second)) + conn := tls.Server(raw, &tls.Config{Certificates: []tls.Certificate{cert}}) + if conn.Handshake() == nil { + conn.Write([]byte("ok")) + } + }() + } + }() + for i := 0; i < 20; i++ { + raw, err := net.DialTimeout("tcp4", ln.Addr().String(), 2*time.Second) + if err != nil { + t.Fatal(err) + } + rc := &recConn{Conn: raw} + w := WrapConn(rc, Options{Random: policies[i%len(policies)]}) + w.SetDeadline(time.Now().Add(5 * time.Second)) + client := tls.Client(w, &tls.Config{ServerName: "www.youtube.com", RootCAs: roots}) + var reply [2]byte + if _, err = io.ReadFull(client, reply[:]); err != nil || string(reply[:]) != "ok" { + t.Fatalf("connection %d: %q %v", i, reply, err) + } + client.Close() + rc.mu.Lock() + segs := rc.segs + rc.mu.Unlock() + checkSegments(t, segs) + if len(segs) < 2 { + t.Fatalf("connection %d: hello was not transformed", i) + } + } +} + +// FuzzRandomCuts checks byte preservation, valid framing, non-empty writes, +// range/minimum-piece bounds and seed reproduction for arbitrary policies. +func FuzzRandomCuts(f *testing.F) { + f.Add(uint64(1), uint8(14), uint16(300), uint16(0), true, int16(-5), uint16(25), uint8(3), uint8(4), false, int16(0), uint16(400), uint8(4), uint8(16), uint8(0), []byte("tail")) + f.Add(uint64(0), uint8(1), uint16(0), uint16(40), false, int16(0), uint16(9000), uint8(64), uint8(1), true, int16(-200), uint16(300), uint8(64), uint8(0), uint8(1), []byte(nil)) + f.Add(uint64(42), uint8(200), uint16(8000), uint16(7), false, int16(-100), uint16(65535), uint8(17), uint8(250), false, int16(30), uint16(1), uint8(1), uint8(1), uint8(63), []byte{22, 3, 3, 0, 1, 1}) + f.Fuzz(func(t *testing.T, seed uint64, hostLen uint8, padding, reframe uint16, + recSNI bool, recFrom int16, recWidth uint16, recCount, recMin uint8, + splitSNI bool, splitFrom int16, splitWidth uint16, splitCount, splitMin uint8, + chunkByte uint8, tail []byte) { + host := strings.Repeat("h", 1+int(hostLen)%200) + rec := framingHello(host, int(padding)%9000) + wire := rec + if r := int(reframe) % len(rec[5:]); r > 0 { + wire = reframeInput(rec, r) + } + wire = append(append([]byte(nil), wire...), tail...) + rc := RandomCut{From: Pos{int(recFrom), recSNI}, Count: int(recCount) % (MaxRandomCount + 1), MinPiece: int(recMin)} + rc.To = Pos{rc.From.Offset + int(recWidth), recSNI} + sc := RandomCut{From: Pos{int(splitFrom), splitSNI}, Count: int(splitCount) % (MaxRandomCount + 1), MinPiece: int(splitMin)} + sc.To = Pos{sc.From.Offset + int(splitWidth), splitSNI} + opts := Options{Random: &RandomOptions{TLSRec: []RandomCut{rc}, Split: []RandomCut{sc}, Seed: seed}} + if err := opts.Validate(); err != nil { + t.Fatal(err) + } + chunk := 1 + int(chunkByte)%64 + sink := randomRun(t, opts, wire, chunk) + checkSegments(t, sink.segs) + bounds := checkRandomOutput(t, wire, sink.data()) + h, _ := ParseHello(rec) + sni := h.SNIOffset - recordHeaderLen + // Without deterministic positions, every boundary is an input + // boundary or a drawn cut inside the clipped range. + var scanner helloScanner + frame, _ := scanner.scan(wire, (*ClientHelloOptions)(nil).limits()) + lo, hi := frame.logicalAt(rc.From.Offset), frame.logicalAt(rc.To.Offset) + if recSNI { + lo, hi = sni+rc.From.Offset, sni+rc.To.Offset + } + existing := map[int]bool{} + for i, logical := 1, 0; i < frame.records.count; i++ { + r := frame.records.at(i - 1) + logical += r.end - r.start - recordHeaderLen + existing[logical] = true + } + gap := rc.MinPiece + if gap < 1 { + gap = 1 + } + prev := -1 + drawn := 0 + for _, b := range bounds { + if existing[b] { + continue + } + drawn++ + if b < lo || b > hi || b < gap || b > frame.size-gap { + t.Fatalf("cut %d outside [%d,%d] gap=%d size=%d", b, lo, hi, gap, frame.size) + } + if prev >= 0 && b-prev < gap { + t.Fatalf("cuts %d and %d closer than %d", prev, b, gap) + } + prev = b + } + want := rc.Count + if want == 0 { + want = 1 + } + if drawn > want { + t.Fatalf("%d cuts drawn, at most %d requested", drawn, want) + } + if seed != 0 { + again := randomRun(t, opts, wire, len(wire)) + if !bytes.Equal(again.data(), sink.data()) { + t.Fatal("seeded output not reproduced") + } + } + }) +} diff --git a/tlsrec.go b/tlsrec.go index 73990a5..add8321 100644 --- a/tlsrec.go +++ b/tlsrec.go @@ -3,7 +3,11 @@ package desync import "sort" func (f helloFrame) cuts(positions []Pos, recordOnly bool) []int { - var cuts []int + return f.normalizeCuts(f.positionCuts(nil, positions), recordOnly) +} + +// positionCuts appends the wire offsets of deterministic positions. +func (f helloFrame) positionCuts(cuts []int, positions []Pos) []int { end := f.handshakeEnd() for _, p := range positions { at := p.Offset @@ -17,6 +21,12 @@ func (f helloFrame) cuts(positions []Pos, recordOnly bool) []int { cuts = append(cuts, at) } } + return cuts +} + +// normalizeCuts sorts and deduplicates cuts in place. Record cuts also drop +// offsets inside or at the edges of an existing record, so no record is empty. +func (f helloFrame) normalizeCuts(cuts []int, recordOnly bool) []int { sort.Ints(cuts) unique := cuts[:0] span := 0 From 4849150f2c9b8c7483b4e3e0b7a4eed32a927960 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Wed, 28 Oct 2026 20:47:00 +0300 Subject: [PATCH 2/2] docs: describe randomization policy and strategy keys --- README.md | 17 +++++++++++++++++ docs/connection-io.md | 2 +- docs/controller.md | 7 +++++++ docs/validation.md | 5 ++++- docs/vnext.md | 15 +++++++++++++++ 5 files changed, 44 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fc769eb..fdf51b4 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/docs/connection-io.md b/docs/connection-io.md index cb11fe9..b5a2cfb 100644 --- a/docs/connection-io.md +++ b/docs/connection-io.md @@ -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{ diff --git a/docs/controller.md b/docs/controller.md index 29d2a5d..e139b2d 100644 --- a/docs/controller.md +++ b/docs/controller.md @@ -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 | diff --git a/docs/validation.md b/docs/validation.md index 495b114..05d2cf4 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -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 ``` @@ -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. diff --git a/docs/vnext.md b/docs/vnext.md index f3c47a0..f124726 100644 --- a/docs/vnext.md +++ b/docs/vnext.md @@ -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 @@ -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.