From 3fbcbd11b5627958c64d4f3b100e9c4ecb941b26 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Thu, 29 Oct 2026 20:38:53 +0300 Subject: [PATCH 1/4] feat(fake): decoy ClientHello and fake combined with split pieces FakeOptions gains SNI (a list, one name drawn per connection, ByeDPI wildcards), FromOriginal, Randomize and Offset (ByeDPI --fake-sni, --fake-tls-mod orig/rand, --fake-offset). The decoy is decoded and re-encoded as a valid ClientHello with every length recomputed, then padded or truncated to the fake piece. Fake now combines with Split, Random.Split, Disorder, OOB, SplitDelay and SplitWaitSent: the fake prefix end is one more cut and the piece ending there is the fake, as in ByeDPI's part sequence. A fake first piece with Disorder/OOB fails with ErrFakeFirstPiece before sending; SplitWaitAcked is rejected. Linux lowers the hop limit only after SIOCOUTQNSD reports the earlier pieces sent; Windows writes the later pieces right after the TransmitFile submission. Key() lists the decoy options only when set. --- conn.go | 133 +++++++++++---- disorder.go | 3 - disorder_test.go | 3 +- fake.go | 87 ++++++++-- fake_hello.go | 395 +++++++++++++++++++++++++++++++++++++++++++ fake_hello_test.go | 211 +++++++++++++++++++++++ fake_linux.go | 29 ++-- fake_linux_test.go | 31 +++- fake_other.go | 4 +- fake_split_test.go | 204 ++++++++++++++++++++++ fake_test.go | 19 ++- fake_windows.go | 18 +- fake_windows_test.go | 41 +++++ key.go | 16 ++ random_test.go | 10 +- third_party/NOTICE | 12 ++ 16 files changed, 1137 insertions(+), 79 deletions(-) create mode 100644 fake_hello.go create mode 100644 fake_hello_test.go create mode 100644 fake_split_test.go diff --git a/conn.go b/conn.go index 6f938e9..7b433f2 100644 --- a/conn.go +++ b/conn.go @@ -4,6 +4,7 @@ import ( "io" "net" "os" + "sort" "sync" "sync/atomic" "time" @@ -98,6 +99,7 @@ func WrapConn(c net.Conn, opts Options) net.Conn { auto := *fake.AutoTTL fake.AutoTTL = &auto } + fake.SNI = append([]string(nil), fake.SNI...) opts.Fake = &fake } if opts.OOB != nil { @@ -303,68 +305,133 @@ func (c *Conn) sendHello(rec []byte, frame helloFrame) (int, error) { if len(recCuts) > 0 { out = fragmentHello(rec, frame, recCuts) } - start := 0 + if !c.opts.Random.enabled() { + splitCuts = frame.cuts(c.opts.Split, false) + } + s := pieceSender{c: c, out: out, ends: mapCuts(splitCuts, recCuts), fakeEnd: -1} if c.opts.Fake != nil { + // The fake prefix end is one more cut; the fake piece ends there. prefix, err := fakePrefixLength(len(out), c.opts.Fake.Prefix) if err != nil { return 0, err } - // Submit the normal tail before waiting for the native prefix. A - // low-TTL prefix can still be pending when this tail reaches the peer. - if err := c.sendFake(out[:prefix], fakePayload(c.opts.Fake.Payload, prefix), out[prefix:]); err != nil { - // A failed native asynchronous send has no reliable prefix count. - // Report zero conservatively and terminate; never replay this stream. - return 0, err - } - return len(rec), nil - } - if !c.opts.Random.enabled() { - splitCuts = frame.cuts(c.opts.Split, false) + s.fakeEnd = prefix } - tcpCuts := mapCuts(splitCuts, recCuts) - var ack ackObserver - var first *firstPiece - if len(tcpCuts) > 0 { + if len(s.ends) > 0 { var err error - if ack, err = c.splitObserver(); err != nil { + if s.ack, err = c.splitObserver(); err != nil { + return 0, err + } + if s.first, err = c.prepareFirstPiece(s.ack); err != nil { return 0, err } - if first, err = c.prepareFirstPiece(ack); err != nil { + } + if s.fakeEnd >= 0 { + firstEnd := s.fakeEnd + if len(s.ends) > 0 && s.ends[0] < firstEnd { + firstEnd = s.ends[0] + } + if firstEnd == s.fakeEnd && s.first != nil { + return 0, ErrFakeFirstPiece + } + s.ends = insertCut(s.ends, s.fakeEnd) + decoy, err := c.fakeDecoy(rec, frame) + if err != nil { return 0, err } + s.decoy = decoy + } + s.ends = append(s.ends, len(out)) + if err := s.send(0, 0); err != nil { + if s.fakeStarted { + // A failed native asynchronous send has no reliable count: report + // only the pieces before the fake piece and terminate; never + // replay this stream. + return originalWriteCount(s.beforeFake, recCuts), err + } + return originalWriteCount(s.written, recCuts), err } + return len(rec), nil +} + +// pieceSender writes the TCP pieces of one transformed ClientHello. +type pieceSender struct { + c *Conn + out []byte + ends []int // piece ends in out, ascending, the last is len(out) + ack ackObserver + first *firstPiece + // fakeEnd is the end of the fake piece, -1 without Fake; decoy is the + // connection's decoy bytes. + fakeEnd int + decoy []byte // written counts bytes of out; extra counts urgent bytes, which are on - // the socket but not part of the stream the server reads. - written, extra := 0, 0 - for i, end := range append(tcpCuts, len(out)) { - if end <= start || end > len(out) { + // the socket but not part of the stream the server reads. beforeFake is + // written when the fake piece started. + written, extra, beforeFake int + fakeStarted bool +} + +// send writes the pieces from index i on, the first of them starting at +// start. The fake piece hands the pieces after it to the native backend, +// which writes them as soon as the low-hop transmission allows. +func (s *pieceSender) send(i, start int) error { + c := s.c + for ; i < len(s.ends); i++ { + end := s.ends[i] + if end <= start || end > len(s.out) { continue } - if i > 0 && ack != nil { - if err := c.waitSplit(ack, int64(written+extra)); err != nil { - return originalWriteCount(written, recCuts), err + if i > 0 && s.ack != nil { + if err := c.waitSplit(s.ack, int64(s.written+s.extra)); err != nil { + return err } } if i > 0 && c.opts.SplitDelay > 0 { if err := c.waitWriteDelay(c.opts.SplitDelay); err != nil { - return originalWriteCount(written, recCuts), err + return err } } + piece := s.out[start:end] + if end == s.fakeEnd { + s.fakeStarted, s.beforeFake = true, s.written + next := i + 1 + payload := fakeBytes(s.decoy, c.opts.Fake.Offset, len(piece)) + return sendFakePieceFunc(c, piece, payload, start > 0, func() error { + s.written += len(piece) + return s.send(next, end) + }) + } var n, urgent int var err error - if i == 0 && first != nil { - n, urgent, err = first.send(c, out[start:end]) + if i == 0 && s.first != nil { + n, urgent, err = s.first.send(c, piece) } else { - n, err = writeAllCount(c.Conn, out[start:end]) + n, err = writeAllCount(c.Conn, piece) } - written += n - extra += urgent + s.written += n + s.extra += urgent if err != nil { - return originalWriteCount(written, recCuts), err + return err } start = end } - return len(rec), nil + return nil +} + +// sendFakePieceFunc is replaced by tests to observe the fake piece. +var sendFakePieceFunc = (*Conn).sendFakePiece + +// insertCut adds at to the ascending cuts unless it is already there. +func insertCut(cuts []int, at int) []int { + i := sort.SearchInts(cuts, at) + if i < len(cuts) && cuts[i] == at { + return cuts + } + cuts = append(cuts, 0) + copy(cuts[i+1:], cuts[i:]) + cuts[i] = at + return cuts } func writeAll(w io.Writer, p []byte) error { diff --git a/disorder.go b/disorder.go index 0ce7c30..b1821df 100644 --- a/disorder.go +++ b/disorder.go @@ -66,9 +66,6 @@ func (o Options) validateSocketMethods() error { if !o.splits() { return fmt.Errorf("desync: disorder and OOB require Split or Random.Split positions") } - if o.Fake != nil { - return fmt.Errorf("desync: fake cannot be combined with disorder or OOB yet") - } if o.Disorder && o.SplitWait == SplitWaitAcked { // The low-hop piece is acknowledged only after its retransmission, // so an acknowledged wait would undo the reordering. diff --git a/disorder_test.go b/disorder_test.go index f11f3ef..ad10ce0 100644 --- a/disorder_test.go +++ b/disorder_test.go @@ -22,8 +22,7 @@ func TestSocketMethodValidation(t *testing.T) { "disorder without split": {Disorder: true}, "oob without split": {OOB: &OOBOptions{}}, "disorder records only": {TLSRec: split, Disorder: true}, - "disorder and fake": {Split: split, Disorder: true, Fake: &FakeOptions{TTL: 4}}, - "oob and fake": {Split: split, OOB: &OOBOptions{}, Fake: &FakeOptions{TTL: 4}}, + "oob and fake, acked": {Split: split, OOB: &OOBOptions{}, SplitWait: SplitWaitAcked, Fake: &FakeOptions{TTL: 4}}, "disorder and acked": {Split: split, Disorder: true, SplitWait: SplitWaitAcked}, } { if err := o.Validate(); err == nil { diff --git a/fake.go b/fake.go index b189c0e..46164cd 100644 --- a/fake.go +++ b/fake.go @@ -12,12 +12,22 @@ var ( ErrFakeUnsupported = errors.New("desync: TCP fake is not implemented on this platform") ErrFakeRequiresTCP = errors.New("desync: TCP fake requires a connection exposing SyscallConn") ErrFakeBusy = errors.New("desync: too many pending TCP fake operations") + // ErrFakeFirstPiece reports that, for this ClientHello, the fake piece + // would be the first TCP piece, which Disorder or OOB already sends. It + // is returned before any byte is written. + ErrFakeFirstPiece = errors.New("desync: the fake piece is the first TCP piece, which Disorder/OOB send; add a split position before the fake prefix") ) -// FakeOptions changes a prefix's initial transmission to low-TTL bytes while -// retaining the original prefix for TCP retransmission. It does not insert -// bytes into the application's stream. Implemented on Windows and Linux -// (including Android); see PlatformCapabilities for the macOS reason. +// FakeOptions changes one TCP piece's initial transmission to low-TTL decoy +// bytes while retaining the original piece for TCP retransmission. It does +// not insert bytes into the application's stream. Implemented on Windows and +// Linux (including Android); see PlatformCapabilities for the macOS reason. +// +// Without Split the fake piece is the prefix [0, Prefix). With Split or +// Random.Split positions the prefix end is one more cut, and the fake piece +// is the piece that ends there (ByeDPI --fake as one of several parts): the +// pieces before it and after it are ordinary writes, Disorder/OOB still act +// on the first piece, and SplitDelay/SplitWaitSent apply between pieces. type FakeOptions struct { // TTL expires the fake before the server (1..255). With AutoTTL it is // the fallback used when the path cannot be observed; 0 then fails the @@ -27,16 +37,42 @@ type FakeOptions struct { // connection (see AutoTTL, ControlAutoTTL and // PlatformCapabilities().AutoTTL). AutoTTL *AutoTTL - // Prefix is measured after TLS record fragmentation. Negative offsets - // count from the end; zero defaults to -1 (all but the last byte). + // Prefix is the end of the fake piece, measured after TLS record + // fragmentation. Negative offsets count from the end; zero defaults to + // -1 (all but the last byte). Prefix int // Payload defaults to ByeDPI v0.17.3's MIT-licensed TLS template. - // It is zero-padded or truncated to the selected prefix length. + // It is zero-padded or truncated to the fake piece's length. Payload []byte // Timeout defaults to 3 seconds for native queue/completion waits. // Normal tail writes obey the connection's write deadline. A deadline on // the wrapper can shorten native waits; Close interrupts them. Timeout time.Duration + + // Decoy ClientHello (ByeDPI --fake-sni, --fake-tls-mod, --fake-offset). + // With any of SNI, FromOriginal or Randomize the decoy is re-encoded per + // connection as a valid ClientHello with every length recomputed, then + // padded/truncated to the fake piece like Payload. + + // SNI replaces the decoy's server name. With several names one is drawn + // per connection. In a name '*' becomes a random letter or digit, '?' a + // random letter and '#' a random digit. Names must be DNS host names + // (at most 64 names). A template's padding extension absorbs the length + // change, so the template keeps its 517 bytes. + SNI []string + // FromOriginal builds the decoy from the connection's own ClientHello + // (ByeDPI --fake-tls-mod orig) instead of Payload or the template. It + // needs SNI or Randomize and excludes Payload. + FromOriginal bool + // Randomize replaces the decoy's random, session ID and key share values + // with fresh random bytes per connection (ByeDPI --fake-tls-mod rand). + // It needs a ClientHello decoy (the template, a ClientHello Payload or + // FromOriginal). + Randomize bool + // Offset starts the decoy transmission at this byte of the decoy + // (ByeDPI --fake-offset), for example to align a decoy with a fake + // piece that does not start the stream. 0 starts at its first byte. + Offset int } // SupportsFake reports platform availability, not effectiveness on a network. @@ -67,8 +103,14 @@ func (o Options) Validate() error { if o.Fake.Timeout < 0 { return fmt.Errorf("desync: fake timeout must not be negative") } - if o.splits() { - return fmt.Errorf("desync: fake and TCP split cannot be combined yet") + if err := o.Fake.validateDecoy(); err != nil { + return err + } + if o.splits() && o.SplitWait == SplitWaitAcked { + // The low-hop fake piece is acknowledged only after its + // retransmission, so the wait after it would last a retransmission + // timeout and undo the order the fake relies on. + return fmt.Errorf("desync: fake cannot be combined with SplitWaitAcked") } if !SupportsFake() { return ErrFakeUnsupported @@ -93,9 +135,17 @@ func fakePayload(data []byte, size int) []byte { if len(data) == 0 { data = defaultFakeTLS() } - out := make([]byte, size) - copy(out, data) - return out + return fakeBytes(data, 0, size) +} + +// sendFake sends real as the fake piece and then tail as an ordinary write. +func (c *Conn) sendFake(real, payload, tail []byte) error { + return c.sendFakePiece(real, payload, false, func() error { + if err := writeAll(c.Conn, tail); err != nil { + return fmt.Errorf("desync: TCP fake: write original tail: %w", err) + } + return nil + }) } func (c *Conn) fakeAbort(start time.Time) error { @@ -104,10 +154,7 @@ func (c *Conn) fakeAbort(start time.Time) error { return net.ErrClosed default: } - timeout := c.opts.Fake.Timeout - if timeout == 0 { - timeout = 3 * time.Second - } + timeout := c.fakeTimeout() c.deadlineMu.Lock() deadline := c.writeDeadline c.deadlineMu.Unlock() @@ -117,3 +164,11 @@ func (c *Conn) fakeAbort(start time.Time) error { } return nil } + +// fakeTimeout is Fake.Timeout or its 3-second default. +func (c *Conn) fakeTimeout() time.Duration { + if c.opts.Fake.Timeout == 0 { + return 3 * time.Second + } + return c.opts.Fake.Timeout +} diff --git a/fake_hello.go b/fake_hello.go new file mode 100644 index 0000000..b73589c --- /dev/null +++ b/fake_hello.go @@ -0,0 +1,395 @@ +package desync + +import ( + crand "crypto/rand" + "encoding/binary" + "errors" + "fmt" + "net" + "strings" +) + +// The decoy ClientHello builder behind FakeOptions.SNI, FromOriginal and +// Randomize. It follows the options of ByeDPI v0.17.3 (--fake-sni and +// --fake-tls-mod rand/orig, packets.c change_tls_sni, randomize_tls and +// copy_name; MIT, see third_party/BYEDPI-LICENSE), reimplemented by parsing +// and re-encoding the handshake, so every length is recomputed. + +const ( + extPadding = 0x0015 + extKeyShare = 0x0033 + // maxFakeSNI bounds FakeOptions.SNI; one name is drawn per connection. + maxFakeSNI = 64 + // maxFakeOffset bounds FakeOptions.Offset (a decoy is at most one + // ClientHello plus padding). + maxFakeOffset = 1 << 16 +) + +var errBadDecoyHello = errors.New("desync: fake payload is not a TLS ClientHello") + +// tlsExt is one ClientHello extension; data excludes type and length. +type tlsExt struct { + typ uint16 + data []byte +} + +// tlsHello is a parsed ClientHello handshake message. +type tlsHello struct { + record [3]byte // content type and record version used to re-frame it + version [2]byte + random [32]byte + sessionID []byte + suites []byte + compression []byte + exts []tlsExt + hasExts bool // TLS 1.2 may omit the extension vector +} + +type byteReader struct { + b []byte + ok bool +} + +func (r *byteReader) take(n int) []byte { + if !r.ok || n < 0 || n > len(r.b) { + r.ok = false + return nil + } + v := r.b[:n:n] + r.b = r.b[n:] + return v +} + +func (r *byteReader) u8() int { + v := r.take(1) + if v == nil { + return 0 + } + return int(v[0]) +} + +func (r *byteReader) u16() int { + v := r.take(2) + if v == nil { + return 0 + } + return int(binary.BigEndian.Uint16(v)) +} + +// decodeHello parses the handshake message of a complete ClientHello given +// as wire bytes (one or more records). The result references fresh copies. +func decodeHello(wire []byte) (*tlsHello, error) { + var s helloScanner + frame, err := s.scan(wire, (*ClientHelloOptions)(nil).limits()) + if err != nil { + return nil, err + } + return decodeHelloFrame(wire, frame) +} + +// decodeHelloFrame parses the hello described by frame inside wire. +func decodeHelloFrame(wire []byte, frame helloFrame) (*tlsHello, error) { + msg := make([]byte, 0, frame.size) + for i := 0; i < frame.records.count && len(msg) < frame.size; i++ { + r := frame.records.at(i) + part := wire[r.start+recordHeaderLen : r.end] + if n := frame.size - len(msg); len(part) > n { + part = part[:n] + } + msg = append(msg, part...) + } + if len(msg) != frame.size || len(msg) < 4 || msg[0] != handshakeClientHelo { + return nil, errBadDecoyHello + } + h := &tlsHello{} + copy(h.record[:], wire[:3]) + r := byteReader{b: msg[4:], ok: true} + copy(h.version[:], r.take(2)) + copy(h.random[:], r.take(32)) + h.sessionID = r.take(r.u8()) + h.suites = r.take(r.u16()) + h.compression = r.take(r.u8()) + if !r.ok || len(h.sessionID) > 32 || len(h.suites) < 2 || len(h.suites)%2 != 0 || len(h.compression) == 0 { + return nil, errBadDecoyHello + } + if len(r.b) == 0 { + return h, nil + } + h.hasExts = true + extBytes := r.take(r.u16()) + exts := byteReader{b: extBytes, ok: r.ok} + if !r.ok || len(r.b) != 0 { + return nil, errBadDecoyHello + } + for len(exts.b) > 0 { + typ := uint16(exts.u16()) + data := exts.take(exts.u16()) + if !exts.ok { + return nil, errBadDecoyHello + } + h.exts = append(h.exts, tlsExt{typ: typ, data: data}) + } + return h, nil +} + +func (h *tlsHello) ext(typ uint16) int { + for i, e := range h.exts { + if e.typ == typ { + return i + } + } + return -1 +} + +// size is the length of the handshake message, its 4-byte header included. +func (h *tlsHello) size() int { + n := 4 + 2 + 32 + 1 + len(h.sessionID) + 2 + len(h.suites) + 1 + len(h.compression) + if h.hasExts { + n += 2 + for _, e := range h.exts { + n += 4 + len(e.data) + } + } + return n +} + +// message encodes the handshake message with every length recomputed. +func (h *tlsHello) message() []byte { + n := h.size() + b := make([]byte, 0, n) + b = append(b, handshakeClientHelo, byte((n-4)>>16), byte((n-4)>>8), byte(n-4)) + b = append(b, h.version[:]...) + b = append(b, h.random[:]...) + b = append(b, byte(len(h.sessionID))) + b = append(b, h.sessionID...) + b = binary.BigEndian.AppendUint16(b, uint16(len(h.suites))) + b = append(b, h.suites...) + b = append(b, byte(len(h.compression))) + b = append(b, h.compression...) + if h.hasExts { + total := 0 + for _, e := range h.exts { + total += 4 + len(e.data) + } + b = binary.BigEndian.AppendUint16(b, uint16(total)) + for _, e := range h.exts { + b = binary.BigEndian.AppendUint16(b, e.typ) + b = binary.BigEndian.AppendUint16(b, uint16(len(e.data))) + b = append(b, e.data...) + } + } + return b +} + +// wire frames the handshake message in TLS records of at most 16 KiB. +func (h *tlsHello) wire() []byte { + msg := h.message() + out := make([]byte, 0, len(msg)+recordHeaderLen*(1+len(msg)/maxRecordPayload)) + for len(msg) > 0 { + n := len(msg) + if n > maxRecordPayload { + n = maxRecordPayload + } + out = append(out, h.record[0], h.record[1], h.record[2], byte(n>>8), byte(n)) + out = append(out, msg[:n]...) + msg = msg[n:] + } + return out +} + +// setSNI replaces (or, when missing, prepends) the server_name extension. +// A padding extension absorbs the size change where it can, so a template +// keeps its length. The result can exceed 16 bits only for absurd inputs, +// which validation rules out. +func (h *tlsHello) setSNI(name string) { + before := h.size() + data := make([]byte, 0, 5+len(name)) + data = binary.BigEndian.AppendUint16(data, uint16(len(name)+3)) + data = append(data, sniHostNameType) + data = binary.BigEndian.AppendUint16(data, uint16(len(name))) + data = append(data, name...) + h.hasExts = true + if i := h.ext(extServerName); i >= 0 { + h.exts[i].data = data + } else { + h.exts = append([]tlsExt{{typ: extServerName, data: data}}, h.exts...) + } + if i := h.ext(extPadding); i >= 0 { + if n := len(h.exts[i].data) - (h.size() - before); n >= 0 { + h.exts[i].data = make([]byte, n) + } + } +} + +// randomize replaces the random, the session ID and the key share values +// (ByeDPI randomize_tls). Lengths are unchanged. +func (h *tlsHello) randomize() error { + if _, err := crand.Read(h.random[:]); err != nil { + return err + } + sid := make([]byte, len(h.sessionID)) + if _, err := crand.Read(sid); err != nil { + return err + } + h.sessionID = sid + i := h.ext(extKeyShare) + if i < 0 { + return nil + } + data := append([]byte(nil), h.exts[i].data...) + r := byteReader{b: data, ok: true} + shares := r.take(r.u16()) + list := byteReader{b: shares, ok: r.ok} + for len(list.b) > 0 { + list.take(2) // group + key := list.take(list.u16()) + if !list.ok { + break // malformed shares stay as they were + } + if _, err := crand.Read(key); err != nil { + return err + } + } + h.exts[i].data = data + return nil +} + +// expandFakeSNI replaces ByeDPI's wildcards: '*' a random lower-case letter +// or digit, '?' a random letter, '#' a random digit. +func expandFakeSNI(name string) (string, error) { + if !strings.ContainsAny(name, "*?#") { + return name, nil + } + random := make([]byte, len(name)) + if _, err := crand.Read(random); err != nil { + return "", err + } + const letters, digits = "abcdefghijklmnopqrstuvwxyz", "0123456789" + b := []byte(name) + for i, c := range b { + switch c { + case '*': + b[i] = (digits + letters)[int(random[i])%36] + case '?': + b[i] = letters[int(random[i])%26] + case '#': + b[i] = digits[int(random[i])%10] + } + } + return string(b), nil +} + +// validFakeSNI checks a decoy server name as a DNS host name (RFC 1123 +// letters, digits and hyphens; wildcards count as letters). IP literals are +// rejected: RFC 6066 does not allow them in server_name. +func validFakeSNI(name string) error { + if name == "" || len(name) > 253 { + return fmt.Errorf("desync: fake SNI %q must be 1 to 253 bytes", name) + } + if net.ParseIP(name) != nil { + return fmt.Errorf("desync: fake SNI %q is an IP address", name) + } + for _, label := range strings.Split(name, ".") { + if label == "" || len(label) > 63 { + return fmt.Errorf("desync: fake SNI %q has an empty or over-long label", name) + } + if label[0] == '-' || label[len(label)-1] == '-' { + return fmt.Errorf("desync: fake SNI %q has a label starting or ending with '-'", name) + } + for i := 0; i < len(label); i++ { + c := label[i] + if !(c >= 'a' && c <= 'z' || c >= 'A' && c <= 'Z' || c >= '0' && c <= '9' || c == '-' || c == '*' || c == '?' || c == '#') { + return fmt.Errorf("desync: fake SNI %q contains %q", name, c) + } + } + } + return nil +} + +// modifiesHello reports whether the decoy is built per connection. +func (f *FakeOptions) modifiesHello() bool { + return len(f.SNI) > 0 || f.FromOriginal || f.Randomize +} + +func (f *FakeOptions) validateDecoy() error { + if f.Offset < 0 || f.Offset >= maxFakeOffset { + return fmt.Errorf("desync: fake offset must be between 0 and %d", maxFakeOffset-1) + } + if len(f.SNI) > maxFakeSNI { + return fmt.Errorf("desync: at most %d fake SNI names", maxFakeSNI) + } + for _, name := range f.SNI { + if err := validFakeSNI(name); err != nil { + return err + } + } + if f.FromOriginal { + if len(f.Payload) > 0 { + return fmt.Errorf("desync: fake FromOriginal and Payload are mutually exclusive") + } + if len(f.SNI) == 0 && !f.Randomize { + return fmt.Errorf("desync: fake FromOriginal needs SNI or Randomize, otherwise the decoy equals the original") + } + return nil + } + if f.modifiesHello() && len(f.Payload) > 0 { + if _, err := decodeHello(f.Payload); err != nil { + return fmt.Errorf("desync: fake SNI/Randomize need a ClientHello payload: %w", err) + } + } + return nil +} + +// fakeDecoy returns the decoy bytes for this connection: Payload or the +// template, or, with SNI/FromOriginal/Randomize, a ClientHello rebuilt from +// them (or from the connection's own hello in rec) with valid lengths. +func (c *Conn) fakeDecoy(rec []byte, frame helloFrame) ([]byte, error) { + f := c.opts.Fake + base := f.Payload + if len(base) == 0 { + base = defaultFakeTLS() + } + if !f.modifiesHello() { + return base, nil + } + var h *tlsHello + var err error + if f.FromOriginal { + h, err = decodeHelloFrame(rec, frame) + } else { + h, err = decodeHello(base) + } + if err != nil { + return nil, fmt.Errorf("desync: build fake ClientHello: %w", err) + } + if len(f.SNI) > 0 { + name := f.SNI[0] + if len(f.SNI) > 1 { + var b [4]byte + if _, err := crand.Read(b[:]); err != nil { + return nil, err + } + name = f.SNI[binary.LittleEndian.Uint32(b[:])%uint32(len(f.SNI))] + } + if name, err = expandFakeSNI(name); err != nil { + return nil, err + } + h.setSNI(name) + } + if f.Randomize { + if err := h.randomize(); err != nil { + return nil, err + } + } + return h.wire(), nil +} + +// fakeBytes is the first transmission of a piece of size bytes: the decoy +// from offset on, zero-padded or truncated. +func fakeBytes(decoy []byte, offset, size int) []byte { + out := make([]byte, size) + if offset < len(decoy) { + copy(out, decoy[offset:]) + } + return out +} diff --git a/fake_hello_test.go b/fake_hello_test.go new file mode 100644 index 0000000..71e69f7 --- /dev/null +++ b/fake_hello_test.go @@ -0,0 +1,211 @@ +package desync + +import ( + "bytes" + "errors" + "strings" + "testing" +) + +// decoyFor builds the decoy of opts for the ClientHello rec. +func decoyFor(t *testing.T, fake FakeOptions, rec []byte) []byte { + t.Helper() + if err := fake.validateDecoy(); err != nil { + t.Fatal(err) + } + var frame helloFrame + if rec != nil { + var s helloScanner + var err error + if frame, err = s.scan(rec, (*ClientHelloOptions)(nil).limits()); err != nil { + t.Fatal(err) + } + } + c := &Conn{opts: Options{Fake: &fake}} + decoy, err := c.fakeDecoy(rec, frame) + if err != nil { + t.Fatal(err) + } + return decoy +} + +func TestFakeSNITemplate(t *testing.T) { + for _, name := range []string{"a.b", "www.example.com", strings.Repeat("x", 63) + "." + strings.Repeat("y", 63) + "." + strings.Repeat("z", 60) + ".com"} { + decoy := decoyFor(t, FakeOptions{TTL: 4, SNI: []string{name}}, nil) + h, err := ParseHello(decoy) + if err != nil || h.SNI != name { + t.Fatalf("%s: %+v %v", name, h, err) + } + if len(name) <= 17+172 && len(decoy) != 517 { + t.Fatalf("%s: the padding did not absorb the change: %d bytes", name, len(decoy)) + } + // The rest of the template is kept. + orig, _ := decodeHello(defaultFakeTLS()) + got, err := decodeHello(decoy) + if err != nil || len(got.exts) != len(orig.exts) || got.random != orig.random || !bytes.Equal(got.suites, orig.suites) { + t.Fatalf("%s: template changed beyond the SNI: %v", name, err) + } + } + if defaultFakeTLS()[0] != 0x16 || mustParse(t, defaultFakeTLS()).SNI != "www.wikipedia.org" { + t.Fatal("template was modified") + } +} + +func TestFakeSNIListAndWildcards(t *testing.T) { + names := []string{"one.example", "two.example", "three.example"} + seen := map[string]bool{} + for i := 0; i < 200 && len(seen) < len(names); i++ { + h := mustParse(t, decoyFor(t, FakeOptions{TTL: 4, SNI: names}, nil)) + seen[h.SNI] = true + } + for _, n := range names { + if !seen[n] { + t.Fatalf("name %s never drawn: %v", n, seen) + } + } + for i := 0; i < 50; i++ { + sni := mustParse(t, decoyFor(t, FakeOptions{TTL: 4, SNI: []string{"w*?#.example"}}, nil)).SNI + if len(sni) != len("w*?#.example") || !strings.HasSuffix(sni, ".example") || sni[0] != 'w' { + t.Fatalf("expanded %q", sni) + } + a, l, d := sni[1], sni[2], sni[3] + if !(a >= 'a' && a <= 'z' || a >= '0' && a <= '9') || !(l >= 'a' && l <= 'z') || !(d >= '0' && d <= '9') { + t.Fatalf("wildcards expanded to %q", sni) + } + } +} + +func TestFakeFromOriginal(t *testing.T) { + rec := captureHello(t, "real.example") + orig, err := decodeHello(rec) + if err != nil { + t.Fatal(err) + } + // Input split into several records parses as one hello again. + for _, input := range [][]byte{rec, reframeInput(rec, 7, 100)} { + decoy := decoyFor(t, FakeOptions{TTL: 4, FromOriginal: true, SNI: []string{"decoy.example.org"}}, input) + h := mustParse(t, decoy) + if h.SNI != "decoy.example.org" { + t.Fatalf("SNI %q", h.SNI) + } + got, err := decodeHello(decoy) + if err != nil || len(got.exts) != len(orig.exts) || got.random != orig.random || !bytes.Equal(got.sessionID, orig.sessionID) { + t.Fatalf("decoy differs from the original beyond the SNI: %v", err) + } + if len(decoy) != len(rec)+len("decoy.example.org")-len("real.example") { + t.Fatalf("decoy has %d bytes, original %d", len(decoy), len(rec)) + } + } + // Without SNI the name is missing; the decoy gets one. + noSNI := framingHello("x", 0) + h, _ := decodeHello(noSNI) + h.exts = nil + h.hasExts = false + plain := h.wire() + if hello := mustParse(t, plain); hello.SNIOffset >= 0 { + t.Fatal("fixture has an SNI") + } + if got := mustParse(t, decoyFor(t, FakeOptions{TTL: 4, FromOriginal: true, SNI: []string{"added.example"}}, plain)); got.SNI != "added.example" { + t.Fatalf("added SNI %q", got.SNI) + } +} + +func TestFakeRandomize(t *testing.T) { + orig, _ := decodeHello(defaultFakeTLS()) + a, err := decodeHello(decoyFor(t, FakeOptions{TTL: 4, Randomize: true}, nil)) + if err != nil { + t.Fatal(err) + } + b, _ := decodeHello(decoyFor(t, FakeOptions{TTL: 4, Randomize: true}, nil)) + if a.random == orig.random || a.random == b.random || bytes.Equal(a.sessionID, orig.sessionID) || len(a.sessionID) != len(orig.sessionID) { + t.Fatal("random or session ID not randomized") + } + ks := a.exts[a.ext(extKeyShare)].data + if bytes.Equal(ks, orig.exts[orig.ext(extKeyShare)].data) || !bytes.Equal(ks[:6], orig.exts[orig.ext(extKeyShare)].data[:6]) { + t.Fatal("key share not randomized, or its framing changed") + } + if mustParse(t, a.wire()).SNI != "www.wikipedia.org" { + t.Fatal("randomize changed the SNI") + } +} + +func TestFakeCustomPayloadSNI(t *testing.T) { + payload := captureHello(t, "payload.example") + h := mustParse(t, decoyFor(t, FakeOptions{TTL: 4, Payload: payload, SNI: []string{"other.example"}}, nil)) + if h.SNI != "other.example" { + t.Fatalf("SNI %q", h.SNI) + } + if err := (&FakeOptions{TTL: 4, Payload: []byte("GET / HTTP/1.1\r\n\r\n"), SNI: []string{"a.example"}}).validateDecoy(); err == nil { + t.Fatal("SNI accepted for a payload that is not a ClientHello") + } + // Without decoy options a payload is used as given. + if !bytes.Equal(decoyFor(t, FakeOptions{TTL: 4, Payload: []byte("raw")}, nil), []byte("raw")) { + t.Fatal("plain payload changed") + } +} + +func TestFakeDecoyValidation(t *testing.T) { + for _, good := range []string{"a", "www.example.com", "xn--80ak6aa92e.com", "*.?#.example", "A-1.b"} { + if err := validFakeSNI(good); err != nil { + t.Errorf("%q: %v", good, err) + } + } + for _, bad := range []string{"", "-a.com", "a-.com", "a..b", ".a", "a.", "1.2.3.4", "::1", "a_b.com", "ex ample.com", "a,b", "a|b", strings.Repeat("a", 64) + ".com", strings.Repeat("a.", 127) + "aa"} { + if err := validFakeSNI(bad); err == nil { + t.Errorf("%q accepted", bad) + } + } + for name, f := range map[string]FakeOptions{ + "orig alone": {TTL: 4, FromOriginal: true}, + "orig with payload": {TTL: 4, FromOriginal: true, Randomize: true, Payload: []byte{1}}, + "negative offset": {TTL: 4, Offset: -1}, + "huge offset": {TTL: 4, Offset: maxFakeOffset}, + "bad name": {TTL: 4, SNI: []string{"ok.example", "bad_name"}}, + "too many names": {TTL: 4, SNI: make([]string, maxFakeSNI+1)}, + } { + f := f + if err := (Options{Fake: &f}).Validate(); err == nil { + t.Errorf("%s accepted", name) + } + } + err := (Options{Fake: &FakeOptions{TTL: 4, SNI: []string{"ok.example"}, Randomize: true, FromOriginal: true, Offset: 3}}).Validate() + if SupportsFake() && err != nil || !SupportsFake() && !errors.Is(err, ErrFakeUnsupported) { + t.Fatalf("valid decoy options: %v", err) + } +} + +func TestFakeDecoyKey(t *testing.T) { + base := Options{Fake: &FakeOptions{TTL: 4}} + const want = "desync/v1;tlsrec=;split=;delay=0;hello=default;fake=ttl:4,prefix:0,timeout:0,payload:default;random=off" + if got := base.Key(); got != want { + t.Fatalf("key of options without decoy options changed:\n%s\n%s", got, want) + } + keys := map[string]bool{} + for _, f := range []FakeOptions{ + {TTL: 4}, + {TTL: 4, SNI: []string{"a.example"}}, + {TTL: 4, SNI: []string{"b.example"}}, + {TTL: 4, SNI: []string{"a.example", "b.example"}}, + {TTL: 4, Randomize: true}, + {TTL: 4, FromOriginal: true, Randomize: true}, + {TTL: 4, Offset: 2}, + } { + f := f + keys[Options{Fake: &f}.Key()] = true + } + if len(keys) != 7 { + t.Fatalf("decoy options are not all part of the key: %v", keys) + } +} + +func TestFakeBytesOffset(t *testing.T) { + if got := fakeBytes([]byte("abcdef"), 2, 3); string(got) != "cde" { + t.Fatalf("%q", got) + } + if got := fakeBytes([]byte("abc"), 2, 3); !bytes.Equal(got, []byte{'c', 0, 0}) { + t.Fatalf("%q", got) + } + if got := fakeBytes([]byte("abc"), 9, 2); !bytes.Equal(got, []byte{0, 0}) { + t.Fatalf("%q", got) + } +} diff --git a/fake_linux.go b/fake_linux.go index 2484ad7..bf3f024 100644 --- a/fake_linux.go +++ b/fake_linux.go @@ -128,7 +128,13 @@ func (o *spliceFake) step(fd uintptr, sent, inPipe, total int) (moved, piped int return int(n), piped, false, nil } -func (c *Conn) sendFake(real, payload, tail []byte) error { +// sendFakePiece sends real as the fake piece, then runs rest, which writes +// the pieces after it with the original page in place and the hop limit +// restored. When queued, bytes were written before the piece: the hop limit +// is lowered only once SIOCOUTQNSD reports them transmitted, so none of them +// goes out with it (ByeDPI waits for sock_has_notsent between parts). A rest +// error is returned as is. +func (c *Conn) sendFakePiece(real, payload []byte, queued bool, rest func() error) error { start := time.Now() if err := c.fakeAbort(start); err != nil { return err @@ -145,6 +151,13 @@ func (c *Conn) sendFake(real, payload, tail []byte) error { if err != nil { return err } + if queued { + if err := c.poll(c.fakeTimeout()-time.Since(start), os.ErrDeadlineExceeded, "TCP fake: wait for earlier pieces", func() (bool, error) { + return obs.reached(SplitWaitSent, 0) + }); err != nil { + return err + } + } select { case fakeSlots <- struct{}{}: default: @@ -158,12 +171,9 @@ func (c *Conn) sendFake(real, payload, tail []byte) error { if err := c.spliceFake(raw, obs, op, real, ttl, start); err != nil { return fmt.Errorf("desync: TCP fake: %w", err) } - // The original prefix is in place and the hop limit restored: the tail - // and every retransmission go out normally. - if err := writeAll(c.Conn, tail); err != nil { - return fmt.Errorf("desync: TCP fake: write original tail: %w", err) - } - return nil + // The original piece is in place and the hop limit restored: the later + // pieces and every retransmission go out normally. + return rest() } // spliceFake transmits the fake prefix with the low hop limit. Whatever @@ -186,10 +196,7 @@ func (c *Conn) spliceFake(raw syscall.RawConn, obs ackObserver, op *spliceFake, err = errors.Join(err, restoreErr) } }() - timeout := c.opts.Fake.Timeout - if timeout == 0 { - timeout = 3 * time.Second - } + timeout := c.fakeTimeout() remaining := func() time.Duration { return timeout - time.Since(start) } sent, inPipe := 0, 0 err = c.poll(remaining(), os.ErrDeadlineExceeded, "splice", func() (bool, error) { diff --git a/fake_linux_test.go b/fake_linux_test.go index a08617d..62292dd 100644 --- a/fake_linux_test.go +++ b/fake_linux_test.go @@ -66,7 +66,7 @@ func linuxFakeRoundTrip(t *testing.T, network string, opts Options, drop bool) { } hello := captureHello(t, "example.test") wire := FragmentRecord(hello, resolve(opts.TLSRec, mustParse(t, hello), recordHeaderLen, len(hello))) - if opts.Fake != nil && opts.Fake.Payload == nil { + if !drop && opts.Fake != nil && opts.Fake.Payload == nil { // Without drops the first transmission reaches the server: a fake // equal to the real bytes keeps that stream verifiable. opts.Fake.Payload = wire @@ -110,6 +110,23 @@ func TestLinuxFakeNativeStream(t *testing.T) { } } } + // Fake with split pieces: the decoy equals the original piece (Payload + // is the stream, Offset aligns it), so the undropped stream is checked. + const cut = 40 + for name, opts := range map[string]Options{ + "split-fake": {Split: []Pos{{Offset: cut}}, Fake: &FakeOptions{TTL: 64, Offset: cut}}, + "fake-split": {Split: []Pos{{Offset: cut}, {Offset: 2 * cut}}, Fake: &FakeOptions{TTL: 64, Prefix: cut}}, + "disorder-fake": {Split: []Pos{{Offset: cut}}, Disorder: true, Fake: &FakeOptions{TTL: 64, Offset: cut}}, + "disoob-fake": {Split: []Pos{{Offset: cut}}, Disorder: true, OOB: &OOBOptions{}, Fake: &FakeOptions{TTL: 64, Offset: cut}}, + "wait-fake": {Split: []Pos{{Offset: cut}, {Offset: 3 * cut}}, SplitWait: SplitWaitSent, SplitDelay: time.Millisecond, Fake: &FakeOptions{TTL: 64, Prefix: 2 * cut, Offset: cut}}, + } { + for _, network := range []string{"tcp4", "tcp6"} { + opts := opts + fake := *opts.Fake + opts.Fake = &fake + t.Run(name+"/"+network, func(t *testing.T) { linuxFakeRoundTrip(t, network, opts, false) }) + } + } if after := openFDs(t); after > fds { t.Fatalf("file descriptors leaked: %d -> %d", fds, after) } @@ -130,6 +147,18 @@ func TestLinuxLowHopDropRetransmitsOriginal(t *testing.T) { "fake-template": {Fake: &FakeOptions{TTL: 3, Payload: defaultFakeTLS()}}, "disorder": {TLSRec: rec, Split: split, Disorder: true}, "disoob": {TLSRec: rec, Split: split, Disorder: true, OOB: &OOBOptions{}}, + // Fake combined with split pieces and the first-piece methods. + "split-fake": {Split: split, Fake: &FakeOptions{TTL: 3, Payload: garbage}}, + "fake-split": {TLSRec: rec, Split: split, Fake: &FakeOptions{TTL: 3, Payload: garbage, Prefix: 20}}, + "split-fake-wait": {TLSRec: rec, Split: []Pos{{Offset: 3}, {Offset: 1, FromSNI: true}, {Offset: 40, FromSNI: true}}, SplitWait: SplitWaitSent, Fake: &FakeOptions{TTL: 3, Payload: garbage, Prefix: -5}}, + "random-fake": {Random: &RandomOptions{Split: []RandomCut{{From: Pos{Offset: -8, FromSNI: true}, To: Pos{Offset: 8, FromSNI: true}, Count: 2, MinPiece: 2}}, Seed: 7}, Fake: &FakeOptions{TTL: 3, Payload: garbage}}, + "disorder-fake": {Split: split, Disorder: true, Fake: &FakeOptions{TTL: 3, Payload: garbage}}, + "oob-fake": {Split: split, OOB: &OOBOptions{}, Fake: &FakeOptions{TTL: 3, Payload: garbage}}, + "disoob-fake": {TLSRec: rec, Split: split, Disorder: true, OOB: &OOBOptions{}, Fake: &FakeOptions{TTL: 3, Payload: garbage}}, + // Decoy ClientHellos with another server name. + "fake-sni": {Fake: &FakeOptions{TTL: 3, SNI: []string{"decoy.example", "*.?#.example"}, Randomize: true}}, + "fake-orig": {Fake: &FakeOptions{TTL: 3, FromOriginal: true, SNI: []string{"decoy.example"}}}, + "split-fake-sni": {Split: split, Fake: &FakeOptions{TTL: 3, SNI: []string{"decoy.example"}, Offset: 7}}, } { for _, network := range []string{"tcp4", "tcp6"} { opts := opts diff --git a/fake_other.go b/fake_other.go index 4c543b5..06a4fbe 100644 --- a/fake_other.go +++ b/fake_other.go @@ -4,4 +4,6 @@ package desync const supportsFake = false -func (c *Conn) sendFake(real, payload, tail []byte) error { return ErrFakeUnsupported } +func (c *Conn) sendFakePiece(real, payload []byte, queued bool, rest func() error) error { + return ErrFakeUnsupported +} diff --git a/fake_split_test.go b/fake_split_test.go new file mode 100644 index 0000000..5a63c56 --- /dev/null +++ b/fake_split_test.go @@ -0,0 +1,204 @@ +package desync + +import ( + "bytes" + "errors" + "fmt" + "net" + "testing" + "time" +) + +type fakeCall struct { + real, payload []byte + queued bool +} + +// observeFake replaces the native backend with one that records the fake +// piece, writes its original bytes (what the server reads after the +// retransmission) and runs the rest. fail makes the backend fail before it +// writes. +func observeFake(t *testing.T, fail error) *[]fakeCall { + t.Helper() + var calls []fakeCall + sendFakePieceFunc = func(c *Conn, real, payload []byte, queued bool, rest func() error) error { + calls = append(calls, fakeCall{append([]byte(nil), real...), append([]byte(nil), payload...), queued}) + if fail != nil { + return fail + } + if err := writeAll(c.Conn, real); err != nil { + return err + } + return rest() + } + t.Cleanup(func() { sendFakePieceFunc = (*Conn).sendFakePiece }) + return &calls +} + +// wrapFake wraps c and, where the platform has no fake, clears the +// validation error so the sequencing can be checked with the observer. +func wrapFake(c net.Conn, opts Options) *Conn { + w := WrapConn(c, opts).(*Conn) + if errors.Is(w.err, ErrFakeUnsupported) { + w.err = nil + } + return w +} + +func TestFakeSplitSequence(t *testing.T) { + hello := framingHello("split.example", 900) + n := len(hello) + sni := mustParse(t, hello).SNIOffset + for _, tc := range []struct { + name string + opts Options + segs []int // segment ends + fakeStart int + fakeEnd int + }{ + {"fake alone", Options{Fake: &FakeOptions{TTL: 4}}, []int{n - 1, n}, 0, n - 1}, + {"split then fake", Options{Split: []Pos{{Offset: 20}}, Fake: &FakeOptions{TTL: 4}}, []int{20, n - 1, n}, 20, n - 1}, + {"fake then split", Options{Split: []Pos{{Offset: 1, FromSNI: true}}, Fake: &FakeOptions{TTL: 4, Prefix: 10}}, []int{10, sni + 1, n}, 0, 10}, + {"split at the fake end", Options{Split: []Pos{{Offset: 30}, {Offset: 60}}, Fake: &FakeOptions{TTL: 4, Prefix: 60}}, []int{30, 60, n}, 30, 60}, + {"splits around", Options{Split: []Pos{{Offset: 30}, {Offset: 600}}, Fake: &FakeOptions{TTL: 4, Prefix: 300}, SplitDelay: time.Millisecond}, []int{30, 300, 600, n}, 30, 300}, + } { + t.Run(tc.name, func(t *testing.T) { + calls := observeFake(t, nil) + sink := newSegmentSink(t) + w := wrapFake(sink, tc.opts) + tail := []byte("tail") + input := append(append([]byte(nil), hello...), tail...) + if got, err := w.Write(input); err != nil || got != len(input) { + t.Fatalf("Write: %d %v", got, err) + } + if !bytes.Equal(sink.data(), input) { + t.Fatal("server stream changed") + } + start := 0 + for i, end := range tc.segs { + if !bytes.Equal(sink.segs[i], hello[start:end]) { + t.Fatalf("segment %d is not [%d,%d): %d bytes", i, start, end, len(sink.segs[i])) + } + start = end + } + if len(*calls) != 1 { + t.Fatalf("%d fake pieces", len(*calls)) + } + call := (*calls)[0] + if !bytes.Equal(call.real, hello[tc.fakeStart:tc.fakeEnd]) || call.queued != (tc.fakeStart > 0) { + t.Fatalf("fake piece [%d,%d) queued=%v: got %d bytes queued=%v", tc.fakeStart, tc.fakeEnd, tc.fakeStart > 0, len(call.real), call.queued) + } + if !bytes.Equal(call.payload, fakePayload(nil, len(call.real))) { + t.Fatal("the fake piece does not carry the template") + } + }) + } +} + +// The decoy carries the configured SNI and starts at Offset; the stream +// is unchanged. +func TestFakeSplitDecoy(t *testing.T) { + hello := framingHello("real.example", 1200) + calls := observeFake(t, nil) + sink := newSegmentSink(t) + w := wrapFake(sink, Options{Split: []Pos{{Offset: 1, FromSNI: true}}, Fake: &FakeOptions{TTL: 4, SNI: []string{"decoy.example"}}}) + if _, err := w.Write(hello); err != nil { + t.Fatal(err) + } + if !bytes.Equal(sink.data(), hello) { + t.Fatal("server stream changed") + } + if h := mustParse(t, (*calls)[0].payload); h.SNI != "decoy.example" { + t.Fatalf("decoy SNI %q", h.SNI) + } + calls = observeFake(t, nil) + sink = newSegmentSink(t) + w = wrapFake(sink, Options{Split: []Pos{{Offset: 40}}, Fake: &FakeOptions{TTL: 4, Payload: hello, Offset: 40}}) + if _, err := w.Write(hello); err != nil { + t.Fatal(err) + } + if c := (*calls)[0]; !bytes.Equal(c.payload, c.real) { + t.Fatal("Offset did not align the decoy with the piece") + } +} + +func TestFakeSplitErrors(t *testing.T) { + hello := framingHello("err.example", 600) + t.Run("partial count", func(t *testing.T) { + observeFake(t, errInjected) + sink := newSegmentSink(t) + w := wrapFake(sink, Options{Split: []Pos{{Offset: 25}}, Fake: &FakeOptions{TTL: 4}}) + n, err := w.Write(hello) + if !errors.Is(err, errInjected) || n != 25 { + t.Fatalf("Write: %d %v, want the 25 bytes before the fake piece", n, err) + } + if _, err := w.Write([]byte("later")); !errors.Is(err, errInjected) { + t.Fatalf("not terminal: %v", err) + } + }) + t.Run("partial count with records", func(t *testing.T) { + observeFake(t, errInjected) + sink := newSegmentSink(t) + w := wrapFake(sink, Options{TLSRec: []Pos{{Offset: 10}}, Split: []Pos{{Offset: 25}}, Fake: &FakeOptions{TTL: 4}}) + if n, err := w.Write(hello); !errors.Is(err, errInjected) || n != 25 { + t.Fatalf("Write: %d %v", n, err) + } + }) + t.Run("first piece", func(t *testing.T) { + for _, opts := range []Options{ + {Split: []Pos{{Offset: 50}}, Disorder: true, Fake: &FakeOptions{TTL: 4, Prefix: 50}}, + {Split: []Pos{{Offset: 50}}, OOB: &OOBOptions{}, Fake: &FakeOptions{TTL: 4, Prefix: 20}}, + } { + calls := observeFake(t, nil) + client, server := loopbackPair(t, "tcp4") + w := wrapFake(client, opts) + if errors.Is(w.err, ErrDisorderUnsupported) || errors.Is(w.err, ErrOOBUnsupported) { + t.Skip(w.err) + } + if _, err := w.Write(hello); !errors.Is(err, ErrFakeFirstPiece) { + t.Fatalf("Write: %v", err) + } + _ = server.SetReadDeadline(time.Now().Add(200 * time.Millisecond)) + if n, _ := server.Read(make([]byte, 16)); n != 0 || len(*calls) != 0 { + t.Fatalf("%d bytes and %d fake pieces sent", n, len(*calls)) + } + } + }) +} + +// With Disorder or OOB the first piece keeps its method and the fake piece +// follows it. +func TestFakeSplitWithSocketMethods(t *testing.T) { + hello := captureHello(t, "methods.example") + for _, m := range []struct { + disorder bool + oob *OOBOptions + }{{true, nil}, {false, &OOBOptions{}}, {true, &OOBOptions{}}} { + opts := Options{Split: []Pos{{Offset: 1, FromSNI: true}}, Disorder: m.disorder, OOB: m.oob, Fake: &FakeOptions{TTL: 4, Prefix: -1}} + t.Run(fmt.Sprintf("disorder=%v,oob=%v", m.disorder, m.oob != nil), func(t *testing.T) { + calls := observeFake(t, nil) + client, server := loopbackPair(t, "tcp4") + before := tcpHop(t, client) + w := wrapFake(client, opts) + if w.err != nil { + t.Skip(w.err) + } + _ = w.SetWriteDeadline(time.Now().Add(5 * time.Second)) + tail := []byte("after") + read := readUntil(server, tail) + if _, err := w.Write(append(append([]byte(nil), hello...), tail...)); err != nil { + t.Fatal(err) + } + if got := <-read; !bytes.Equal(got, append(append([]byte(nil), hello...), tail...)) { + t.Fatalf("server stream changed: %d bytes", len(got)) + } + sni := mustParse(t, hello).SNIOffset + if len(*calls) != 1 || !bytes.Equal((*calls)[0].real, hello[sni+1:len(hello)-1]) || !(*calls)[0].queued { + t.Fatalf("fake piece: %+v", *calls) + } + if after := tcpHop(t, client); after != before { + t.Fatalf("hop limit %d -> %d", before, after) + } + }) + } +} diff --git a/fake_test.go b/fake_test.go index 9799e2b..e1b37a2 100644 --- a/fake_test.go +++ b/fake_test.go @@ -51,8 +51,23 @@ func TestFakeValidation(t *testing.T) { if err := (Options{Fake: &FakeOptions{TTL: 4, Timeout: -time.Second}}).Validate(); err == nil { t.Fatal("accepted negative timeout") } - if err := (Options{Fake: &FakeOptions{TTL: 4}, Split: []Pos{{Offset: 1}}}).Validate(); err == nil { - t.Fatal("accepted unsupported fake + split") + for name, o := range map[string]Options{ + "split": {Fake: &FakeOptions{TTL: 4}, Split: []Pos{{Offset: 1}}}, + "split-sent": {Fake: &FakeOptions{TTL: 4}, Split: []Pos{{Offset: 1}}, SplitWait: SplitWaitSent}, + "disorder": {Fake: &FakeOptions{TTL: 4}, Split: []Pos{{Offset: 1}}, Disorder: true}, + "oob": {Fake: &FakeOptions{TTL: 4}, Split: []Pos{{Offset: 1}}, OOB: &OOBOptions{}}, + "disoob-delayed": {Fake: &FakeOptions{TTL: 4}, Split: []Pos{{Offset: 1}}, Disorder: true, OOB: &OOBOptions{}, SplitDelay: time.Millisecond}, + } { + err := o.Validate() + if SupportsFake() && err != nil && !errors.Is(err, ErrSplitWaitUnsupported) { + t.Errorf("fake + %s: %v", name, err) + } + if !SupportsFake() && err == nil { + t.Errorf("fake + %s accepted without fake support", name) + } + } + if err := (Options{Fake: &FakeOptions{TTL: 4}, Split: []Pos{{Offset: 1}}, SplitWait: SplitWaitAcked}).Validate(); err == nil { + t.Fatal("accepted fake + SplitWaitAcked") } } diff --git a/fake_windows.go b/fake_windows.go index 13b5fa0..bad7a36 100644 --- a/fake_windows.go +++ b/fake_windows.go @@ -191,7 +191,12 @@ func (o *nativeFake) reap() { } } -func (c *Conn) sendFake(real, payload, tail []byte) error { +// sendFakePiece sends real as the fake piece and runs rest, which writes the +// pieces after it, as soon as the native request is submitted. queued (bytes +// written before the piece) needs nothing here: Winsock captures the TTL per +// send request, as ByeDPI's Windows path relies on. A rest error is returned +// as is, joined with a native error if both occur. +func (c *Conn) sendFakePiece(real, payload []byte, queued bool, rest func() error) error { start := time.Now() if err := c.fakeAbort(start); err != nil { return err @@ -279,14 +284,13 @@ acquire: // ByeDPI sends this normal-TTL tail immediately after restoring the file // cache and TTL. Waiting for the prefix first can block until timeout: // the initial low-TTL data may require TCP retransmission and tail ACKs. + var restErr error if nativeErr == nil { - if tailErr := writeAll(c.Conn, tail); tailErr != nil { - nativeErr = fmt.Errorf("write original tail: %w", tailErr) - } + restErr = rest() } err = raw.Control(func(fd uintptr) { socket := syscall.Handle(fd) - for nativeErr == nil { + for nativeErr == nil && restErr == nil { n, resultErr := op.result(socket) if !errors.Is(resultErr, wsaIOIncomplete) { if resultErr != nil { @@ -327,7 +331,7 @@ acquire: } } if nativeErr != nil { - return fmt.Errorf("desync: TCP fake: %w", nativeErr) + nativeErr = fmt.Errorf("desync: TCP fake: %w", nativeErr) } - return nil + return errors.Join(restErr, nativeErr) } diff --git a/fake_windows_test.go b/fake_windows_test.go index d5fbbd9..84f0fb2 100644 --- a/fake_windows_test.go +++ b/fake_windows_test.go @@ -345,3 +345,44 @@ func TestWindowsFakeQueuedCancellation(t *testing.T) { }) } } + +// Fake combined with Split, Disorder and OOB on the native backend. On +// loopback the low TTL does not expire, so the decoy is the original piece +// itself (Payload is the stream, Offset aligns it with the piece). +func TestWindowsFakeSplitNativeStream(t *testing.T) { + hello := captureHello(t, "example.test") + const cut = 40 + for name, opts := range map[string]Options{ + "split-fake": {Split: []Pos{{Offset: cut}}, Fake: &FakeOptions{TTL: 64, Offset: cut}}, + "fake-split": {Split: []Pos{{Offset: cut}, {Offset: 2 * cut}}, Fake: &FakeOptions{TTL: 64, Prefix: cut}}, + "split-fake-wait": {Split: []Pos{{Offset: cut}, {Offset: len(hello) - 5}}, SplitWait: SplitWaitSent, SplitDelay: time.Millisecond, Fake: &FakeOptions{TTL: 64, Prefix: 2 * cut, Offset: cut}}, + "disorder-fake": {Split: []Pos{{Offset: cut}}, Disorder: true, Fake: &FakeOptions{TTL: 64, Offset: cut}}, + "oob-fake": {Split: []Pos{{Offset: cut}}, OOB: &OOBOptions{}, Fake: &FakeOptions{TTL: 64, Offset: cut}}, + "disoob-fake": {Split: []Pos{{Offset: cut}}, Disorder: true, OOB: &OOBOptions{}, Fake: &FakeOptions{TTL: 64, Offset: cut}}, + } { + opts := opts + t.Run(name, func(t *testing.T) { + fake := *opts.Fake + fake.Payload = hello + opts.Fake = &fake + client, server := loopbackPair(t, "tcp4") + before := socketTTL(t, client) + w := WrapConn(client, opts) + _ = w.SetWriteDeadline(time.Now().Add(5 * time.Second)) + tail := []byte("AFTER") + read := readUntil(server, tail) + if _, err := w.Write(append(append([]byte(nil), hello...), tail...)); err != nil { + t.Fatal(err) + } + if got := <-read; !bytes.Equal(got, append(append([]byte(nil), hello...), tail...)) { + t.Fatalf("server stream changed: %d bytes", len(got)) + } + if after := socketTTL(t, client); after != before { + t.Fatalf("TTL changed: %d -> %d", before, after) + } + }) + } + if len(fakeSlots) != 0 { + t.Fatalf("pending resources: %d", len(fakeSlots)) + } +} diff --git a/key.go b/key.go index 62383f6..86d3bb6 100644 --- a/key.go +++ b/key.go @@ -57,6 +57,22 @@ func (o Options) Key() string { } // Only when set, so keys of fixed-TTL fakes are unchanged. writeAutoTTL(&b, f.AutoTTL) + // Decoy options are appended only when set, so keys of options + // without them are unchanged. Validated names contain no ',' or '|'. + if len(f.SNI) > 0 { + b.WriteString(",sni:") + b.WriteString(strings.Join(f.SNI, "|")) + } + if f.FromOriginal { + b.WriteString(",orig:1") + } + if f.Randomize { + b.WriteString(",rand:1") + } + if f.Offset != 0 { + b.WriteString(",offset:") + b.WriteString(strconv.Itoa(f.Offset)) + } } b.WriteString(";random=") if r := o.Random; r == nil { diff --git a/random_test.go b/random_test.go index fc1a370..feb7ae4 100644 --- a/random_test.go +++ b/random_test.go @@ -404,9 +404,13 @@ func TestRandomValidation(t *testing.T) { 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) + fake := Options{Fake: &FakeOptions{TTL: 4}, Random: &RandomOptions{Split: []RandomCut{{From: Pos{Offset: 1}, To: Pos{Offset: 40}}}}} + if err := fake.Validate(); SupportsFake() != (err == nil) { + t.Fatalf("fake with random split: %v", err) + } + fake.SplitWait = SplitWaitAcked + if err := fake.Validate(); err == nil { + t.Fatal("fake with random split and SplitWaitAcked accepted") } } diff --git a/third_party/NOTICE b/third_party/NOTICE index 6e8fef9..1d5fa88 100644 --- a/third_party/NOTICE +++ b/third_party/NOTICE @@ -18,6 +18,18 @@ hufrea. The license text is in BYEDPI-LICENSE. Derived from it: before the next one), --oob and --disoob (the piece and one urgent byte sent with MSG_OOB), desync.c DESYNC_DISORDER, DESYNC_OOB, DESYNC_DISOOB and send_oob. Reimplemented in Go; the default urgent byte 'a' is ByeDPI's. +- fake_hello.go: the decoy ClientHello options --fake-sni (a list with one + name drawn per connection; the wildcards '*', '?' and '#' of copy_name), + --fake-tls-mod rand and orig (randomize_tls: random, session ID and key + share values; the real ClientHello as the decoy base) and --fake-offset, + packets.c change_tls_sni, randomize_tls, copy_name and desync.c + get_tcp_fake. Reimplemented in Go by decoding and re-encoding the + handshake instead of resizing it in place. +- conn.go: the fake as one of several split parts (the piece between the + previous cut and the fake position is sent as fake, the pieces around it + normally; Linux waits until earlier bytes were transmitted before lowering + the hop limit), desync.c desync() with DESYNC_FAKE among other parts and + sock_has_notsent. zapret (https://github.com/bol-van/zapret), MIT License, Copyright (c) 2016-2024 bol-van. The license text is in ZAPRET-LICENSE. Derived from it: From 4e7181eefddcd7d72ce0d22e190df6057a01574c Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Thu, 29 Oct 2026 20:38:53 +0300 Subject: [PATCH 2/4] feat(udp): QUIC Initial decoy template and QUIC-only burst UDPOptions.Template = UDPTemplateQUICInitial generates a QUIC v1 client Initial per burst: random DCID/SCID, a CRYPTO frame with a ClientHello for UDPOptions.SNI, PADDING to 1200 bytes, payload and header protection with the RFC 9001 Initial keys. QUICInitialPayload returns one such packet for a fixed Payload. QUICOnly limits the burst to datagrams that look like a QUIC client Initial, leaving other UDP traffic untouched. --- packet.go | 45 +++++++- packet_quic.go | 231 ++++++++++++++++++++++++++++++++++++++++ packet_quic_test.go | 250 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 523 insertions(+), 3 deletions(-) create mode 100644 packet_quic.go create mode 100644 packet_quic_test.go diff --git a/packet.go b/packet.go index ed82d6f..dc4ad38 100644 --- a/packet.go +++ b/packet.go @@ -28,6 +28,18 @@ type UDPOptions struct { Packets int // Payload defaults to 64 zero bytes. Custom payloads may contain 1-1200 bytes. Payload []byte + + // QUIC decoys. Template generates the decoy instead of Payload (which + // must then be empty); SNI is the server name in the QUIC Initial + // template's ClientHello (default DefaultQUICSNI, wildcards as in + // FakeOptions.SNI); QUICOnly limits the burst to datagrams that look like + // a QUIC client Initial (long header, version 1, a draft or 2, Initial + // type, at least 1200 bytes), so other UDP traffic passes untouched and + // does not count towards Packets. + Template UDPTemplate + SNI string + QUICOnly bool + // Counters can be shared by sockets belonging to one outbound. Do not copy // or reset a counters value after it has been used. Counters *UDPCounters @@ -70,6 +82,20 @@ func (o UDPOptions) Validate() error { if len(o.Payload) > 1200 { return fmt.Errorf("desync: UDP fake payload exceeds 1200 bytes") } + if o.Template != UDPTemplateZero && o.Template != UDPTemplateQUICInitial { + return fmt.Errorf("desync: unknown UDP template %d", int(o.Template)) + } + if o.Template != UDPTemplateZero && len(o.Payload) > 0 { + return fmt.Errorf("desync: UDP Template and Payload are mutually exclusive") + } + if o.SNI != "" { + if o.Template != UDPTemplateQUICInitial { + return fmt.Errorf("desync: UDP SNI needs Template UDPTemplateQUICInitial") + } + if err := validFakeSNI(o.SNI); err != nil { + return err + } + } if !SupportsUDPFake() { return ErrUDPFakeUnsupported } @@ -121,7 +147,11 @@ func WrapPacketConn(pc net.PacketConn, opts UDPOptions) (*PacketConn, error) { if opts.Packets == 0 { opts.Packets = 3 } - if len(opts.Payload) == 0 { + if opts.Template == UDPTemplateQUICInitial { + if opts.SNI == "" { + opts.SNI = DefaultQUICSNI + } + } else if len(opts.Payload) == 0 { opts.Payload = make([]byte, 64) } else { opts.Payload = append([]byte(nil), opts.Payload...) @@ -183,8 +213,17 @@ func (c *PacketConn) WriteTo(p []byte, addr net.Addr) (int, error) { if c.closed.Load() { return 0, net.ErrClosed } - if len(p) > 0 && c.shouldInject(addr) { - unsafeTTL, err := sendUDPFake(c.PacketConn, c.raw, c.opts, addr) + if len(p) > 0 && (!c.opts.QUICOnly || looksLikeQUICInitial(p)) && c.shouldInject(addr) { + opts := c.opts + if opts.Template == UDPTemplateQUICInitial { + payload, err := quicInitial(opts.SNI) + if err != nil { + c.opts.Counters.errors.Add(1) + return 0, err + } + opts.Payload = payload + } + unsafeTTL, err := sendUDPFake(c.PacketConn, c.raw, opts, addr) if err != nil { c.opts.Counters.errors.Add(1) if unsafeTTL { diff --git a/packet_quic.go b/packet_quic.go new file mode 100644 index 0000000..50e069a --- /dev/null +++ b/packet_quic.go @@ -0,0 +1,231 @@ +package desync + +import ( + "crypto/aes" + "crypto/cipher" + "crypto/hmac" + crand "crypto/rand" + "crypto/sha256" + "encoding/binary" + "errors" + "fmt" +) + +// UDPTemplate selects a generated decoy for the UDP burst. +type UDPTemplate int + +const ( + // UDPTemplateZero is 64 zero bytes (ByeDPI's UDP fake), the default. + UDPTemplateZero UDPTemplate = iota + // UDPTemplateQUICInitial is a QUIC v1 client Initial packet (RFC 9000, + // RFC 9001): long header, version 1, random 8-byte DCID and SCID, a + // CRYPTO frame with a TLS ClientHello for UDPOptions.SNI, PADDING to + // 1200 bytes, payload and header protection with the Initial keys derived + // from the DCID. An inspecting device that decrypts Initials, as anyone + // can, reads the decoy's server name. A new packet is generated for every + // burst. + UDPTemplateQUICInitial +) + +func (t UDPTemplate) String() string { + switch t { + case UDPTemplateZero: + return "zero" + case UDPTemplateQUICInitial: + return "quic-initial" + } + return fmt.Sprintf("UDPTemplate(%d)", int(t)) +} + +// DefaultQUICSNI is the decoy server name of the QUIC Initial template when +// UDPOptions.SNI is empty (the server name of the TCP fake template). +const DefaultQUICSNI = "www.wikipedia.org" + +// quicInitialSize is the minimum size of a datagram carrying a client +// Initial (RFC 9000 section 14.1); the template has exactly this size. +const quicInitialSize = 1200 + +const ( + quicVersion1 = 0x00000001 + quicVersion2 = 0x6b3343cf + quicConnIDLen = 8 + quicPacketNumLen = 4 + quicTagLen = 16 + extALPN = 0x0010 + extQUICTransport = 0x0039 +) + +// RFC 9001 section 5.2. +var quicV1InitialSalt = []byte{0x38, 0x76, 0x2c, 0xf7, 0xf5, 0x59, 0x34, 0xb3, 0x4d, 0x17, 0x9a, 0xe6, 0xa4, 0xc8, 0x0c, 0xad, 0xcc, 0xbb, 0x7f, 0x0a} + +// QUICInitialPayload returns one QUIC v1 Initial decoy of 1200 bytes whose +// ClientHello carries sni (DefaultQUICSNI when empty; ByeDPI wildcards +// '*', '?' and '#' are expanded). Use it as a fixed UDPOptions.Payload; +// UDPOptions.Template = UDPTemplateQUICInitial generates a fresh one per +// burst instead. +func QUICInitialPayload(sni string) ([]byte, error) { + if sni == "" { + sni = DefaultQUICSNI + } + if err := validFakeSNI(sni); err != nil { + return nil, err + } + return quicInitial(sni) +} + +// looksLikeQUICInitial reports whether p is a datagram starting with a QUIC +// v1 (or draft) or v2 client Initial long-header packet of at least 1200 +// bytes, the size a client Initial datagram must have. +func looksLikeQUICInitial(p []byte) bool { + if len(p) < quicInitialSize || p[0]&0xc0 != 0xc0 { + return false + } + typ := p[0] >> 4 & 3 + switch v := binary.BigEndian.Uint32(p[1:5]); { + case v == quicVersion1 || v&0xffffff00 == 0xff000000: + if typ != 0 { + return false + } + case v == quicVersion2: + if typ != 1 { + return false + } + default: + return false + } + return p[5] <= 20 +} + +func hkdfExtract(salt, secret []byte) []byte { + m := hmac.New(sha256.New, salt) + m.Write(secret) + return m.Sum(nil) +} + +// hkdfExpandLabel is TLS 1.3's HKDF-Expand-Label with an empty context, for +// outputs of at most one SHA-256 block. +func hkdfExpandLabel(secret []byte, label string, n int) []byte { + full := "tls13 " + label + info := make([]byte, 0, 4+len(full)) + info = binary.BigEndian.AppendUint16(info, uint16(n)) + info = append(info, byte(len(full))) + info = append(info, full...) + info = append(info, 0, 1) // empty context, then the HKDF counter + m := hmac.New(sha256.New, secret) + m.Write(info) + return m.Sum(nil)[:n] +} + +// quicClientInitialKeys derives the client Initial key, IV and header +// protection key from the destination connection ID (RFC 9001 section 5.2). +func quicClientInitialKeys(dcid []byte) (key, iv, hp []byte) { + client := hkdfExpandLabel(hkdfExtract(quicV1InitialSalt, dcid), "client in", 32) + return hkdfExpandLabel(client, "quic key", 16), hkdfExpandLabel(client, "quic iv", 12), hkdfExpandLabel(client, "quic hp", 16) +} + +func appendQUICVarint(b []byte, v uint64) []byte { + switch { + case v < 1<<6: + return append(b, byte(v)) + case v < 1<<14: + return binary.BigEndian.AppendUint16(b, uint16(v)|0x4000) + case v < 1<<30: + return binary.BigEndian.AppendUint32(b, uint32(v)|0x80000000) + } + return binary.BigEndian.AppendUint64(b, v|0xc0<<56) +} + +// quicHello is the TLS template's ClientHello adapted to QUIC: the server +// name sni, fresh random values, ALPN h3, QUIC transport parameters with the +// source connection ID, and no padding extension (PADDING frames pad). +func quicHello(sni string, scid []byte) ([]byte, error) { + h, err := decodeHello(defaultFakeTLS()) + if err != nil { + return nil, err + } + if sni, err = expandFakeSNI(sni); err != nil { + return nil, err + } + h.setSNI(sni) + if err := h.randomize(); err != nil { + return nil, err + } + h.sessionID = nil // QUIC has no middlebox-compatibility session ID + exts := h.exts[:0] + for _, e := range h.exts { + switch e.typ { + case extPadding: + continue + case extALPN: + e.data = []byte{0, 3, 2, 'h', '3'} + } + exts = append(exts, e) + } + // initial_source_connection_id (0x0f) and max_idle_timeout (0x01) = 30 s. + params := []byte{0x0f, byte(len(scid))} + params = append(params, scid...) + params = append(params, 0x01, 4) + params = appendQUICVarint(params, 30000) + h.exts = append(exts, tlsExt{typ: extQUICTransport, data: params}) + return h.message(), nil +} + +func quicInitial(sni string) ([]byte, error) { + ids := make([]byte, 2*quicConnIDLen) + if _, err := crand.Read(ids); err != nil { + return nil, err + } + dcid, scid := ids[:quicConnIDLen], ids[quicConnIDLen:] + hello, err := quicHello(sni, scid) + if err != nil { + return nil, err + } + header := make([]byte, 0, 32) + header = append(header, 0xc0|(quicPacketNumLen-1)) + header = binary.BigEndian.AppendUint32(header, quicVersion1) + header = append(header, quicConnIDLen) + header = append(header, dcid...) + header = append(header, quicConnIDLen) + header = append(header, scid...) + header = append(header, 0) // no token + // Length covers the packet number, the payload and the tag; it is + // encoded on two bytes, so the header size is known in advance. + headerLen := len(header) + 2 + quicPacketNumLen + plainLen := quicInitialSize - headerLen - quicTagLen + header = binary.BigEndian.AppendUint16(header, uint16(quicPacketNumLen+plainLen+quicTagLen)|0x4000) + pnOffset := len(header) + header = append(header, 0, 0, 0, 0) // packet number 0 + + plain := make([]byte, 0, plainLen) + plain = append(plain, 0x06, 0) // CRYPTO frame at offset 0 + plain = appendQUICVarint(plain, uint64(len(hello))) + plain = append(plain, hello...) + if len(plain) > plainLen { + return nil, errors.New("desync: QUIC decoy ClientHello does not fit 1200 bytes") + } + plain = plain[:plainLen] // the rest are PADDING frames (zero bytes) + + key, iv, hp := quicClientInitialKeys(dcid) + block, err := aes.NewCipher(key) + if err != nil { + return nil, err + } + aead, err := cipher.NewGCM(block) + if err != nil { + return nil, err + } + // The packet number is zero, so the nonce is the IV itself. + aad := append([]byte(nil), header...) + packet := aead.Seal(header, iv, plain, aad) + hpBlock, err := aes.NewCipher(hp) + if err != nil { + return nil, err + } + var mask [16]byte + hpBlock.Encrypt(mask[:], packet[pnOffset+4:pnOffset+4+16]) + packet[0] ^= mask[0] & 0x0f + for i := 0; i < quicPacketNumLen; i++ { + packet[pnOffset+i] ^= mask[1+i] + } + return packet, nil +} diff --git a/packet_quic_test.go b/packet_quic_test.go new file mode 100644 index 0000000..6f96435 --- /dev/null +++ b/packet_quic_test.go @@ -0,0 +1,250 @@ +package desync + +import ( + "bytes" + "crypto/aes" + "crypto/cipher" + "encoding/binary" + "encoding/hex" + "net" + "testing" + "time" +) + +// RFC 9001 appendix A.1. +func TestQUICInitialKeysRFC9001(t *testing.T) { + dcid, _ := hex.DecodeString("8394c8f03e515708") + key, iv, hp := quicClientInitialKeys(dcid) + for name, got := range map[string][]byte{"1f369613dd76d5467730efcbe3b1a22d": key, "fa044b2f42a3fd3b46fb255c": iv, "9f50449e04a0e810283a1e9933adedd2": hp} { + if hex.EncodeToString(got) != name { + t.Fatalf("got %x, want %s", got, name) + } + } +} + +// openQUICInitial removes header protection, decrypts the packet and returns +// the header fields and the CRYPTO frame data. +func openQUICInitial(t *testing.T, p []byte) (dcid, scid, crypto []byte) { + t.Helper() + if len(p) != 1200 || p[0]&0xf0 != 0xc0 || binary.BigEndian.Uint32(p[1:5]) != 1 { + t.Fatalf("not a v1 Initial: % x", p[:8]) + } + at := 5 + dcid = p[at+1 : at+1+int(p[at])] + at += 1 + len(dcid) + scid = p[at+1 : at+1+int(p[at])] + at += 1 + len(scid) + if p[at] != 0 { // token length + t.Fatal("token present") + } + at++ + length := int(binary.BigEndian.Uint16(p[at:]) & 0x3fff) + at += 2 + if at+length != len(p) { + t.Fatalf("Length %d does not end the datagram", length) + } + key, iv, hp := quicClientInitialKeys(dcid) + block, _ := aes.NewCipher(hp) + var mask [16]byte + block.Encrypt(mask[:], p[at+4:at+20]) + header := append([]byte(nil), p[:at+4]...) + header[0] ^= mask[0] & 0x0f + pnLen := int(header[0]&3) + 1 + if pnLen != 4 { + t.Fatalf("packet number length %d", pnLen) + } + for i := 0; i < pnLen; i++ { + header[at+i] ^= mask[1+i] + } + pn := binary.BigEndian.Uint32(header[at:]) + nonce := append([]byte(nil), iv...) + for i := 0; i < 4; i++ { + nonce[len(nonce)-1-i] ^= byte(pn >> (8 * i)) + } + kb, _ := aes.NewCipher(key) + aead, _ := cipher.NewGCM(kb) + plain, err := aead.Open(nil, nonce, p[at+4:], header) + if err != nil { + t.Fatalf("decrypt: %v", err) + } + if plain[0] != 0x06 || plain[1] != 0 { + t.Fatalf("no CRYPTO frame at offset 0: % x", plain[:4]) + } + n := int(binary.BigEndian.Uint16(plain[2:]) & 0x3fff) + crypto = plain[4 : 4+n] + for _, b := range plain[4+n:] { + if b != 0 { + t.Fatal("padding is not PADDING frames") + } + } + return dcid, scid, crypto +} + +func TestQUICInitialPayload(t *testing.T) { + seen := map[string]bool{} + for _, sni := range []string{"", "quic.example", "q#.example"} { + p, err := QUICInitialPayload(sni) + if err != nil { + t.Fatal(err) + } + if !looksLikeQUICInitial(p) { + t.Fatal("the template does not look like a QUIC Initial") + } + dcid, scid, crypto := openQUICInitial(t, p) + if len(dcid) != 8 || len(scid) != 8 || seen[string(dcid)] { + t.Fatalf("connection IDs %x %x", dcid, scid) + } + seen[string(dcid)] = true + // Frame the handshake message as a record to parse it. + rec := append([]byte{0x16, 3, 1, byte(len(crypto) >> 8), byte(len(crypto))}, crypto...) + h := mustParse(t, rec) + want := sni + switch sni { + case "": + want = DefaultQUICSNI + case "q#.example": + if len(h.SNI) != len(sni) || h.SNI[1] < '0' || h.SNI[1] > '9' { + t.Fatalf("wildcard SNI %q", h.SNI) + } + want = h.SNI + } + if h.SNI != want { + t.Fatalf("SNI %q, want %q", h.SNI, want) + } + hello, err := decodeHello(rec) + if err != nil { + t.Fatal(err) + } + if i := hello.ext(extALPN); i < 0 || !bytes.Equal(hello.exts[i].data, []byte{0, 3, 2, 'h', '3'}) { + t.Fatal("ALPN is not h3") + } + if i := hello.ext(extQUICTransport); i < 0 || !bytes.Contains(hello.exts[i].data, append([]byte{0x0f, 8}, scid...)) { + t.Fatal("transport parameters lack initial_source_connection_id") + } + if hello.ext(extPadding) >= 0 || len(hello.sessionID) != 0 { + t.Fatal("TLS padding or session ID inside QUIC") + } + } + if _, err := QUICInitialPayload("bad_name"); err == nil { + t.Fatal("bad SNI accepted") + } +} + +func TestLooksLikeQUICInitial(t *testing.T) { + p, _ := QUICInitialPayload("") + mk := func(first byte, version uint32, size int) []byte { + b := make([]byte, size) + b[0] = first + binary.BigEndian.PutUint32(b[1:], version) + b[5] = 8 + return b + } + for name, c := range map[string]struct { + p []byte + want bool + }{ + "template": {p, true}, + "v1 initial": {mk(0xc3, 1, 1250), true}, + "draft-29": {mk(0xc0, 0xff00001d, 1200), true}, + "v2 initial": {mk(0xd0, quicVersion2, 1200), true}, + "v2 type 0": {mk(0xc0, quicVersion2, 1200), false}, + "v1 handshake": {mk(0xe0, 1, 1200), false}, + "short header": {mk(0x40, 1, 1200), false}, + "no fixed bit": {mk(0x80, 1, 1200), false}, + "too small": {mk(0xc0, 1, 1199), false}, + "negotiation": {mk(0xc0, 0, 1200), false}, + "unknown": {mk(0xc0, 0x0a0a0a0a, 1200), false}, + "zeros": {make([]byte, 64), false}, + "dns": {[]byte{0x12, 0x34, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0}, false}, + "oversized cid": {func() []byte { b := mk(0xc0, 1, 1200); b[5] = 21; return b }(), false}, + } { + if got := looksLikeQUICInitial(c.p); got != c.want { + t.Errorf("%s: %v", name, got) + } + } +} + +func TestUDPTemplateValidation(t *testing.T) { + for name, o := range map[string]UDPOptions{ + "unknown template": {TTL: 4, Template: 7}, + "template and payload": {TTL: 4, Template: UDPTemplateQUICInitial, Payload: []byte{1}}, + "sni without template": {TTL: 4, SNI: "a.example"}, + "bad sni": {TTL: 4, Template: UDPTemplateQUICInitial, SNI: "1.2.3.4"}, + } { + if err := o.Validate(); err == nil { + t.Errorf("%s accepted", name) + } + } + if err := (UDPOptions{TTL: 4, Template: UDPTemplateQUICInitial, SNI: "a.example", QUICOnly: true}).Validate(); SupportsUDPFake() && err != nil { + t.Fatal(err) + } + if UDPTemplateQUICInitial.String() != "quic-initial" || UDPTemplateZero.String() != "zero" { + t.Fatal("template names") + } +} + +// QUICOnly leaves datagrams that are not QUIC Initials untouched, and the +// QUIC template's decoys precede the original. +func TestUDPQUICOnlyAndTemplate(t *testing.T) { + if !SupportsUDPFake() { + t.Skip("no UDP fake") + } + server, err := net.ListenPacket("udp4", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + defer server.Close() + client, err := net.ListenPacket("udp4", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + counters := &UDPCounters{} + pc, err := WrapPacketConn(client, UDPOptions{TTL: 64, Repeats: 2, Packets: 1, Template: UDPTemplateQUICInitial, SNI: "decoy.example", QUICOnly: true, Counters: counters}) + if err != nil { + client.Close() + t.Fatal(err) + } + defer pc.Close() + read := func() []byte { + _ = server.SetReadDeadline(time.Now().Add(2 * time.Second)) + b := make([]byte, 2048) + n, _, err := server.ReadFrom(b) + if err != nil { + t.Fatal(err) + } + return b[:n] + } + dns := []byte{0x12, 0x34, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0} + quic := make([]byte, 1250) + quic[0] = 0xc3 + binary.BigEndian.PutUint32(quic[1:], 1) + for _, p := range [][]byte{dns, dns, quic, quic} { + if _, err := pc.WriteTo(p, server.LocalAddr()); err != nil { + t.Fatal(err) + } + } + // Two DNS datagrams untouched; before the first QUIC Initial two + // decoys; the second QUIC Initial is past Packets. + if got := read(); !bytes.Equal(got, dns) { + t.Fatalf("first datagram %d bytes", len(got)) + } + if got := read(); !bytes.Equal(got, dns) { + t.Fatalf("second datagram %d bytes", len(got)) + } + var dcids [][]byte + for i := 0; i < 2; i++ { + dcid, _, _ := openQUICInitial(t, read()) + dcids = append(dcids, dcid) + } + if !bytes.Equal(dcids[0], dcids[1]) { + t.Fatal("one burst used two decoys") + } + for i := 0; i < 2; i++ { + if got := read(); !bytes.Equal(got, quic) { + t.Fatalf("QUIC datagram %d changed", i) + } + } + if s := counters.Snapshot(); s.Packets != 4 || s.FakePackets != 2 || s.Peers != 1 { + t.Fatalf("counters %+v", s) + } +} From 9b8fbec963c5f18e660c87bf50e38f577d400436 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Thu, 29 Oct 2026 20:38:53 +0300 Subject: [PATCH 3/4] feat(desync-socks): add fake SNI, TLS mod and offset flags -fake-sni, -fake-tls-mod rand,orig and -fake-offset set the decoy ClientHello; -fake now combines with -split, -disorder and -oob. --- cmd/desync-socks/main.go | 36 ++++++++++++++++++++++++++++++++--- cmd/desync-socks/main_test.go | 23 ++++++++++++++++++++++ 2 files changed, 56 insertions(+), 3 deletions(-) diff --git a/cmd/desync-socks/main.go b/cmd/desync-socks/main.go index b35197c..dbcaead 100644 --- a/cmd/desync-socks/main.go +++ b/cmd/desync-socks/main.go @@ -9,6 +9,9 @@ // desync-socks -split 1+s -disorder // desync-socks -split 3+s -oob // desync-socks -tlsrec 1+s -fake -1 -ttl 4 +// desync-socks -fake -1 -ttl 4 -fake-sni www.example.com,*.example.org -fake-tls-mod rand +// desync-socks -split 1+s -fake -1 -ttl 4 (fake piece after the split) +// desync-socks -split 1 -disorder -fake -1 -ttl 4 (ByeDPI -d 1 -f -1) package main import ( @@ -33,12 +36,15 @@ func main() { delay := flag.Duration("split-delay", 0, "pause between TCP pieces") wait := flag.String("split-wait", "none", "before each further TCP piece, wait until the previous bytes are sent or acked: none, sent, acked") waitTimeout := flag.Duration("split-wait-timeout", 0, "bound for each split wait (0: library default)") - fake := flag.Int("fake", 0, "TCP fake prefix (Windows, Linux): 0 disables, -1 means all but the last byte") + fake := flag.Int("fake", 0, "TCP fake (Windows, Linux): end of the fake piece, 0 disables, -1 means all but the last byte; with -split the fake piece is the piece ending here") ttl := flag.Int("ttl", 4, "TTL for a fake initial transmission") disorder := flag.Bool("disorder", false, "send the first TCP piece with hop limit 1 (needs -split)") oob := flag.Bool("oob", false, "send one out-of-band byte after the first TCP piece (needs -split; with -disorder: disoob)") oobByte := flag.String("oob-byte", "a", "the out-of-band byte: one character or a 0x-prefixed hex value (0x00 selects the default a)") fakeTimeout := flag.Duration("fake-timeout", 3*time.Second, "maximum duration of a native fake operation") + fakeSNI := flag.String("fake-sni", "", "server names for the decoy ClientHello, comma-separated, one drawn per connection; * ? # are random alphanumeric/letter/digit") + fakeMod := flag.String("fake-tls-mod", "", "decoy ClientHello changes, comma-separated: rand (random, session ID, key shares), orig (build the decoy from the real ClientHello)") + fakeOffset := flag.Int("fake-offset", 0, "start the decoy transmission at this byte of the decoy") verbose := flag.Bool("v", false, "log every connection") flag.Parse() @@ -51,7 +57,20 @@ func main() { opts.OOB = &desync.OOBOptions{Byte: b} } if *fake != 0 { - opts.Fake = &desync.FakeOptions{TTL: *ttl, Prefix: *fake, Timeout: *fakeTimeout} + opts.Fake = &desync.FakeOptions{TTL: *ttl, Prefix: *fake, Timeout: *fakeTimeout, Offset: *fakeOffset} + opts.Fake.SNI = splitList(*fakeSNI) + for _, m := range splitList(*fakeMod) { + switch m { + case "rand": + opts.Fake.Randomize = true + case "orig": + opts.Fake.FromOriginal = true + default: + log.Fatalf("unknown -fake-tls-mod %q: want rand or orig", m) + } + } + } else if *fakeSNI != "" || *fakeMod != "" || *fakeOffset != 0 { + log.Fatal("-fake-sni, -fake-tls-mod and -fake-offset need -fake") } var err error if opts.SplitWait, err = desync.ParseSplitWait(*wait); err != nil { @@ -71,7 +90,7 @@ func main() { if err != nil { log.Fatal(err) } - log.Printf("desync-socks on %s (tlsrec=%v split=%v delay=%v wait=%v disorder=%v oob=%v fake=%d ttl=%d)", ln.Addr(), opts.TLSRec, opts.Split, *delay, opts.SplitWait, *disorder, *oob, *fake, *ttl) + log.Printf("desync-socks on %s (tlsrec=%v split=%v delay=%v wait=%v disorder=%v oob=%v fake=%d ttl=%d fake-sni=%q fake-tls-mod=%q)", ln.Addr(), opts.TLSRec, opts.Split, *delay, opts.SplitWait, *disorder, *oob, *fake, *ttl, *fakeSNI, *fakeMod) for { c, err := ln.Accept() if err != nil { @@ -96,6 +115,17 @@ func parseList(s string) ([]desync.Pos, error) { return out, nil } +// splitList splits a comma-separated list, dropping empty entries. +func splitList(s string) []string { + var out []string + for _, f := range strings.Split(s, ",") { + if f = strings.TrimSpace(f); f != "" { + out = append(out, f) + } + } + return out +} + // parseByte parses one character or a 0x-prefixed hex byte. func parseByte(s string) (byte, error) { if strings.HasPrefix(s, "0x") { diff --git a/cmd/desync-socks/main_test.go b/cmd/desync-socks/main_test.go index 87190ae..dbe7c86 100644 --- a/cmd/desync-socks/main_test.go +++ b/cmd/desync-socks/main_test.go @@ -114,3 +114,26 @@ func TestParseList(t *testing.T) { t.Fatal("bad position accepted") } } + +func TestSplitList(t *testing.T) { + got := splitList(" a.example, ,*.b.example,") + if len(got) != 2 || got[0] != "a.example" || got[1] != "*.b.example" { + t.Fatalf("%q", got) + } + if splitList("") != nil { + t.Fatal("empty list") + } +} + +// The flags' fake options validate together with split and disorder where +// the platform has the fake. +func TestFakeSplitOptions(t *testing.T) { + opts := desync.Options{ + Split: []desync.Pos{{Offset: 1}}, + Disorder: true, + Fake: &desync.FakeOptions{TTL: 4, Prefix: -1, SNI: splitList("www.example.com,*.example.org"), Randomize: true}, + } + if err := opts.Validate(); desync.SupportsFake() && err != nil { + t.Fatal(err) + } +} From 37d2a7ebac8087f8b932bc9fe6432cdc12b23216 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Thu, 29 Oct 2026 20:38:53 +0300 Subject: [PATCH 4/4] docs: document decoy SNI, fake with split pieces and the QUIC template --- README.md | 50 +++++++++++++++++++++++++++++++++++++------ docs/connection-io.md | 29 +++++++++++++++++++++++-- docs/vnext.md | 20 +++++++++++++++-- 3 files changed, 89 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 577c75d..fd99c4b 100644 --- a/README.md +++ b/README.md @@ -28,8 +28,11 @@ A filter on the path and the destination server can read the same bytes differen | Split wait (`SplitWait`) | Before each further piece, waits until the kernel reports the previous bytes as sent or acknowledged | sent, acked¹ | sent, acked | acked | | Disorder (`Disorder`) | The first TCP piece goes out with hop limit 1 and expires; TCP retransmits it after the later pieces | ✓¹ | ✓ | ✓² | | Out-of-band byte (`OOB`) | One urgent byte follows the first TCP piece; the server's TCP removes it from the stream | ✓ | ✓ | ✓ | -| Low-TTL fake prefix (`Fake`) | First transmission of a prefix carries other bytes with a short hop limit; a retransmission carries the original | ✓ | ✓ | —³ | +| Low-TTL fake piece (`Fake`) | First transmission of a prefix, or of one split piece, carries other bytes with a short hop limit; a retransmission carries the original | ✓ | ✓ | —³ | +| Decoy ClientHello (`Fake.SNI`, `FromOriginal`, `Randomize`) | The fake bytes are a valid ClientHello for another server name, built from the template or the real hello | ✓ | ✓ | —³ | +| Fake with split pieces (`Fake` + `Split`, `Disorder`, `OOB`) | The piece ending at the fake prefix is the fake; the pieces around it are ordinary, disorder or out-of-band | ✓ | ✓ | —³ | | Low-TTL UDP burst (`WrapPacketConn`) | Bounded low-TTL datagrams before the first datagrams to each peer; originals are unchanged | ✓ | ✓ | ✓ | +| QUIC Initial decoy (`UDPOptions.Template`, `QUICOnly`) | The burst datagrams are QUIC v1 Initials for another server name; optionally only QUIC Initials get a burst | ✓ | ✓ | ✓ | Linux includes Android. ¹ Inferred from counters, not reliable; see [platform capabilities](#platform-capabilities-and-split-wait). ² The transmission before the hop limit is restored is inferred, not observed; see [disorder](#disorder-and-out-of-band-byte). ³ Not implementable: macOS cannot make a retransmission carry other bytes than the first transmission; see [connection I/O](docs/connection-io.md#macos-tcp-fake). @@ -143,11 +146,11 @@ opts := desync.Options{ } ``` -- Both act on the first TCP piece, so they need `Split` or `Random.Split` positions; a ClientHello where no split position resolves is written in one piece, as with `Split` alone. `TLSRec`, `SplitDelay` and `SplitWaitSent` combine with them; `Fake` does not, and `Disorder` rejects `SplitWaitAcked` (the dropped piece is acknowledged only after its retransmission). +- Both act on the first TCP piece, so they need `Split` or `Random.Split` positions; a ClientHello where no split position resolves is written in one piece, as with `Split` alone. `TLSRec`, `SplitDelay`, `SplitWaitSent` and `Fake` (on a later piece, see below) combine with them; `Disorder` rejects `SplitWaitAcked` (the dropped piece is acknowledged only after its retransmission). - `Disorder` sets hop limit 1 for the first piece, so it expires at the first router. The hop limit is restored before the next piece and on every error, and TCP retransmits the piece with the normal limit after the server received the later pieces. On Linux and Windows the limit is restored only after the kernel reports the piece as transmitted (`SIOCOUTQNSD`, `SIO_TCP_INFO`), bounded by `SplitWaitTimeout` (`ErrSplitWaitTimeout`), the write deadline and `Close`. macOS cannot observe unsent bytes: the piece is written once `SO_NWRITE` reports an empty send buffer, so the kernel builds the segment inside the send call, and `Capabilities.Disorder.Observed` is false. - `OOB` sends the first piece followed by one byte (`Byte`, default `'a'`) with `MSG_OOB`. The server's TCP takes that byte out of the stream as urgent data, so the application reads the original bytes; an inspecting device that ignores the urgent pointer sees one extra byte. A server using `SO_OOBINLINE`, or a middlebox that clears the URG flag, would put the byte into the stream and break the handshake. -### Low-TTL fake prefix (Windows, Linux) +### Low-TTL fake piece (Windows, Linux) ```go opts := desync.Options{ @@ -158,10 +161,41 @@ 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. `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. +- `Payload` replaces the bytes of the first transmission; by default an embedded TLS template is used, padded or truncated to the fake piece. `Offset` starts the decoy at a later byte (ByeDPI `--fake-offset`). - `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"]`). +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. macOS reports it unsupported (`Capabilities.Unsupported["fake-tcp"]`). + +Decoy ClientHello (ByeDPI `--fake-sni`, `--fake-tls-mod`): + +```go +opts := desync.Options{ + Fake: &desync.FakeOptions{ + TTL: 4, + SNI: []string{"www.example.com", "cdn-##.example.net"}, // one per connection; * ? # are random + Randomize: true, // fresh random, session ID and key shares per connection + // FromOriginal: true, // build the decoy from the real ClientHello instead of the template + }, +} +``` + +- With `SNI`, `Randomize` or `FromOriginal` the decoy is decoded and re-encoded as a valid ClientHello with every length recomputed, then padded or truncated to the fake piece. The template's padding extension absorbs a longer or shorter name, so it keeps its 517 bytes; a decoy built from the real hello changes length with the name. +- Names must be DNS host names (no IP literals, at most 64 names); `*` becomes a random letter or digit, `?` a letter, `#` a digit. A custom `Payload` must then be a ClientHello. `FromOriginal` needs `SNI` or `Randomize` and excludes `Payload`. + +Fake with split pieces (ByeDPI `--split`/`--disorder`/`--oob` followed by `--fake`): + +```go +opts := desync.Options{ + Split: []desync.Pos{{Offset: 1, FromSNI: true}}, + Disorder: true, // optional: the first piece goes out with hop limit 1 + Fake: &desync.FakeOptions{TTL: 4, Prefix: -1}, // the piece from 1+s to the last byte is the fake +} +``` + +- The fake prefix end is one more cut. The fake piece is the piece that ends there and starts at the previous split cut (or at 0); every other piece is an ordinary write, and `Disorder`/`OOB` still act on the first piece. If for a ClientHello the fake piece would be the first piece while `Disorder` or `OOB` is set, the write fails with `ErrFakeFirstPiece` before any byte is sent. +- `SplitDelay` and `SplitWaitSent` apply between all pieces; `SplitWaitAcked` is rejected (the fake piece is acknowledged only after its retransmission). +- Linux lowers the hop limit for the fake piece only once `SIOCOUTQNSD` reports the earlier pieces transmitted, so none of them goes out with it (ByeDPI waits the same way). Windows, like ByeDPI, does not wait: the TTL applies to the `TransmitFile` request. The pieces after the fake are written as soon as the native request is submitted. +- After an error at or after the fake piece, `Write` counts only the pieces before it. ### Automatic TTL @@ -212,6 +246,8 @@ _, err = packets.WriteTo(datagram, peer) - Needs an **unconnected** UDP socket that exposes `SyscallConn`. The wrapper owns all writes to it. - `Repeats` (1–16, default 6) low-TTL datagrams go before each of the first `Packets` (1–8, default 3) datagrams to a peer. The default payload is 64 zero bytes. +- `Template: desync.UDPTemplateQUICInitial` generates a QUIC v1 client Initial per burst instead: long header, version 1, random 8-byte DCID and SCID, a CRYPTO frame with a ClientHello for `SNI` (default `www.wikipedia.org`, ALPN `h3`, QUIC transport parameters), PADDING to 1200 bytes, protected with the Initial keys of RFC 9001, so a device that decrypts Initials reads the decoy name. `desync.QUICInitialPayload(sni)` returns one such packet for a fixed `Payload`. +- `QUICOnly: true` gives a burst only to datagrams that look like a QUIC client Initial (long header, version 1, a draft or 2, Initial type, at least 1200 bytes); other datagrams pass untouched and do not count towards `Packets`. - Originals keep their content, order and source port. The hop limit is restored before every original; if it cannot be restored, the socket is closed. - Up to 64 peers per socket are tracked, with a 2-minute idle expiry; further peers pass through unchanged. - TTL-expired ICMP replies do not surface as receive errors. Windows suppresses them on the socket (`SIO_UDP_NETRESET`); Linux reports them on an unconnected socket only with `IP_RECVERR`/`IPV6_RECVERR`, which the wrapper turns off if they were enabled; macOS never delivers them to an unconnected socket. @@ -231,6 +267,8 @@ go run ./cmd/desync-socks -listen 127.0.0.1:10802 -split 1+s -split-wait acked go run ./cmd/desync-socks -listen 127.0.0.1:10802 -split 1+s -disorder go run ./cmd/desync-socks -listen 127.0.0.1:10802 -split 3+s -oob -oob-byte a go run ./cmd/desync-socks -listen 127.0.0.1:10802 -tlsrec 1+s -fake -1 -ttl 4 # Windows, Linux +go run ./cmd/desync-socks -listen 127.0.0.1:10802 -fake -1 -ttl 4 -fake-sni www.example.com -fake-tls-mod rand +go run ./cmd/desync-socks -listen 127.0.0.1:10802 -split 1+s -disorder -fake -1 -ttl 4 ``` Point the application under test at the SOCKS endpoint. It does not change system proxy settings, has no authentication and no UDP. @@ -251,4 +289,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), the automatic TTL estimate from zapret (MIT); what was taken is listed in [third_party/NOTICE](third_party/NOTICE). +MIT, see [LICENSE](LICENSE). The default fake TLS template, the fake, decoy, 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). diff --git a/docs/connection-io.md b/docs/connection-io.md index 8654d4e..4e4bc3b 100644 --- a/docs/connection-io.md +++ b/docs/connection-io.md @@ -59,7 +59,7 @@ The implementation follows [TLS record framing, RFC 8446 section 5.1](https://da ## Disorder and out-of-band byte -`Options.Disorder` and `Options.OOB` change how the first TCP piece of a split ClientHello is sent; every later piece is an ordinary write. They need split positions (`Split` or `Random.Split`); when none resolves for a ClientHello, it is written in one piece, as with `Split` alone. Both are prepared before the first piece: a connection without a TCP `SyscallConn` returns `ErrSocketMethodRequiresTCP` before any byte is sent, and an OS without the method fails `Validate` with `ErrDisorderUnsupported` / `ErrOOBUnsupported`. Neither combines with `Fake`; `Disorder` rejects `SplitWaitAcked`, because the dropped piece is acknowledged only after its retransmission, so the wait would undo the reordering. `SplitWaitSent` and `SplitDelay` apply between the later pieces as usual. +`Options.Disorder` and `Options.OOB` change how the first TCP piece of a split ClientHello is sent; every later piece is an ordinary write. They need split positions (`Split` or `Random.Split`); when none resolves for a ClientHello, it is written in one piece, as with `Split` alone. Both are prepared before the first piece: a connection without a TCP `SyscallConn` returns `ErrSocketMethodRequiresTCP` before any byte is sent, and an OS without the method fails `Validate` with `ErrDisorderUnsupported` / `ErrOOBUnsupported`. Both combine with `Fake` on a later piece (see [fake with split pieces](#fake-with-split-pieces)); `Disorder` rejects `SplitWaitAcked`, because the dropped piece is acknowledged only after its retransmission, so the wait would undo the reordering. `SplitWaitSent` and `SplitDelay` apply between the later pieces as usual. Disorder (ByeDPI `--disorder`): the hop limit of the connected peer's family is set to 1, the first piece is written, the hop limit is restored, then the remaining pieces follow. The piece expires at the first router; the server receives the later pieces first, acknowledges what it can (with SACK), and the client's TCP retransmits the first piece with the restored limit. The kernel stamps the hop limit when it builds a segment, not when `write` returns, so the restore must wait for the transmission: @@ -79,7 +79,26 @@ The page is rewritten before the hop limit is restored on every path, including The kernel splices without copying only when the route's device supports scatter-gather (`NETIF_F_SG`); loopback, Ethernet, Wi-Fi, tun and WireGuard devices do. On a device without it the kernel copies the spliced data, a retransmission repeats the fake, and the server's TLS handshake fails rather than succeeding with altered bytes. -A loopback test verifies the property directly: a classic BPF socket filter on the server's socket drops every segment with a TTL or hop limit below 8 before TCP processing, the client sends a fake prefix of different bytes with TTL 3, and the server still reads the exact original stream after the client's retransmission (`tcpi_total_retrans` 1). Disabling the page rewrite makes the server read the fake bytes. The same filter verifies disorder and disoob. +A loopback test verifies the property directly: a classic BPF socket filter on the server's socket drops every segment with a TTL or hop limit below 8 before TCP processing, the client sends a fake prefix of different bytes with TTL 3, and the server still reads the exact original stream after the client's retransmission (`tcpi_total_retrans` 1). Disabling the page rewrite makes the server read the fake bytes. The same filter verifies disorder and disoob, the fake combined with split pieces, disorder, OOB, `SplitWaitSent` and random cuts, and decoy ClientHellos with another server name (`TestLinuxLowHopDropRetransmitsOriginal`). + +## Fake with split pieces + +With `Split` or `Random.Split` positions the fake prefix end (`Fake.Prefix`, measured after record fragmentation) becomes one more cut, and the piece that ends there, starting at the previous cut or at 0, is sent as the fake; this is ByeDPI's `--fake` as one part among `--split`, `--disorder` and `--oob` parts. Every other piece is an ordinary write; `Disorder` and `OOB` still act on the first piece, and `SplitDelay` and `SplitWaitSent` apply between all pieces. `SplitWaitAcked` is rejected: the low-hop piece is acknowledged only after its retransmission. When, for a given ClientHello, no split cut lies before the fake end while `Disorder` or `OOB` is set, the first piece would need two methods; the write then fails with `ErrFakeFirstPiece` before anything is sent (it is terminal, like other first-write errors). When no split position resolves, the hello is sent as with `Fake` alone. + +Every guarantee of the single fake holds for the piece: the hop limit is restored on every path, a retransmission carries the original bytes, native waits are bounded by `Fake.Timeout`, the write deadline and `Close`, and any error after the first transformed send is terminal. + +- **Linux and Android**: before lowering the hop limit for a fake piece that does not start the stream, the wrapper polls until `SIOCOUTQNSD` is zero (bounded like the fake itself), so no byte of an earlier piece is built into a segment with the low hop limit; ByeDPI waits the same way (`sock_has_notsent`) between parts. Then the piece is spliced as before; the pieces after it are written once the page holds the original bytes and the hop limit is restored. +- **Windows**: the piece goes out through `TransmitFile` as before; the later pieces (with their waits and delays) are written right after the request is submitted and before its completion is awaited, as the single tail is. No wait precedes the piece: as in ByeDPI, the TTL is set around the `TransmitFile` request. The process-wide two-transmission slot is held while those later pieces are written, so a long `SplitDelay` after a fake piece delays other connections' fakes. + +Write accounting: once the fake piece has started, a failure reports only the bytes of the pieces before it (generated record headers excluded), never more than what reached the socket; zero is still not permission to replay. + +The decoy (`Payload`, the template, or a decoy ClientHello) starts at `Fake.Offset` and is zero-padded or truncated to the piece length. A fake piece in the middle of the stream therefore carries the beginning of the decoy unless `Offset` moves it (ByeDPI `--fake-offset`). + +## Decoy ClientHello + +`Fake.SNI`, `Fake.FromOriginal` and `Fake.Randomize` (ByeDPI `--fake-sni`, `--fake-tls-mod orig`, `--fake-tls-mod rand`) make the decoy a ClientHello built per connection. The base (the template, a custom `Payload`, or with `FromOriginal` the connection's own hello, reassembled across its input records) is decoded into its fields and extensions, changed, and encoded again with every length (record, handshake, extensions, server name list) recomputed, in records of at most 16 KiB. `SNI` replaces the server_name extension, or prepends one when the base has none; one name is drawn per connection from `crypto/rand`, with `*`, `?` and `#` replaced by a random letter or digit, letter, or digit. A padding extension absorbs the length change where it can. `Randomize` replaces the random, the session ID and every key share value, keeping their lengths. ByeDPI instead resizes the hello in place to keep its size; here only the template keeps its size, through its padding extension. + +`Validate` checks names as DNS host names (letters, digits and hyphens, labels of 1 to 63 bytes, at most 253 bytes, no IP literals; at most 64 names), that a custom `Payload` decodes as a ClientHello when it is to be modified, that `FromOriginal` has `SNI` or `Randomize` and no `Payload`, and that `Offset` is between 0 and 65535. `Options.Key()` lists the names, `orig`, `rand` and `offset` only when set. ## macOS TCP fake @@ -112,6 +131,12 @@ The low-TTL datagrams can draw ICMP time-exceeded replies from the router where On a macOS dual-stack socket, `IPV6_UNICAST_HOPS` also sets the TTL of IPv4-mapped traffic, and `IPPROTO_IP` options are rejected. A default hop limit (-1) is therefore restored as its explicit value, and only when the IPv4 and IPv6 defaults (`net.inet.ip.ttl`, `net.inet6.ip6.hlim`) are equal; otherwise the burst fails with an error instead of changing the socket. +## QUIC Initial decoy + +`UDPOptions.Template = UDPTemplateQUICInitial` replaces the 64 zero bytes with a QUIC version 1 client Initial packet generated per burst (every datagram of one burst is the same packet): a long header with a random 8-byte destination and source connection ID, no token, a 4-byte packet number 0, one CRYPTO frame at offset 0 with a ClientHello and PADDING frames to a 1200-byte datagram (RFC 9000 section 14.1). The ClientHello is the TCP template with `UDPOptions.SNI` (default `www.wikipedia.org`), fresh random values, no session ID and no padding extension, ALPN `h3`, and QUIC transport parameters carrying `initial_source_connection_id` and `max_idle_timeout`. The packet is protected like a real client's: AES-128-GCM with the client Initial key and IV derived from the destination connection ID with the version 1 salt, and AES header protection (RFC 9001 sections 5.2 to 5.4; HKDF is implemented with `crypto/hmac` because `crypto/hkdf` needs Go 1.24, and the derivation is tested against appendix A.1). Any observer can derive these keys, which is the point: a device that reads Initials sees the decoy name. `QUICInitialPayload(sni)` returns one such packet for a fixed `Payload`. ByeDPI v0.17.3 has no QUIC template; its `--udp-fake` sends the 64 zero bytes. + +`UDPOptions.QUICOnly` applies the burst only to a datagram that looks like a client Initial: long header with the fixed bit, version 1 or a draft (`0xff0000xx`) with packet type 0, or version 2 with type 1, a destination connection ID of at most 20 bytes, and at least 1200 bytes. Other datagrams pass untouched and do not count towards `Packets` for the peer, so a DNS query before the QUIC handshake does not use up the burst. Hop-limit handling, ordering, source port and counters are unchanged. + ## Windows native fake socket options The TCP fake backend selects the TTL/hop-limit option for its connected peer's address family and restores that same option. It does not try to set IPv4 TTL on an IPv6-only connection merely because reading that option succeeded. This also keeps option selection explicit for IPv4-mapped peers. Native overlapped resource lifetime, cancellation and transmit-slot limits remain in place. Socket options are read through `syscall.Getsockopt` (ws2_32 `getsockopt`), because `syscall.GetsockoptInt` returns `EWINDOWS` on Windows before Go 1.21; the module's minimum Go 1.20 is tested on Windows in CI. See [IPv4 socket options](https://learn.microsoft.com/en-us/windows/win32/winsock/ipproto-ip-socket-options) and [IPv6 socket options](https://learn.microsoft.com/en-us/windows/win32/winsock/ipproto-ipv6-socket-options). diff --git a/docs/vnext.md b/docs/vnext.md index d994a4a..5d0163c 100644 --- a/docs/vnext.md +++ b/docs/vnext.md @@ -36,6 +36,7 @@ application probe and real application tests; a successful TCP dial is insuffici | 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 | | Cross-platform methods | `Options.Disorder` and `Options.OOB` (ByeDPI disorder, oob, disoob) on Windows, Linux/Android and macOS; TCP fake on Linux/Android via vmsplice/splice; UDP low-TTL burst on Linux/Android and macOS; macOS TCP fake reported unsupported with the reason; `Capabilities.Disorder`, `OOB` and `Unsupported` | | Automatic TTL | `FakeOptions.AutoTTL` (zapret-style delta/min/max) from the SYN-ACK hop limit on Linux/Android IPv6 (`ControlAutoTTL`, `ObserveHops`, `EstimateHops`), with an optional fixed fallback TTL; Linux IPv4, Windows and macOS reported unsupported with the reason; `FakeTTLCandidates`/`UDPTTLCandidates` and `UDPOptions.Key()` for range discovery elsewhere | +| Fake improvements | Decoy ClientHello with another server name (`Fake.SNI` list with wildcards, `FromOriginal`, `Randomize`, `Offset`; ByeDPI `--fake-sni`, `--fake-tls-mod`, `--fake-offset`); the fake as one piece among `Split`/`Random.Split` pieces with `Disorder`, `OOB`, `SplitDelay` and `SplitWaitSent` on Windows and Linux/Android; QUIC v1 Initial decoy template for the UDP burst (`UDPOptions.Template`, `SNI`, `QUICOnly`, `QUICInitialPayload`) | | 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 @@ -138,8 +139,23 @@ with a BPF filter that drops the low-hop segments. The UDP burst runs on Linux/Android and macOS with ICMP errors kept off the owned socket. The macOS TCP fake is not implementable (sendfile copies into the socket buffer) and is reported in `Capabilities.Unsupported`. Not yet done: macOS runtime evidence -beyond CI, real-network effectiveness, and combining Fake with Split, -Disorder or OOB. +beyond CI and real-network effectiveness. + +### Fake improvements + +Status: implemented in the library. `FakeOptions.SNI` (one name per +connection, ByeDPI wildcards), `FromOriginal` and `Randomize` re-encode the +decoy as a valid ClientHello with recomputed lengths; `Offset` shifts it. +With split positions the fake prefix end is one more cut and the piece ending +there is the fake (ByeDPI `-s`/`-d`/`-o` parts followed by `-f`); Disorder and +OOB keep the first piece, a fake first piece with them fails with +`ErrFakeFirstPiece` before sending, and `SplitWaitAcked` is rejected. Linux +lowers the hop limit only after `SIOCOUTQNSD` reports the earlier pieces sent. +Verified on Linux loopback with the low-hop drop filter (IPv4 and IPv6) and on +Windows loopback with byte-identical streams. The UDP burst can send a QUIC v1 +Initial decoy (keys per RFC 9001, test vectors from appendix A.1) and can be +limited to datagrams that look like QUIC Initials. Not yet done: real-network +effectiveness of the decoy names and the QUIC template; macOS has no TCP fake. Automatic TTL: implemented where an unprivileged TCP socket can see the server's TTL, which is Linux/Android over IPv6 only (`IPV6_RECVHOPLIMIT`