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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,55 @@ Newest first. This file records *why* things changed, since that is the part a d
does not keep. Structural decisions live in [`DESIGN.md`](../DESIGN.md) §14 and in
[`docs/adr/`](adr/).

## 2026-10-03 — L1 hardening: echo the borrowed suite, correct the SNI claim

Two distinguishers found while reading the code during the 2026-10-01 pass
(ROADMAP H4 and H5), closed together because both are about the relay's two
answer paths — local for a tagged client, spliced for everyone else — agreeing
on what they put in cleartext.

### The relay echoes the cipher suite the site negotiates (H4)

`buildServerHello` pinned the suite to `TLS_AES_128_GCM_SHA256`, and the profile
never recorded what the borrowed site actually chose. The cipher suite sits in
cleartext in the ServerHello, so against a site preferring AES-256 or ChaCha20 a
tagged client got `0x1301` from local state while a spliced probe got the site's
real choice — two suites from one address, separable with no decryption and no
key, exactly the shape of split the 2026-10-01 pass closed on the time axis.

`ProfileSite` now reads the negotiated suite off the wire
(`FlightProfile.CipherSuite`) and the relay echoes it. The value names nothing
about how Warren encrypts the session — that is still ChaCha20-Poly1305 under the
derived key regardless — it only has to match what the site answers, so echoing
the measured value costs nothing. An unmeasured profile falls back to the pinned
suite, which every parroted Chrome hello offers.

The gate now measures it: `Compare` parses both ServerHellos' suites and reports
a mismatch, and a canary (`TestCanary_CipherSuiteMismatchIsDetected`) forces the
relay onto a suite the site does not negotiate and requires the finding to fire —
because a measurement with no canary is one that can quietly stop measuring.

### The SNI claim is corrected to match the single-site splice (H5)

The transport package comment said an unauthenticated connection is spliced "to
the real site the ClientHello's SNI names". It is not: a relay fronts **one**
site and splices every unauthenticated connection to `FallbackAddr`, whatever SNI
the hello carried. For real traffic the two coincide — a genuine Warren client
always presents the borrowed site's SNI — and for a probe presenting some other
name the relay hands back the borrowed site anyway, which is precisely what a
real single-site server does with an unexpected SNI (its default certificate).

Routing by SNI was considered and rejected: it would turn the relay into an open
proxy to arbitrary hosts, which is the amplification problem tracked as H7, and a
security regression rather than a fix. So the behaviour is correct and the claim
was wrong; the comment is fixed, and an `unexpected-sni` probe now asserts the
relay still matches the borrowed site under a name neither endpoint fronts — a
relay that *did* route by SNI would return a certificate for a different name and
separate itself on the leaf digest alone.

Verified: `go build`, `go vet`, `go test ./...`, `gofmt`. Not verified locally:
`-race` (needs cgo and a C toolchain this machine lacks); CI covers it.

## 2026-10-01 — L1 hardening: answer timing, replay freshness, and canaries on the gate

Three weaknesses closed and three defects found on the way, one of which had been
Expand Down
12 changes: 10 additions & 2 deletions docs/ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,8 +130,6 @@ from it, not by effort. Items marked **found** came out of the hardening pass on
| H1 | **Traffic shape after the handshake** (`bucket`/`cover`, DESIGN §6.4) | The largest measured gap. The machinery exists — every record carries a kind byte and filler is already discarded by the peer — so this is a policy layer over tested code, not a new wire format. Slice 2 |
| H2 | **The gate stops measuring where the handshake ends** | `cmd/probe` compares handshake shape and now answer timing; it does not compare the data phase against the borrowed site's real responses. Slice 1's PASS is routinely misread as deployability because of this |
| H3 | **One round trip still separates the relay's two answer paths** — *found* | The ServerHello wait equalises the site's answer time but not the TCP connect the splice additionally pays. Fix is warm upstream connections (better: keeps Warren fast) or measuring from dial (simpler: makes Warren slower). Measured and reported by `cmd/probe` today |
| H4 | **The relay hardcodes its ServerHello cipher suite** — *found* | `tls13CipherSuite` is pinned to `TLS_AES_128_GCM_SHA256`, and the profile never records what the borrowed site actually negotiated. Against a site preferring AES-256 or ChaCha20, a tagged client and a spliced probe get *different* cipher suites from the same relay. It names nothing about how Warren really encrypts, so echoing the measured value is free |
| H5 | **The splice ignores the ClientHello's SNI** — *found* | The code always dials `FallbackAddr`; the package comment and the README both say it splices to the site the SNI names. A probe presenting an unexpected SNI gets a certificate for the wrong name. Fix the behaviour or the claim, and add the probe case either way |
| H6 | **No session rekey** | One ChaCha20-Poly1305 key for the whole connection, no record-count limit, no KeyUpdate equivalent. TLS 1.3 rekeys; a long-lived tunnel should too |

### Resource and failure behaviour
Expand Down Expand Up @@ -178,6 +176,16 @@ from it, not by effort. Items marked **found** came out of the hardening pass on
| H24 | **No relay operator guide** | How to choose a site to borrow, what that site's operator sees (a handshake every 30 minutes, plus a connection per probe), and what abuse handling is expected. §7.4 is logged as a requirement with nothing written against it |
| H25 | **"~5,500 lines" is hardcoded in four documents** | A drift magnet. Say it once, or derive it |

### Resolved

Closed since the 2026-10-01 pass, kept here so the numbering stays stable and
the history is legible.

| # | Item | How it was closed |
|---|------|-------------------|
| H4 | **The relay hardcoded its ServerHello cipher suite** — *found* | ✅ `ProfileSite` now records the suite the borrowed site negotiates (`FlightProfile.CipherSuite`) and the relay echoes it rather than a pinned `TLS_AES_128_GCM_SHA256`, so a tagged client and a spliced probe see the same suite. `cmd/probe` compares the two ServerHellos' suites, guarded by a canary. It still names nothing about how Warren encrypts (ChaCha20-Poly1305 under the derived key); the echoed value only has to agree with the site |
| H5 | **The splice ignored the ClientHello's SNI** — *found* | ✅ Claim corrected rather than behaviour changed: a relay fronts **one** site and splices every unauthenticated connection to `FallbackAddr` regardless of the SNI, exactly as a real single-site server answers an unexpected SNI with its own default certificate. Routing by SNI was rejected on purpose — it would make the relay an open proxy to arbitrary hosts (see H7). The package comment is fixed and a `unexpected-sni` probe asserts the relay still matches the borrowed site |

---

## Slice 2 — L1 breadth + client distribution ⬜
Expand Down
29 changes: 29 additions & 0 deletions internal/network/probe/canary_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,35 @@ func TestCanary_AnswerLatencySplitIsDetected(t *testing.T) {
}
}

// TestCanary_CipherSuiteMismatchIsDetected guards the cipher-suite measurement
// (H4). The borrowed site negotiates one TLS 1.3 suite; a relay that answers a
// tagged client with a different one splits its two answer paths onto suites a
// censor can read in cleartext from the ServerHello. The measurement is new, so
// it gets a canary: force the relay to echo a suite the loopback site does not
// negotiate and require the comparison to say so.
func TestCanary_CipherSuiteMismatchIsDetected(t *testing.T) {
site := startBorrowedSite(t)

relay, clientCfg := startRelayShaped(t, site, func(p *transport.FlightProfile) {
// The Go test site negotiates AES-128 (0x1301) on loopback hardware;
// force the relay to answer AES-256 so the two disagree. This does not
// touch Warren's own encryption, which is ChaCha20-Poly1305 under the
// derived key regardless of the suite named here.
p.CipherSuite = 0x1302
})

report := captureAndCompare(t, relay, clientCfg, site)

f := findingByName(t, report, "ServerHello cipher suite")
if f.Warren == "unparsed" || f.Real == "unparsed" {
t.Fatalf("a ServerHello did not parse, so this canary measured nothing: warren %s, real %s", f.Warren, f.Real)
}
if !f.Distinguisher {
t.Errorf("a relay answering 0x1302 where the site negotiates %s was reported as indistinguishable: warren %s, real %s",
f.Real, f.Warren, f.Real)
}
}

// TestCanary_MissingSessionTicketsAreDetected guards the post-handshake
// measurement, which is the one a relay would fail a few records later than the
// certificate flight if it stopped replaying what the site sends after the
Expand Down
23 changes: 23 additions & 0 deletions internal/network/probe/probe.go
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ func Suite() []Probe {
return []Probe{
tlsHandshakeProbe(),
repeatHandshakeProbe(),
unexpectedSNIProbe(),
plaintextHTTPProbe(),
randomJunkProbe(),
truncatedHelloProbe(),
Expand Down Expand Up @@ -149,6 +150,28 @@ func repeatHandshakeProbe() Probe {
}
}

// unexpectedSNIProbe connects with an SNI the relay does not front (H5). A
// Warren relay borrows one site and splices every unauthenticated connection to
// it regardless of the SNI presented — it does not route by SNI — so it must
// answer an unexpected SNI exactly as the borrowed site does: with that site's
// own default certificate. A relay that instead dialed the SNI-named host would
// return a certificate for a different name and separate itself from the site on
// the leaf digest alone. The SNI argument from the suite is deliberately ignored
// in favour of a fixed name neither endpoint is configured for.
func unexpectedSNIProbe() Probe {
const unexpected = "nonexistent.example"
return Probe{
Name: "unexpected-sni",
Desc: "handshake with an SNI the relay does not front; it must still answer like the borrowed site",
Run: func(ctx context.Context, addr, _ string) Observation {
return runTLSHandshake(ctx, addr, unexpected)
},
Signature: func(o Observation) string {
return fmt.Sprintf("ok=%t cert=%s err=%s", o.HandshakeOK, o.CertSHA256, o.ErrClass)
},
}
}

func runTLSHandshake(ctx context.Context, addr, sni string) Observation {
start := time.Now()
raw, err := dial(ctx, addr)
Expand Down
39 changes: 39 additions & 0 deletions internal/network/probe/probe_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -262,6 +262,45 @@ func TestProbeSuite_TLSHandshakeSeesBorrowedCertificate(t *testing.T) {
}
}

// TestUnexpectedSNIIsSplicedToTheBorrowedSite is H5: a relay fronts one site and
// splices every unauthenticated connection to it regardless of the SNI, so a
// probe that presents an SNI the relay does not front must still be answered by
// the borrowed site — the same certificate a real single-site server returns for
// an unexpected SNI. A relay that routed by SNI would hand back a certificate for
// a different name, which the leaf digest would expose.
func TestUnexpectedSNIIsSplicedToTheBorrowedSite(t *testing.T) {
site := startBorrowedSite(t)
relay, _ := startRelay(t, site)

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

// The probe must be in the suite — otherwise H5's guard runs nowhere.
var inSuite bool
for _, p := range Suite() {
if p.Name == "unexpected-sni" {
inSuite = true
}
}
if !inSuite {
t.Fatal("the unexpected-sni probe is not in the suite; H5's guard is not running")
}

const unexpected = "nonexistent.example"
viaRelay := runTLSHandshake(ctx, relay, unexpected)
direct := runTLSHandshake(ctx, site, unexpected)

// The comparison is only meaningful if both actually handshook and returned a
// certificate; "both failed identically" would pass vacuously.
if !viaRelay.HandshakeOK || viaRelay.CertSHA256 == "" {
t.Fatalf("relay did not complete a handshake and present a certificate under an unexpected SNI: %+v", viaRelay)
}
if viaRelay.CertSHA256 != direct.CertSHA256 {
t.Errorf("under an unexpected SNI the relay returned certificate %q, the borrowed site %q: a relay that routed by SNI would do exactly this",
viaRelay.CertSHA256, direct.CertSHA256)
}
}

// TestCompare_FlightMatchesRealSite is Stage A's verdict, measured rather than
// asserted: a Warren session's record shape no longer separates from a real TLS
// session to the same site.
Expand Down
90 changes: 88 additions & 2 deletions internal/network/probe/trace.go
Original file line number Diff line number Diff line change
Expand Up @@ -75,11 +75,22 @@ type Trace struct {
// ClientHello can be replayed back at the relay (ReplayProbe) — which is
// exactly the move a censor makes with one recording.
ClientBytes []byte

// ServerBytes is the head of the server->client stream, kept so the
// ServerHello's cleartext fields — the negotiated cipher suite in
// particular — can be read back off the wire. A censor needs no key to see
// them, so the harness compares them the same way.
ServerBytes []byte
}

// maxCapturedClientBytes bounds ClientBytes; a ClientHello record is ~1.5 KB
// and nothing beyond the first record is replayable anyway.
const maxCapturedClientBytes = 16 << 10
// and nothing beyond the first record is replayable anyway. maxCapturedServerBytes
// matches it: a hybrid ServerHello record is ~1.2 KB and only the first record
// is parsed.
const (
maxCapturedClientBytes = 16 << 10
maxCapturedServerBytes = 16 << 10
)

// FirstClientRecord returns the first complete TLS record the client sent, or
// nil if the capture did not contain one.
Expand All @@ -94,6 +105,38 @@ func (t Trace) FirstClientRecord() []byte {
return t.ClientBytes[:end]
}

// ServerHelloCipherSuite reads the negotiated cipher suite out of the first
// server handshake record. It parses only the fixed prefix up to the suite —
// legacy_version, random, session_id, cipher_suite — which is all cleartext in
// a TLS 1.3 ServerHello. ok is false if the capture held no parseable
// ServerHello.
func (t Trace) ServerHelloCipherSuite() (suite uint16, ok bool) {
b := t.ServerBytes
if len(b) < 5 || b[0] != TypeHandshake {
return 0, false
}
recLen := int(b[3])<<8 | int(b[4])
rec := b[5:]
if recLen < len(rec) {
rec = rec[:recLen]
}
// handshake: msg_type(1)=server_hello + length(3) + body
if len(rec) < 4 || rec[0] != 0x02 {
return 0, false
}
body := rec[4:]
// legacy_version(2) + random(32) + session_id_len(1)
if len(body) < 35 {
return 0, false
}
sidLen := int(body[34])
p := body[35:]
if len(p) < sidLen+2 {
return 0, false
}
return uint16(p[sidLen])<<8 | uint16(p[sidLen+1]), true
}

func (t Trace) String() string {
var b strings.Builder
fmt.Fprintf(&b, "%s (%d records)\n", t.Label, len(t.Records))
Expand Down Expand Up @@ -126,6 +169,12 @@ func (s *scanner) Write(p []byte) (int, error) {
s.out.ClientBytes = append(s.out.ClientBytes, p[:min(room, len(p))]...)
}
s.mu.Unlock()
} else {
s.mu.Lock()
if room := maxCapturedServerBytes - len(s.out.ServerBytes); room > 0 {
s.out.ServerBytes = append(s.out.ServerBytes, p[:min(room, len(p))]...)
}
s.mu.Unlock()
}

for {
Expand Down Expand Up @@ -205,6 +254,7 @@ func Capture(ctx context.Context, label, target string, drive func(ctx context.C
defer mu.Unlock()
trace.Records = append([]Record(nil), trace.Records...)
trace.ClientBytes = append([]byte(nil), trace.ClientBytes...)
trace.ServerBytes = append([]byte(nil), trace.ServerBytes...)
sort.SliceStable(trace.Records, func(i, j int) bool { return trace.Records[i].At < trace.Records[j].At })
return trace, driveErr
}
Expand Down Expand Up @@ -374,6 +424,23 @@ func Compare(warren, real Trace) Report {
Distinguisher: absDiff(wSH, rSH) > serverHelloSizeTolerance,
})

// The negotiated cipher suite, in cleartext in the ServerHello. The relay
// answers a tagged client from local state and everyone else by splicing to
// the borrowed site; if the local answer hardcodes a suite the site does not
// negotiate, the two paths to one address differ on a field a censor reads
// without a key. Only flagged when both ServerHellos parse, so a capture
// that missed one is not mistaken for a mismatch (that failure is the
// capture canary's job, not this measurement's).
wCS, wCSOK := warren.ServerHelloCipherSuite()
rCS, rCSOK := real.ServerHelloCipherSuite()
r.Findings = append(r.Findings, Finding{
Name: "ServerHello cipher suite",
Warren: cipherSuiteName(wCS, wCSOK),
Real: cipherSuiteName(rCS, rCSOK),
Distinguisher: wCSOK && rCSOK && wCS != rCS,
Note: "the relay must echo the suite the borrowed site negotiates, not a hardcoded one",
})

// How long the peer took to answer, which is a shape measurement on the
// time axis and the cheapest one a passive observer has: it needs no
// decryption, no key, and no probe of its own, just a clock.
Expand Down Expand Up @@ -543,6 +610,25 @@ func shortType(t byte) string {
}
}

// cipherSuiteName renders a TLS 1.3 cipher suite for a report. The three TLS
// 1.3 suites get their names; anything else is shown as its hex code, which is
// enough to see a mismatch.
func cipherSuiteName(suite uint16, ok bool) string {
if !ok {
return "unparsed"
}
switch suite {
case 0x1301:
return "AES_128_GCM_SHA256"
case 0x1302:
return "AES_256_GCM_SHA384"
case 0x1303:
return "CHACHA20_POLY1305_SHA256"
default:
return fmt.Sprintf("0x%04x", suite)
}
}

func absDiff(a, b int) int {
if a > b {
return a - b
Expand Down
25 changes: 20 additions & 5 deletions internal/network/transport/camouflage.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,15 @@
// identity exchange (see handshake.go). Application data then flows in
// records shaped like TLS application_data.
// - tag invalid, absent, or replayed -> the connection is spliced
// byte-for-byte to the real site the ClientHello's SNI names. A censor's
// active probe (or any passive DPI classifier) sees a completely genuine
// handshake with the real site's real certificate, because it *is* one.
// byte-for-byte to the one site this relay borrows (Config.FallbackAddr),
// not to whatever the ClientHello's SNI names. A relay fronts a single
// site, and a genuine Warren client always carries that site's SNI
// (Config.FallbackSNI) in its hello, so for real traffic the two are the
// same; a probe presenting some other SNI is still handed the borrowed
// site, exactly as a real single-site server answers an unexpected SNI
// with its own default certificate. A censor's active probe (or any
// passive DPI classifier) sees a completely genuine handshake with that
// site's real certificate, because it *is* one.
//
// Known gap vs. full REALITY (xtls/xray-core's `reality` package): a genuine
// Warren session's second flight is shaped like TLS 1.3 but is not a real TLS
Expand Down Expand Up @@ -367,10 +373,19 @@ func serveConn(ctx context.Context, raw net.Conn, cfg Config, replays *replayCac
// the key exchange below has to fall inside that budget rather than extend it.
helloAt := time.Now()
if err == nil {
// Fetch the flight before validating the tag: its measured cipher suite
// goes into the ServerHello serverAccept builds, so the relay echoes the
// suite the borrowed site negotiated rather than a hardcoded one. A nil
// or unmeasured profile leaves it zero, which buildServerHello falls back
// from; flight.Validate below is what refuses to serve on a nil profile.
flight := cfg.flight()
var cipherSuite uint16
if flight != nil {
cipherSuite = flight.CipherSuite
}
accepted, acceptErr := serverAccept(
cfg.ServerPrivateKey, hello.random, hello.sessionID, hello.share, helloAt)
cfg.ServerPrivateKey, hello.random, hello.sessionID, hello.share, helloAt, cipherSuite)

flight := cfg.flight()
if acceptErr == nil && flight.Validate() == nil && replays.admit(hello.random, helloAt) {
raw.SetReadDeadline(time.Now().Add(sniffTimeout + maxServerHelloDelay))
conn, err := completeHandshake(raw, br, recordLen, helloAt, accepted, flight, hello.random, hello.share)
Expand Down
Loading
Loading