From 24320adb1f43077e800827f61cae1cfac0c88589 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Sun, 4 Oct 2026 01:10:42 +0300 Subject: [PATCH 01/27] fix(reality): imitate target TLS 1.3 post-handshake records After ClientFinished, the REALITY server may remain silent where the configured target emits TLS 1.3 post-handshake records. Learn target post-handshake record lengths asynchronously per destination, SNI, ALPN mode and cipher suite, then emit matching encrypted application-data records before marking the handshake complete. Probe failures preserve existing behavior, probes are coalesced and rate-limited, and RealityConfig clones share the cache. Client-side REALITY behavior is unchanged. (cherry picked from commit 0eed8b0e197105a2f9aa237834d77ad32f4c3300) --- reality.go | 22 +- reality_post_handshake.go | 346 ++++++++++++++ reality_post_handshake_test.go | 819 +++++++++++++++++++++++++++++++++ 3 files changed, 1186 insertions(+), 1 deletion(-) create mode 100644 reality_post_handshake.go create mode 100644 reality_post_handshake_test.go diff --git a/reality.go b/reality.go index 7f2b4f2c8d..f9dea33b00 100644 --- a/reality.go +++ b/reality.go @@ -20,6 +20,7 @@ import ( "net" "runtime" "sync" + "sync/atomic" "time" "github.com/metacubex/utls/internal/ratelimit" @@ -113,10 +114,15 @@ type RealityConfig struct { LimitFallbackDownload RealityLimitFallback Config + + // postHandshake caches the target's learned post-handshake record + // pattern. It is created lazily and shared with clones so that clones do + // not probe the target again. + postHandshake atomic.Pointer[realityPostHandshakeCache] } func (a *RealityConfig) Clone() *RealityConfig { - return &RealityConfig{ + c := &RealityConfig{ DialContext: a.DialContext, Log: a.Log, Type: a.Type, @@ -132,6 +138,8 @@ func (a *RealityConfig) Clone() *RealityConfig { LimitFallbackDownload: a.LimitFallbackDownload, Config: *a.Config.Clone(), } + c.postHandshake.Store(a.postHandshakeCache()) + return c } type rateLimitedConn struct { @@ -212,6 +220,10 @@ type realityServerHandshakeStateTLS13 struct { ClientTime time.Time ClientShortId [8]byte Config *RealityConfig + + // firstFlightPostHandshakeRecords counts the records after the server + // Finished that were already mirrored in the first flight. + firstFlightPostHandshakeRecords int } func (hs *realityServerHandshakeStateTLS13) handshake() error { @@ -296,6 +308,7 @@ func (hs *realityServerHandshakeStateTLS13) handshake() error { if _, err := c.realityWriteRecord(recordTypeHandshake, []byte{typeNewSessionTicket}); err != nil { return err } + hs.firstFlightPostHandshakeRecords++ } // Note that at this point we could start sending application data without // waiting for the client's second flight, but the application might not @@ -556,6 +569,13 @@ func RealityServer(ctx context.Context, conn net.Conn, config *RealityConfig) (* if err != nil { break } + err = hs.imitatePostHandshakeRecords() + if err != nil { + if config.Log != nil { + config.Log("REALITY remoteAddr: %v hs.imitatePostHandshakeRecords() err: %v", remoteAddr, err) + } + break + } hs.c.isHandshakeComplete.Store(true) break } diff --git a/reality_post_handshake.go b/reality_post_handshake.go new file mode 100644 index 0000000000..b046e04e2a --- /dev/null +++ b/reality_post_handshake.go @@ -0,0 +1,346 @@ +package tls + +// REALITY server: learn and imitate the configured target's TLS 1.3 +// post-handshake records. +// +// A TLS 1.3 server may send encrypted records after its Finished message, most +// commonly NewSessionTicket. Some servers send them in their first flight +// (reproduced per connection via handshakeLen[6]), others only after they have +// received the client's Finished. The REALITY server cannot observe the latter +// on the live connection, because the real client's Finished is never +// forwarded to the target once the client has been authenticated. Instead, the +// wire lengths of those records are learned once per (target, SNI, ALPN, +// cipher suite) with an asynchronous probe handshake and replayed as empty +// application_data records of the same length after the client's Finished. + +import ( + "context" + "encoding/binary" + "errors" + "fmt" + "sync" + "time" +) + +const ( + realityALPNNone uint8 = iota + realityALPNHTTP1 + realityALPNH2 +) + +const ( + // realityMaxPostHandshakeRecords bounds how many records are imitated. A + // target emitting more than this in the probe window is not imitated. + realityMaxPostHandshakeRecords = 8 + // realityMinPostHandshakeRecordLen is the smallest TLS 1.3 encrypted record: + // header, one byte of TLSInnerPlaintext (the content type) and the AEAD tag. + realityMinPostHandshakeRecordLen = recordHeaderLen + 1 + 16 + // realityMaxPostHandshakeRecordLen is the largest record that can carry an + // empty application_data fragment padded to length. + realityMaxPostHandshakeRecordLen = recordHeaderLen + maxPlaintext + 1 + 16 +) + +// Probe tunables. Variables so tests can shorten them. +var ( + // realityPostHandshakeProbeTimeout bounds dial plus handshake of a probe. + realityPostHandshakeProbeTimeout = 15 * time.Second + // realityPostHandshakeCollectWindow is how long a probe waits for + // post-handshake records after its handshake completed. + realityPostHandshakeCollectWindow = 5 * time.Second + // realityPostHandshakeRetryInterval is the minimum delay before a failed + // probe is attempted again for the same key. + realityPostHandshakeRetryInterval = time.Minute +) + +// realityPostHandshakeKey identifies a learned post-handshake record pattern. +// The key space is bounded by RealityConfig.ServerNames, the three ALPN modes +// and the TLS 1.3 cipher suites, because lookups only happen for authenticated +// clients whose ClientHello the target already answered. +type realityPostHandshakeKey struct { + network string + dest string + serverName string + alpn uint8 + cipherSuite uint16 +} + +type realityPostHandshakeEntry struct { + done chan struct{} // closed when the probe finished; fields below are valid after that + + lens []uint16 + ok bool + finished time.Time +} + +// realityPostHandshakeCache is shared by a RealityConfig and all its clones. +type realityPostHandshakeCache struct { + mu sync.Mutex + entries map[realityPostHandshakeKey]*realityPostHandshakeEntry +} + +func newRealityPostHandshakeCache() *realityPostHandshakeCache { + return &realityPostHandshakeCache{entries: make(map[realityPostHandshakeKey]*realityPostHandshakeEntry)} +} + +// lookup returns the learned record lengths for key. When nothing has been +// learned yet it starts at most one probe for the key and returns ok=false +// without blocking. +func (c *realityPostHandshakeCache) lookup(config *RealityConfig, key realityPostHandshakeKey) (lens []uint16, ok bool) { + c.mu.Lock() + defer c.mu.Unlock() + + if e := c.entries[key]; e != nil { + select { + case <-e.done: + if e.ok { + return e.lens, true + } + if time.Since(e.finished) < realityPostHandshakeRetryInterval { + return nil, false + } + // A stale failure: probe again below. + default: + return nil, false // probe in flight + } + } + + e := &realityPostHandshakeEntry{done: make(chan struct{})} + c.entries[key] = e + go e.run(config, key) + return nil, false +} + +func (e *realityPostHandshakeEntry) run(config *RealityConfig, key realityPostHandshakeKey) { + lens, err := realityProbePostHandshakeRecords(config, key) + if config.Log != nil { + config.Log("REALITY probe dest: %v sni: %v alpn: %v suite: %x lens: %v err: %v", key.dest, key.serverName, key.alpn, key.cipherSuite, lens, err) + } + e.lens = lens + e.ok = err == nil + e.finished = time.Now() + close(e.done) +} + +// realityALPNMode reduces the client's ALPN list to the mode the probe offers. +// Servers typically apply their own preference, so any offer of h2 is treated +// as an h2 negotiation. +func realityALPNMode(protos []string) uint8 { + if len(protos) == 0 { + return realityALPNNone + } + for _, p := range protos { + if p == "h2" { + return realityALPNH2 + } + } + return realityALPNHTTP1 +} + +func realityProbeALPN(mode uint8) []string { + switch mode { + case realityALPNH2: + return []string{"h2", "http/1.1"} + case realityALPNHTTP1: + return []string{"http/1.1"} + default: + return nil + } +} + +// realityProbeClientHelloSpec builds a minimal TLS 1.3-only ClientHello that +// pins the negotiation to the observed cipher suite and ALPN mode. +func realityProbeClientHelloSpec(key realityPostHandshakeKey) *ClientHelloSpec { + extensions := []TLSExtension{ + &SNIExtension{ServerName: key.serverName}, + &SupportedCurvesExtension{Curves: []CurveID{X25519}}, + &SupportedPointsExtension{SupportedPoints: []uint8{pointFormatUncompressed}}, + &SignatureAlgorithmsExtension{SupportedSignatureAlgorithms: []SignatureScheme{ + ECDSAWithP256AndSHA256, + PSSWithSHA256, + PKCS1WithSHA256, + ECDSAWithP384AndSHA384, + PSSWithSHA384, + PKCS1WithSHA384, + PSSWithSHA512, + PKCS1WithSHA512, + Ed25519, + }}, + } + if protos := realityProbeALPN(key.alpn); protos != nil { + extensions = append(extensions, &ALPNExtension{AlpnProtocols: protos}) + } + extensions = append(extensions, + &KeyShareExtension{KeyShares: []KeyShare{{Group: X25519}}}, + &PSKKeyExchangeModesExtension{Modes: []uint8{PskModeDHE}}, + &SupportedVersionsExtension{Versions: []uint16{VersionTLS13}}, + ) + return &ClientHelloSpec{ + CipherSuites: []uint16{key.cipherSuite}, + CompressionMethods: []uint8{compressionNone}, + Extensions: extensions, + } +} + +// realityProbePostHandshakeRecords performs one handshake with the target and +// returns the wire lengths of every record the target sent after its Finished +// within the collection window. +func realityProbePostHandshakeRecords(config *RealityConfig, key realityPostHandshakeKey) ([]uint16, error) { + ctx, cancel := context.WithTimeout(context.Background(), realityPostHandshakeProbeTimeout) + defer cancel() + + target, err := config.DialContext(ctx, key.network, key.dest) + if err != nil { + return nil, err + } + defer target.Close() + + uconn := UClient(target, &Config{ + ServerName: key.serverName, + InsecureSkipVerify: true, // only record lengths are of interest + }, HelloCustom) + if err := uconn.ApplyPreset(realityProbeClientHelloSpec(key)); err != nil { + return nil, err + } + if err := uconn.HandshakeContext(ctx); err != nil { + return nil, err + } + if state := uconn.ConnectionState(); state.Version != VersionTLS13 || state.CipherSuite != key.cipherSuite { + return nil, errors.New("REALITY: probe negotiated unexpected parameters") + } + + // The client handshake consumed records up to and including the server + // Finished. Whatever it read beyond that is the start of the + // post-handshake stream. + data := append([]byte(nil), uconn.rawInput.Bytes()...) + + // Bound the collection: a read deadline where supported, and a hard close + // for transports that ignore deadlines. + stop := time.AfterFunc(realityPostHandshakeCollectWindow, func() { target.Close() }) + defer stop.Stop() + target.SetReadDeadline(time.Now().Add(realityPostHandshakeCollectWindow)) + + const maxCollect = (realityMaxPostHandshakeRecords + 1) * realityMaxPostHandshakeRecordLen + buf := make([]byte, 4096) + for len(data) <= maxCollect { + n, err := target.Read(buf) + data = append(data, buf[:n]...) + if err != nil { + break + } + } + + lens, ok := realityParsePostHandshakeRecords(data) + if !ok { + return nil, errors.New("REALITY: probe observed an unusable post-handshake record stream") + } + return lens, nil +} + +// realityParsePostHandshakeRecords splits data into TLS 1.3 encrypted records +// and returns their wire lengths. It reports ok=false when the stream holds +// anything other than complete application_data records of imitable size. +func realityParsePostHandshakeRecords(data []byte) (lens []uint16, ok bool) { + lens = make([]uint16, 0, 2) + for len(data) > 0 { + if len(data) < recordHeaderLen { + return nil, false // cut inside a record header + } + if recordType(data[0]) != recordTypeApplicationData || + data[1] != 0x03 || data[2] != 0x03 { // record-layer version is frozen to TLS 1.2 + return nil, false + } + length := recordHeaderLen + int(binary.BigEndian.Uint16(data[3:5])) + if length < realityMinPostHandshakeRecordLen || length > realityMaxPostHandshakeRecordLen { + return nil, false + } + if len(data) < length { + return nil, false // cut inside a record + } + if len(lens) == realityMaxPostHandshakeRecords { + return nil, false + } + lens = append(lens, uint16(length)) + data = data[length:] + } + return lens, true +} + +// realityWritePostHandshakeRecord writes a single TLS 1.3 record of exactly +// length bytes on the wire. The record carries an empty application_data +// fragment and zero padding, so clients ignore it, and it consumes one +// sequence number of the server application traffic keys like the record it +// imitates. +func (c *Conn) realityWritePostHandshakeRecord(length int) error { + c.out.Lock() + defer c.out.Unlock() + + sealer, ok := c.out.cipher.(aead) + if !ok || c.vers != VersionTLS13 { + return errors.New("REALITY: post-handshake record without TLS 1.3 application keys") + } + inner := length - recordHeaderLen - sealer.Overhead() + if inner < 1 || inner > maxPlaintext+1 { + return fmt.Errorf("REALITY: invalid post-handshake record length %d", length) + } + + record := make([]byte, recordHeaderLen, length) + record[0] = byte(recordTypeApplicationData) + record[1] = 0x03 // record-layer version is frozen to TLS 1.2 + record[2] = 0x03 + record[3] = byte((length - recordHeaderLen) >> 8) + record[4] = byte(length - recordHeaderLen) + + // TLSInnerPlaintext: empty content, the real content type, zero padding. + plaintext := make([]byte, inner) + plaintext[0] = byte(recordTypeApplicationData) + + record = sealer.Seal(record, c.out.seq[:], plaintext, record[:recordHeaderLen]) + c.out.incSeq() + _, err := c.write(record) + return err +} + +// postHandshakeCache returns the cache shared by this config and its clones, +// creating it on first use. +func (a *RealityConfig) postHandshakeCache() *realityPostHandshakeCache { + if c := a.postHandshake.Load(); c != nil { + return c + } + c := newRealityPostHandshakeCache() + if a.postHandshake.CompareAndSwap(nil, c) { + return c + } + return a.postHandshake.Load() +} + +// imitatePostHandshakeRecords is called after the client's Finished was +// verified. It replays the target's learned post-handshake records, minus the +// ones already mirrored in the first flight. Without a usable cache entry it +// changes nothing. +func (hs *realityServerHandshakeStateTLS13) imitatePostHandshakeRecords() error { + config := hs.Config + key := realityPostHandshakeKey{ + network: config.Type, + dest: config.Dest, + serverName: hs.clientHello.serverName, + alpn: realityALPNMode(hs.clientHello.alpnProtocols), + cipherSuite: hs.hello.cipherSuite, + } + lens, ok := config.postHandshakeCache().lookup(config, key) + if !ok { + return nil + } + skip := hs.firstFlightPostHandshakeRecords + if skip > len(lens) { + skip = len(lens) + } + for _, length := range lens[skip:] { + if err := hs.c.realityWritePostHandshakeRecord(int(length)); err != nil { + return err + } + if config.Log != nil { + config.Log("REALITY remoteAddr: %v post-handshake record: %v", hs.c.RemoteAddr(), length) + } + } + return nil +} diff --git a/reality_post_handshake_test.go b/reality_post_handshake_test.go new file mode 100644 index 0000000000..7447eb0456 --- /dev/null +++ b/reality_post_handshake_test.go @@ -0,0 +1,819 @@ +package tls + +import ( + "context" + "crypto/aes" + "crypto/cipher" + "crypto/ecdh" + "crypto/rand" + "crypto/sha256" + "encoding/binary" + "errors" + "io" + "net" + "reflect" + "sync" + "sync/atomic" + "testing" + "time" + + "golang.org/x/crypto/curve25519" + "golang.org/x/crypto/hkdf" +) + +func init() { + // Keep probes fast in tests. Set once for the whole package so that no + // probe goroutine can race with a later test changing them. + realityPostHandshakeCollectWindow = 500 * time.Millisecond + realityPostHandshakeProbeTimeout = 2 * time.Second +} + +const realityTestServerName = "example.golang" + +var ( + realityTestShortID = [8]byte{1, 2, 3, 4, 5, 6, 7, 8} + realityTestMarker = []byte("REALITY application data marker") + realityTestSuites = []uint16{TLS_AES_128_GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256, TLS_AES_256_GCM_SHA384} +) + +// realityTestTarget is a local TLS 1.3 server standing in for the REALITY +// destination. After each completed handshake it writes one application_data +// record per entry of postRecords for the negotiated ALPN, then either hangs +// up without close_notify or stays open until the peer closes. +type realityTestTarget struct { + ln net.Listener + config *Config + postRecords map[string][]int + hangUp bool + + accepted atomic.Int32 // TCP connections accepted (live REALITY mirrors and probes) + completed atomic.Int32 // handshakes completed (only probes and direct clients) +} + +func realityTestTargetConfig(nextProtos []string, sessionTickets bool) *Config { + config := testConfig.Clone() + config.MinVersion = VersionTLS13 + config.DynamicRecordSizingDisabled = true + config.SessionTicketsDisabled = !sessionTickets + config.NextProtos = nextProtos + return config +} + +func newRealityTestTarget(t *testing.T, config *Config, postRecords map[string][]int, hangUp bool) *realityTestTarget { + t.Helper() + ln, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + tt := &realityTestTarget{ln: ln, config: config, postRecords: postRecords, hangUp: hangUp} + t.Cleanup(func() { ln.Close() }) + go func() { + for { + raw, err := ln.Accept() + if err != nil { + return + } + tt.accepted.Add(1) + go tt.handle(raw) + } + }() + return tt +} + +func (tt *realityTestTarget) handle(raw net.Conn) { + defer raw.Close() + tc := Server(raw, tt.config) + if err := tc.Handshake(); err != nil { + return + } + tt.completed.Add(1) + for _, n := range tt.postRecords[tc.ConnectionState().NegotiatedProtocol] { + if _, err := tc.Write(make([]byte, n)); err != nil { + return + } + } + if tt.hangUp { + return + } + io.Copy(io.Discard, tc) +} + +func (tt *realityTestTarget) addr() string { return tt.ln.Addr().String() } + +func newRealityTestConfig(t *testing.T, dest string) (*RealityConfig, *ecdh.PublicKey) { + t.Helper() + priv := make([]byte, 32) + if _, err := io.ReadFull(rand.Reader, priv); err != nil { + t.Fatal(err) + } + pub, err := curve25519.X25519(priv, curve25519.Basepoint) + if err != nil { + t.Fatal(err) + } + pubKey, err := ecdh.X25519().NewPublicKey(pub) + if err != nil { + t.Fatal(err) + } + config := &RealityConfig{ + DialContext: (&net.Dialer{}).DialContext, + Type: "tcp", + Dest: dest, + ServerNames: map[string]bool{realityTestServerName: true}, + PrivateKey: priv, + ShortIds: map[[8]byte]bool{realityTestShortID: true}, + } + config.SessionTicketsDisabled = true + return config, pubKey +} + +// newRealityTestServer accepts connections, runs RealityServer on each and, +// once the REALITY handshake completed, writes realityTestMarker. +func newRealityTestServer(t *testing.T, config *RealityConfig) string { + t.Helper() + ln, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { ln.Close() }) + go func() { + for { + raw, err := ln.Accept() + if err != nil { + return + } + go func() { + c, err := RealityServer(context.Background(), raw, config) + if err != nil { + return + } + defer c.Close() + if _, err := c.Write(realityTestMarker); err != nil { + return + } + io.Copy(io.Discard, c) + }() + } + }() + return ln.Addr().String() +} + +// realityRecordingConn keeps a copy of everything read from the wrapped connection. +type realityRecordingConn struct { + net.Conn + mu sync.Mutex + buf []byte +} + +func (c *realityRecordingConn) Read(b []byte) (int, error) { + n, err := c.Conn.Read(b) + c.mu.Lock() + c.buf = append(c.buf, b[:n]...) + c.mu.Unlock() + return n, err +} + +func (c *realityRecordingConn) bytes() []byte { + c.mu.Lock() + defer c.mu.Unlock() + return append([]byte(nil), c.buf...) +} + +// realityTestRecordLens splits a raw TLS stream into records and returns +// their wire lengths. +func realityTestRecordLens(t *testing.T, data []byte) []int { + t.Helper() + lens := []int{} + for len(data) > 0 { + if len(data) < recordHeaderLen { + t.Fatalf("partial record header: % x", data) + } + n := recordHeaderLen + int(binary.BigEndian.Uint16(data[3:5])) + if len(data) < n { + t.Fatalf("partial record: want %d bytes, have %d", n, len(data)) + } + lens = append(lens, n) + data = data[n:] + } + return lens +} + +// realityTestAuthenticate turns the prepared ClientHello of uconn into a +// REALITY ClientHello for the server public key pub, mirroring what a REALITY +// client does. +func realityTestAuthenticate(t *testing.T, uconn *UConn, pub *ecdh.PublicKey) { + t.Helper() + if err := uconn.BuildHandshakeState(); err != nil { + t.Fatal(err) + } + hello := uconn.HandshakeState.Hello + rawSessionID := hello.Raw[39 : 39+32] + for i := range rawSessionID { + rawSessionID[i] = 0 + } + binary.BigEndian.PutUint64(hello.SessionId, uint64(time.Now().Unix())) + copy(hello.SessionId[8:], realityTestShortID[:]) + hello.SessionId[0] = 1 + hello.SessionId[1] = 8 + hello.SessionId[2] = 2 + + keys := uconn.HandshakeState.State13.KeyShareKeys + if keys == nil || keys.Ecdhe == nil { + t.Fatal("no X25519 key share private key") + } + authKey, err := keys.Ecdhe.ECDH(pub) + if err != nil { + t.Fatal(err) + } + if _, err := hkdf.New(sha256.New, authKey, hello.Random[:20], []byte("REALITY")).Read(authKey); err != nil { + t.Fatal(err) + } + block, _ := aes.NewCipher(authKey) + aead, _ := cipher.NewGCM(block) + aead.Seal(hello.SessionId[:0], hello.Random[20:], hello.SessionId[:16], hello.Raw) + copy(hello.Raw[39:], hello.SessionId) +} + +// realityTestDial connects to addr with a TLS 1.3 client offering alpn and +// suites. With pub set it authenticates as a REALITY client. It returns the +// connection, the raw recorder and the offset in the recorded stream of the +// first byte after the server Finished. +func realityTestDial(t *testing.T, addr string, pub *ecdh.PublicKey, alpn []string, suites []uint16) (*UConn, *realityRecordingConn, int) { + t.Helper() + raw, err := net.Dial("tcp", addr) + if err != nil { + t.Fatal(err) + } + rec := &realityRecordingConn{Conn: raw} + t.Cleanup(func() { raw.Close() }) + + uconn := UClient(rec, &Config{ + ServerName: realityTestServerName, + InsecureSkipVerify: true, + SessionTicketsDisabled: true, + }, HelloCustom) + spec := realityProbeClientHelloSpec(realityPostHandshakeKey{ + serverName: realityTestServerName, + alpn: realityALPNMode(alpn), + cipherSuite: suites[0], + }) + spec.CipherSuites = append([]uint16(nil), suites...) + if err := uconn.ApplyPreset(spec); err != nil { + t.Fatal(err) + } + if pub != nil { + realityTestAuthenticate(t, uconn, pub) + } + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + if err := uconn.HandshakeContext(ctx); err != nil { + t.Fatalf("handshake: %v", err) + } + if v := uconn.ConnectionState().Version; v != VersionTLS13 { + t.Fatalf("negotiated version %x, want TLS 1.3", v) + } + boundary := len(rec.bytes()) - uconn.rawInput.Len() + return uconn, rec, boundary +} + +// realityTestObserveTarget connects directly to the target and returns the +// wire lengths of every record the target sends after its Finished. +func realityTestObserveTarget(t *testing.T, tt *realityTestTarget, alpn []string, suites []uint16) []int { + t.Helper() + uconn, rec, boundary := realityTestDial(t, tt.addr(), nil, alpn, suites) + defer uconn.Close() + expect := 0 + for _, n := range tt.postRecords[uconn.ConnectionState().NegotiatedProtocol] { + expect += n + } + if expect > 0 { + if _, err := io.ReadFull(uconn, make([]byte, expect)); err != nil { + t.Fatalf("reading target payload: %v", err) + } + } else { + uconn.SetReadDeadline(time.Now().Add(500 * time.Millisecond)) + io.ReadAll(uconn) // drain whatever the target sends; EOF or timeout ends it + } + return realityTestRecordLens(t, rec.bytes()[boundary:]) +} + +// realityTestConnect performs an authenticated REALITY handshake, reads the +// marker written by the REALITY server and returns the wire lengths of the +// records between the server Finished and the marker record, plus the +// negotiated cipher suite. +func realityTestConnect(t *testing.T, addr string, pub *ecdh.PublicKey, alpn []string, suites []uint16) ([]int, uint16) { + t.Helper() + uconn, rec, boundary := realityTestDial(t, addr, pub, alpn, suites) + defer uconn.Close() + uconn.SetReadDeadline(time.Now().Add(10 * time.Second)) + got := make([]byte, len(realityTestMarker)) + if _, err := io.ReadFull(uconn, got); err != nil { + t.Fatalf("reading marker: %v", err) + } + if string(got) != string(realityTestMarker) { + t.Fatalf("marker = %q, want %q", got, realityTestMarker) + } + lens := realityTestRecordLens(t, rec.bytes()[boundary:]) + if len(lens) == 0 { + t.Fatal("marker record not found in the recorded stream") + } + return lens[:len(lens)-1], uconn.ConnectionState().CipherSuite +} + +func realityTestKey(config *RealityConfig, alpn []string, suite uint16) realityPostHandshakeKey { + return realityPostHandshakeKey{ + network: config.Type, + dest: config.Dest, + serverName: realityTestServerName, + alpn: realityALPNMode(alpn), + cipherSuite: suite, + } +} + +// realityTestWaitProbe waits for the probe of key to finish. The entry must +// already exist, which is guaranteed once a REALITY connection for that key +// delivered the marker. +func realityTestWaitProbe(t *testing.T, config *RealityConfig, key realityPostHandshakeKey) *realityPostHandshakeEntry { + t.Helper() + cache := config.postHandshakeCache() + cache.mu.Lock() + e := cache.entries[key] + cache.mu.Unlock() + if e == nil { + t.Fatalf("no probe entry for %+v", key) + } + select { + case <-e.done: + case <-time.After(10 * time.Second): + t.Fatal("probe did not finish") + } + return e +} + +func realityTestCacheSize(config *RealityConfig) int { + cache := config.postHandshakeCache() + cache.mu.Lock() + defer cache.mu.Unlock() + return len(cache.entries) +} + +func toUint16s(lens []int) []uint16 { + out := make([]uint16, 0, len(lens)) + for _, n := range lens { + out = append(out, uint16(n)) + } + return out +} + +// Scenario A and B: the target sends records only after it received the +// client's Finished. The first REALITY connection (nothing learned yet) shows +// the mismatch; once the probe finished the REALITY server reproduces the +// target's record lengths. +func TestRealityPostHandshakeRecordsImitated(t *testing.T) { + tt := newRealityTestTarget(t, realityTestTargetConfig(nil, false), map[string][]int{"": {300, 150}}, true) + config, pub := newRealityTestConfig(t, tt.addr()) + addr := newRealityTestServer(t, config) + + want := realityTestObserveTarget(t, tt, nil, realityTestSuites) + if len(want) != 2 { + t.Fatalf("target after-Finished records = %v, want 2 records", want) + } + + got, suite := realityTestConnect(t, addr, pub, nil, realityTestSuites) + if len(got) != 0 { + t.Fatalf("cold connection records = %v, want none (nothing learned yet)", got) + } + + e := realityTestWaitProbe(t, config, realityTestKey(config, nil, suite)) + if !e.ok || !reflect.DeepEqual(e.lens, toUint16s(want)) { + t.Fatalf("probe result ok=%v lens=%v, want %v", e.ok, e.lens, want) + } + + for i := 0; i < 3; i++ { + if got, _ := realityTestConnect(t, addr, pub, nil, realityTestSuites); !reflect.DeepEqual(got, want) { + t.Fatalf("warm connection %d records = %v, want %v", i, got, want) + } + } + if n := tt.completed.Load(); n != 2 { // the direct observation and exactly one probe + t.Fatalf("target completed %d handshakes, want 2", n) + } +} + +// Scenario C: a target that sends nothing after its Finished. +func TestRealityPostHandshakeNoRecords(t *testing.T) { + tt := newRealityTestTarget(t, realityTestTargetConfig(nil, false), nil, true) + config, pub := newRealityTestConfig(t, tt.addr()) + addr := newRealityTestServer(t, config) + + if want := realityTestObserveTarget(t, tt, nil, realityTestSuites); len(want) != 0 { + t.Fatalf("target after-Finished records = %v, want none", want) + } + got, suite := realityTestConnect(t, addr, pub, nil, realityTestSuites) + if len(got) != 0 { + t.Fatalf("cold connection records = %v, want none", got) + } + e := realityTestWaitProbe(t, config, realityTestKey(config, nil, suite)) + if !e.ok || len(e.lens) != 0 { + t.Fatalf("probe result ok=%v lens=%v, want ok with no records", e.ok, e.lens) + } + if got, _ := realityTestConnect(t, addr, pub, nil, realityTestSuites); len(got) != 0 { + t.Fatalf("warm connection records = %v, want none", got) + } +} + +// The probe must also work against a target that keeps the connection open: +// the collection window ends the probe. +func TestRealityPostHandshakeTargetKeepsOpen(t *testing.T) { + tt := newRealityTestTarget(t, realityTestTargetConfig(nil, false), map[string][]int{"": {777}}, false) + config, pub := newRealityTestConfig(t, tt.addr()) + addr := newRealityTestServer(t, config) + + want := realityTestObserveTarget(t, tt, nil, realityTestSuites) + _, suite := realityTestConnect(t, addr, pub, nil, realityTestSuites) + e := realityTestWaitProbe(t, config, realityTestKey(config, nil, suite)) + if !e.ok || !reflect.DeepEqual(e.lens, toUint16s(want)) { + t.Fatalf("probe result ok=%v lens=%v, want %v", e.ok, e.lens, want) + } + if got, _ := realityTestConnect(t, addr, pub, nil, realityTestSuites); !reflect.DeepEqual(got, want) { + t.Fatalf("warm connection records = %v, want %v", got, want) + } +} + +// Scenario D: the learned pattern is keyed by ALPN mode. +func TestRealityPostHandshakeALPN(t *testing.T) { + post := map[string][]int{ + "": {100}, + "http/1.1": {200}, + "h2": {300, 400}, + } + tt := newRealityTestTarget(t, realityTestTargetConfig([]string{"h2", "http/1.1"}, false), post, true) + config, pub := newRealityTestConfig(t, tt.addr()) + addr := newRealityTestServer(t, config) + + cases := []struct { + name string + alpn []string + }{ + {"none", nil}, + {"http1", []string{"http/1.1"}}, + {"h2", []string{"h2", "http/1.1"}}, + } + learned := map[string][]int{} + for _, tc := range cases { + want := realityTestObserveTarget(t, tt, tc.alpn, realityTestSuites) + learned[tc.name] = want + got, suite := realityTestConnect(t, addr, pub, tc.alpn, realityTestSuites) + if len(got) != 0 { + t.Fatalf("%s: cold connection records = %v, want none", tc.name, got) + } + e := realityTestWaitProbe(t, config, realityTestKey(config, tc.alpn, suite)) + if !e.ok || !reflect.DeepEqual(e.lens, toUint16s(want)) { + t.Fatalf("%s: probe result ok=%v lens=%v, want %v", tc.name, e.ok, e.lens, want) + } + if got, _ := realityTestConnect(t, addr, pub, tc.alpn, realityTestSuites); !reflect.DeepEqual(got, want) { + t.Fatalf("%s: warm connection records = %v, want %v", tc.name, got, want) + } + } + if n := realityTestCacheSize(config); n != 3 { + t.Fatalf("cache holds %d entries, want 3", n) + } + // The three modes must have produced different patterns, or the test + // would not prove the keying. + if reflect.DeepEqual(learned["none"], learned["http1"]) || reflect.DeepEqual(learned["http1"], learned["h2"]) { + t.Fatalf("patterns are not distinct per ALPN mode: %v", learned) + } +} + +// A target that sends NewSessionTicket in its first flight (like Go servers) +// and more records after the client's Finished. The first-flight ticket is +// mirrored live and must not be imitated a second time. +func TestRealityPostHandshakeFirstFlightTicket(t *testing.T) { + tt := newRealityTestTarget(t, realityTestTargetConfig(nil, true), map[string][]int{"": {250}}, true) + config, pub := newRealityTestConfig(t, tt.addr()) + addr := newRealityTestServer(t, config) + + want := realityTestObserveTarget(t, tt, nil, realityTestSuites) + if len(want) != 2 { + t.Fatalf("target after-Finished records = %v, want ticket and one data record", want) + } + + _, suite := realityTestConnect(t, addr, pub, nil, realityTestSuites) + e := realityTestWaitProbe(t, config, realityTestKey(config, nil, suite)) + if !e.ok || !reflect.DeepEqual(e.lens, toUint16s(want)) { + t.Fatalf("probe result ok=%v lens=%v, want %v", e.ok, e.lens, want) + } + for i := 0; i < 3; i++ { + if got, _ := realityTestConnect(t, addr, pub, nil, realityTestSuites); !reflect.DeepEqual(got, want) { + t.Fatalf("warm connection %d records = %v, want %v", i, got, want) + } + } +} + +// Scenario E: many concurrent REALITY connections trigger exactly one probe. +func TestRealityPostHandshakeConcurrentProbe(t *testing.T) { + tt := newRealityTestTarget(t, realityTestTargetConfig(nil, false), map[string][]int{"": {512}}, true) + config, pub := newRealityTestConfig(t, tt.addr()) + addr := newRealityTestServer(t, config) + want := realityTestObserveTarget(t, tt, nil, realityTestSuites) + + const n = 16 + var suite atomic.Uint32 + run := func(check func(got []int) error) { + var wg sync.WaitGroup + errs := make(chan error, n) + for i := 0; i < n; i++ { + wg.Add(1) + go func() { + defer wg.Done() + got, s := realityTestConnect(t, addr, pub, nil, realityTestSuites) + suite.Store(uint32(s)) + errs <- check(got) + }() + } + wg.Wait() + close(errs) + for err := range errs { + if err != nil { + t.Fatal(err) + } + } + } + + run(func(got []int) error { + if len(got) != 0 && !reflect.DeepEqual(got, want) { + return errors.New("unexpected records on a cold connection") + } + return nil + }) + realityTestWaitProbe(t, config, realityTestKey(config, nil, uint16(suite.Load()))) + run(func(got []int) error { + if !reflect.DeepEqual(got, want) { + return errors.New("warm connection did not reproduce the target records") + } + return nil + }) + if c := tt.completed.Load(); c != 2 { // the direct observation and a single probe + t.Fatalf("target completed %d handshakes, want 2", c) + } + if c := tt.accepted.Load(); c != 2*n+2 { + t.Fatalf("target accepted %d connections, want %d", c, 2*n+2) + } +} + +// Scenario F: a probe whose handshake is rejected does not affect service, +// is attempted once, and is retried only after the retry interval. +func TestRealityPostHandshakeProbeFailure(t *testing.T) { + targetConfig := realityTestTargetConfig(nil, false) + targetConfig.GetConfigForClient = func(chi *ClientHelloInfo) (*Config, error) { + if len(chi.CipherSuites) == 1 { // only the probe pins a single suite + return nil, errors.New("probe rejected") + } + return nil, nil + } + tt := newRealityTestTarget(t, targetConfig, map[string][]int{"": {128}}, true) + config, pub := newRealityTestConfig(t, tt.addr()) + addr := newRealityTestServer(t, config) + + var key realityPostHandshakeKey + for i := 0; i < 4; i++ { + got, suite := realityTestConnect(t, addr, pub, nil, realityTestSuites) + if len(got) != 0 { + t.Fatalf("connection %d records = %v, want none", i, got) + } + if i == 0 { + key = realityTestKey(config, nil, suite) + if e := realityTestWaitProbe(t, config, key); e.ok { + t.Fatal("probe reported success although the target rejected it") + } + } + } + if c := tt.accepted.Load(); c != 4+1 { + t.Fatalf("target accepted %d connections, want 4 live + 1 probe", c) + } + + // Age the failure past the retry interval: the next connection probes again. + cache := config.postHandshakeCache() + cache.mu.Lock() + cache.entries[key].finished = time.Now().Add(-2 * realityPostHandshakeRetryInterval) + cache.mu.Unlock() + if got, _ := realityTestConnect(t, addr, pub, nil, realityTestSuites); len(got) != 0 { + t.Fatalf("records = %v, want none", got) + } + if e := realityTestWaitProbe(t, config, key); e.ok { + t.Fatal("retried probe reported success although the target rejected it") + } + if c := tt.accepted.Load(); c != 5+2 { + t.Fatalf("target accepted %d connections, want 7", c) + } +} + +// Scenario F: a probe that hangs times out without blocking service. +func TestRealityPostHandshakeProbeTimeout(t *testing.T) { + release := make(chan struct{}) + t.Cleanup(func() { close(release) }) + targetConfig := realityTestTargetConfig(nil, false) + targetConfig.GetConfigForClient = func(chi *ClientHelloInfo) (*Config, error) { + if len(chi.CipherSuites) == 1 { + <-release + return nil, errors.New("probe rejected") + } + return nil, nil + } + tt := newRealityTestTarget(t, targetConfig, nil, true) + config, pub := newRealityTestConfig(t, tt.addr()) + addr := newRealityTestServer(t, config) + + start := time.Now() + var suite uint16 + for i := 0; i < 3; i++ { + got, s := realityTestConnect(t, addr, pub, nil, realityTestSuites) + if len(got) != 0 { + t.Fatalf("connection %d records = %v, want none", i, got) + } + suite = s + } + if d := time.Since(start); d > realityPostHandshakeProbeTimeout { + t.Fatalf("connections took %v; the hanging probe blocked them", d) + } + e := realityTestWaitProbe(t, config, realityTestKey(config, nil, suite)) + if e.ok { + t.Fatal("hanging probe reported success") + } + if got, _ := realityTestConnect(t, addr, pub, nil, realityTestSuites); len(got) != 0 { + t.Fatalf("records after probe timeout = %v, want none", got) + } +} + +// Scenario G: clones share the probe state of the original config. +func TestRealityConfigCloneSharesProbeCache(t *testing.T) { + if zero := (&RealityConfig{}).Clone(); zero.postHandshake.Load() == nil { + t.Fatal("clone of a zero config did not initialise the shared cache") + } + + tt := newRealityTestTarget(t, realityTestTargetConfig(nil, false), map[string][]int{"": {333}}, true) + config, pub := newRealityTestConfig(t, tt.addr()) + clone := config.Clone() + if clone.postHandshakeCache() != config.postHandshakeCache() { + t.Fatal("clone does not share the probe cache") + } + if clone.Clone().postHandshakeCache() != config.postHandshakeCache() { + t.Fatal("clone of a clone does not share the probe cache") + } + + want := realityTestObserveTarget(t, tt, nil, realityTestSuites) + viaClone := newRealityTestServer(t, clone) + viaOriginal := newRealityTestServer(t, config) + + _, suite := realityTestConnect(t, viaClone, pub, nil, realityTestSuites) + realityTestWaitProbe(t, config, realityTestKey(config, nil, suite)) + if got, _ := realityTestConnect(t, viaOriginal, pub, nil, realityTestSuites); !reflect.DeepEqual(got, want) { + t.Fatalf("original config records = %v, want %v", got, want) + } + if got, _ := realityTestConnect(t, viaClone, pub, nil, realityTestSuites); !reflect.DeepEqual(got, want) { + t.Fatalf("clone config records = %v, want %v", got, want) + } + if c := tt.completed.Load(); c != 2 { + t.Fatalf("target completed %d handshakes, want the observation and one shared probe", c) + } +} + +// The negotiated cipher suite is part of the key, and the probe pins it. +func TestRealityPostHandshakeCipherSuiteKey(t *testing.T) { + tt := newRealityTestTarget(t, realityTestTargetConfig(nil, false), map[string][]int{"": {64}}, true) + config, pub := newRealityTestConfig(t, tt.addr()) + addr := newRealityTestServer(t, config) + + for _, suite := range []uint16{TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384} { + want := realityTestObserveTarget(t, tt, nil, []uint16{suite}) + if _, negotiated := realityTestConnect(t, addr, pub, nil, []uint16{suite}); negotiated != suite { + t.Fatalf("negotiated %x, want %x", negotiated, suite) + } + e := realityTestWaitProbe(t, config, realityTestKey(config, nil, suite)) + if !e.ok || !reflect.DeepEqual(e.lens, toUint16s(want)) { + t.Fatalf("suite %x: probe result ok=%v lens=%v, want %v", suite, e.ok, e.lens, want) + } + if got, _ := realityTestConnect(t, addr, pub, nil, []uint16{suite}); !reflect.DeepEqual(got, want) { + t.Fatalf("suite %x: warm connection records = %v, want %v", suite, got, want) + } + } + if n := realityTestCacheSize(config); n != 2 { + t.Fatalf("cache holds %d entries, want one per suite", n) + } +} + +func TestRealityParsePostHandshakeRecords(t *testing.T) { + record := func(typ byte, payload int) []byte { + b := []byte{typ, 3, 3, byte(payload >> 8), byte(payload)} + return append(b, make([]byte, payload)...) + } + cat := func(parts ...[]byte) (out []byte) { + for _, p := range parts { + out = append(out, p...) + } + return out + } + cases := []struct { + name string + data []byte + want []uint16 + ok bool + }{ + {"empty", nil, []uint16{}, true}, + {"one", record(23, 100), []uint16{105}, true}, + {"two", cat(record(23, 17), record(23, 16384+17)), []uint16{22, 16406}, true}, + {"too short", record(23, 16), nil, false}, + {"too long", record(23, 16384+18), nil, false}, + {"handshake type", record(22, 100), nil, false}, + {"alert type", record(21, 2), nil, false}, + {"bad version", []byte{23, 3, 4, 0, 20, 0}, nil, false}, + {"cut header", []byte{23, 3, 3, 0}, nil, false}, + {"cut body", record(23, 100)[:50], nil, false}, + {"trailing garbage", cat(record(23, 100), []byte{23, 3}), nil, false}, + {"too many", cat(record(23, 20), record(23, 20), record(23, 20), record(23, 20), record(23, 20), record(23, 20), record(23, 20), record(23, 20), record(23, 20)), nil, false}, + {"at limit", cat(record(23, 20), record(23, 20), record(23, 20), record(23, 20), record(23, 20), record(23, 20), record(23, 20), record(23, 20)), []uint16{25, 25, 25, 25, 25, 25, 25, 25}, true}, + } + for _, tc := range cases { + got, ok := realityParsePostHandshakeRecords(tc.data) + if ok != tc.ok || (ok && !reflect.DeepEqual(got, tc.want)) { + t.Errorf("%s: got %v ok=%v, want %v ok=%v", tc.name, got, ok, tc.want, tc.ok) + } + } +} + +func TestRealityALPNMode(t *testing.T) { + cases := []struct { + protos []string + want uint8 + }{ + {nil, realityALPNNone}, + {[]string{}, realityALPNNone}, + {[]string{"http/1.1"}, realityALPNHTTP1}, + {[]string{"h2"}, realityALPNH2}, + {[]string{"h2", "http/1.1"}, realityALPNH2}, + {[]string{"http/1.1", "h2"}, realityALPNH2}, + {[]string{"foo"}, realityALPNHTTP1}, + } + for _, tc := range cases { + if got := realityALPNMode(tc.protos); got != tc.want { + t.Errorf("realityALPNMode(%v) = %d, want %d", tc.protos, got, tc.want) + } + } +} + +// Writing an imitation record must leave the sequence numbers consistent so +// that later application data still decrypts; the end-to-end tests above rely +// on the marker for that. This checks the length and validation directly. +func TestRealityWritePostHandshakeRecordLength(t *testing.T) { + server, client := localPipe(t) + defer server.Close() + defer client.Close() + + serverConfig := realityTestTargetConfig(nil, false) + done := make(chan error, 1) + go func() { + c := Client(client, &Config{ServerName: realityTestServerName, InsecureSkipVerify: true, MinVersion: VersionTLS13}) + if err := c.Handshake(); err != nil { + done <- err + return + } + buf := make([]byte, len(realityTestMarker)) + _, err := io.ReadFull(c, buf) + done <- err + }() + + countingConn := &countingWriter{Conn: server} + s := Server(countingConn, serverConfig) + if err := s.Handshake(); err != nil { + t.Fatal(err) + } + for _, bad := range []int{0, 21, realityMaxPostHandshakeRecordLen + 1} { + if err := s.realityWritePostHandshakeRecord(bad); err == nil { + t.Fatalf("length %d accepted", bad) + } + } + for _, length := range []int{realityMinPostHandshakeRecordLen, 123, realityMaxPostHandshakeRecordLen} { + countingConn.n = 0 + if err := s.realityWritePostHandshakeRecord(length); err != nil { + t.Fatal(err) + } + if countingConn.n != length { + t.Fatalf("wrote %d bytes, want %d", countingConn.n, length) + } + } + if _, err := s.Write(realityTestMarker); err != nil { + t.Fatal(err) + } + if err := <-done; err != nil { + t.Fatalf("client failed after imitation records: %v", err) + } +} + +type countingWriter struct { + net.Conn + n int +} + +func (c *countingWriter) Write(b []byte) (int, error) { + n, err := c.Conn.Write(b) + c.n += n + return n, err +} From c61133fed5b3504073993641486d8d5ced70304d Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Sun, 11 Oct 2026 20:58:29 +0300 Subject: [PATCH 02/27] fix(reality): raise the target record buffer to 17 KiB A target whose first flight holds a full-size TLS 1.3 record (16384 bytes of plaintext, up to 16645 bytes on the wire) exceeded the 16 KiB buffer and the REALITY handshake was aborted. Use 17 KiB like XTLS/REALITY#33 (Xray v26.9.8). (cherry picked from commit 1a98a454c0b1075421ed11d465e011164fbf8248) --- reality.go | 6 +- reality_citrus_test.go | 146 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 151 insertions(+), 1 deletion(-) create mode 100644 reality_citrus_test.go diff --git a/reality.go b/reality.go index f9dea33b00..f998a37477 100644 --- a/reality.go +++ b/reality.go @@ -70,7 +70,11 @@ func (c *realityMirrorConn) SetWriteDeadline(t time.Time) error { return nil } -const realitySize uint16 = 16384 +// realitySize bounds the target's first flight buffered by the REALITY +// server. It is 17 KiB (XTLS/REALITY#33) so that targets sending full-size +// TLS 1.3 records (up to 2^14+256 bytes of ciphertext) are mirrored instead of +// being rejected as too long. +const realitySize uint16 = 17 * 1024 var realityTypes = [7]string{ "Server Hello", diff --git a/reality_citrus_test.go b/reality_citrus_test.go new file mode 100644 index 0000000000..b3fa27dd47 --- /dev/null +++ b/reality_citrus_test.go @@ -0,0 +1,146 @@ +package tls + +import ( + "bytes" + "context" + "crypto/aes" + "crypto/cipher" + "crypto/ecdh" + "crypto/ed25519" + "crypto/hmac" + "crypto/sha256" + "crypto/sha512" + "encoding/binary" + "io" + "net" + "testing" + "time" + + "golang.org/x/crypto/hkdf" +) + +// realityTestBigTarget is a target whose certificate chain holds at least +// chainSize bytes of parseable certificates, so its Certificate record can +// hide the REALITY temporary certificate (or fill whole TLS records). +func realityTestBigTarget(t *testing.T, chainSize int) *realityTestTarget { + config := realityTestTargetConfig(nil, false) + config.NameToCertificate = nil + config.CurvePreferences = nil // defaults, X25519MLKEM768 first + chain := [][]byte{testRSACertificate} + for size := len(testRSACertificate); size < chainSize; size += len(testRSACertificate) { + chain = append(chain, testRSACertificate) + } + config.Certificates = []Certificate{{Certificate: chain, PrivateKey: testRSAPrivateKey}} + return newRealityTestTarget(t, config, nil, false) +} + +// realityTestDialShares performs a REALITY client handshake offering the given +// key share groups and returns the connection and the auth key. +func realityTestDialShares(t *testing.T, addr string, pub *ecdh.PublicKey, groups []CurveID) (uconn *UConn, authKey []byte) { + t.Helper() + raw, err := net.Dial("tcp", addr) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { raw.Close() }) + uconn = UClient(raw, &Config{ + ServerName: realityTestServerName, + InsecureSkipVerify: true, + SessionTicketsDisabled: true, + }, HelloCustom) + spec := realityProbeClientHelloSpec(realityPostHandshakeKey{serverName: realityTestServerName, cipherSuite: TLS_AES_128_GCM_SHA256}) + shares := make([]KeyShare, 0, len(groups)) + for _, g := range groups { + shares = append(shares, KeyShare{Group: g}) + } + for _, ext := range spec.Extensions { + switch e := ext.(type) { + case *KeyShareExtension: + e.KeyShares = shares + case *SupportedCurvesExtension: + e.Curves = groups + } + } + if err := uconn.ApplyPreset(spec); err != nil { + t.Fatal(err) + } + if err := uconn.BuildHandshakeState(); err != nil { + t.Fatal(err) + } + + hello := uconn.HandshakeState.Hello + for i := range hello.Raw[39 : 39+32] { + hello.Raw[39+i] = 0 + } + binary.BigEndian.PutUint64(hello.SessionId, uint64(time.Now().Unix())) + copy(hello.SessionId[8:], realityTestShortID[:]) + hello.SessionId[0], hello.SessionId[1], hello.SessionId[2] = 1, 8, 2 + keys := uconn.HandshakeState.State13.KeyShareKeys + ecdhe := keys.Ecdhe + if ecdhe == nil { + ecdhe = keys.MlkemEcdhe + } + authKey, err = ecdhe.ECDH(pub) + if err != nil { + t.Fatal(err) + } + if _, err := hkdf.New(sha256.New, authKey, hello.Random[:20], []byte("REALITY")).Read(authKey); err != nil { + t.Fatal(err) + } + block, _ := aes.NewCipher(authKey) + aead, _ := cipher.NewGCM(block) + aead.Seal(hello.SessionId[:0], hello.Random[20:], hello.SessionId[:16], hello.Raw) + copy(hello.Raw[39:], hello.SessionId) + + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + if err := uconn.HandshakeContext(ctx); err != nil { + t.Fatalf("handshake %v: %v", groups, err) + } + return uconn, authKey +} + +// realityTestIsReality is the certificate check of Xray's REALITY client +// (transport/internet/reality.UConn.VerifyPeerCertificate) without +// mldsa65Verify: it reports whether the peer is the REALITY server. +func realityTestIsReality(t *testing.T, uconn *UConn, authKey []byte) bool { + t.Helper() + certs := uconn.ConnectionState().PeerCertificates + pub, ok := certs[0].PublicKey.(ed25519.PublicKey) + if !ok { + return false + } + h := hmac.New(sha512.New, authKey) + h.Write(pub) + return bytes.Equal(h.Sum(nil), certs[0].Signature) +} + +func realityTestReadMarker(t *testing.T, uconn *UConn) { + t.Helper() + uconn.SetReadDeadline(time.Now().Add(10 * time.Second)) + got := make([]byte, len(realityTestMarker)) + if _, err := io.ReadFull(uconn, got); err != nil { + t.Fatalf("reading marker: %v", err) + } + if !bytes.Equal(got, realityTestMarker) { + t.Fatalf("marker = %q", got) + } +} + +// A target whose Certificate message fills a whole TLS 1.3 record (16384 +// bytes of plaintext, 16406 bytes on the wire) must still be mirrored; with a +// 16 KiB buffer the REALITY server rejected it as too long (XTLS/REALITY#33). +func TestRealityFullSizeTargetRecord(t *testing.T) { + tt := realityTestBigTarget(t, 17000) + + direct, _, _ := realityTestDial(t, tt.addr(), nil, nil, realityTestSuites) + direct.Close() + + realityConfig, pub := newRealityTestConfig(t, tt.addr()) + addr := newRealityTestServer(t, realityConfig) + uconn, authKey := realityTestDialShares(t, addr, pub, []CurveID{X25519}) + if !realityTestIsReality(t, uconn, authKey) { + t.Fatal("REALITY certificate not recognised") + } + realityTestReadMarker(t, uconn) +} From a21435a26b6758670b8006ec604d2793b13fa18b Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Sun, 11 Oct 2026 20:58:43 +0300 Subject: [PATCH 03/27] feat(reality): sign the temporary certificate with ML-DSA-65 Add RealityConfig.Mldsa65Seed, the 32-byte seed of Xray's "mldsa65Seed". When set, the server uses a temporary certificate whose first extension (OID 0.0) carries an ML-DSA-65 signature, as XTLS/REALITY does: the HMAC over the ed25519 public key keyed with the auth key is continued over the raw ClientHello and the raw ServerHello, and its digest is signed deterministically with an empty context. Xray clients configured with "mldsa65Verify" require this signature. Keys come from github.com/metacubex/mldsa (crypto/mldsa backported to Go 1.20). Test vectors generated with cloudflare/circl, which Xray uses, prove that seeds expand to the same public keys and produce the same signatures. RealityMldsa65Verify returns the "mldsa65Verify" value for a seed. (cherry picked from commit ebc62b0bb07eae43cd940d8e30737adabdae50f2) --- go.mod | 4 +- go.sum | 2 + reality.go | 32 +++++++ reality_mldsa65.go | 84 ++++++++++++++++++ reality_mldsa65_test.go | 183 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 304 insertions(+), 1 deletion(-) create mode 100644 reality_mldsa65.go create mode 100644 reality_mldsa65_test.go diff --git a/go.mod b/go.mod index e5fb205284..b1c5501c12 100644 --- a/go.mod +++ b/go.mod @@ -10,7 +10,9 @@ retract ( require ( github.com/andybalholm/brotli v1.0.6 github.com/klauspost/compress v1.17.9 // lastest version compatible with golang1.20 + github.com/metacubex/mldsa v0.1.1 // backport of crypto/mldsa for golang1.20 golang.org/x/crypto v0.33.0 // lastest version compatible with golang1.20 golang.org/x/exp v0.0.0-20240904232852-e7e105dedf7e // lastest version compatible with golang1.20 - golang.org/x/sys v0.30.0 // indirect ) + +require golang.org/x/sys v0.30.0 // indirect diff --git a/go.sum b/go.sum index 0fbc1b1129..cfee793cb6 100644 --- a/go.sum +++ b/go.sum @@ -2,6 +2,8 @@ github.com/andybalholm/brotli v1.0.6 h1:Yf9fFpf49Zrxb9NlQaluyE92/+X7UVHlhMNJN2sx github.com/andybalholm/brotli v1.0.6/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig= github.com/klauspost/compress v1.17.9 h1:6KIumPrER1LHsvBVuDa0r5xaG0Es51mhhB9BQB2qeMA= github.com/klauspost/compress v1.17.9/go.mod h1:Di0epgTjJY877eYKx5yC51cX2A2Vl2ibi7bDH9ttBbw= +github.com/metacubex/mldsa v0.1.1 h1:Tl9+FeM+AUqL5lG3C8JuoxVGsIINuY0b7XsQgz8jwyU= +github.com/metacubex/mldsa v0.1.1/go.mod h1:RY6NOdBYmQ17ZRAn5TgXtJCTmuaI3oYdU+XicSGO8Lg= golang.org/x/crypto v0.33.0 h1:IOBPskki6Lysi0lo9qQvbxiQ+FvsCC/YWOecCHAixus= golang.org/x/crypto v0.33.0/go.mod h1:bVdXmD7IV/4GdElGPozy6U7lWdRXA4qyRVGJV57uQ5M= golang.org/x/exp v0.0.0-20240904232852-e7e105dedf7e h1:I88y4caeGeuDQxgdoFPUq097j7kNfw6uvuiNxUBfcBk= diff --git a/reality.go b/reality.go index f998a37477..cf7c501c53 100644 --- a/reality.go +++ b/reality.go @@ -23,6 +23,7 @@ import ( "sync/atomic" "time" + "github.com/metacubex/mldsa" "github.com/metacubex/utls/internal/ratelimit" "github.com/metacubex/utls/mlkem" @@ -117,12 +118,22 @@ type RealityConfig struct { LimitFallbackUpload RealityLimitFallback LimitFallbackDownload RealityLimitFallback + // Mldsa65Seed is the 32-byte ML-DSA-65 private key seed, the + // base64url-decoded value of Xray's "mldsa65Seed". When set, the temporary + // certificate carries an ML-DSA-65 signature in its first extension, which + // Xray clients configured with "mldsa65Verify" require. The matching + // "mldsa65Verify" value is returned by RealityMldsa65Verify. + Mldsa65Seed []byte + Config // postHandshake caches the target's learned post-handshake record // pattern. It is created lazily and shared with clones so that clones do // not probe the target again. postHandshake atomic.Pointer[realityPostHandshakeCache] + + // mldsa65 caches the private key expanded from Mldsa65Seed. + mldsa65 atomic.Pointer[realityMldsa65Key] } func (a *RealityConfig) Clone() *RealityConfig { @@ -140,6 +151,7 @@ func (a *RealityConfig) Clone() *RealityConfig { ShortIds: a.ShortIds, LimitFallbackUpload: a.LimitFallbackUpload, LimitFallbackDownload: a.LimitFallbackDownload, + Mldsa65Seed: a.Mldsa65Seed, Config: *a.Config.Clone(), } c.postHandshake.Store(a.postHandshakeCache()) @@ -286,12 +298,32 @@ func (hs *realityServerHandshakeStateTLS13) handshake() error { */ { ed25519Priv, signedCert := realityServerCert() + mldsa65Key, err := config.mldsa65Key() + if err != nil { + return err + } + mldsa65Offset := 0 + if mldsa65Key != nil { + signedCert, mldsa65Offset = realityServerCertMldsa65() + } signedCert = append([]byte{}, signedCert...) h := hmac.New(sha512.New, hs.AuthKey) h.Write(ed25519Priv[32:]) h.Sum(signedCert[:len(signedCert)-64]) + if mldsa65Key != nil { + // Same construction as XTLS/REALITY: the HMAC keeps running over + // the raw ClientHello and the raw ServerHello as sent to the client. + h.Write(hs.clientHello.original) + h.Write(hs.hello.original) + sig, err := mldsa65Key.SignDeterministic(h.Sum(nil), nil) + if err != nil { + return err + } + copy(signedCert[mldsa65Offset:mldsa65Offset+mldsa.MLDSA65SignatureSize], sig) + } + hs.cert = &Certificate{ Certificate: [][]byte{signedCert}, PrivateKey: ed25519Priv, diff --git a/reality_mldsa65.go b/reality_mldsa65.go new file mode 100644 index 0000000000..2137850bdc --- /dev/null +++ b/reality_mldsa65.go @@ -0,0 +1,84 @@ +package tls + +// REALITY server: optional ML-DSA-65 signature of the temporary certificate +// (Xray "mldsa65Seed" / "mldsa65Verify", XTLS/REALITY@4eaf792). + +import ( + "bytes" + "crypto/ed25519" + "crypto/rand" + "crypto/x509" + "crypto/x509/pkix" + "errors" + "math/big" + + "github.com/metacubex/mldsa" +) + +// RealityMldsa65SeedSize is the size of RealityConfig.Mldsa65Seed. +const RealityMldsa65SeedSize = mldsa.PrivateKeySize + +type realityMldsa65Key struct { + seed []byte + key *mldsa.PrivateKey +} + +func newRealityMldsa65Key(seed []byte) (*mldsa.PrivateKey, error) { + if len(seed) != RealityMldsa65SeedSize { + return nil, errors.New("REALITY: ML-DSA-65 seed must be 32 bytes") + } + return mldsa.NewPrivateKey(mldsa.MLDSA65(), seed) +} + +// mldsa65Key returns the ML-DSA-65 private key for Mldsa65Seed, or nil when no +// seed is configured. The expanded key is cached. +func (a *RealityConfig) mldsa65Key() (*mldsa.PrivateKey, error) { + if len(a.Mldsa65Seed) == 0 { + return nil, nil + } + if k := a.mldsa65.Load(); k != nil && bytes.Equal(k.seed, a.Mldsa65Seed) { + return k.key, nil + } + key, err := newRealityMldsa65Key(a.Mldsa65Seed) + if err != nil { + return nil, err + } + a.mldsa65.Store(&realityMldsa65Key{seed: append([]byte(nil), a.Mldsa65Seed...), key: key}) + return key, nil +} + +// RealityMldsa65Verify returns the ML-DSA-65 public key for seed, the value +// REALITY clients take as "mldsa65Verify". The key is identical to the one +// Xray derives with circl's mldsa65.NewKeyFromSeed. +func RealityMldsa65Verify(seed []byte) ([]byte, error) { + key, err := newRealityMldsa65Key(seed) + if err != nil { + return nil, err + } + return key.PublicKey().Bytes(), nil +} + +// realityServerCertMldsa65 is the temporary certificate with room for an +// ML-DSA-65 signature: its first extension (OID 0.0) holds a zeroed value of +// the signature size, which is overwritten per connection. offset is the +// position of that value in the DER encoding. +var realityServerCertMldsa65 = onceValues(func() (signedCert []byte, offset int) { + ed25519Priv, _ := realityServerCert() + placeholder := make([]byte, mldsa.MLDSA65SignatureSize) + certificate := x509.Certificate{ + SerialNumber: &big.Int{}, + ExtraExtensions: []pkix.Extension{{Id: []int{0, 0}, Value: placeholder}}, + } + signedCert, err := x509.CreateCertificate(rand.Reader, &certificate, &certificate, ed25519.PublicKey(ed25519Priv[32:]), ed25519Priv) + if err != nil { + panic("REALITY: ML-DSA-65 certificate: " + err.Error()) + } + // The value is an OCTET STRING of MLDSA65SignatureSize (0x0ced) bytes. + size := len(placeholder) + header := []byte{0x04, 0x82, byte(size >> 8), byte(size)} + offset = bytes.Index(signedCert, append(header, placeholder...)) + if offset < 0 { + panic("REALITY: ML-DSA-65 certificate: extension not found") + } + return signedCert, offset + len(header) +}) diff --git a/reality_mldsa65_test.go b/reality_mldsa65_test.go new file mode 100644 index 0000000000..a76861c50b --- /dev/null +++ b/reality_mldsa65_test.go @@ -0,0 +1,183 @@ +package tls + +import ( + "bytes" + "crypto/ed25519" + "crypto/hmac" + "crypto/sha256" + "crypto/sha512" + "crypto/x509" + "encoding/base64" + "encoding/hex" + "testing" + + "github.com/metacubex/mldsa" +) + +// Vectors generated with github.com/cloudflare/circl v1.6.5, the library Xray +// uses: mldsa65.NewKeyFromSeed(seed) for the key pair, and +// mldsa65.SignTo(key, msg, nil, false, sig) (Xray's REALITY server call) for +// the signature of realityMldsa65TestMessage. Values are SHA-256 digests of +// the public key encoding and of the signature. +var realityMldsa65TestVectors = []struct { + seed, pub, sig string +}{ + { + seed: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", + pub: "085ba380ff386dd52e42349c6eb88489d6058ea541a4e3fb0dce9a3fd1f7a911", + sig: "4d77d702f9fb2f7ef7820cbf2337babd60fd818edac29381bdf22d7f3250c687", + }, + { + seed: "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8", + pub: "d666806e11cee19a7c989f7445f90dd419cf4d2d51db8c0fdb4c0f0a542238c9", + sig: "6dba3e963b1daa5ce881cb01246b543fe97eb209a4d8642b8e07b76a271b7841", + }, + { + seed: "__jx6uPc1c7HwLmyq6Sdlo-IgXpzbGVeV1BJQjs0LSY", + pub: "974764eec574cb14359ba6f2fee2439f5845d440a3c0c8f8d3e6eb7daac864c2", + sig: "ca37ee7ae41836483883c777f91752d19a7c55c493ccc78e65eaf1da76c4919e", + }, +} + +var realityMldsa65TestMessage = []byte("REALITY ML-DSA-65 test message") + +func TestRealityMldsa65MatchesCircl(t *testing.T) { + for _, v := range realityMldsa65TestVectors { + seed, err := base64.RawURLEncoding.DecodeString(v.seed) + if err != nil { + t.Fatal(err) + } + verify, err := RealityMldsa65Verify(seed) + if err != nil { + t.Fatal(err) + } + if len(verify) != mldsa.MLDSA65PublicKeySize { + t.Fatalf("public key size %d", len(verify)) + } + if got := sha256.Sum256(verify); hex.EncodeToString(got[:]) != v.pub { + t.Errorf("seed %s: public key digest %x, want %s", v.seed, got, v.pub) + } + + config := &RealityConfig{Mldsa65Seed: seed} + key, err := config.mldsa65Key() + if err != nil { + t.Fatal(err) + } + sig, err := key.SignDeterministic(realityMldsa65TestMessage, nil) + if err != nil { + t.Fatal(err) + } + if got := sha256.Sum256(sig); hex.EncodeToString(got[:]) != v.sig { + t.Errorf("seed %s: signature digest %x, want %s", v.seed, got, v.sig) + } + if again, _ := config.mldsa65Key(); again != key { + t.Error("expanded key is not cached") + } + } +} + +func TestRealityMldsa65BadSeed(t *testing.T) { + if _, err := RealityMldsa65Verify(make([]byte, 31)); err == nil { + t.Fatal("31-byte seed accepted") + } + config := &RealityConfig{Mldsa65Seed: make([]byte, 64)} + if _, err := config.mldsa65Key(); err == nil { + t.Fatal("64-byte seed accepted") + } + if key, err := (&RealityConfig{}).mldsa65Key(); key != nil || err != nil { + t.Fatalf("no seed: key=%v err=%v", key, err) + } +} + +func TestRealityServerCertMldsa65Layout(t *testing.T) { + signedCert, offset := realityServerCertMldsa65() + if offset != 126 { // the fixed location used by XTLS/REALITY + t.Errorf("signature offset %d, want 126", offset) + } + cert := append([]byte(nil), signedCert...) + marker := bytes.Repeat([]byte{0xa5}, mldsa.MLDSA65SignatureSize) + copy(cert[offset:], marker) + parsed, err := x509.ParseCertificate(cert) + if err != nil { + t.Fatal(err) + } + if len(parsed.Extensions) == 0 || !parsed.Extensions[0].Id.Equal([]int{0, 0}) || !bytes.Equal(parsed.Extensions[0].Value, marker) { + t.Fatalf("Extensions[0] does not hold the signature slot: %+v", parsed.Extensions) + } + ed25519Priv, plain := realityServerCert() + if !ed25519Priv.Public().(ed25519.PublicKey).Equal(parsed.PublicKey) { + t.Fatal("certificates use different keys") + } + if len(plain) >= len(signedCert) { + t.Fatal("plain certificate is not smaller") + } +} + +// realityTestVerifyMldsa65 is the certificate check of Xray's REALITY client +// (transport/internet/reality.UConn.VerifyPeerCertificate) with +// mldsa65Verify set. +func realityTestVerifyMldsa65(t *testing.T, uconn *UConn, authKey, mldsa65Verify []byte) bool { + t.Helper() + if !realityTestIsReality(t, uconn, authKey) { + return false + } + certs := uconn.ConnectionState().PeerCertificates + if len(certs[0].Extensions) == 0 { + return false + } + h := hmac.New(sha512.New, authKey) + h.Write(certs[0].PublicKey.(ed25519.PublicKey)) + h.Write(uconn.HandshakeState.Hello.Raw) + h.Write(uconn.HandshakeState.ServerHello.Raw) + verify, err := mldsa.NewPublicKey(mldsa.MLDSA65(), mldsa65Verify) + if err != nil { + t.Fatal(err) + } + return mldsa.Verify(verify, h.Sum(nil), certs[0].Extensions[0].Value, nil) == nil +} + +func TestRealityMldsa65Handshake(t *testing.T) { + tt := realityTestBigTarget(t, 6000) + config, pub := newRealityTestConfig(t, tt.addr()) + seed, _ := base64.RawURLEncoding.DecodeString(realityMldsa65TestVectors[2].seed) + config.Mldsa65Seed = seed + verify, err := RealityMldsa65Verify(seed) + if err != nil { + t.Fatal(err) + } + otherVerify, _ := RealityMldsa65Verify(make([]byte, 32)) + addr := newRealityTestServer(t, config) + + // (A ClientHello with only X25519MLKEM768 is covered by + // TestRealityClientPeerPub: the uTLS client requires an X25519 key share.) + for _, groups := range [][]CurveID{{X25519}, {X25519MLKEM768, X25519}} { + uconn, authKey := realityTestDialShares(t, addr, pub, groups) + if !realityTestIsReality(t, uconn, authKey) { + t.Fatalf("%v: REALITY certificate not recognised", groups) + } + if !realityTestVerifyMldsa65(t, uconn, authKey, verify) { + t.Fatalf("%v: ML-DSA-65 signature rejected", groups) + } + if realityTestVerifyMldsa65(t, uconn, authKey, otherVerify) { + t.Fatalf("%v: ML-DSA-65 signature accepted for a different key", groups) + } + realityTestReadMarker(t, uconn) + uconn.Close() + } +} + +func TestRealityWithoutMldsa65(t *testing.T) { + tt := realityTestBigTarget(t, 6000) + config, pub := newRealityTestConfig(t, tt.addr()) + addr := newRealityTestServer(t, config) + verify, _ := RealityMldsa65Verify(make([]byte, 32)) + + uconn, authKey := realityTestDialShares(t, addr, pub, []CurveID{X25519}) + if !realityTestIsReality(t, uconn, authKey) { + t.Fatal("REALITY certificate not recognised") + } + if realityTestVerifyMldsa65(t, uconn, authKey, verify) { + t.Fatal("client requiring ML-DSA-65 accepted a server without it") + } + realityTestReadMarker(t, uconn) +} From e8458422de47fc8b8e431dd3d50a513f58cdc6ee Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Sun, 11 Oct 2026 20:59:24 +0300 Subject: [PATCH 04/27] feat(reality): optionally require an X25519MLKEM768 key share Add RealityConfig.RequireX25519MLKEM768 (default off). When set, a ClientHello is only considered for REALITY authentication if it carries exactly one X25519MLKEM768 key share placed before an optional X25519 key share; anything else is forwarded to the target. This mirrors Xray's rule from XTLS/REALITY@8cdf7bf, which rejects outdated or unusual ClientHellos. The key share selection moves to realityClientPeerPub; without the flag it behaves as before (X25519, else the X25519 part of X25519MLKEM768). (cherry picked from commit 37238a179ceca11e87a411dd8a7183b3715eb4a6) --- reality.go | 24 +++++++-------- reality_keyshare.go | 40 +++++++++++++++++++++++++ reality_keyshare_test.go | 64 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 114 insertions(+), 14 deletions(-) create mode 100644 reality_keyshare.go create mode 100644 reality_keyshare_test.go diff --git a/reality.go b/reality.go index cf7c501c53..4dba4dad49 100644 --- a/reality.go +++ b/reality.go @@ -125,6 +125,12 @@ type RealityConfig struct { // "mldsa65Verify" value is returned by RealityMldsa65Verify. Mldsa65Seed []byte + // RequireX25519MLKEM768 makes the server treat a ClientHello as + // unauthenticated (and forward it to the target) unless it carries exactly + // one X25519MLKEM768 key share placed before an optional X25519 key share, + // as Xray does since XTLS/REALITY@8cdf7bf. Off by default for older clients. + RequireX25519MLKEM768 bool + Config // postHandshake caches the target's learned post-handshake record @@ -152,6 +158,7 @@ func (a *RealityConfig) Clone() *RealityConfig { LimitFallbackUpload: a.LimitFallbackUpload, LimitFallbackDownload: a.LimitFallbackDownload, Mldsa65Seed: a.Mldsa65Seed, + RequireX25519MLKEM768: a.RequireX25519MLKEM768, Config: *a.Config.Clone(), } c.postHandshake.Store(a.postHandshakeCache()) @@ -434,20 +441,9 @@ func RealityServer(ctx context.Context, conn net.Conn, config *RealityConfig) (* if copying || err != nil || hs.c.vers != VersionTLS13 || !config.ServerNames[hs.clientHello.serverName] { break } - var peerPub []byte - for _, keyShare := range hs.clientHello.keyShares { - if keyShare.group == X25519 && len(keyShare.data) == 32 { - peerPub = keyShare.data - break - } - } - if peerPub == nil { - for _, keyShare := range hs.clientHello.keyShares { - if keyShare.group == X25519MLKEM768 && len(keyShare.data) == mlkem.EncapsulationKeySize768+32 { - peerPub = keyShare.data[mlkem.EncapsulationKeySize768:] - break - } - } + peerPub := realityClientPeerPub(hs.clientHello.keyShares, config.RequireX25519MLKEM768) + if peerPub == nil && config.Log != nil { + config.Log("REALITY remoteAddr: %v no acceptable key share", remoteAddr) } for peerPub != nil { if hs.AuthKey, err = curve25519.X25519(config.PrivateKey, peerPub); err != nil { diff --git a/reality_keyshare.go b/reality_keyshare.go new file mode 100644 index 0000000000..8e897d0859 --- /dev/null +++ b/reality_keyshare.go @@ -0,0 +1,40 @@ +package tls + +// REALITY server: choice of the client key share that authenticates a +// REALITY ClientHello, optionally requiring X25519MLKEM768 like Xray +// (XTLS/REALITY@8cdf7bf). + +import "github.com/metacubex/utls/internal/mlkem" + +// realityClientPeerPub picks the X25519 public key used to derive the REALITY +// auth key: the X25519 key share, else the X25519 part of X25519MLKEM768. +// +// With requireMLKEM it mirrors Xray (XTLS/REALITY@8cdf7bf) and returns nil, +// rejecting the ClientHello, unless exactly one X25519MLKEM768 key share comes +// before an optional X25519 key share. +func realityClientPeerPub(keyShares []keyShare, requireMLKEM bool) []byte { + var x25519, hybrid []byte + for _, ks := range keyShares { + if ks.group == X25519MLKEM768 && len(ks.data) == mlkem.EncapsulationKeySize768+32 { + if hybrid != nil { + if requireMLKEM { + return nil + } + continue + } + hybrid = ks.data[mlkem.EncapsulationKeySize768:] + continue + } + if ks.group == X25519 && len(ks.data) == 32 { + x25519 = ks.data + break + } + } + if requireMLKEM && hybrid == nil { + return nil + } + if x25519 != nil { + return x25519 + } + return hybrid +} diff --git a/reality_keyshare_test.go b/reality_keyshare_test.go new file mode 100644 index 0000000000..aa032b17f2 --- /dev/null +++ b/reality_keyshare_test.go @@ -0,0 +1,64 @@ +package tls + +import ( + "bytes" + "testing" + + "github.com/metacubex/utls/internal/mlkem" +) + +func TestRealityClientPeerPub(t *testing.T) { + x := keyShare{group: X25519, data: bytes.Repeat([]byte{1}, 32)} + h := keyShare{group: X25519MLKEM768, data: append(make([]byte, mlkem.EncapsulationKeySize768), bytes.Repeat([]byte{2}, 32)...)} + h2 := keyShare{group: X25519MLKEM768, data: append(make([]byte, mlkem.EncapsulationKeySize768), bytes.Repeat([]byte{3}, 32)...)} + p := keyShare{group: CurveP256, data: make([]byte, 65)} + bad := keyShare{group: X25519MLKEM768, data: make([]byte, 32)} + hx := h.data[mlkem.EncapsulationKeySize768:] + for _, tc := range []struct { + name string + shares []keyShare + lenient []byte + strict []byte + }{ + {"none", nil, nil, nil}, + {"x25519 only", []keyShare{x}, x.data, nil}, + {"mlkem only", []keyShare{h}, hx, hx}, + {"mlkem then x25519", []keyShare{h, x}, x.data, x.data}, + {"x25519 then mlkem", []keyShare{x, h}, x.data, nil}, + {"p256 mlkem x25519", []keyShare{p, h, x}, x.data, x.data}, + {"duplicate mlkem", []keyShare{h, h2, x}, x.data, nil}, + {"malformed mlkem", []keyShare{bad, x}, x.data, nil}, + } { + if got := realityClientPeerPub(tc.shares, false); !bytes.Equal(got, tc.lenient) { + t.Errorf("%s lenient: got %x, want %x", tc.name, got, tc.lenient) + } + if got := realityClientPeerPub(tc.shares, true); !bytes.Equal(got, tc.strict) { + t.Errorf("%s strict: got %x, want %x", tc.name, got, tc.strict) + } + } +} + +func TestRealityRequireX25519MLKEM768(t *testing.T) { + tt := realityTestBigTarget(t, 6000) + config, pub := newRealityTestConfig(t, tt.addr()) + config.RequireX25519MLKEM768 = true + addr := newRealityTestServer(t, config) + + for _, tc := range []struct { + groups []CurveID + accept bool + }{ + {[]CurveID{X25519MLKEM768, X25519}, true}, + {[]CurveID{X25519}, false}, + {[]CurveID{X25519, X25519MLKEM768}, false}, + } { + uconn, authKey := realityTestDialShares(t, addr, pub, tc.groups) + if got := realityTestIsReality(t, uconn, authKey); got != tc.accept { + t.Fatalf("%v: accepted=%v, want %v", tc.groups, got, tc.accept) + } + if tc.accept { + realityTestReadMarker(t, uconn) + } + uconn.Close() + } +} From 66302000002de48a586c801cc7d53263d94c3e41 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Sun, 11 Oct 2026 21:00:51 +0300 Subject: [PATCH 05/27] test(reality): browser fingerprints pass the X25519MLKEM768 requirement (cherry picked from commit 5ad21de4b48fa3198d0a124b200de07c2d0eef21) --- reality_keyshare_test.go | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/reality_keyshare_test.go b/reality_keyshare_test.go index aa032b17f2..efef8f6515 100644 --- a/reality_keyshare_test.go +++ b/reality_keyshare_test.go @@ -2,6 +2,7 @@ package tls import ( "bytes" + "net" "testing" "github.com/metacubex/utls/internal/mlkem" @@ -62,3 +63,21 @@ func TestRealityRequireX25519MLKEM768(t *testing.T) { uconn.Close() } } + +// Browser fingerprints with post-quantum key shares must pass the strict +// check, so REALITY clients using them work with RequireX25519MLKEM768. +func TestRealityClientPeerPubParrots(t *testing.T) { + for _, id := range []ClientHelloID{HelloChrome_Auto, HelloFirefox_Auto, HelloSafari_Auto, HelloFirefox_148, HelloSafari_26_3} { + uconn := UClient(&net.TCPConn{}, &Config{ServerName: realityTestServerName}, id) + if err := uconn.BuildHandshakeState(); err != nil { + t.Fatalf("%v: %v", id, err) + } + hello := new(clientHelloMsg) + if !hello.unmarshal(uconn.HandshakeState.Hello.Raw) { + t.Fatalf("%v: cannot parse ClientHello", id) + } + if realityClientPeerPub(hello.keyShares, true) == nil { + t.Errorf("%v: rejected with RequireX25519MLKEM768", id) + } + } +} From 974cea2a2d15c10cdf4b6c4847809f9a05665cd6 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Tue, 13 Oct 2026 17:57:34 +0300 Subject: [PATCH 06/27] fix(ech): return the outer ClientHello build error UConn.MarshalClientHello ignored the error from computeAndUpdateOuterECHExtension. With ECH configured and a ClientHelloSpec that cannot carry ECH (e.g. no ECH extension), the handshake went on and wrote a ClientHello without a sealed inner hello. Return the error so nothing is sent. (cherry picked from commit 3a71ed005d3b65f337bf97d2ae2c1f43d936c94e) --- u_conn.go | 6 ++- u_ech_build_test.go | 97 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 102 insertions(+), 1 deletion(-) create mode 100644 u_ech_build_test.go diff --git a/u_conn.go b/u_conn.go index 08c044d6b2..55334dc55b 100644 --- a/u_conn.go +++ b/u_conn.go @@ -572,7 +572,11 @@ func (uconn *UConn) MarshalClientHello() error { ech.innerHello = inner - uconn.computeAndUpdateOuterECHExtension(inner, ech, true) + // The outer ClientHello must not go out if it could not be built: + // without a sealed ECH extension it would not protect the inner one. + if err := uconn.computeAndUpdateOuterECHExtension(inner, ech, true); err != nil { + return err + } uconn.echCtx = ech return nil diff --git a/u_ech_build_test.go b/u_ech_build_test.go new file mode 100644 index 0000000000..62011aaf22 --- /dev/null +++ b/u_ech_build_test.go @@ -0,0 +1,97 @@ +package tls + +import ( + "bytes" + "crypto/ecdh" + "crypto/rand" + "io" + "net" + "testing" + "time" + + "github.com/metacubex/utls/internal/hpke" + "golang.org/x/crypto/cryptobyte" +) + +// testECHConfigList returns an ECHConfigList with a single X25519 config. +func testECHConfigList(t *testing.T, publicName string) []byte { + t.Helper() + echKey, err := ecdh.X25519().GenerateKey(rand.Reader) + if err != nil { + t.Fatal(err) + } + builder := cryptobyte.NewBuilder(nil) + builder.AddUint16LengthPrefixed(func(builder *cryptobyte.Builder) { + builder.AddUint16(extensionEncryptedClientHello) + builder.AddUint16LengthPrefixed(func(builder *cryptobyte.Builder) { + builder.AddUint8(1) + builder.AddUint16(hpke.DHKEM_X25519_HKDF_SHA256) + builder.AddUint16LengthPrefixed(func(builder *cryptobyte.Builder) { + builder.AddBytes(echKey.PublicKey().Bytes()) + }) + builder.AddUint16LengthPrefixed(func(builder *cryptobyte.Builder) { + for _, aeadID := range sortedSupportedAEADs { + builder.AddUint16(hpke.KDF_HKDF_SHA256) + builder.AddUint16(aeadID) + } + }) + builder.AddUint8(32) + builder.AddUint8LengthPrefixed(func(builder *cryptobyte.Builder) { + builder.AddBytes([]byte(publicName)) + }) + builder.AddUint16(0) + }) + }) + return builder.BytesOrPanic() +} + +// A ClientHelloSpec that cannot carry ECH (no ECH extension) must fail the +// handshake on the client before anything is written, instead of silently +// sending an outer ClientHello without a sealed inner one. +func TestUConnECHSpecBuildErrorIsReturned(t *testing.T) { + const secretName = "secret.example" + + config := &Config{ + ServerName: secretName, + MinVersion: VersionTLS13, + EncryptedClientHelloConfigList: testECHConfigList(t, "public.example"), + } + spec := &ClientHelloSpec{ + CipherSuites: []uint16{TLS_AES_128_GCM_SHA256}, + CompressionMethods: []byte{compressionNone}, + Extensions: []TLSExtension{ + &SNIExtension{}, + &SupportedCurvesExtension{[]CurveID{X25519}}, + &SignatureAlgorithmsExtension{SupportedSignatureAlgorithms: []SignatureScheme{ECDSAWithP256AndSHA256}}, + &KeyShareExtension{[]KeyShare{{Group: X25519}}}, + &SupportedVersionsExtension{[]uint16{VersionTLS13}}, + // No EncryptedClientHelloExtension. + }, + } + + c, s := net.Pipe() + defer s.Close() + + received := make(chan []byte, 1) + go func() { + var buf bytes.Buffer + s.SetReadDeadline(time.Now().Add(2 * time.Second)) + io.Copy(&buf, s) + received <- buf.Bytes() + }() + + c.SetDeadline(time.Now().Add(3 * time.Second)) + uconn := UClient(c, config, HelloCustom) + if err := uconn.ApplyPreset(spec); err != nil { + t.Fatalf("ApplyPreset: %v", err) + } + err := uconn.Handshake() + c.Close() + if err == nil { + t.Fatal("handshake succeeded without an ECH extension in the spec") + } + + if wire := <-received; len(wire) != 0 { + t.Fatalf("client wrote %d bytes after a failed ClientHello build", len(wire)) + } +} From 72306d96b52b4d23f5a7ed627d6da4ecd5ae1476 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Tue, 13 Oct 2026 17:58:49 +0300 Subject: [PATCH 07/27] fix(ech): pass the server certificates to EncryptedClientHelloRejectionVerify The callback is documented to verify the ECH provider certificate, but it was called before peerCertificates was set, so ConnectionState.PeerCertificates was always empty (same as upstream Go, golang/go#75242). Set the peer certificates before calling it. (cherry picked from commit d00159da627f1456b54917e77fd16a7cebd3c5f3) --- ech_rejection_verify_test.go | 85 ++++++++++++++++++++++++++++++++++++ handshake_client.go | 3 ++ 2 files changed, 88 insertions(+) create mode 100644 ech_rejection_verify_test.go diff --git a/ech_rejection_verify_test.go b/ech_rejection_verify_test.go new file mode 100644 index 0000000000..425774c96e --- /dev/null +++ b/ech_rejection_verify_test.go @@ -0,0 +1,85 @@ +package tls + +import ( + "crypto/ecdsa" + "crypto/elliptic" + "crypto/rand" + "crypto/x509" + "errors" + "math/big" + "testing" + "time" +) + +// EncryptedClientHelloRejectionVerify verifies the ECH provider certificate, +// so the ConnectionState it gets must carry the server's certificates. +func TestECHRejectionVerifySeesPeerCertificates(t *testing.T) { + k, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + if err != nil { + t.Fatal(err) + } + tmpl := &x509.Certificate{ + SerialNumber: big.NewInt(1), + DNSNames: []string{"public.example"}, + NotBefore: time.Now().Add(-time.Hour), + NotAfter: time.Now().Add(time.Hour), + } + publicCertDER, err := x509.CreateCertificate(rand.Reader, tmpl, tmpl, k.Public(), k) + if err != nil { + t.Fatal(err) + } + + var gotCerts []*x509.Certificate + called := false + + clientConfig := &Config{ + ServerName: "secret.example", + MinVersion: VersionTLS13, + EncryptedClientHelloConfigList: testECHConfigList(t, "public.example"), + EncryptedClientHelloRejectionVerify: func(cs ConnectionState) error { + called = true + gotCerts = cs.PeerCertificates + return nil + }, + } + // The server has no ECH keys, so it rejects ECH and answers as + // public.example. + serverConfig := &Config{ + MinVersion: VersionTLS13, + Certificates: []Certificate{{Certificate: [][]byte{publicCertDER}, PrivateKey: k}}, + } + + c, s := localPipe(t) + done := make(chan error, 1) + go func() { + srv := Server(s, serverConfig) + err := srv.Handshake() + s.Close() + done <- err + }() + + cli := Client(c, clientConfig) + err = cli.Handshake() + c.Close() + <-done + + var echErr *ECHRejectionError + if !errors.As(err, &echErr) { + t.Fatalf("Handshake error = %v; want ECHRejectionError", err) + } + if !called { + t.Fatal("EncryptedClientHelloRejectionVerify was not called") + } + if len(gotCerts) != 1 || !gotCerts[0].Equal(mustParseCert(t, publicCertDER)) { + t.Fatalf("EncryptedClientHelloRejectionVerify got %d peer certificates; want the server's one", len(gotCerts)) + } +} + +func mustParseCert(t *testing.T, der []byte) *x509.Certificate { + t.Helper() + cert, err := x509.ParseCertificate(der) + if err != nil { + t.Fatal(err) + } + return cert +} diff --git a/handshake_client.go b/handshake_client.go index 7806e5d343..5c87a12a8c 100644 --- a/handshake_client.go +++ b/handshake_client.go @@ -1194,6 +1194,9 @@ func (c *Conn) verifyServerCertificate(certificates [][]byte) error { echRejected := c.config.EncryptedClientHelloConfigList != nil && !c.echAccepted if echRejected { if c.config.EncryptedClientHelloRejectionVerify != nil { + // The callback exists to verify the ECH provider (outer) certificate, + // so it must see the certificates the server sent. + c.peerCertificates = certs if err := c.config.EncryptedClientHelloRejectionVerify(c.connectionStateLocked()); err != nil { c.sendAlert(alertBadCertificate) return err From c7889abe3a56fd38c9618bb902d39656710c1861 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Tue, 13 Oct 2026 17:59:41 +0300 Subject: [PATCH 08/27] fix: default the server minimum version to TLS 1.2 MinVersion documents TLS 1.2 as the default minimum, but with the tls10server GODEBUG knob stubbed out the server side kept accepting TLS 1.0 and 1.1 when MinVersion was 0. Apply the default to servers as in crypto/tls; an explicit MinVersion still allows older versions. (cherry picked from commit 9f703115c133e8c99b0d74588d7974b48dd36c68) --- common.go | 10 +++++----- server_min_version_test.go | 30 ++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 5 deletions(-) create mode 100644 server_min_version_test.go diff --git a/common.go b/common.go index 868c725e07..f095ad38c2 100644 --- a/common.go +++ b/common.go @@ -851,8 +851,8 @@ type Config struct { // By default, TLS 1.2 is currently used as the minimum. TLS 1.0 is the // minimum supported by this package. // - // The server-side default can be reverted to TLS 1.0 by including the value - // "tls10server=1" in the GODEBUG environment variable. + // [uTLS] The "tls10server=1" GODEBUG setting is not supported: set + // MinVersion to VersionTLS10 explicitly to accept TLS 1.0 on a server. MinVersion uint16 // MaxVersion contains the maximum TLS version that is acceptable. @@ -1320,9 +1320,9 @@ func (c *Config) supportedVersions(isClient bool) []uint16 { // if isClient || tls10server.Value() != "1" { // continue // } - if isClient { - continue - } + // Without the godebug knob the documented default (TLS 1.2 + // minimum) applies to servers as well as clients. + continue // [uTLS SECTION END] } if isClient && c.EncryptedClientHelloConfigList != nil && v < VersionTLS13 { diff --git a/server_min_version_test.go b/server_min_version_test.go new file mode 100644 index 0000000000..9d394c8a6f --- /dev/null +++ b/server_min_version_test.go @@ -0,0 +1,30 @@ +package tls + +import "testing" + +// A server with MinVersion unset must default to TLS 1.2, like crypto/tls +// without the tls10server GODEBUG. +func TestServerDefaultMinVersion(t *testing.T) { + for _, v := range []uint16{VersionTLS10, VersionTLS11} { + clientConfig := testConfig.Clone() + clientConfig.MinVersion = v + clientConfig.MaxVersion = v + + serverConfig := testConfig.Clone() + serverConfig.MinVersion = 0 + if _, _, err := testHandshake(t, clientConfig, serverConfig); err == nil { + t.Errorf("server with MinVersion 0 accepted %s", VersionName(v)) + } + + serverConfig.MinVersion = v + if _, cs, err := testHandshake(t, clientConfig, serverConfig); err != nil { + t.Errorf("server with MinVersion %s: %v", VersionName(v), err) + } else if cs.Version != v { + t.Errorf("negotiated %s; want %s", VersionName(cs.Version), VersionName(v)) + } + } + + if got := (&Config{}).supportedVersions(roleServer); got[len(got)-1] != VersionTLS12 { + t.Errorf("server default minimum = %s; want TLS 1.2", VersionName(got[len(got)-1])) + } +} From b605f4573de5c75a1ada6908f3eb8ae10d2d87f7 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Tue, 13 Oct 2026 18:01:55 +0300 Subject: [PATCH 09/27] fix: return errors instead of panicking on malformed ClientHello imports ClientHelloSpec.UnmarshalJSON dereferenced nil cipher_suites, compression_methods or extensions when they were missing; it now returns an error, and the ClientHelloSpecJSONUnmarshaler accessors are nil-safe. ImportTLSClientHello sliced key_share in 4-byte steps without checking the length, panicking on truncated input, and read only the low byte of each key_exchange length. Reject input that is not a whole number of entries and use the full 16-bit length. (cherry picked from commit a3a2a550af02fb72dd140080784245435bcd3591) --- u_clienthello_import_test.go | 72 ++++++++++++++++++++++++++++++++++++ u_clienthello_json.go | 9 +++++ u_common.go | 19 ++++++++-- 3 files changed, 97 insertions(+), 3 deletions(-) create mode 100644 u_clienthello_import_test.go diff --git a/u_clienthello_import_test.go b/u_clienthello_import_test.go new file mode 100644 index 0000000000..a1000c43e4 --- /dev/null +++ b/u_clienthello_import_test.go @@ -0,0 +1,72 @@ +package tls + +import "testing" + +func TestClientHelloSpecUnmarshalJSONMissingFields(t *testing.T) { + for _, in := range []string{ + `{}`, + `{"cipher_suites":["TLS_AES_128_GCM_SHA256"]}`, + `{"cipher_suites":["TLS_AES_128_GCM_SHA256"],"compression_methods":["NULL"]}`, + `{"compression_methods":["NULL"],"extensions":[]}`, + } { + var spec ClientHelloSpec + func() { + defer func() { + if r := recover(); r != nil { + t.Errorf("UnmarshalJSON(%s) panicked: %v", in, r) + } + }() + if err := spec.UnmarshalJSON([]byte(in)); err == nil { + t.Errorf("UnmarshalJSON(%s) = nil error; want an error", in) + } + }() + } + + // A zero ClientHelloSpecJSONUnmarshaler must not panic either. + _ = (&ClientHelloSpecJSONUnmarshaler{}).ClientHelloSpec() + + var spec ClientHelloSpec + if err := spec.UnmarshalJSON([]byte(`{"cipher_suites":["TLS_AES_128_GCM_SHA256"],"compression_methods":["NULL"],"extensions":[]}`)); err != nil { + t.Errorf("UnmarshalJSON of a minimal spec: %v", err) + } +} + +func TestImportTLSClientHelloKeyShare(t *testing.T) { + base := func(keyShare []byte) map[string][]byte { + return map[string][]byte{ + "cipher_suites": {0x13, 0x01}, + "compression_methods": {0}, + "extensions": {0, 51}, + "key_share": keyShare, + } + } + + for _, ks := range [][]byte{ + {0x0a}, + {0x0a, 0x0a, 0x00}, + {0x0a, 0x0a, 0x00, 0x01, 0x00, 0x1d}, + } { + func() { + defer func() { + if r := recover(); r != nil { + t.Errorf("ImportTLSClientHello(key_share=%v) panicked: %v", ks, r) + } + }() + var spec ClientHelloSpec + if err := spec.ImportTLSClientHello(base(ks)); err == nil { + t.Errorf("ImportTLSClientHello(key_share=%v) = nil error; want an error", ks) + } + }() + } + + // GREASE (1 byte), X25519 (32 bytes) and X25519MLKEM768 (1216 bytes, a + // length that does not fit in one byte). + var spec ClientHelloSpec + if err := spec.ImportTLSClientHello(base([]byte{0x0a, 0x0a, 0x00, 0x01, 0x00, 0x1d, 0x00, 0x20, 0x11, 0xec, 0x04, 0xc0})); err != nil { + t.Fatalf("ImportTLSClientHello: %v", err) + } + ext, ok := spec.Extensions[0].(*KeyShareExtension) + if !ok || len(ext.KeyShares) != 3 || ext.KeyShares[2].Group != X25519MLKEM768 { + t.Fatalf("unexpected key_share extension: %#v", spec.Extensions[0]) + } +} diff --git a/u_clienthello_json.go b/u_clienthello_json.go index 94cec19509..db5fae2779 100644 --- a/u_clienthello_json.go +++ b/u_clienthello_json.go @@ -56,6 +56,9 @@ func (c *CipherSuitesJSONUnmarshaler) UnmarshalJSON(jsonStr []byte) error { } func (c *CipherSuitesJSONUnmarshaler) CipherSuites() []uint16 { + if c == nil { + return nil + } return c.cipherSuites } @@ -81,6 +84,9 @@ func (c *CompressionMethodsJSONUnmarshaler) UnmarshalJSON(jsonStr []byte) error } func (c *CompressionMethodsJSONUnmarshaler) CompressionMethods() []uint8 { + if c == nil { + return nil + } return c.compressionMethods } @@ -148,6 +154,9 @@ func (e *TLSExtensionsJSONUnmarshaler) UnmarshalJSON(jsonStr []byte) error { } func (e *TLSExtensionsJSONUnmarshaler) Extensions() []TLSExtension { + if e == nil { + return nil + } var exts []TLSExtension = make([]TLSExtension, 0, len(e.extensions)) for _, ext := range e.extensions { exts = append(exts, ext) diff --git a/u_common.go b/u_common.go index 770507c6a1..a4db5df94a 100644 --- a/u_common.go +++ b/u_common.go @@ -395,13 +395,17 @@ func (chs *ClientHelloSpec) ImportTLSClientHello(data map[string][]byte) error { return errors.New("key_share is required") } + // Each entry is group (2 bytes) + key_exchange length (2 bytes). + if len(data["key_share"])%4 != 0 { + return errors.New("key_share must be a list of 4-byte (group, length) entries") + } + // need to add (zero) data per each key share, [10, 10, 0, 1] => [10, 10, 0, 1, 0] fixedData := make([]byte, 0) for i := 0; i < len(data["key_share"]); i += 4 { fixedData = append(fixedData, data["key_share"][i:i+4]...) - for j := 0; j < int(data["key_share"][i+3]); j++ { - fixedData = append(fixedData, 0) - } + dataLen := int(data["key_share"][i+2])<<8 | int(data["key_share"][i+3]) + fixedData = append(fixedData, make([]byte, dataLen)...) } // add uint16 length prefix fixedData = append([]byte{uint8(len(fixedData) >> 8), uint8(len(fixedData) & 0xff)}, fixedData...) @@ -581,6 +585,15 @@ func (chs *ClientHelloSpec) UnmarshalJSON(jsonB []byte) error { return err } + switch { + case chsju.CipherSuites == nil: + return errors.New("tls: ClientHello JSON: cipher_suites is required") + case chsju.CompressionMethods == nil: + return errors.New("tls: ClientHello JSON: compression_methods is required") + case chsju.Extensions == nil: + return errors.New("tls: ClientHello JSON: extensions is required") + } + *chs = chsju.ClientHelloSpec() return nil } From 86e294bb5a01c947aeebe899fc024a0a6e1d072e Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Tue, 13 Oct 2026 18:02:29 +0300 Subject: [PATCH 10/27] fix(roller): close the TCP connection after a failed handshake Roller.Dial moved on to the next ClientHelloID without closing the connection whose handshake had failed, leaking one socket per attempt. (cherry picked from commit 2b28146f4264d00b1ddc0b486745617e63099037) --- u_roller.go | 1 + u_roller_close_test.go | 60 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 u_roller_close_test.go diff --git a/u_roller.go b/u_roller.go index a1c5291423..c8206658cb 100644 --- a/u_roller.go +++ b/u_roller.go @@ -88,6 +88,7 @@ func (c *Roller) Dial(network, addr, serverName string) (*UConn, error) { err = client.Handshake() client.SetDeadline(time.Time{}) // unset timeout if err != nil { + tcpConn.Close() continue // on tls Dial error keep trying HelloIDs } diff --git a/u_roller_close_test.go b/u_roller_close_test.go new file mode 100644 index 0000000000..8e6c10881d --- /dev/null +++ b/u_roller_close_test.go @@ -0,0 +1,60 @@ +package tls + +import ( + "io" + "net" + "testing" + "time" +) + +// Roller.Dial must close the TCP connection of every failed handshake attempt. +func TestRollerDialClosesFailedConns(t *testing.T) { + ln, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + defer ln.Close() + + roller, err := NewRoller() + if err != nil { + t.Fatal(err) + } + roller.HelloIDs = []ClientHelloID{HelloChrome_Auto, HelloFirefox_Auto} + roller.TcpDialTimeout = 5 * time.Second + roller.TlsHandshakeTimeout = 5 * time.Second + + closed := make(chan bool, len(roller.HelloIDs)) + go func() { + for range roller.HelloIDs { + conn, err := ln.Accept() + if err != nil { + return + } + go func(conn net.Conn) { + defer conn.Close() + // Read the ClientHello, then answer with something that is + // not TLS so the handshake fails. + buf := make([]byte, 1<<16) + conn.SetReadDeadline(time.Now().Add(5 * time.Second)) + if _, err := conn.Read(buf); err != nil { + closed <- false + return + } + conn.Write([]byte("HTTP/1.0 400 Bad Request\r\n\r\n")) + // The client must close its side: expect EOF, not a timeout. + conn.SetReadDeadline(time.Now().Add(3 * time.Second)) + _, err := io.Copy(io.Discard, conn) + closed <- err == nil + }(conn) + } + }() + + if _, err := roller.Dial("tcp", ln.Addr().String(), "example.com"); err == nil { + t.Fatal("Dial succeeded against a non-TLS server") + } + for range roller.HelloIDs { + if !<-closed { + t.Fatal("Roller.Dial left a failed connection open") + } + } +} From 4da4d8335d4d4834a3d2c0eedd8a60398c1b3af6 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Tue, 13 Oct 2026 18:03:42 +0300 Subject: [PATCH 11/27] fix: bound compressed certificate decompression decompressCert allocated the peer-declared uncompressed_length (up to 16 MiB) before any check. Reject lengths above maxHandshakeCertificateMsg, the limit already applied to uncompressed Certificate messages. It also used a single Read, which can return less than the full message (zlib returns 32 KiB chunks), failing valid certificates over that size; use io.ReadFull. (cherry picked from commit 22b73c4f89f77629429340c8ba5bc115f71eb1aa) --- u_compress_cert_limit_test.go | 66 +++++++++++++++++++++++++++++++++++ u_handshake_client.go | 11 ++++-- 2 files changed, 75 insertions(+), 2 deletions(-) create mode 100644 u_compress_cert_limit_test.go diff --git a/u_compress_cert_limit_test.go b/u_compress_cert_limit_test.go new file mode 100644 index 0000000000..7aef2e0ec8 --- /dev/null +++ b/u_compress_cert_limit_test.go @@ -0,0 +1,66 @@ +package tls + +import ( + "bytes" + "compress/zlib" + "net" + "strings" + "testing" +) + +type certDiscardConn struct{ net.Conn } + +func (certDiscardConn) Write(b []byte) (int, error) { return len(b), nil } + +func newDecompressTestState() *clientHandshakeStateTLS13 { + c := &Conn{conn: certDiscardConn{}, isClient: true, config: &Config{}} + uconn := &UConn{Conn: c, certCompressionAlgs: []CertCompressionAlgo{CertCompressionZlib}} + return &clientHandshakeStateTLS13{c: c, uconn: uconn} +} + +// A compressed certificate whose declared uncompressed length is above the +// limit for certificate messages must be rejected before allocating it. +func TestDecompressCertLengthLimit(t *testing.T) { + var compressed bytes.Buffer + w := zlib.NewWriter(&compressed) + w.Write([]byte{0}) + w.Close() + + hs := newDecompressTestState() + _, err := hs.decompressCert(utlsCompressedCertificateMsg{ + algorithm: uint16(CertCompressionZlib), + uncompressedLength: 1<<24 - 1, + compressedCertificateMessage: compressed.Bytes(), + }) + if err == nil || !strings.Contains(err.Error(), "exceeds maximum") { + t.Fatalf("decompressCert error = %v; want a length limit error", err) + } +} + +// The decompressed data may arrive in several reads; it must still be accepted. +func TestDecompressCertReadsFully(t *testing.T) { + certMsg := &certificateMsgTLS13{certificate: Certificate{Certificate: [][]byte{bytes.Repeat([]byte{0x42}, 100000)}}} + raw, err := certMsg.marshal() + if err != nil { + t.Fatal(err) + } + body := raw[4:] + + var compressed bytes.Buffer + w := zlib.NewWriter(&compressed) + w.Write(body) + w.Close() + + hs := newDecompressTestState() + got, err := hs.decompressCert(utlsCompressedCertificateMsg{ + algorithm: uint16(CertCompressionZlib), + uncompressedLength: uint32(len(body)), + compressedCertificateMessage: compressed.Bytes(), + }) + if err != nil { + t.Fatalf("decompressCert: %v", err) + } + if len(got.certificate.Certificate) != 1 || len(got.certificate.Certificate[0]) != 100000 { + t.Fatal("decompressed certificate does not match") + } +} diff --git a/u_handshake_client.go b/u_handshake_client.go index 790a003c40..a485c77894 100644 --- a/u_handshake_client.go +++ b/u_handshake_client.go @@ -95,14 +95,21 @@ func (hs *clientHandshakeStateTLS13) decompressCert(m utlsCompressedCertificateM return nil, fmt.Errorf("unsupported algorithm (%d)", m.algorithm) } + // Apply the limit used for uncompressed certificate messages before + // allocating: uncompressed_length is up to 16 MiB and peer-controlled. + if m.uncompressedLength > maxHandshakeCertificateMsg { + c.sendAlert(alertBadCertificate) + return nil, fmt.Errorf("uncompressed certificate message of length %d bytes exceeds maximum of %d bytes", m.uncompressedLength, maxHandshakeCertificateMsg) + } + rawMsg := make([]byte, m.uncompressedLength+4) // +4 for message type and uint24 length field rawMsg[0] = typeCertificate rawMsg[1] = uint8(m.uncompressedLength >> 16) rawMsg[2] = uint8(m.uncompressedLength >> 8) rawMsg[3] = uint8(m.uncompressedLength) - n, err := decompressed.Read(rawMsg[4:]) - if err != nil && !errors.Is(err, io.EOF) { + n, err := io.ReadFull(decompressed, rawMsg[4:]) + if err != nil && !errors.Is(err, io.EOF) && !errors.Is(err, io.ErrUnexpectedEOF) { c.sendAlert(alertBadCertificate) return nil, err } From 45903f8cc9b5fbc6656d6b6fa292cbf22661fb97 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Tue, 13 Oct 2026 18:04:26 +0300 Subject: [PATCH 12/27] fix(mlkem): panic when crypto/rand fails instead of using zero bytes The ML-KEM code ignored errors from crypto/rand.Read. Since Go 1.24 that call crashes on failure, but this module supports older Go, where it returns the error and the seed or encapsulation message would stay all-zero. Read through a helper that panics on failure, matching the fatal behaviour of Go's own ML-KEM DRBG. (cherry picked from commit 5f40e260c8b312c394c6b34d551b8ea066dc0535) --- mlkem/mlkem1024.go | 9 ++++----- mlkem/mlkem768.go | 9 ++++----- mlkem/rand.go | 20 ++++++++++++++++++++ mlkem/rand_test.go | 40 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 68 insertions(+), 10 deletions(-) create mode 100644 mlkem/rand.go create mode 100644 mlkem/rand_test.go diff --git a/mlkem/mlkem1024.go b/mlkem/mlkem1024.go index fb071cc91e..10fc77532a 100644 --- a/mlkem/mlkem1024.go +++ b/mlkem/mlkem1024.go @@ -4,7 +4,6 @@ package mlkem import ( "bytes" - drbg "crypto/rand" "crypto/subtle" "errors" @@ -114,9 +113,9 @@ func GenerateKey1024() (*DecapsulationKey1024, error) { func generateKey1024(dk *DecapsulationKey1024) (*DecapsulationKey1024, error) { var d [32]byte - drbg.Read(d[:]) + randRead(d[:]) var z [32]byte - drbg.Read(z[:]) + randRead(z[:]) kemKeyGen1024(dk, &d, &z) return dk, nil } @@ -189,7 +188,7 @@ func TestingOnlyNewDecapsulationKey1024(b []byte) (*DecapsulationKey1024, error) // that avoids returning a broken key vs a random key if this function is // called in contravention of the TestingOnlyNewDecapsulationKey1024 function // comment advising against it. - drbg.Read(dk.d[:]) + randRead(dk.d[:]) return dk, nil } @@ -276,7 +275,7 @@ func (ek *EncapsulationKey1024) Encapsulate() (sharedKey, ciphertext []byte) { func (ek *EncapsulationKey1024) encapsulate(cc *[CiphertextSize1024]byte) (sharedKey, ciphertext []byte) { var m [messageSize]byte - drbg.Read(m[:]) + randRead(m[:]) return kemEncaps1024(cc, ek, &m) } diff --git a/mlkem/mlkem768.go b/mlkem/mlkem768.go index 7b65f9c83c..ea83b924c0 100644 --- a/mlkem/mlkem768.go +++ b/mlkem/mlkem768.go @@ -25,7 +25,6 @@ package mlkem import ( "bytes" - drbg "crypto/rand" "crypto/subtle" "errors" @@ -173,9 +172,9 @@ func GenerateKey768() (*DecapsulationKey768, error) { func generateKey(dk *DecapsulationKey768) (*DecapsulationKey768, error) { var d [32]byte - drbg.Read(d[:]) + randRead(d[:]) var z [32]byte - drbg.Read(z[:]) + randRead(z[:]) kemKeyGen(dk, &d, &z) return dk, nil } @@ -248,7 +247,7 @@ func TestingOnlyNewDecapsulationKey768(b []byte) (*DecapsulationKey768, error) { // that avoids returning a broken key vs a random key if this function is // called in contravention of the TestingOnlyNewDecapsulationKey768 function // comment advising against it. - drbg.Read(dk.d[:]) + randRead(dk.d[:]) return dk, nil } @@ -335,7 +334,7 @@ func (ek *EncapsulationKey768) Encapsulate() (sharedKey, ciphertext []byte) { func (ek *EncapsulationKey768) encapsulate(cc *[CiphertextSize768]byte) (sharedKey, ciphertext []byte) { var m [messageSize]byte - drbg.Read(m[:]) + randRead(m[:]) return kemEncaps(cc, ek, &m) } diff --git a/mlkem/rand.go b/mlkem/rand.go new file mode 100644 index 0000000000..e6051c60ab --- /dev/null +++ b/mlkem/rand.go @@ -0,0 +1,20 @@ +package mlkem + +import ( + "crypto/rand" + "io" +) + +// randRead fills b with random bytes from crypto/rand.Reader and panics if +// that fails. +// +// Go's own ML-KEM draws from crypto/internal/fips140/drbg, which crashes the +// program when the system randomness source fails (as crypto/rand.Read does +// since Go 1.24). Before Go 1.24 crypto/rand.Read returns the error instead, +// and ignoring it would leave keys and encapsulation messages all-zero. +// Panicking keeps that guarantee on every Go version this module supports. +func randRead(b []byte) { + if _, err := io.ReadFull(rand.Reader, b); err != nil { + panic("mlkem: failed to read random data: " + err.Error()) + } +} diff --git a/mlkem/rand_test.go b/mlkem/rand_test.go new file mode 100644 index 0000000000..9eacf2cfa0 --- /dev/null +++ b/mlkem/rand_test.go @@ -0,0 +1,40 @@ +package mlkem + +import ( + "crypto/rand" + "errors" + "testing" +) + +type failingReader struct{} + +func (failingReader) Read([]byte) (int, error) { return 0, errors.New("entropy source failed") } + +// A failing randomness source must not yield a key or ciphertext built from +// zero bytes. +func TestRandFailurePanics(t *testing.T) { + dk, err := GenerateKey768() + if err != nil { + t.Fatal(err) + } + ek := dk.EncapsulationKey() + + orig := rand.Reader + rand.Reader = failingReader{} + defer func() { rand.Reader = orig }() + + for name, f := range map[string]func(){ + "GenerateKey768": func() { GenerateKey768() }, + "GenerateKey1024": func() { GenerateKey1024() }, + "Encapsulate768": func() { ek.Encapsulate() }, + } { + func() { + defer func() { + if recover() == nil { + t.Errorf("%s did not panic when crypto/rand failed", name) + } + }() + f() + }() + } +} From c57d07e5d80a3cb957e15f0aebf6348a61045bfe Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Wed, 11 Nov 2026 12:54:22 +0300 Subject: [PATCH 13/27] port: follow the v1.9 mlkem and hpke package layout internal/mlkem moved to mlkem and internal/hpke became the hpke package with a different API. Point the REALITY key share code at mlkem and build the ECH test config list from RFC 9180 identifiers. --- reality_keyshare.go | 2 +- reality_keyshare_test.go | 2 +- u_ech_build_test.go | 15 +++++++++++---- 3 files changed, 13 insertions(+), 6 deletions(-) diff --git a/reality_keyshare.go b/reality_keyshare.go index 8e897d0859..3f068f4abd 100644 --- a/reality_keyshare.go +++ b/reality_keyshare.go @@ -4,7 +4,7 @@ package tls // REALITY ClientHello, optionally requiring X25519MLKEM768 like Xray // (XTLS/REALITY@8cdf7bf). -import "github.com/metacubex/utls/internal/mlkem" +import "github.com/metacubex/utls/mlkem" // realityClientPeerPub picks the X25519 public key used to derive the REALITY // auth key: the X25519 key share, else the X25519 part of X25519MLKEM768. diff --git a/reality_keyshare_test.go b/reality_keyshare_test.go index efef8f6515..da251de6de 100644 --- a/reality_keyshare_test.go +++ b/reality_keyshare_test.go @@ -5,7 +5,7 @@ import ( "net" "testing" - "github.com/metacubex/utls/internal/mlkem" + "github.com/metacubex/utls/mlkem" ) func TestRealityClientPeerPub(t *testing.T) { diff --git a/u_ech_build_test.go b/u_ech_build_test.go index 62011aaf22..84af239e7c 100644 --- a/u_ech_build_test.go +++ b/u_ech_build_test.go @@ -9,10 +9,17 @@ import ( "testing" "time" - "github.com/metacubex/utls/internal/hpke" "golang.org/x/crypto/cryptobyte" ) +// HPKE identifiers (RFC 9180) for the test ECH config. +const ( + testHPKEKEMX25519 = 0x0020 // DHKEM(X25519, HKDF-SHA256) + testHPKEKDFSHA256 = 0x0001 // HKDF-SHA256 + testHPKEAEADAES128GCM = 0x0001 // AES-128-GCM + testHPKEAEADChaCha20 = 0x0003 // ChaCha20Poly1305 +) + // testECHConfigList returns an ECHConfigList with a single X25519 config. func testECHConfigList(t *testing.T, publicName string) []byte { t.Helper() @@ -25,13 +32,13 @@ func testECHConfigList(t *testing.T, publicName string) []byte { builder.AddUint16(extensionEncryptedClientHello) builder.AddUint16LengthPrefixed(func(builder *cryptobyte.Builder) { builder.AddUint8(1) - builder.AddUint16(hpke.DHKEM_X25519_HKDF_SHA256) + builder.AddUint16(testHPKEKEMX25519) builder.AddUint16LengthPrefixed(func(builder *cryptobyte.Builder) { builder.AddBytes(echKey.PublicKey().Bytes()) }) builder.AddUint16LengthPrefixed(func(builder *cryptobyte.Builder) { - for _, aeadID := range sortedSupportedAEADs { - builder.AddUint16(hpke.KDF_HKDF_SHA256) + for _, aeadID := range []uint16{testHPKEAEADAES128GCM, testHPKEAEADChaCha20} { + builder.AddUint16(testHPKEKDFSHA256) builder.AddUint16(aeadID) } }) From 6a8792853233c7445e222d604161f4c35bc01345 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Tue, 13 Oct 2026 18:05:43 +0300 Subject: [PATCH 14/27] fix: return errors for out-of-range HKDF and exporter lengths hkdf.Expand and hkdf.Key panicked on a negative length or one above 255 hash blocks; check both and return an error, as crypto/hkdf does. ConnectionState.ExportKeyingMaterial panicked on a negative length and, in TLS 1.3, on a label longer than HkdfLabel allows or a length beyond the HKDF limit (lengths over 65535 would also have been truncated in the HkdfLabel). Return errors instead; signatures are unchanged. (cherry picked from commit fe273b2a88b8e60053e83a9c2cc16cf2e3946010) --- common.go | 3 +++ export_bounds_test.go | 59 +++++++++++++++++++++++++++++++++++++++++++ hkdf/hkdf.go | 19 ++++++++++++++ hkdf/hkdf_test.go | 34 +++++++++++++++++++++++++ key_schedule.go | 10 ++++++++ 5 files changed, 125 insertions(+) create mode 100644 export_bounds_test.go create mode 100644 hkdf/hkdf_test.go diff --git a/common.go b/common.go index f095ad38c2..1d19ee0761 100644 --- a/common.go +++ b/common.go @@ -359,6 +359,9 @@ type ConnectionState struct { // of RFC 5705 and RFC 7627), but can be re-enabled with the GODEBUG setting // tlsunsafeekm=1. func (cs *ConnectionState) ExportKeyingMaterial(label string, context []byte, length int) ([]byte, error) { + if length < 0 { + return nil, errors.New("crypto/tls: ExportKeyingMaterial length is negative") + } return cs.ekm(label, context, length) } diff --git a/export_bounds_test.go b/export_bounds_test.go new file mode 100644 index 0000000000..311c8a1ca0 --- /dev/null +++ b/export_bounds_test.go @@ -0,0 +1,59 @@ +package tls + +import ( + "strings" + "testing" +) + +func TestExportKeyingMaterialBounds(t *testing.T) { + for _, v := range []uint16{VersionTLS12, VersionTLS13} { + clientConfig := testConfig.Clone() + clientConfig.MaxVersion = v + clientConfig.CipherSuites = []uint16{TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256} + serverConfig := testConfig.Clone() + serverConfig.MaxVersion = v + _, cs, err := testHandshake(t, clientConfig, serverConfig) + if err != nil { + t.Fatal(err) + } + + bad := []struct { + label string + length int + }{ + {"label", -1}, + } + if v == VersionTLS13 { + bad = append(bad, + struct { + label string + length int + }{strings.Repeat("a", 250), 32}, + struct { + label string + length int + }{"label", 255*32 + 1}, + struct { + label string + length int + }{"label", 0x10000}, + ) + } + for _, b := range bad { + func() { + defer func() { + if r := recover(); r != nil { + t.Errorf("%s: ExportKeyingMaterial(len(label)=%d, %d) panicked: %v", VersionName(v), len(b.label), b.length, r) + } + }() + if _, err := cs.ExportKeyingMaterial(b.label, nil, b.length); err == nil { + t.Errorf("%s: ExportKeyingMaterial(len(label)=%d, %d) = nil error", VersionName(v), len(b.label), b.length) + } + }() + } + + if out, err := cs.ExportKeyingMaterial("label", []byte("ctx"), 64); err != nil || len(out) != 64 { + t.Errorf("%s: ExportKeyingMaterial(64) = %d bytes, %v", VersionName(v), len(out), err) + } + } +} diff --git a/hkdf/hkdf.go b/hkdf/hkdf.go index 70b32cb9ce..9d1ef3da4c 100644 --- a/hkdf/hkdf.go +++ b/hkdf/hkdf.go @@ -11,6 +11,7 @@ package hkdf import ( + "errors" "hash" "github.com/metacubex/utls/internal/hkdf" @@ -34,6 +35,9 @@ func Extract[H hash.Hash](h func() H, secret, salt []byte) ([]byte, error) { // random or pseudorandom cryptographically strong key. See RFC 5869, Section // 3.3. Most common scenarios will want to use [Key] instead. func Expand[H hash.Hash](h func() H, pseudorandomKey []byte, info string, keyLength int) ([]byte, error) { + if err := checkKeyLength(h, keyLength); err != nil { + return nil, err + } return hkdf.Expand(h, pseudorandomKey, info, keyLength), nil } @@ -41,5 +45,20 @@ func Expand[H hash.Hash](h func() H, pseudorandomKey []byte, info string, keyLen // returning a []byte of length keyLength that can be used as cryptographic key. // Salt and info can be nil. func Key[Hash hash.Hash](h func() Hash, secret, salt []byte, info string, keyLength int) ([]byte, error) { + if err := checkKeyLength(h, keyLength); err != nil { + return nil, err + } return hkdf.Key(h, secret, salt, info, keyLength), nil } + +// checkKeyLength enforces the RFC 5869 limit of 255 hash blocks, as +// crypto/hkdf does, and rejects negative lengths. +func checkKeyLength[H hash.Hash](h func() H, keyLength int) error { + if keyLength < 0 { + return errors.New("hkdf: requested key length is negative") + } + if keyLength > 255*h().Size() { + return errors.New("hkdf: requested key length too large") + } + return nil +} diff --git a/hkdf/hkdf_test.go b/hkdf/hkdf_test.go new file mode 100644 index 0000000000..da481a7ca2 --- /dev/null +++ b/hkdf/hkdf_test.go @@ -0,0 +1,34 @@ +package hkdf + +import ( + "crypto/sha256" + "testing" +) + +func TestKeyLengthBounds(t *testing.T) { + prk, err := Extract(sha256.New, []byte("secret"), nil) + if err != nil { + t.Fatal(err) + } + for _, n := range []int{-1, 255*sha256.Size + 1, 1 << 20} { + func() { + defer func() { + if r := recover(); r != nil { + t.Errorf("length %d panicked: %v", n, r) + } + }() + if _, err := Expand(sha256.New, prk, "info", n); err == nil { + t.Errorf("Expand(length %d) = nil error", n) + } + if _, err := Key(sha256.New, []byte("secret"), nil, "info", n); err == nil { + t.Errorf("Key(length %d) = nil error", n) + } + }() + } + for _, n := range []int{0, 32, 255 * sha256.Size} { + out, err := Key(sha256.New, []byte("secret"), nil, "info", n) + if err != nil || len(out) != n { + t.Errorf("Key(length %d) = %d bytes, %v", n, len(out), err) + } + } +} diff --git a/key_schedule.go b/key_schedule.go index 6cc1a0f8ed..b0ecfef6fc 100644 --- a/key_schedule.go +++ b/key_schedule.go @@ -46,6 +46,16 @@ func (c *cipherSuiteTLS13) finishedHash(baseKey []byte, transcript hash.Hash) [] func (c *cipherSuiteTLS13) exportKeyingMaterial(s *tls13.MasterSecret, transcript hash.Hash) func(string, []byte, int) ([]byte, error) { expMasterSecret := s.ExporterMasterSecret(transcript) return func(label string, context []byte, length int) ([]byte, error) { + // HKDF-Expand-Label carries the label in an opaque<7..255> field + // (with the "tls13 " prefix) and the length in a uint16, and HKDF + // cannot produce more than 255 hash blocks. Reject what would not + // fit instead of panicking (or truncating the length). + if len("tls13 ")+len(label) > 255 { + return nil, errors.New("crypto/tls: ExportKeyingMaterial label too long") + } + if length < 0 || length > 0xffff || length > 255*c.hash.Size() { + return nil, errors.New("crypto/tls: ExportKeyingMaterial length out of range") + } return expMasterSecret.Exporter(label, context, length), nil } } From fa224e23fd36b0930a23f05f2f9a33edacebfa35 Mon Sep 17 00:00:00 2001 From: Neal Patel Date: Mon, 28 Sep 2026 18:45:24 +0000 Subject: [PATCH 15/27] crypto/tls: validate ECH outer extension references Using a single cursor, reject malformed encodings and esnure that each outer extension is copied at most once. Fixes CVE-2026-97031 For golang/go#81855 Fixes golang/go#81915 Change-Id: I5b09f2b6275d42f7701fae4e583eb3a2caeaa44d Reviewed-on: https://go-internal-review.googlesource.com/c/go/+/5320 Reviewed-by: Roland Shoemaker Reviewed-by: Nicholas Husin Reviewed-on: https://go-internal-review.googlesource.com/c/go/+/6160 Reviewed-by: Damien Neil Reviewed-on: https://go-review.googlesource.com/c/go/+/847105 Auto-Submit: Gopher Robot TryBot-Bypass: Gopher Robot Reviewed-by: Michael Pratt Reviewed-by: Dmitri Shuralyov Reviewed-by: Neal Patel (cherry picked from commit e798688348cdf597f7d06fda854b57e8c466b8cb) --- ech.go | 22 +++++++-- ech_test.go | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+), 4 deletions(-) diff --git a/ech.go b/ech.go index e8ed89a28e..f6f5574292 100644 --- a/ech.go +++ b/ech.go @@ -319,6 +319,7 @@ func decodeInnerClientHello(outer *clientHelloMsg, encoded []byte) (*clientHello recon.AddBytes(compressionMethods) }) recon.AddUint16LengthPrefixed(func(recon *cryptobyte.Builder) { + var outerExtensionsSeen bool for !extensions.Empty() { var extension uint16 var extData cryptobyte.String @@ -328,18 +329,30 @@ func decodeInnerClientHello(outer *clientHelloMsg, encoded []byte) (*clientHello return } if extension == extensionECHOuterExtensions { - if !extData.ReadUint8LengthPrefixed(&extData) { + if outerExtensionsSeen { + recon.SetError(errors.New("tls: invalid outer extensions")) + return + } + outerExtensionsSeen = true + var outerExtensions cryptobyte.String + if !extData.ReadUint8LengthPrefixed(&outerExtensions) || !extData.Empty() || + outerExtensions.Empty() { recon.SetError(errors.New("tls: invalid inner client hello")) return } + // OuterExtensions reconstruction per RFC 9849, Appendix A. + // i scans the outer extensions in order and never rewinds, + // so a referenced type that is out of order or duplicated + // cannot be found again and is rejected. var i int - for !extData.Empty() { + for !outerExtensions.Empty() { var extType uint16 - if !extData.ReadUint16(&extType) { + if !outerExtensions.ReadUint16(&extType) { recon.SetError(errors.New("tls: invalid inner client hello")) return } - if extType == extensionEncryptedClientHello { + if extType == extensionEncryptedClientHello || + extType == extensionECHOuterExtensions { recon.SetError(errors.New("tls: invalid outer extensions")) return } @@ -356,6 +369,7 @@ func decodeInnerClientHello(outer *clientHelloMsg, encoded []byte) (*clientHello recon.AddUint16LengthPrefixed(func(recon *cryptobyte.Builder) { recon.AddBytes(rawOuterExts[i].data) }) + i++ } } else { recon.AddUint16(extension) diff --git a/ech_test.go b/ech_test.go index 5adbb0293d..78da79f730 100644 --- a/ech_test.go +++ b/ech_test.go @@ -7,6 +7,8 @@ package tls import ( "encoding/hex" "testing" + + "golang.org/x/crypto/cryptobyte" ) func TestDecodeECHConfigLists(t *testing.T) { @@ -46,3 +48,130 @@ func TestSkipBadConfigs(t *testing.T) { t.Fatal("pickECHConfig picked an invalid config") } } + +func TestDecodeInnerClientHelloOuterExtensions(t *testing.T) { + outer := &clientHelloMsg{ + vers: VersionTLS12, + random: make([]byte, 32), + cipherSuites: []uint16{TLS_AES_128_GCM_SHA256}, + compressionMethods: []uint8{compressionNone}, + ocspStapling: true, + supportedCurves: []CurveID{CurveP256}, + encryptedClientHello: []byte{byte(innerECHExt)}, + } + outer.original = mustMarshal(t, outer) + + encodeInner := func(buildExts func(*cryptobyte.Builder)) []byte { + var b cryptobyte.Builder + b.AddUint16(VersionTLS12) + b.AddBytes(make([]byte, 32)) + b.AddUint8(0) + b.AddUint16LengthPrefixed(func(b *cryptobyte.Builder) { + b.AddUint16(TLS_AES_128_GCM_SHA256) + }) + b.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) { + b.AddUint8(compressionNone) + }) + b.AddUint16LengthPrefixed(func(b *cryptobyte.Builder) { + buildExts(b) + b.AddUint16(extensionEncryptedClientHello) + b.AddUint16LengthPrefixed(func(b *cryptobyte.Builder) { + b.AddUint8(uint8(innerECHExt)) + }) + b.AddUint16(extensionSupportedVersions) + b.AddUint16LengthPrefixed(func(b *cryptobyte.Builder) { + b.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) { + b.AddUint16(VersionTLS13) + }) + }) + }) + return b.BytesOrPanic() + } + + outerExts := func(b *cryptobyte.Builder, extTypes ...uint16) { + b.AddUint16(extensionECHOuterExtensions) + b.AddUint16LengthPrefixed(func(b *cryptobyte.Builder) { + b.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) { + for _, extType := range extTypes { + b.AddUint16(extType) + } + }) + }) + } + + for _, tc := range []struct { + name string + buildExts func(*cryptobyte.Builder) + wantErr string + }{ + { + name: "valid order", + buildExts: func(b *cryptobyte.Builder) { + outerExts(b, extensionStatusRequest, extensionSupportedCurves) + }, + }, + { + name: "duplicate reference", + buildExts: func(b *cryptobyte.Builder) { + outerExts(b, extensionStatusRequest, extensionStatusRequest) + }, + wantErr: "tls: invalid outer extensions", + }, + { + name: "references encrypted_client_hello", + buildExts: func(b *cryptobyte.Builder) { + outerExts(b, extensionEncryptedClientHello) + }, + wantErr: "tls: invalid outer extensions", + }, + { + name: "references ech_outer_extensions", + buildExts: func(b *cryptobyte.Builder) { + outerExts(b, extensionECHOuterExtensions) + }, + wantErr: "tls: invalid outer extensions", + }, + { + name: "multiple ech_outer_extensions", + buildExts: func(b *cryptobyte.Builder) { + outerExts(b, extensionStatusRequest) + outerExts(b, extensionSupportedCurves) + }, + wantErr: "tls: invalid outer extensions", + }, + { + name: "odd-length reference list", + buildExts: func(b *cryptobyte.Builder) { + b.AddUint16(extensionECHOuterExtensions) + b.AddUint16LengthPrefixed(func(b *cryptobyte.Builder) { + b.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) { + b.AddUint8(0) + }) + }) + }, + wantErr: "tls: invalid inner client hello", + }, + { + name: "empty reference list", + buildExts: func(b *cryptobyte.Builder) { + b.AddUint16(extensionECHOuterExtensions) + b.AddUint16LengthPrefixed(func(b *cryptobyte.Builder) { + b.AddUint8(0) + }) + }, + wantErr: "tls: invalid inner client hello", + }, + } { + t.Run(tc.name, func(t *testing.T) { + encoded := encodeInner(tc.buildExts) + _, err := decodeInnerClientHello(outer, encoded) + if tc.wantErr == "" { + if err != nil { + t.Fatalf("decodeInnerClientHello returned %v, want nil", err) + } + } else if err == nil || err.Error() != tc.wantErr { + t.Fatalf("decodeInnerClientHello returned %v, want %q", err, tc.wantErr) + } + }) + } +} From e7886491b9eef50986ed5586390051987ad7c689 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Tue, 13 Oct 2026 20:21:12 +0300 Subject: [PATCH 16/27] crypto/tls: do not count handshake messages as state-advancing post-handshake Port of Go commit b6432317a (release-branch.go1.26). After the handshake, KeyUpdate messages reset the non-advancing record counter, so a peer could keep sending them and force key derivation indefinitely. Only application data, and handshake messages before the handshake completes, now count as state-advancing. (cherry picked from commit c4444fe6e1bd46f80f6f538206007791f0dfe1b5) --- conn.go | 2 +- conn_test.go | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/conn.go b/conn.go index 1bb40f7e71..a6a6076fd3 100644 --- a/conn.go +++ b/conn.go @@ -747,7 +747,7 @@ func (c *Conn) readRecordOrCCS(expectChangeCipherSpec bool) error { return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage)) } - if typ != recordTypeAlert && typ != recordTypeChangeCipherSpec && len(data) > 0 { + if (typ == recordTypeApplicationData || (typ == recordTypeHandshake && !handshakeComplete)) && len(data) > 0 { // This is a state-advancing message: reset the retry count. c.retryCount = 0 } diff --git a/conn_test.go b/conn_test.go index 5fd48d6bd5..9adb47e030 100644 --- a/conn_test.go +++ b/conn_test.go @@ -321,3 +321,37 @@ func TestRecordBadVersionTLS13(t *testing.T) { t.Fatalf("unexpected error: got %q, want %q", err, expectedErr) } } + +// TestKeyUpdateSpamPostHandshakeTLS13 tests that TLS 1.3 KeyUpdate messages do +// not count as a state-advancing message after a handshake has been completed. +func TestKeyUpdateSpamPostHandshakeTLS13(t *testing.T) { + client, server := localPipe(t) + defer server.Close() + defer client.Close() + + go func() { + c := Client(client, testConfig.Clone()) + if err := c.Handshake(); err != nil { + t.Error(err) + return + } + ku, err := (&keyUpdateMsg{}).marshal() + if err != nil { + t.Error(err) + return + } + cs := cipherSuiteTLS13ByID(c.cipherSuite) + for i := 0; i <= maxUselessRecords; i++ { + c.writeRecordLocked(recordTypeHandshake, ku) + c.out.setTrafficSecret(cs, QUICEncryptionLevelInitial, cs.nextTrafficSecret(c.out.trafficSecret)) + } + }() + s := Server(server, testConfig.Clone()) + if err := s.Handshake(); err != nil { + t.Fatal(err) + } + expectedErr := "tls: too many non-advancing records" + if _, err := s.Read(make([]byte, 1)); err == nil || err.Error() != expectedErr { + t.Fatalf("unexpected error: got %v, want %q", err, expectedErr) + } +} From 78bccfa9f8561f763bb2bd192df9dd165ff9bf10 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Wed, 14 Oct 2026 23:21:59 +0300 Subject: [PATCH 17/27] ci: test the citrus branch on push and pull requests Go 1.26 on Linux and Windows with go vet, the minimum Go 1.20 on Linux, and a race detector run. Replaces the upstream matrix of 30 jobs. (cherry picked from commit b0d97247e154db6a39cbc6841d47ac1f131c07a7) --- .github/workflows/ci.yml | 48 ++++++++++++++++++++++++++++++++++++++++ .github/workflows/go.yml | 47 --------------------------------------- 2 files changed, 48 insertions(+), 47 deletions(-) create mode 100644 .github/workflows/ci.yml delete mode 100644 .github/workflows/go.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000000..a1358005e9 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,48 @@ +name: CI + +on: + push: + branches: [citrus] + pull_request: + branches: [citrus] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +permissions: + contents: read + +jobs: + test: + strategy: + fail-fast: false + matrix: + include: + - { os: ubuntu-latest, go: '1.26' } + - { os: windows-latest, go: '1.26' } + - { os: ubuntu-latest, go: '1.20' } + runs-on: ${{ matrix.os }} + env: + CGO_ENABLED: 0 + GOTOOLCHAIN: local + steps: + - uses: actions/checkout@v5 + - uses: actions/setup-go@v6 + with: + go-version: ${{ matrix.go }} + - name: Vet + if: matrix.go == '1.26' + run: go vet ./... + - name: Test + run: go test -count=1 ./... + + race: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + - uses: actions/setup-go@v6 + with: + go-version: '1.26' + - name: Test with the race detector + run: go test -race -count=1 ./... diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml deleted file mode 100644 index 61f2f32e1c..0000000000 --- a/.github/workflows/go.yml +++ /dev/null @@ -1,47 +0,0 @@ -# This workflow will build a golang project -# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go - -name: "Go" - -on: - push: - pull_request: - -jobs: - build: - strategy: - matrix: - os: - - 'ubuntu-latest' # amd64 linux - - 'windows-latest' # amd64 windows - - 'macos-latest' # arm64 macos - - 'ubuntu-24.04-arm' # arm64 linux - - 'macos-15-intel' # amd64 macos - go-version: - - '1.26' - - '1.25' - - '1.24' - - '1.23' - - '1.22' - - '1.21' - - '1.20' - fail-fast: false - runs-on: ${{ matrix.os }} - defaults: - run: - shell: bash - env: - CGO_ENABLED: 0 - GOTOOLCHAIN: local - # Fix mingw trying to be smart and converting paths https://github.com/moby/moby/issues/24029#issuecomment-250412919 - MSYS_NO_PATHCONV: true - steps: - - uses: actions/checkout@v5 - - uses: actions/setup-go@v6 - with: - go-version: ${{ matrix.go-version }} - - run: go version - - name: Build - run: go build -v ./... - - name: Test - run: go test -v ./... From 7f0c8af3f824d6f84a2ac32b5b259047f1140ef5 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Wed, 14 Oct 2026 23:29:07 +0300 Subject: [PATCH 18/27] test: report ApplyPreset errors without racing on err The client goroutine in testUtlsHandshake assigned the ApplyPreset result to the named return err, which the test goroutine also writes, and returned without sending on errChan when it failed. (cherry picked from commit 42cb40a6bc25120cfd337b473940f82ebedf1dfd) --- handshake_test.go | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/handshake_test.go b/handshake_test.go index 18cdbb9044..7af266bcb0 100644 --- a/handshake_test.go +++ b/handshake_test.go @@ -503,7 +503,11 @@ func testUtlsHandshake(t *testing.T, clientConfig, serverConfig *Config, spec *C } if spec != nil { ucli := UClient(c, clientConfig, HelloCustom) - if err = ucli.ApplyPreset(spec); err != nil { + // Do not assign to the outer err: the test goroutine writes it + // concurrently, and returning without a send would block it. + if err := ucli.ApplyPreset(spec); err != nil { + errChan <- fmt.Errorf("client: %v", err) + c.Close() return } cli = ucli From b60d673f02353104a3ec574632e4e78c1656e4a2 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Wed, 14 Oct 2026 23:29:08 +0300 Subject: [PATCH 19/27] ci: run on main and dev, skip loopclosure in vet, keep LF on Windows (cherry picked from commit a6af36b78238de30d20e6bfafb6f05e9dc6dc84f) --- .github/workflows/ci.yml | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a1358005e9..847173a70c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,9 +2,9 @@ name: CI on: push: - branches: [citrus] + branches: [main, dev] pull_request: - branches: [citrus] + branches: [main, dev] concurrency: group: ${{ github.workflow }}-${{ github.ref }} @@ -27,13 +27,21 @@ jobs: CGO_ENABLED: 0 GOTOOLCHAIN: local steps: + # Keep testdata byte-exact: autocrlf on Windows runners rewrites LF. + - name: Disable CRLF conversion + if: runner.os == 'Windows' + run: | + git config --global core.autocrlf false + git config --global core.eol lf - uses: actions/checkout@v5 - uses: actions/setup-go@v6 with: go-version: ${{ matrix.go }} + # go.mod says go 1.20, so loopclosure flags upstream Go tests that assume + # per-iteration loop variables; the rest of vet stays on. - name: Vet if: matrix.go == '1.26' - run: go vet ./... + run: go vet -loopclosure=false ./... - name: Test run: go test -count=1 ./... From 14b5323e5cfe8ff71935f2275cffcda6830529b4 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Sun, 18 Oct 2026 02:21:16 +0300 Subject: [PATCH 20/27] crypto/tls: write the records of one write together A write of more than one record sent every record with its own write to the connection, and the network stack is paid per write. The records of one write are now encrypted in place one behind the other and written together, up to eight full-sized records (about 128 KiB) at a time. Nothing is held back: all of it is written before the call returns. (cherry picked from commit b76689d5c62ff526256fc121fd2ed490dedb40af) --- coalesce_test.go | 142 +++++++++++++++++++++++++++++++++++++++++++++++ conn.go | 67 ++++++++++++++++++---- 2 files changed, 199 insertions(+), 10 deletions(-) create mode 100644 coalesce_test.go diff --git a/coalesce_test.go b/coalesce_test.go new file mode 100644 index 0000000000..b415bd3598 --- /dev/null +++ b/coalesce_test.go @@ -0,0 +1,142 @@ +package tls + +import ( + "bytes" + "io" + "net" + "sync" + "testing" +) + +// writeSizeConn records the size of every write to the connection. +type writeSizeConn struct { + net.Conn + mu sync.Mutex + writes []int +} + +func (c *writeSizeConn) Write(b []byte) (int, error) { + c.mu.Lock() + c.writes = append(c.writes, len(b)) + c.mu.Unlock() + return c.Conn.Write(b) +} + +func (c *writeSizeConn) reset() []int { + c.mu.Lock() + defer c.mu.Unlock() + w := c.writes + c.writes = nil + return w +} + +// TestWriteCoalescesRecords checks that the records of one large write go to +// the connection in writes of several records, up to coalesceLimit, and that +// the peer reads the same data, with every cipher kind. +func TestWriteCoalescesRecords(t *testing.T) { + configs := map[string]func(*Config){ + "TLSv13": func(*Config) {}, + "AEAD": func(c *Config) { + c.MaxVersion = VersionTLS12 + c.CipherSuites = []uint16{TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256} + }, + "CBC": func(c *Config) { + c.MaxVersion = VersionTLS12 + c.CipherSuites = []uint16{TLS_RSA_WITH_AES_256_CBC_SHA} + }, + "Stream": func(c *Config) { + c.MaxVersion = VersionTLS12 + c.CipherSuites = []uint16{TLS_RSA_WITH_RC4_128_SHA} + }, + } + for name, configure := range configs { + for _, dynamic := range []bool{false, true} { + config := testConfig.Clone() + configure(config) + serverConfig := config.Clone() + serverConfig.DynamicRecordSizingDisabled = !dynamic + testWriteCoalescesRecords(t, name, dynamic, config, serverConfig) + } + } +} + +func testWriteCoalescesRecords(t *testing.T, name string, dynamic bool, clientConfig, serverConfig *Config) { + clientConn, serverConn := localPipe(t) + counted := &writeSizeConn{Conn: serverConn} + server := Server(counted, serverConfig) + defer server.Close() + + plaintext := make([]byte, 1<<20+123) + for i := range plaintext { + plaintext[i] = byte(i * 7) + } + got := make(chan []byte, 1) + go func() { + client := Client(clientConn, clientConfig) + defer client.Close() + data, err := io.ReadAll(io.LimitReader(client, int64(len(plaintext)))) + if err != nil { + t.Errorf("%s: client read: %v", name, err) + } + got <- data + }() + if err := server.Handshake(); err != nil { + t.Fatalf("%s: handshake: %v", name, err) + } + counted.reset() + if n, err := server.Write(plaintext); err != nil || n != len(plaintext) { + t.Fatalf("%s: write = %d, %v", name, n, err) + } + writes := counted.reset() + if data := <-got; !bytes.Equal(data, plaintext) { + t.Fatalf("%s: the client read other data (%d bytes)", name, len(data)) + } + + total := 0 + for i, size := range writes { + total += size + if size > coalesceLimit { + t.Errorf("%s: write #%d of %d bytes, over the limit of %d", name, i, size, coalesceLimit) + } + } + fullRecords := len(plaintext)/maxPlaintext + 1 + maxWrites := fullRecords/7 + 1 // about eight records per write + if dynamic { + maxWrites += recordSizeBoostThreshold / (8 * 1000) // the small records first + } + if len(writes) > maxWrites { + t.Errorf("%s (dynamic %v): %d writes for %d bytes of records, want at most %d", name, dynamic, len(writes), total, maxWrites) + } +} + +// TestWriteSmallRecordsUnchanged checks that a write of one record is still +// one write of that record. +func TestWriteSmallRecordsUnchanged(t *testing.T) { + clientConn, serverConn := localPipe(t) + counted := &writeSizeConn{Conn: serverConn} + server := Server(counted, testConfig.Clone()) + defer server.Close() + go func() { + client := Client(clientConn, testConfig.Clone()) + defer client.Close() + buf := make([]byte, 100) + for i := 0; i < 3; i++ { + if _, err := io.ReadFull(client, buf[:10]); err != nil { + t.Errorf("client read: %v", err) + return + } + } + }() + if err := server.Handshake(); err != nil { + t.Fatal(err) + } + counted.reset() + for i := 0; i < 3; i++ { + if _, err := server.Write(bytes.Repeat([]byte{'a'}, 10)); err != nil { + t.Fatal(err) + } + if writes := counted.reset(); len(writes) != 1 || writes[0] != recordHeaderLen+10+1+16 { + t.Fatalf("write %d: writes %v, want one record of %d bytes", i, writes, recordHeaderLen+10+1+16) + } + } +} diff --git a/conn.go b/conn.go index a6a6076fd3..383ad9ba80 100644 --- a/conn.go +++ b/conn.go @@ -1034,6 +1034,17 @@ var outBufPool = sync.Pool{ }, } +// coalesceLimit bounds the records of one write that are sent to the +// connection together: eight full-sized records. A large write goes out in +// writes of up to about 128 KiB instead of one write per record, and the +// network stack is paid per write. Nothing is held back: all of it is written +// before the call returns. +const coalesceLimit = 8 * (recordHeaderLen + maxPlaintext + maxRecordExpansion) + +// maxRecordExpansion bounds what encryption adds to a record payload: an +// explicit nonce, a MAC or an AEAD tag, CBC padding, the TLS 1.3 content type. +const maxRecordExpansion = 16 + 48 + 256 + 1 + // writeRecordLocked writes a TLS record with the given type and payload to the // connection and updates the record layer state. func (c *Conn) writeRecordLocked(typ recordType, data []byte) (int, error) { @@ -1062,15 +1073,43 @@ func (c *Conn) writeRecordLocked(typ recordType, data []byte) (int, error) { outBufPool.Put(outBufPtr) }() - var n int + // outBuf holds the encrypted records not written yet, which carry queued + // bytes of data. + outBuf = outBuf[:0] + var n, queued int for len(data) > 0 { m := len(data) if maxPayload := c.maxPayloadSizeForWrite(typ); m > maxPayload { m = maxPayload } - _, outBuf = sliceForAppend(outBuf[:0], recordHeaderLen) - outBuf[0] = byte(typ) + start := len(outBuf) + need := start + recordHeaderLen + m + maxRecordExpansion + if start > 0 && need > coalesceLimit { + if _, err := c.write(outBuf); err != nil { + return n, err + } + n += queued + outBuf, queued = outBuf[:0], 0 + start, need = 0, recordHeaderLen+m+maxRecordExpansion + } + if cap(outBuf) < need { + // Room for this record and, up to the limit, the ones after it, + // so that every record is encrypted in place behind the last. + size := start + len(data) + (len(data)/maxPlaintext+1)*(recordHeaderLen+maxRecordExpansion) + if size > coalesceLimit { + size = coalesceLimit + } + if size < need { + size = need + } + grown := make([]byte, start, size) + copy(grown, outBuf) + outBuf = grown + } + + record := outBuf[start : start+recordHeaderLen] + record[0] = byte(typ) vers := c.vers if vers == 0 { // Some TLS servers fail if the record version is @@ -1081,21 +1120,29 @@ func (c *Conn) writeRecordLocked(typ recordType, data []byte) (int, error) { // See RFC 8446, Section 5.1. vers = VersionTLS12 } - outBuf[1] = byte(vers >> 8) - outBuf[2] = byte(vers) - outBuf[3] = byte(m >> 8) - outBuf[4] = byte(m) + record[1] = byte(vers >> 8) + record[2] = byte(vers) + record[3] = byte(m >> 8) + record[4] = byte(m) var err error - outBuf, err = c.out.encrypt(outBuf, data[:m], c.config.rand()) + record, err = c.out.encrypt(record, data[:m], c.config.rand()) if err != nil { return n, err } + if &record[0] == &outBuf[:start+1][start] { + outBuf = outBuf[:start+len(record)] // encrypted in place + } else { + outBuf = append(outBuf[:start], record...) + } + queued += m + data = data[m:] + } + if len(outBuf) > 0 { if _, err := c.write(outBuf); err != nil { return n, err } - n += m - data = data[m:] + n += queued } if typ == recordTypeChangeCipherSpec && c.vers != VersionTLS13 { From 757e109e4bf01d3bb25fb8623a2e781a544b2354 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Sun, 18 Oct 2026 07:41:40 +0300 Subject: [PATCH 21/27] test: wait for the client before closing in TestWriteSmallRecordsUnchanged (cherry picked from commit 5b1b53d534a81fcb13af4cf87851d13d8632ce81) --- coalesce_test.go | 3 +++ 1 file changed, 3 insertions(+) diff --git a/coalesce_test.go b/coalesce_test.go index b415bd3598..8cde034363 100644 --- a/coalesce_test.go +++ b/coalesce_test.go @@ -116,7 +116,9 @@ func TestWriteSmallRecordsUnchanged(t *testing.T) { counted := &writeSizeConn{Conn: serverConn} server := Server(counted, testConfig.Clone()) defer server.Close() + clientDone := make(chan struct{}) go func() { + defer close(clientDone) client := Client(clientConn, testConfig.Clone()) defer client.Close() buf := make([]byte, 100) @@ -139,4 +141,5 @@ func TestWriteSmallRecordsUnchanged(t *testing.T) { t.Fatalf("write %d: writes %v, want one record of %d bytes", i, writes, recordHeaderLen+10+1+16) } } + <-clientDone // before the connections are closed } From 3f03773f54d951a4ee50709751581ae4d01056e1 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Tue, 20 Oct 2026 19:40:12 +0300 Subject: [PATCH 22/27] fix: bound REALITY handshakes and preserve JLS application verification (cherry picked from commit bc98cb67212df127a457cf88bd07197ee8fbb5b2) --- handshake_client.go | 6 -- jls_verify_test.go | 57 ++++++++++++ reality.go | 60 ++++++++++--- reality_guard.go | 72 +++++++++++++++ reality_guard_test.go | 198 ++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 374 insertions(+), 19 deletions(-) create mode 100644 jls_verify_test.go create mode 100644 reality_guard.go create mode 100644 reality_guard_test.go diff --git a/handshake_client.go b/handshake_client.go index 5c87a12a8c..2f811fb96d 100644 --- a/handshake_client.go +++ b/handshake_client.go @@ -1286,12 +1286,6 @@ func (c *Conn) verifyServerCertificate(certificates [][]byte) error { c.activeCertHandles = activeHandles c.peerCertificates = certs - // JLS BEGIN: external verifiers are skipped after successful JLS authentication. - if c.jlsAuthenticated() { - return nil - } - // JLS END - if c.config.VerifyPeerCertificate != nil && !echRejected { if err := c.config.VerifyPeerCertificate(certificates, c.verifiedChains); err != nil { c.sendAlert(alertBadCertificate) diff --git a/jls_verify_test.go b/jls_verify_test.go new file mode 100644 index 0000000000..84628d893f --- /dev/null +++ b/jls_verify_test.go @@ -0,0 +1,57 @@ +package tls + +import ( + "bytes" + "crypto/x509" + "errors" + "testing" +) + +func TestJLSAuthenticationStillRunsCertificateCallbacks(t *testing.T) { + for _, reject := range []string{"", "peer", "connection"} { + t.Run(reject, func(t *testing.T) { + refusal := errors.New("application refused JLS peer") + var calls []string + config := &Config{ + InsecureSkipVerify: true, + VerifyPeerCertificate: func(raw [][]byte, chains [][]*x509.Certificate) error { + calls = append(calls, "peer") + if len(raw) != 1 || !bytes.Equal(raw[0], testRSACertificate) { + t.Fatal("callback received wrong certificate") + } + if reject == "peer" { + return refusal + } + return nil + }, + VerifyConnection: func(state ConnectionState) error { + calls = append(calls, "connection") + if len(state.PeerCertificates) != 1 { + t.Fatal("connection state lacks peer certificate") + } + if reject == "connection" { + return refusal + } + return nil + }, + } + conn := Client(&bytesConn{Reader: bytes.NewReader(nil)}, config) + conn.jlsState = jlsStateAuthSuccess + err := conn.verifyServerCertificate([][]byte{testRSACertificate}) + if reject == "" { + if err != nil { + t.Fatal(err) + } + } else if !errors.Is(err, refusal) { + t.Fatalf("application verifier bypassed: %v", err) + } + want := 2 + if reject == "peer" { + want = 1 + } + if len(calls) != want || calls[0] != "peer" { + t.Fatalf("callback sequence %v", calls) + } + }) + } +} diff --git a/reality.go b/reality.go index 4dba4dad49..f4ed169872 100644 --- a/reality.go +++ b/reality.go @@ -6,6 +6,7 @@ import ( "context" "crypto/aes" "crypto/cipher" + "crypto/ecdh" "crypto/ed25519" "crypto/hmac" "crypto/rand" @@ -27,7 +28,6 @@ import ( "github.com/metacubex/utls/internal/ratelimit" "github.com/metacubex/utls/mlkem" - "golang.org/x/crypto/curve25519" "golang.org/x/crypto/hkdf" ) @@ -60,15 +60,15 @@ func (c *realityMirrorConn) Close() error { } func (c *realityMirrorConn) SetDeadline(t time.Time) error { - return nil + return c.Conn.SetDeadline(t) } func (c *realityMirrorConn) SetReadDeadline(t time.Time) error { - return nil + return c.Conn.SetReadDeadline(t) } func (c *realityMirrorConn) SetWriteDeadline(t time.Time) error { - return nil + return c.Conn.SetWriteDeadline(t) } // realitySize bounds the target's first flight buffered by the REALITY @@ -118,6 +118,11 @@ type RealityConfig struct { LimitFallbackUpload RealityLimitFallback LimitFallbackDownload RealityLimitFallback + // HandshakeTimeout bounds authentication and the TLS handshake, until the + // connection is accepted or handed to fallback. Zero uses 15 seconds. + // A fallback relay has no total duration limit imposed by this setting. + HandshakeTimeout time.Duration + // Mldsa65Seed is the 32-byte ML-DSA-65 private key seed, the // base64url-decoded value of Xray's "mldsa65Seed". When set, the temporary // certificate carries an ML-DSA-65 signature in its first extension, which @@ -140,6 +145,7 @@ type RealityConfig struct { // mldsa65 caches the private key expanded from Mldsa65Seed. mldsa65 atomic.Pointer[realityMldsa65Key] + ecdhKey atomic.Pointer[realityECDHKey] } func (a *RealityConfig) Clone() *RealityConfig { @@ -157,11 +163,13 @@ func (a *RealityConfig) Clone() *RealityConfig { ShortIds: a.ShortIds, LimitFallbackUpload: a.LimitFallbackUpload, LimitFallbackDownload: a.LimitFallbackDownload, + HandshakeTimeout: a.HandshakeTimeout, Mldsa65Seed: a.Mldsa65Seed, RequireX25519MLKEM768: a.RequireX25519MLKEM768, Config: *a.Config.Clone(), } c.postHandshake.Store(a.postHandshakeCache()) + c.ecdhKey.Store(a.ecdhKey.Load()) return c } @@ -172,6 +180,10 @@ type rateLimitedConn struct { } func (c *rateLimitedConn) Read(b []byte) (int, error) { + // Do not let the last free read cross the configured threshold. + if c.After > 0 && int64(len(b)) > c.After { + b = b[:int(c.After)] + } n, err := c.Conn.Read(b) if n != 0 { if c.After > 0 { @@ -409,6 +421,8 @@ func RealityServer(ctx context.Context, conn net.Conn, config *RealityConfig) (* conn.Close() return nil, errors.New("REALITY: failed to dial dest: " + err.Error()) } + stopHandshake := guardRealityHandshake(ctx, conn, target, config.HandshakeTimeout) + defer stopHandshake() underlying := conn @@ -424,7 +438,7 @@ func RealityServer(ctx context.Context, conn net.Conn, config *RealityConfig) (* }, config: &config.Config, }, - ctx: context.Background(), + ctx: ctx, }, Config: config, } @@ -437,7 +451,7 @@ func RealityServer(ctx context.Context, conn net.Conn, config *RealityConfig) (* go func() { for { mutex.Lock() - hs.clientHello, _, err = hs.c.readClientHello(context.Background()) // TODO: Change some rules in this function. + hs.clientHello, _, err = hs.c.readClientHello(ctx) // TODO: Change some rules in this function. if copying || err != nil || hs.c.vers != VersionTLS13 || !config.ServerNames[hs.clientHello.serverName] { break } @@ -446,7 +460,17 @@ func RealityServer(ctx context.Context, conn net.Conn, config *RealityConfig) (* config.Log("REALITY remoteAddr: %v no acceptable key share", remoteAddr) } for peerPub != nil { - if hs.AuthKey, err = curve25519.X25519(config.PrivateKey, peerPub); err != nil { + privateKey, keyErr := config.realityPrivateKey() + if keyErr != nil { + err = keyErr + break + } + publicKey, keyErr := ecdh.X25519().NewPublicKey(peerPub) + if keyErr != nil { + err = keyErr + break + } + if hs.AuthKey, err = privateKey.ECDH(publicKey); err != nil { break } if _, err = hkdf.New(sha256.New, hs.AuthKey, hs.clientHello.random[:20], []byte("REALITY")).Read(hs.AuthKey); err != nil { @@ -454,9 +478,6 @@ func RealityServer(ctx context.Context, conn net.Conn, config *RealityConfig) (* } block, _ := aes.NewCipher(hs.AuthKey) aead, _ := cipher.NewGCM(block) - if config.Log != nil { - config.Log("REALITY remoteAddr: %v hs.c.AuthKey[:16]: %v AEAD: %T", remoteAddr, hs.AuthKey[:16], aead) - } ciphertext := make([]byte, 32) plainText := make([]byte, 32) copy(ciphertext, hs.clientHello.sessionId) @@ -471,7 +492,6 @@ func RealityServer(ctx context.Context, conn net.Conn, config *RealityConfig) (* if config.Log != nil { config.Log("REALITY remoteAddr: %v hs.c.ClientVer: %v", remoteAddr, hs.ClientVer) config.Log("REALITY remoteAddr: %v hs.c.ClientTime: %v", remoteAddr, hs.ClientTime) - config.Log("REALITY remoteAddr: %v hs.c.ClientShortId: %v", remoteAddr, hs.ClientShortId) } if (config.MinClientVer == nil || realityValue(hs.ClientVer[:]...) >= realityValue(config.MinClientVer...)) && (config.MaxClientVer == nil || realityValue(hs.ClientVer[:]...) <= realityValue(config.MaxClientVer...)) && @@ -488,6 +508,7 @@ func RealityServer(ctx context.Context, conn net.Conn, config *RealityConfig) (* } mutex.Unlock() if hs.c.conn != conn { + stopHandshake() if config.Log != nil && hs.clientHello != nil { config.Log("REALITY remoteAddr: %v forwarded SNI: %v", remoteAddr, hs.clientHello.serverName) } @@ -497,8 +518,17 @@ func RealityServer(ctx context.Context, conn net.Conn, config *RealityConfig) (* }() go func() { - s2cSaved := make([]byte, 0, realitySize) - buf := make([]byte, realitySize) + savedBlock := realityBufferPool.Get().(*[realitySize]byte) + defer realityBufferPool.Put(savedBlock) + s2cSaved := savedBlock[:0] + readBlock := realityBufferPool.Get().(*[realitySize]byte) + probeOwnsBuffer := false + defer func() { + if !probeOwnsBuffer { + realityBufferPool.Put(readBlock) + } + }() + buf := readBlock[:] handshakeLen := 0 f: for { @@ -581,7 +611,9 @@ func RealityServer(ctx context.Context, conn net.Conn, config *RealityConfig) (* if err != nil { break } + probeOwnsBuffer = true go func() { // TODO: Probe target's maxUselessRecords and some time-outs in advance. + defer realityBufferPool.Put(readBlock) if handshakeLen-len(s2cSaved) > 0 { io.ReadFull(target, buf[:handshakeLen-len(s2cSaved)]) } @@ -609,10 +641,12 @@ func RealityServer(ctx context.Context, conn net.Conn, config *RealityConfig) (* break } hs.c.isHandshakeComplete.Store(true) + stopHandshake() break } mutex.Unlock() if hs.c.out.handshakeLen[0] == 0 { // if the target sent an incorrect Server Hello, or before that + stopHandshake() if hs.c.conn == conn { // if we processed the Client Hello successfully but the target did not waitGroup.Add(1) go func() { diff --git a/reality_guard.go b/reality_guard.go new file mode 100644 index 0000000000..b6308eebb5 --- /dev/null +++ b/reality_guard.go @@ -0,0 +1,72 @@ +package tls + +import ( + "context" + "crypto/ecdh" + "errors" + "net" + "sync" + "time" +) + +var realityBufferPool = sync.Pool{New: func() any { return new([realitySize]byte) }} + +type realityECDHKey struct { + source [32]byte + key *ecdh.PrivateKey +} + +func (c *RealityConfig) realityPrivateKey() (*ecdh.PrivateKey, error) { + if len(c.PrivateKey) != 32 { + return nil, errors.New("REALITY: invalid private key length") + } + source := [32]byte(c.PrivateKey) + if cached := c.ecdhKey.Load(); cached != nil && cached.source == source { + return cached.key, nil + } + key, err := ecdh.X25519().NewPrivateKey(c.PrivateKey) + if err != nil { + return nil, err + } + c.ecdhKey.Store(&realityECDHKey{source: source, key: key}) + return key, nil +} + +func guardRealityHandshake(ctx context.Context, conn, target net.Conn, timeout time.Duration) func() { + if timeout <= 0 { + timeout = 15 * time.Second + } + deadline := time.Now().Add(timeout) + if until, ok := ctx.Deadline(); ok && until.Before(deadline) { + deadline = until + } + _ = conn.SetReadDeadline(deadline) + stopped := make(chan struct{}) + closePending := func() { + select { + case <-stopped: + return + default: + } + _ = conn.Close() + _ = target.Close() + } + timer := time.AfterFunc(time.Until(deadline), closePending) + if ctx.Done() != nil { + go func() { + select { + case <-ctx.Done(): + closePending() + case <-stopped: + } + }() + } + var once sync.Once + return func() { + once.Do(func() { + close(stopped) + timer.Stop() + _ = conn.SetReadDeadline(time.Time{}) + }) + } +} diff --git a/reality_guard_test.go b/reality_guard_test.go new file mode 100644 index 0000000000..66cc1161a5 --- /dev/null +++ b/reality_guard_test.go @@ -0,0 +1,198 @@ +package tls + +import ( + "bytes" + "context" + "crypto/ecdh" + "fmt" + "io" + "net" + "strings" + "sync" + "testing" + "time" + + "github.com/metacubex/utls/internal/ratelimit" + "golang.org/x/crypto/curve25519" +) + +func TestRealitySilentHandshakeTimesOut(t *testing.T) { + for _, cancelled := range []bool{false, true} { + t.Run(fmt.Sprint(cancelled), func(t *testing.T) { + client, server := net.Pipe() + target, peer := net.Pipe() + defer client.Close() + defer peer.Close() + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + config := &RealityConfig{HandshakeTimeout: 30 * time.Millisecond, DialContext: func(context.Context, string, string) (net.Conn, error) { return target, nil }} + done := make(chan error, 1) + go func() { _, err := RealityServer(ctx, server, config); done <- err }() + if cancelled { + cancel() + } + select { + case err := <-done: + if err == nil { + t.Fatal("silent peer authenticated") + } + case <-time.After(time.Second): + t.Fatal("handshake did not close") + } + for _, c := range []net.Conn{client, peer} { + c.SetReadDeadline(time.Now().Add(time.Second)) + if _, err := c.Read(make([]byte, 1)); err != io.EOF { + t.Fatalf("socket retained after handshake: %v", err) + } + } + }) + } +} + +func TestRealityFallbackOutlivesHandshakeTimeout(t *testing.T) { + client, server := net.Pipe() + target, peer := net.Pipe() + done := make(chan struct{}) + config := &RealityConfig{HandshakeTimeout: 100 * time.Millisecond, DialContext: func(context.Context, string, string) (net.Conn, error) { return target, nil }} + go func() { defer close(done); RealityServer(context.Background(), server, config) }() + defer func() { client.Close(); peer.Close(); <-done }() + go func() { + defer peer.Close() + for n := 0; n < 2; n++ { + var data [5]byte + if _, err := io.ReadFull(peer, data[:]); err != nil { + return + } + if _, err := peer.Write(data[:]); err != nil { + return + } + } + }() + client.SetDeadline(time.Now().Add(2 * time.Second)) + for n := 0; n < 2; n++ { + if n == 1 { + time.Sleep(200 * time.Millisecond) + } + if _, err := client.Write([]byte("hello")); err != nil { + t.Fatal(err) + } + var data [5]byte + if _, err := io.ReadFull(client, data[:]); err != nil { + t.Fatal(err) + } + if string(data[:]) != "hello" { + t.Fatal("fallback changed bytes") + } + } +} + +func TestRealityMirrorHonorsReadDeadline(t *testing.T) { + a, b := net.Pipe() + defer a.Close() + defer b.Close() + x, y := net.Pipe() + defer x.Close() + defer y.Close() + m := &realityMirrorConn{Mutex: new(sync.Mutex), Conn: a, Target: x} + if err := m.SetReadDeadline(time.Now()); err != nil { + t.Fatal(err) + } + m.Lock() + _, err := m.Read(make([]byte, 1)) + m.Unlock() + if timeout, ok := err.(net.Error); !ok || !timeout.Timeout() { + t.Fatalf("expected timeout, got %v", err) + } +} + +func TestRealityFallbackFreeThresholdIsExact(t *testing.T) { + raw := &bytesConn{Reader: bytes.NewReader(bytes.Repeat([]byte{'x'}, 32))} + c := &rateLimitedConn{Conn: raw, After: 3, Bucket: ratelimit.NewBucketWithRate(1e9, 32)} + buffer := make([]byte, 32) + if n, err := c.Read(buffer); n != 3 || err != nil { + t.Fatalf("free read crossed threshold: %d, %v", n, err) + } + if c.After != 0 { + t.Fatal("invalid remaining free budget") + } + if n, err := c.Read(buffer); n != 29 || err != nil { + t.Fatalf("limited read: %d, %v", n, err) + } +} + +type bytesConn struct{ *bytes.Reader } + +func (*bytesConn) Write(p []byte) (int, error) { return len(p), nil } +func (*bytesConn) Close() error { return nil } +func (*bytesConn) LocalAddr() net.Addr { return nil } +func (*bytesConn) RemoteAddr() net.Addr { return nil } +func (*bytesConn) SetDeadline(time.Time) error { return nil } +func (*bytesConn) SetReadDeadline(time.Time) error { return nil } +func (*bytesConn) SetWriteDeadline(time.Time) error { return nil } + +func TestRealityPrivateKeyCacheFollowsCloneAndRotation(t *testing.T) { + c := &RealityConfig{PrivateKey: bytes.Repeat([]byte{1}, 32)} + first, err := c.realityPrivateKey() + if err != nil { + t.Fatal(err) + } + clone := c.Clone() + again, err := clone.realityPrivateKey() + if err != nil || again != first { + t.Fatal("clone did not share cached key") + } + clone.PrivateKey = bytes.Repeat([]byte{2}, 32) + rotated, err := clone.realityPrivateKey() + if err != nil || rotated == first { + t.Fatal("rotated clone retained old key") + } + if !bytes.Equal(rotated.Bytes(), clone.PrivateKey) { + t.Fatal("wrong private key after rotation") + } + if original, _ := c.realityPrivateKey(); original != first { + t.Fatal("rotation changed original config") + } +} + +func TestRealityLogsOmitAuthenticationMaterial(t *testing.T) { + target := realityTestBigTarget(t, 8000) + config, pub := newRealityTestConfig(t, target.addr()) + var mu sync.Mutex + var output strings.Builder + config.Log = func(format string, args ...any) { mu.Lock(); defer mu.Unlock(); fmt.Fprintf(&output, format, args...) } + addr := newRealityTestServer(t, config) + conn, _ := realityTestDialShares(t, addr, pub, []CurveID{X25519MLKEM768, X25519}) + defer conn.Close() + mu.Lock() + defer mu.Unlock() + if strings.Contains(output.String(), "AuthKey") || strings.Contains(output.String(), "ClientShortId") { + t.Fatal("authentication material logged") + } +} + +func BenchmarkRealityECDH(b *testing.B) { + c := &RealityConfig{PrivateKey: bytes.Repeat([]byte{1}, 32)} + key, _ := c.realityPrivateKey() + peerBytes := key.PublicKey().Bytes() + b.Run("uncached", func(b *testing.B) { + b.ReportAllocs() + for n := 0; n < b.N; n++ { + if _, err := curve25519.X25519(c.PrivateKey, peerBytes); err != nil { + b.Fatal(err) + } + } + }) + b.Run("cached", func(b *testing.B) { + b.ReportAllocs() + for n := 0; n < b.N; n++ { + k, _ := c.realityPrivateKey() + peer, err := ecdh.X25519().NewPublicKey(peerBytes) + if err != nil { + b.Fatal(err) + } + if _, err := k.ECDH(peer); err != nil { + b.Fatal(err) + } + } + }) +} From 2454432303625ba2504bdddc0bb47b0d94187ab0 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Tue, 20 Oct 2026 20:19:24 +0300 Subject: [PATCH 23/27] fix(reality): release hosting handshake guards on fallback (cherry picked from commit 9c481dd0134be5084407e3c02c6ffd09fe21936e) --- reality_guard.go | 3 +++ reality_guard_test.go | 14 +++++++++++++- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/reality_guard.go b/reality_guard.go index b6308eebb5..e40f7a4bea 100644 --- a/reality_guard.go +++ b/reality_guard.go @@ -67,6 +67,9 @@ func guardRealityHandshake(ctx context.Context, conn, target net.Conn, timeout t close(stopped) timer.Stop() _ = conn.SetReadDeadline(time.Time{}) + if notifier, ok := conn.(interface{ HandshakeComplete() }); ok { + notifier.HandshakeComplete() + } }) } } diff --git a/reality_guard_test.go b/reality_guard_test.go index 66cc1161a5..919e865ae9 100644 --- a/reality_guard_test.go +++ b/reality_guard_test.go @@ -9,6 +9,7 @@ import ( "net" "strings" "sync" + "sync/atomic" "testing" "time" @@ -51,10 +52,11 @@ func TestRealitySilentHandshakeTimesOut(t *testing.T) { func TestRealityFallbackOutlivesHandshakeTimeout(t *testing.T) { client, server := net.Pipe() + notifier := &realityHandshakeNotifier{Conn: server} target, peer := net.Pipe() done := make(chan struct{}) config := &RealityConfig{HandshakeTimeout: 100 * time.Millisecond, DialContext: func(context.Context, string, string) (net.Conn, error) { return target, nil }} - go func() { defer close(done); RealityServer(context.Background(), server, config) }() + go func() { defer close(done); RealityServer(context.Background(), notifier, config) }() defer func() { client.Close(); peer.Close(); <-done }() go func() { defer peer.Close() @@ -83,9 +85,19 @@ func TestRealityFallbackOutlivesHandshakeTimeout(t *testing.T) { if string(data[:]) != "hello" { t.Fatal("fallback changed bytes") } + if notifier.calls.Load() != 1 { + t.Fatal("fallback did not release the hosting listener's handshake guard exactly once") + } } } +type realityHandshakeNotifier struct { + net.Conn + calls atomic.Int32 +} + +func (c *realityHandshakeNotifier) HandshakeComplete() { c.calls.Add(1) } + func TestRealityMirrorHonorsReadDeadline(t *testing.T) { a, b := net.Pipe() defer a.Close() From d0ddc8d11063d976d81df1a119fceea2871bedcf Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Wed, 11 Nov 2026 00:10:18 +0300 Subject: [PATCH 24/27] feat: add HelloChrome_155 and make it HelloChrome_Auto Port the Chrome 155 profile from refraction-networking/utls 6ebdceb2 ("Add Chrome 155 fingerprint verified against a fresh browser capture"), verified there against Chrome 155.0.8059.40. Compared with Chrome 133 the ClientHello gains a GREASE value and the three ML-DSA schemes (0x0904/0x0905/0x0906) in signature_algorithms and the trust_anchors extension (0xca34) with 28 Chrome Root Store IDs. - HelloChrome_155 and its spec; HelloChrome_Auto now points to it, as upstream does. HelloChrome_133 is unchanged. - TrustAnchorsExtension (typed, JSON, Fingerprinter via ExtensionFromID). - GREASE in signature_algorithms drawn from its own BoringSSL seed slot; the internal seed grows to 8 slots while GetBoringGREASEValue keeps its [5]uint16 signature. - MLDSA44/65/87 SignatureScheme constants and dicttls names. Unlike upstream (go 1.27 sync) this fork does not implement ML-DSA, so the codepoints are only advertised. - Upstream tests and the captured ClientHello fixture. Not ported: the ML-DSA handshake test (needs crypto/mldsa) and the preset ownership test (needs upstream's ClientHelloSpec.clone). (cherry picked from commit 540608d73ec927c4a53e4aecf25f9d0176152d6a) --- README.md | 8 + common.go | 6 + common_string.go | 8 + dicttls/exttype_values.go | 23 ++- dicttls/signaturescheme.go | 9 + testdata/chrome155_clienthello.hex | 1 + testdata/chrome155_clienthello.md | 52 +++++ u_chrome155.go | 38 ++++ u_chrome155_test.go | 320 +++++++++++++++++++++++++++++ u_common.go | 6 +- u_conn.go | 2 +- u_grease_api_test.go | 21 ++ u_mldsa_json_test.go | 54 +++++ u_parrots.go | 100 ++++++++- u_tls_extensions.go | 13 +- u_trust_anchors.go | 103 ++++++++++ u_trust_anchors_test.go | 173 ++++++++++++++++ 17 files changed, 916 insertions(+), 21 deletions(-) create mode 100644 testdata/chrome155_clienthello.hex create mode 100644 testdata/chrome155_clienthello.md create mode 100644 u_chrome155.go create mode 100644 u_chrome155_test.go create mode 100644 u_grease_api_test.go create mode 100644 u_mldsa_json_test.go create mode 100644 u_trust_anchors.go create mode 100644 u_trust_anchors_test.go diff --git a/README.md b/README.md index f30b35baf8..1514bfc5c9 100644 --- a/README.md +++ b/README.md @@ -251,8 +251,16 @@ will prepare ClientHello with empty uconn.Extensions so you can fill it with TLS 4. The rest will will parrot given browser. Such parrots include, for example: * `utls.HelloChrome_Auto`- parrots recommended(usually latest) Google Chrome version * `utls.HelloChrome_58` - parrots Google Chrome 58 + * `utls.HelloChrome_155` - parrots a fresh Chrome 155.0.8059.40 connection on macOS * `utls.HelloFirefox_Auto` - parrots recommended(usually latest) Firefox version * `utls.HelloFirefox_55` - parrots Firefox 55 + +`HelloChrome_Auto` currently selects `HelloChrome_155`. This profile includes +GREASE and ML-DSA signature schemes and the 28 trust anchor IDs observed in a +[fresh Chrome capture](testdata/chrome155_clienthello.md). The IDs are a snapshot +of that build's Chrome Root Store; component updates and browser feature settings +can change the ClientHello. `TrustAnchorsExtension` preserves these IDs when +fingerprinting a capture and does not change `Config.RootCAs`. # Usage ## Examples diff --git a/common.go b/common.go index 1d19ee0761..41f1bcf7a2 100644 --- a/common.go +++ b/common.go @@ -447,6 +447,12 @@ const ( // EdDSA algorithms. Ed25519 SignatureScheme = 0x0807 + // ML-DSA algorithms (draft-ietf-tls-mldsa). uTLS only advertises these + // codepoints for ClientHello parroting; it cannot verify ML-DSA signatures. + MLDSA44 SignatureScheme = 0x0904 + MLDSA65 SignatureScheme = 0x0905 + MLDSA87 SignatureScheme = 0x0906 + // Legacy signature and hash algorithms for TLS 1.2. PKCS1WithSHA1 SignatureScheme = 0x0201 ECDSAWithSHA1 SignatureScheme = 0x0203 diff --git a/common_string.go b/common_string.go index 1e868e7162..f9ea4d9639 100644 --- a/common_string.go +++ b/common_string.go @@ -18,6 +18,9 @@ func _() { _ = x[ECDSAWithP384AndSHA384-1283] _ = x[ECDSAWithP521AndSHA512-1539] _ = x[Ed25519-2055] + _ = x[MLDSA44-2308] + _ = x[MLDSA65-2309] + _ = x[MLDSA87-2310] _ = x[PKCS1WithSHA1-513] _ = x[ECDSAWithSHA1-515] } @@ -32,10 +35,12 @@ const ( _SignatureScheme_name_6 = "PKCS1WithSHA512" _SignatureScheme_name_7 = "ECDSAWithP521AndSHA512" _SignatureScheme_name_8 = "PSSWithSHA256PSSWithSHA384PSSWithSHA512Ed25519" + _SignatureScheme_name_9 = "MLDSA44MLDSA65MLDSA87" ) var ( _SignatureScheme_index_8 = [...]uint8{0, 13, 26, 39, 46} + _SignatureScheme_index_9 = [...]uint8{0, 7, 14, 21} ) func (i SignatureScheme) String() string { @@ -59,6 +64,9 @@ func (i SignatureScheme) String() string { case 2052 <= i && i <= 2055: i -= 2052 return _SignatureScheme_name_8[_SignatureScheme_index_8[i]:_SignatureScheme_index_8[i+1]] + case 2308 <= i && i <= 2310: + i -= 2308 + return _SignatureScheme_name_9[_SignatureScheme_index_9[i]:_SignatureScheme_index_9[i+1]] default: return "SignatureScheme(" + strconv.FormatInt(int64(i), 10) + ")" } diff --git a/dicttls/exttype_values.go b/dicttls/exttype_values.go index cb0ef403fc..30cbea8938 100644 --- a/dicttls/exttype_values.go +++ b/dicttls/exttype_values.go @@ -67,11 +67,12 @@ const ( // Not IANA assigned const ( - ExtType_next_protocol_negotiation uint16 = 13172 // https://datatracker.ietf.org/doc/html/draft-agl-tls-nextprotoneg-04 - ExtType_application_settings uint16 = 17513 // https://www.ietf.org/archive/id/draft-vvv-tls-alps-01.html - ExtType_application_settings_new uint16 = 17613 // https://www.ietf.org/archive/id/draft-vvv-tls-alps-01.html - ExtType_channel_id_old uint16 = 30031 // https://datatracker.ietf.org/doc/html/draft-balfanz-tls-channelid-01 - ExtType_channel_id uint16 = 30032 // https://datatracker.ietf.org/doc/html/draft-balfanz-tls-channelid-01 + ExtType_next_protocol_negotiation uint16 = 13172 // https://datatracker.ietf.org/doc/html/draft-agl-tls-nextprotoneg-04 + ExtType_application_settings uint16 = 17513 // https://www.ietf.org/archive/id/draft-vvv-tls-alps-01.html + ExtType_application_settings_new uint16 = 17613 // https://www.ietf.org/archive/id/draft-vvv-tls-alps-01.html + ExtType_channel_id_old uint16 = 30031 // https://datatracker.ietf.org/doc/html/draft-balfanz-tls-channelid-01 + ExtType_channel_id uint16 = 30032 // https://datatracker.ietf.org/doc/html/draft-balfanz-tls-channelid-01 + ExtType_trust_anchors uint16 = 0xca34 // draft-ietf-tls-trust-anchor-ids ) var DictExtTypeValueIndexed = map[uint16]string{ @@ -135,11 +136,12 @@ var DictExtTypeValueIndexed = map[uint16]string{ 59: "dnssec_chain", 65281: "renegotiation_info", - 13172: "next_protocol_negotiation", - 17513: "application_settings", - 17613: "application_settings_new", - 30031: "channel_id_old", - 30032: "channel_id", + 13172: "next_protocol_negotiation", + 17513: "application_settings", + 17613: "application_settings_new", + 30031: "channel_id_old", + 30032: "channel_id", + 0xca34: "trust_anchors", } var DictExtTypeNameIndexed = map[string]uint16{ @@ -209,4 +211,5 @@ var DictExtTypeNameIndexed = map[string]uint16{ "application_settings_new": 17613, "channel_id_old": 30031, "channel_id": 30032, + "trust_anchors": 0xca34, } diff --git a/dicttls/signaturescheme.go b/dicttls/signaturescheme.go index d0b9803f8e..70e5e3dc50 100644 --- a/dicttls/signaturescheme.go +++ b/dicttls/signaturescheme.go @@ -38,6 +38,9 @@ const ( SigScheme_ecdsa_brainpoolP256r1tls13_sha256 uint16 = 0x081A SigScheme_ecdsa_brainpoolP384r1tls13_sha384 uint16 = 0x081B SigScheme_ecdsa_brainpoolP512r1tls13_sha512 uint16 = 0x081C + SigScheme_mldsa44 uint16 = 0x0904 + SigScheme_mldsa65 uint16 = 0x0905 + SigScheme_mldsa87 uint16 = 0x0906 ) var DictSignatureSchemeValueIndexed = map[uint16]string{ @@ -75,6 +78,9 @@ var DictSignatureSchemeValueIndexed = map[uint16]string{ 0x081A: "ecdsa_brainpoolP256r1tls13_sha256", 0x081B: "ecdsa_brainpoolP384r1tls13_sha384", 0x081C: "ecdsa_brainpoolP512r1tls13_sha512", + 0x0904: "mldsa44", + 0x0905: "mldsa65", + 0x0906: "mldsa87", } var DictSignatureSchemeNameIndexed = map[string]uint16{ @@ -113,4 +119,7 @@ var DictSignatureSchemeNameIndexed = map[string]uint16{ "ecdsa_brainpoolP256r1tls13_sha256": 0x081A, "ecdsa_brainpoolP384r1tls13_sha384": 0x081B, "ecdsa_brainpoolP512r1tls13_sha512": 0x081C, + "mldsa44": 0x0904, + "mldsa65": 0x0905, + "mldsa87": 0x0906, } diff --git a/testdata/chrome155_clienthello.hex b/testdata/chrome155_clienthello.hex new file mode 100644 index 0000000000..1d31499a84 --- /dev/null +++ b/testdata/chrome155_clienthello.hex @@ -0,0 +1 @@ +160301079e0100079a030397ba84e6911f26dc308204a2e65a2264ea769abc71617e9832e8a05327e2c03f20130452c827a0b862598e1f621324a0887d19f386284186f43e136844ed39fbb200201a1a130113021303c02bc02fc02cc030cca9cca8c013c014009c009d002f003501000731fafa000000120000ca3400ba00b80582df1302010582df1302060582df13020d0582df13020e0582df13020f0582df1302120582df1302130582df13021408839a648c9b2d010708839a648c9b2d010808839a648c9b2d010908839a648c9b2d010a08839a648c9b2d010b08839a648c9b2d010c08839a648c9b2d010d08839a648c9b2d011208839a648c9b2d011304d679090104d679090404d679090504d679090604d679090704d679090804d679090a04d679090b04d679090c04d679090d04d679090ffe0d00da00000100014200200b81d7a0c9bb3d4482028d5f90d7ed4f702aa257f7621d379be6d154251e745b00b0573e4731d509ac8e562a21f30236277f71fef7f0bd518c2c9916022a74afcb7d4d6145d72ee33f2f3720f85df5d6840bf3ce4dde5bc3efdacda6d4116add75ced6fa8c993692791f9437400ea835ff5f57776025cc7ff2828a93fff832dc24a1e394cf503813d67c4f45b0580f68d16fcaf5d774ac28a4bedac83733318c7cca132bebd041bba4077e53f51a2e30018559b2ed802ecf7398d369ab3090b8c4eb257b197631fad183682d83c8b40f82be001b0003020002000a000c000a7a7a11ec001d00170018ff0100010000230000002b0007065a5a030403030010000e000c02683208687474702f312e31000b00020100003304ef04ed7a7a00010011ec04c049c251fae6095e3992e4517d82ba97a8c7a789c66f450b0d9c3579870445f17856d8e0c53dfb643fe54032044236154d1fd722e7f6c3bf3606e84a68775638e765a7fdb85672dc3768941eaf232a55b229fe58cb41e35683b0532ff873249acd08ac19f79091c1acb54c53459d9ca31ac998ca6a67f172a1ef9b839151797e78589ca4aee75056be454adb070f6622577abc664b353fbc2272bf4c8cea7724dad8bfa0617d21555e3d0b69de388505b01d00ec263334c535c99699b20d8cd741f48646aea8c519334623ab33ea990701d7c400e48415da30a468953d5bbdc684aa78f1aca5c591a1805b69a786257099f5a02a833339bb9794dccc40b9188dd189596039623d76534ac1481e695b38974c5738a8107a16f5d4c19cd51d52c70bde8566b8500c73bba0e55ba09e067c6d3c76ddb99ae7da0fb7950d344bc86b1ac36827ae483a0ded32be2f897f66b96100440f6e148be9c19a3c1c7504e01eef443d4a674043e41f4f3c70029801a756227e5c95041053138472b19a103d95807ec57c02316499e72362642fe0c418c2306cdfb44dee570bc2783596a1464d5a16e4d59cb1bcb967e4459ce0430787141b547abeda15c418acd2f095addac18866cd99b2c70b3087c1b070f95320853a33b3d4bf9edca3cdf2b4a96c74154b57aab782d3e97d1801b95c2b586b7a0ca38bafc4d987ee600585ac8c359bc9c89997ed1231d87b28c0e32f90e16778a29cc2d3c4dbea79db389df497cf2210bd4dd46d7d21a6b3b683eb040bfca87019ec921b3a3ae7f20eb90a95449b70c2740fe4ea2c16e1c01ba5367676b48f58a6d7d657a52c61737b1671214b1210252107b441cc5c968a998616a77047a3d7516f28ac92438287b6bb178024566ce4a1b6f11efe9abb73894605b313567c60693c13f156a6fb55304134007c69128249a381281099a50cd18b0873a1697045bc8224bec2f87e4b09002703766e87b2c8845f56a7b77385562f41644710a36f9388fb4ab1311482b61c056b171919b3ac3b8cbf38e1971686ceead326e4654ded168b8ed8064b3032f23a7793c51700b9ba0cfbbc39390f3c82256898bb1933c1fec6cae242772e7b4076a6cf0d996c7cb6960930bea5a384083a18c00883ced91206c6401fb45b75fb44d073726d5bcaeffabd077705816c7ec7b03b0468a1f7238c660ac5f34b86b12968338c2817f45197cb04c5db396c4a13dc6a104663b57f43bad5063591c63d9cac2a199885a048809246bbd20191f211080d7286c7b61525382dada5ab9c175913cc0c9a011c4217575d1756d1e4b6b1da94b8cc1321a269d0310eb0374fe4bb39e41673d7742f335191290aaf3ec846a0d209546a97707938b3a307fe191599b59b26e1cfc92b6c69818a8de06c6e6215ce20c1057a8f7ed6912a5a89d64447aaa5b3b5a27cd41b8715fb44a502697e3185ca005077a194cfd2ce4b44cc3d5c7538e60718e90247ac1912329bf8e7c7e03078601b93a11163d5b0c1b34b1358608dfc282ebc18bd20f5a35c610e59c09f200875f05c10de1c7f27dc050296a49d4a03469c365f16a9b9a6c5def522832718e8022440019ad0d662237bb3535b912fab358c9a89fc944c201afe4a3c4d65837b31e2eb034759da63d960226e2669b646b549d3161427956172e60d876d0353ab787ac5cad550790a65ef062efbbf97f65f1cf62d001d0020d6b7a093831d73daf8e2aa6d7106321215cce52e6d14c408a0dafe217a207654000d001a0018aaaa0904090509060403080404010503080505010806060100170000002d0002010100050005010000000000000014001200000f7777772e6578616d706c652e636f6d44cd00050003026832caca000100 diff --git a/testdata/chrome155_clienthello.md b/testdata/chrome155_clienthello.md new file mode 100644 index 0000000000..9ecc533c7c --- /dev/null +++ b/testdata/chrome155_clienthello.md @@ -0,0 +1,52 @@ +# Chrome 155 ClientHello fixture + +`chrome155_clienthello.hex` is the complete first TLS record from a fresh HTTPS +connection made by official, branded Google Chrome 155.0.8059.40 on macOS arm64 +on October 6, 2026. The browser version was checked in `chrome://version`. +The browser ran with a new dedicated profile, no TLS feature overrides, and QUIC +disabled so that the HTTPS connection used TCP. The page was opened through +native computer use at `https://www.example.com/`. + +Wireshark's `dumpcap` recorded the connection, and `tshark` extracted TCP stream +0's ClientHello. The original TLS keylog was used separately to verify that the +connection completed a full TLS 1.3 handshake. Neither the keylog nor the +certificate/application traffic is included in this fixture. + +The retained record is 1,955 bytes; its ClientHello handshake is 1,950 bytes. +SHA-256 of the decoded ClientHello handshake (excluding the five-byte TLS record +header): + +``` +235618e3922e52a71a9f6593a71ec4ca182dab6b3ab4e90a2a1733133e97439a +``` + +The original capture showed a new TCP SYN in frame 1, SYN/ACK in frame 3, and +ClientHello in frame 6. The ClientHello contains an empty `session_ticket` and +no `pre_shared_key`. The ServerHello in frame 13 selected TLS 1.3 and +`TLS_AES_128_GCM_SHA256`, without selecting a PSK. The decrypted server flight +in frame 19 contains EncryptedExtensions, CompressedCertificate, +CertificateVerify, and Finished; the client Finished follows in frame 21. +NewSessionTickets appear later in frame 35 and do not indicate resumption of +this connection. Chrome also opened an independent, fresh parallel connection +in stream 1, which completed a full handshake. + +The profile advertises 28 trust anchor IDs in the captured order, three ML-DSA +signature schemes preceded by GREASE, X25519MLKEM768 and X25519 key shares, and +the new ALPS codepoint. The TLS server-padding extension is absent from this +normal Chrome capture. + +Extraction command, using the original capture filename: + +```sh +tshark -r chrome155-example.pcapng \ + -Y 'tcp.stream == 0 && tls.handshake.type == 1' \ + -T fields -e tcp.reassembled.data > chrome155_clienthello.hex +``` + +`u_chrome155_test.go` compares this independent browser capture with the generated +profile. It ignores only randomized extension permutation, GREASE codepoints, +ephemeral key material, and GREASE ECH config/key/payload randomness. The ECH +payload length must belong to BoringSSL's 144/176/208/240-byte family. Cipher, +signature, group, version, ALPN, key-share group/length, and trust-anchor list +order remain significant; other extension bodies are compared exactly. The +same fixture also exercises default Fingerprinter parsing and regeneration. diff --git a/u_chrome155.go b/u_chrome155.go new file mode 100644 index 0000000000..c41b1c8495 --- /dev/null +++ b/u_chrome155.go @@ -0,0 +1,38 @@ +package tls + +// chrome155TrustAnchorIDs returns the Chrome Root Store IDs advertised by a fresh +// Google Chrome 155.0.8059.40 (macOS) connection. Chrome encodes the IDs in +// lexicographic order. Return fresh slices because ClientHelloSpec is mutable. +// Source: https://chromium.googlesource.com/chromium/src/+/refs/tags/155.0.8059.40/net/data/ssl/chrome_root_store/root_store.textproto +func chrome155TrustAnchorIDs() [][]byte { + return [][]byte{ + {0x82, 0xdf, 0x13, 0x02, 0x01}, + {0x82, 0xdf, 0x13, 0x02, 0x06}, + {0x82, 0xdf, 0x13, 0x02, 0x0d}, + {0x82, 0xdf, 0x13, 0x02, 0x0e}, + {0x82, 0xdf, 0x13, 0x02, 0x0f}, + {0x82, 0xdf, 0x13, 0x02, 0x12}, + {0x82, 0xdf, 0x13, 0x02, 0x13}, + {0x82, 0xdf, 0x13, 0x02, 0x14}, + {0x83, 0x9a, 0x64, 0x8c, 0x9b, 0x2d, 0x01, 0x07}, + {0x83, 0x9a, 0x64, 0x8c, 0x9b, 0x2d, 0x01, 0x08}, + {0x83, 0x9a, 0x64, 0x8c, 0x9b, 0x2d, 0x01, 0x09}, + {0x83, 0x9a, 0x64, 0x8c, 0x9b, 0x2d, 0x01, 0x0a}, + {0x83, 0x9a, 0x64, 0x8c, 0x9b, 0x2d, 0x01, 0x0b}, + {0x83, 0x9a, 0x64, 0x8c, 0x9b, 0x2d, 0x01, 0x0c}, + {0x83, 0x9a, 0x64, 0x8c, 0x9b, 0x2d, 0x01, 0x0d}, + {0x83, 0x9a, 0x64, 0x8c, 0x9b, 0x2d, 0x01, 0x12}, + {0x83, 0x9a, 0x64, 0x8c, 0x9b, 0x2d, 0x01, 0x13}, + {0xd6, 0x79, 0x09, 0x01}, + {0xd6, 0x79, 0x09, 0x04}, + {0xd6, 0x79, 0x09, 0x05}, + {0xd6, 0x79, 0x09, 0x06}, + {0xd6, 0x79, 0x09, 0x07}, + {0xd6, 0x79, 0x09, 0x08}, + {0xd6, 0x79, 0x09, 0x0a}, + {0xd6, 0x79, 0x09, 0x0b}, + {0xd6, 0x79, 0x09, 0x0c}, + {0xd6, 0x79, 0x09, 0x0d}, + {0xd6, 0x79, 0x09, 0x0f}, + } +} diff --git a/u_chrome155_test.go b/u_chrome155_test.go new file mode 100644 index 0000000000..cf1f491c18 --- /dev/null +++ b/u_chrome155_test.go @@ -0,0 +1,320 @@ +// Copyright 2026 The uTLS Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +package tls + +import ( + "bytes" + "encoding/hex" + "fmt" + "net" + "os" + "reflect" + "slices" + "sort" + "strings" + "testing" +) + +// This parser is deliberately independent of Fingerprinter: comparing the +// captured browser bytes against generated bytes must not hide a parser bug. +// Only extension permutation, GREASE codepoints, ephemeral public keys, and +// GREASE ECH randomness are normalized. Ordered capability lists and trust +// anchor IDs retain their original order and bytes. +type chrome155WireHello struct { + Version uint16 + RandomLength int + SessionIDLength int + CipherSuites []uint16 + CompressionMethods []byte + Extensions map[uint16][]string +} + +type chrome155Reader struct { + t *testing.T + b []byte + label string +} + +func (r *chrome155Reader) take(n int) []byte { + r.t.Helper() + if n < 0 || n > len(r.b) { + r.t.Fatalf("%s: truncated field: need %d bytes, have %d", r.label, n, len(r.b)) + } + b := r.b[:n] + r.b = r.b[n:] + return b +} + +func (r *chrome155Reader) number(n int) int { + r.t.Helper() + v := 0 + for _, b := range r.take(n) { + v = v<<8 | int(b) + } + return v +} + +func (r *chrome155Reader) vector(n int) []byte { + r.t.Helper() + return r.take(r.number(n)) +} + +func (r *chrome155Reader) end() { + r.t.Helper() + if len(r.b) != 0 { + r.t.Fatalf("%s: %d trailing bytes", r.label, len(r.b)) + } +} + +func chrome155NormalizeGREASE(v uint16) uint16 { + if isGREASEUint16(v) { + return GREASE_PLACEHOLDER + } + return v +} + +func chrome155Uint16s(t *testing.T, b []byte) []uint16 { + t.Helper() + if len(b)%2 != 0 { + t.Fatalf("odd uint16 vector length: %d", len(b)) + } + out := make([]uint16, len(b)/2) + for i := range out { + out[i] = chrome155NormalizeGREASE(uint16(b[2*i])<<8 | uint16(b[2*i+1])) + } + return out +} + +func chrome155NormalizeExtension(t *testing.T, id uint16, body []byte) string { + t.Helper() + r := chrome155Reader{t, body, fmt.Sprintf("extension %#04x", id)} + var value string + switch id { + case 10, 13: // supported_groups, signature_algorithms + value = fmt.Sprint(chrome155Uint16s(t, r.vector(2))) + case 43: // supported_versions + value = fmt.Sprint(chrome155Uint16s(t, r.vector(1))) + case 51: // key_share + shares := chrome155Reader{t, r.vector(2), "key_share entries"} + var entries []string + for len(shares.b) > 0 { + group := uint16(shares.number(2)) + key := shares.vector(2) + entry := fmt.Sprintf("%04x/%d", chrome155NormalizeGREASE(group), len(key)) + if isGREASEUint16(group) { + entry += "/" + hex.EncodeToString(key) + } + entries = append(entries, entry) + } + value = strings.Join(entries, ",") + case 0xfe0d: // GREASE encrypted_client_hello + outer, kdf, aead := r.number(1), r.number(2), r.number(2) + r.take(1) // randomized config_id + enc, payload := r.vector(2), r.vector(2) + if outer != 0 || !slices.Contains([]int{144, 176, 208, 240}, len(payload)) { + t.Fatalf("unexpected GREASE ECH shape: outer=%d, payload length=%d", outer, len(payload)) + } + value = fmt.Sprintf("%d/%d/%d/enc=%d/payload=144,176,208,240", outer, kdf, aead, len(enc)) + case 0xca34: // trust_anchors + ids := chrome155Reader{t, r.vector(2), "trust anchor IDs"} + for len(ids.b) > 0 { + if len(ids.vector(1)) == 0 { + t.Fatal("empty trust anchor ID in fixture") + } + } + value = hex.EncodeToString(body) + default: + value = hex.EncodeToString(r.take(len(r.b))) + } + r.end() + return value +} + +func chrome155ParseWire(t *testing.T, data []byte) (chrome155WireHello, []uint16, map[uint16][]byte) { + t.Helper() + r := chrome155Reader{t, data, "ClientHello"} + if len(data) > 0 && data[0] == byte(recordTypeHandshake) { + if r.number(1) != int(recordTypeHandshake) || r.number(2) != int(VersionTLS10) { + t.Fatal("unexpected ClientHello TLS record header") + } + record := r.vector(2) + r.end() + r = chrome155Reader{t, record, "ClientHello handshake"} + } + if r.number(1) != 1 { + t.Fatal("fixture is not a ClientHello") + } + body := r.vector(3) + r.end() + r = chrome155Reader{t, body, "ClientHello body"} + version := uint16(r.number(2)) + random := r.take(32) + sid := r.vector(1) + ciphers := chrome155Uint16s(t, r.vector(2)) + compression := bytes.Clone(r.vector(1)) + extensions := r.vector(2) + r.end() + out := chrome155WireHello{version, len(random), len(sid), ciphers, compression, make(map[uint16][]string)} + r = chrome155Reader{t, extensions, "ClientHello extensions"} + seen, raw := make(map[uint16]bool), make(map[uint16][]byte) + var order []uint16 + for len(r.b) > 0 { + id := uint16(r.number(2)) + body := r.vector(2) + if seen[id] { + t.Fatalf("duplicate extension %#04x", id) + } + seen[id] = true + raw[id] = bytes.Clone(body) + normalizedID := chrome155NormalizeGREASE(id) + order = append(order, normalizedID) + out.Extensions[normalizedID] = append(out.Extensions[normalizedID], chrome155NormalizeExtension(t, id, body)) + } + for _, values := range out.Extensions { + sort.Strings(values) // distinguish the two GREASE bodies independently of their values + } + return out, order, raw +} + +func chrome155Fixture(t *testing.T) []byte { + t.Helper() + text, err := os.ReadFile("testdata/chrome155_clienthello.hex") + if err != nil { + t.Fatal(err) + } + data, err := hex.DecodeString(strings.Join(strings.Fields(string(text)), "")) + if err != nil { + t.Fatal(err) + } + return data +} + +func chrome155FixtureServerName(t *testing.T, raw map[uint16][]byte) string { + t.Helper() + r := chrome155Reader{t, raw[0], "server_name"} + names := chrome155Reader{t, r.vector(2), "server_name list"} + r.end() + if names.number(1) != 0 { + t.Fatal("fixture SNI is not a host name") + } + name := string(names.vector(2)) + names.end() + return name +} + +func chrome155Build(t *testing.T, id ClientHelloID, serverName string, spec *ClientHelloSpec) *UConn { + t.Helper() + client := UClient(&net.TCPConn{}, &Config{ServerName: serverName, ClientSessionCache: nil}, id) + if spec != nil { + if err := client.ApplyPreset(spec); err != nil { + t.Fatal(err) + } + } + if err := client.BuildHandshakeState(); err != nil { + t.Fatal(err) + } + return client +} + +func chrome155CompareWire(t *testing.T, want, got chrome155WireHello) { + t.Helper() + if !reflect.DeepEqual(got, want) { + t.Errorf("generated ClientHello differs from fresh Chrome 155 capture:\n got: %+v\nwant: %+v", got, want) + } +} + +func TestChrome155CapturedClientHello(t *testing.T) { + if HelloChrome_Auto != HelloChrome_155 { + t.Fatalf("HelloChrome_Auto = %s, want %s", HelloChrome_Auto.Str(), HelloChrome_155.Str()) + } + want, _, captured := chrome155ParseWire(t, chrome155Fixture(t)) + client := chrome155Build(t, HelloChrome_155, chrome155FixtureServerName(t, captured), nil) + got, _, generated := chrome155ParseWire(t, client.HandshakeState.Hello.Raw) + chrome155CompareWire(t, want, got) + if ticket, ok := generated[35]; !ok || len(ticket) != 0 { + t.Fatal("fresh profile must advertise an empty session_ticket extension") + } + if _, ok := generated[41]; ok { + t.Fatal("fresh profile unexpectedly offers pre_shared_key") + } +} + +func TestChrome155DefaultFingerprintRoundTrip(t *testing.T) { + fixture := chrome155Fixture(t) + want, wantOrder, raw := chrome155ParseWire(t, fixture) + spec, err := (&Fingerprinter{}).FingerprintClientHello(fixture) + if err != nil { + t.Fatalf("default Fingerprinter must parse captured Chrome 155 ClientHello: %v", err) + } + client := chrome155Build(t, HelloCustom, chrome155FixtureServerName(t, raw), spec) + got, gotOrder, _ := chrome155ParseWire(t, client.HandshakeState.Hello.Raw) + chrome155CompareWire(t, want, got) + if !slices.Equal(gotOrder, wantOrder) { + t.Errorf("fingerprint roundtrip reordered extensions: got %x, want %x", gotOrder, wantOrder) + } + if chrome155TrustAnchors(t, spec.Extensions) == nil { + t.Fatal("fingerprinted trust anchors must use the typed extension") + } +} + +func chrome155TrustAnchors(t *testing.T, extensions []TLSExtension) *TrustAnchorsExtension { + t.Helper() + for _, extension := range extensions { + if anchors, ok := extension.(*TrustAnchorsExtension); ok { + return anchors + } + } + t.Fatal("missing typed trust_anchors extension") + return nil +} + +func TestChrome155SignatureGREASESeed(t *testing.T) { + client := UClient(&net.TCPConn{}, &Config{ + ServerName: "example.com", + Rand: &incrementingSource{next: 0x81}, + }, HelloChrome_155) + if err := client.BuildHandshakeState(); err != nil { + t.Fatal(err) + } + // BoringSSL reserves seed slot 7 for signature algorithms, independently + // of the cipher, group, extension, and version GREASE slots. + const signatureSeedSlot = 7 + seed := client.greaseSeed[signatureSeedSlot] + want := (seed & 0xf0) | 0x0a + want |= want << 8 + if want == GREASE_PLACEHOLDER { + t.Fatal("deterministic test seed must distinguish generated GREASE from the placeholder") + } + _, _, raw := chrome155ParseWire(t, client.HandshakeState.Hello.Raw) + r := chrome155Reader{t, raw[13], "signature_algorithms"} + signatures := chrome155Reader{t, r.vector(2), "signature schemes"} + r.end() + got := uint16(signatures.number(2)) + if got != want || got == GREASE_PLACEHOLDER { + t.Fatalf("signature GREASE = %#04x, want %#04x from BoringSSL seed slot 7", got, want) + } + if gotState := uint16(client.HandshakeState.Hello.SupportedSignatureAlgorithms[0]); gotState != want { + t.Fatalf("signature GREASE in handshake state = %#04x, want %#04x", gotState, want) + } +} + +func TestChrome133CapabilitiesPreserved(t *testing.T) { + client := chrome155Build(t, HelloChrome_133, "example.com", nil) + _, _, raw := chrome155ParseWire(t, client.HandshakeState.Hello.Raw) + r := chrome155Reader{t, raw[13], "Chrome 133 signature_algorithms"} + got := chrome155Uint16s(t, r.vector(2)) + r.end() + want := []uint16{ + uint16(ECDSAWithP256AndSHA256), uint16(PSSWithSHA256), uint16(PKCS1WithSHA256), + uint16(ECDSAWithP384AndSHA384), uint16(PSSWithSHA384), uint16(PKCS1WithSHA384), + uint16(PSSWithSHA512), uint16(PKCS1WithSHA512), + } + if !slices.Equal(got, want) { + t.Fatalf("Chrome 133 signature schemes changed: got %x, want original classical schemes %x", got, want) + } + if _, ok := raw[0xca34]; ok { + t.Fatal("Chrome 155 trust anchor IDs leaked into the Chrome 133 profile") + } +} diff --git a/u_common.go b/u_common.go index a4db5df94a..dd13498496 100644 --- a/u_common.go +++ b/u_common.go @@ -41,6 +41,7 @@ const ( utlsFakeExtensionCustom uint16 = 1234 // not IANA assigned, for ALPS utlsExtensionECH uint16 = 0xfe0d // draft-ietf-tls-esni-17 utlsExtensionECHOuterExtensions uint16 = 0xfd00 // draft-ietf-tls-esni-17 + utlsExtensionTrustAnchors uint16 = 0xca34 // draft-ietf-tls-trust-anchor-ids // extensions with 'fake' prefix break connection, if server echoes them back fakeExtensionEncryptThenMAC uint16 = 22 @@ -626,7 +627,7 @@ var ( HelloFirefox_120 = ClientHelloID{helloFirefox, "120", nil, nil} HelloFirefox_148 = ClientHelloID{helloFirefox, "148", nil, nil} - HelloChrome_Auto = HelloChrome_133 + HelloChrome_Auto = HelloChrome_155 HelloChrome_58 = ClientHelloID{helloChrome, "58", nil, nil} HelloChrome_62 = ClientHelloID{helloChrome, "62", nil, nil} HelloChrome_70 = ClientHelloID{helloChrome, "70", nil, nil} @@ -658,6 +659,9 @@ var ( HelloChrome_131 = ClientHelloID{helloChrome, "131", nil, nil} // Chrome w/ New ALPS codepoint HelloChrome_133 = ClientHelloID{helloChrome, "133", nil, nil} + // Chrome 155.0.8059.40 on macOS, with ML-DSA signatures and a snapshot of + // the Chrome Root Store trust anchor IDs. See testdata/chrome155_clienthello.md. + HelloChrome_155 = ClientHelloID{helloChrome, "155", nil, nil} HelloIOS_Auto = HelloIOS_14 HelloIOS_11_1 = ClientHelloID{helloIOS, "111", nil, nil} // legacy "111" means 11.1 diff --git a/u_conn.go b/u_conn.go index 55334dc55b..e89d4ded0d 100644 --- a/u_conn.go +++ b/u_conn.go @@ -38,7 +38,7 @@ type UConn struct { HandshakeState PubClientHandshakeState - greaseSeed [ssl_grease_last_index]uint16 + greaseSeed [ssl_grease_seed_count]uint16 omitSNIExtension bool diff --git a/u_grease_api_test.go b/u_grease_api_test.go new file mode 100644 index 0000000000..d2088bb628 --- /dev/null +++ b/u_grease_api_test.go @@ -0,0 +1,21 @@ +package tls_test + +import ( + "testing" + + tls "github.com/metacubex/utls" +) + +// The public helper's five-element array remains source-compatible when the +// internal GREASE seed gains slots for additional ClientHello fields. +var _ func([5]uint16, int) uint16 = tls.GetBoringGREASEValue + +func TestBoringGREASEPublicAPI(t *testing.T) { + seed := [5]uint16{0x0000, 0x0012, 0x0080, 0x00f0, 0xffe1} + want := [5]uint16{0x0a0a, 0x1a1a, 0x8a8a, 0xfafa, 0xeaea} + for i, expected := range want { + if got := tls.GetBoringGREASEValue(seed, i); got != expected { + t.Fatalf("GREASE index %d = %#04x; want %#04x", i, got, expected) + } + } +} diff --git a/u_mldsa_json_test.go b/u_mldsa_json_test.go new file mode 100644 index 0000000000..a660e89eca --- /dev/null +++ b/u_mldsa_json_test.go @@ -0,0 +1,54 @@ +package tls + +import ( + "encoding/json" + "fmt" + "slices" + "testing" + + "github.com/metacubex/utls/dicttls" +) + +func TestMLDSASignatureSchemeJSON(t *testing.T) { + for _, tc := range []struct { + name string + scheme SignatureScheme + }{ + {"mldsa44", MLDSA44}, + {"mldsa65", MLDSA65}, + {"mldsa87", MLDSA87}, + } { + if got := dicttls.DictSignatureSchemeNameIndexed[tc.name]; got != uint16(tc.scheme) { + t.Fatalf("signature scheme %s = %#04x, want %#04x", tc.name, got, tc.scheme) + } + if got := dicttls.DictSignatureSchemeValueIndexed[uint16(tc.scheme)]; got != tc.name { + t.Fatalf("signature scheme %#04x = %s, want %s", tc.scheme, got, tc.name) + } + } + for _, name := range []string{"signature_algorithms", "signature_algorithms_cert"} { + t.Run(name, func(t *testing.T) { + data := fmt.Sprintf(`[{"name":%q,"supported_signature_algorithms":["GREASE","mldsa44","mldsa65","mldsa87"]}]`, name) + var extensions TLSExtensionsJSONUnmarshaler + if err := json.Unmarshal([]byte(data), &extensions); err != nil { + t.Fatal(err) + } + exts := extensions.Extensions() + if len(exts) != 1 { + t.Fatalf("parsed %d extensions, want 1", len(exts)) + } + var got []SignatureScheme + switch ext := exts[0].(type) { + case *SignatureAlgorithmsExtension: + got = ext.SupportedSignatureAlgorithms + case *SignatureAlgorithmsCertExtension: + got = ext.SupportedSignatureAlgorithms + default: + t.Fatalf("unexpected extension type %T", ext) + } + want := []SignatureScheme{GREASE_PLACEHOLDER, MLDSA44, MLDSA65, MLDSA87} + if !slices.Equal(got, want) { + t.Fatalf("signature algorithms = %x, want %x", got, want) + } + }) + } +} diff --git a/u_parrots.go b/u_parrots.go index 425ab6ddda..bbe9739b2e 100644 --- a/u_parrots.go +++ b/u_parrots.go @@ -964,6 +964,84 @@ func utlsIdToSpec(id ClientHelloID) (ClientHelloSpec, error) { &UtlsGREASEExtension{}, }), }, nil + case HelloChrome_155: + return ClientHelloSpec{ + CipherSuites: []uint16{ + GREASE_PLACEHOLDER, + TLS_AES_128_GCM_SHA256, + TLS_AES_256_GCM_SHA384, + TLS_CHACHA20_POLY1305_SHA256, + TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, + TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, + TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, + TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, + TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305, + TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305, + TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, + TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, + TLS_RSA_WITH_AES_128_GCM_SHA256, + TLS_RSA_WITH_AES_256_GCM_SHA384, + TLS_RSA_WITH_AES_128_CBC_SHA, + TLS_RSA_WITH_AES_256_CBC_SHA, + }, + CompressionMethods: []byte{ + 0x00, // compressionNone + }, + Extensions: ShuffleChromeTLSExtensions([]TLSExtension{ + &UtlsGREASEExtension{}, + &SNIExtension{}, + &ExtendedMasterSecretExtension{}, + &RenegotiationInfoExtension{Renegotiation: RenegotiateOnceAsClient}, + &SupportedCurvesExtension{[]CurveID{ + GREASE_PLACEHOLDER, + X25519MLKEM768, + X25519, + CurveP256, + CurveP384, + }}, + &SupportedPointsExtension{SupportedPoints: []byte{ + 0x00, // pointFormatUncompressed + }}, + &SessionTicketExtension{}, + &ALPNExtension{AlpnProtocols: []string{"h2", "http/1.1"}}, + &StatusRequestExtension{}, + &SignatureAlgorithmsExtension{SupportedSignatureAlgorithms: []SignatureScheme{ + GREASE_PLACEHOLDER, + MLDSA44, + MLDSA65, + MLDSA87, + ECDSAWithP256AndSHA256, + PSSWithSHA256, + PKCS1WithSHA256, + ECDSAWithP384AndSHA384, + PSSWithSHA384, + PKCS1WithSHA384, + PSSWithSHA512, + PKCS1WithSHA512, + }}, + &SCTExtension{}, + &KeyShareExtension{[]KeyShare{ + {Group: CurveID(GREASE_PLACEHOLDER), Data: []byte{0}}, + {Group: X25519MLKEM768}, + {Group: X25519}, + }}, + &PSKKeyExchangeModesExtension{[]uint8{ + PskModeDHE, + }}, + &SupportedVersionsExtension{[]uint16{ + GREASE_PLACEHOLDER, + VersionTLS13, + VersionTLS12, + }}, + &UtlsCompressCertExtension{[]CertCompressionAlgo{ + CertCompressionBrotli, + }}, + &ApplicationSettingsExtensionNew{SupportedProtocols: []string{"h2"}}, + &TrustAnchorsExtension{TrustAnchorIDs: chrome155TrustAnchorIDs()}, + BoringGREASEECH(), + &UtlsGREASEExtension{}, + }), + }, nil case HelloFirefox_55, HelloFirefox_56: return ClientHelloSpec{ TLSVersMax: VersionTLS12, @@ -3064,7 +3142,7 @@ func (uconn *UConn) ApplyPreset(p *ClientHelloSpec) error { } // Currently, GREASE is assumed to come from BoringSSL - grease_bytes := make([]byte, 2*ssl_grease_last_index) + grease_bytes := make([]byte, 2*ssl_grease_seed_count) grease_extensions_seen := 0 _, err = io.ReadFull(uconn.config.rand(), grease_bytes) if err != nil { @@ -3073,7 +3151,7 @@ func (uconn *UConn) ApplyPreset(p *ClientHelloSpec) error { for i := range uconn.greaseSeed { uconn.greaseSeed[i] = binary.LittleEndian.Uint16(grease_bytes[2*i : 2*i+2]) } - if GetBoringGREASEValue(uconn.greaseSeed, ssl_grease_extension1) == GetBoringGREASEValue(uconn.greaseSeed, ssl_grease_extension2) { + if getBoringGREASEValue(uconn.greaseSeed[:], ssl_grease_extension1) == getBoringGREASEValue(uconn.greaseSeed[:], ssl_grease_extension2) { uconn.greaseSeed[ssl_grease_extension2] ^= 0x1010 } @@ -3081,7 +3159,7 @@ func (uconn *UConn) ApplyPreset(p *ClientHelloSpec) error { copy(hello.CipherSuites, p.CipherSuites) for i := range hello.CipherSuites { if isGREASEUint16(hello.CipherSuites[i]) { // just in case the user set a GREASE value instead of unGREASEd - hello.CipherSuites[i] = GetBoringGREASEValue(uconn.greaseSeed, ssl_grease_cipher) + hello.CipherSuites[i] = getBoringGREASEValue(uconn.greaseSeed[:], ssl_grease_cipher) } } @@ -3117,9 +3195,9 @@ func (uconn *UConn) ApplyPreset(p *ClientHelloSpec) error { case *UtlsGREASEExtension: switch grease_extensions_seen { case 0: - ext.Value = GetBoringGREASEValue(uconn.greaseSeed, ssl_grease_extension1) + ext.Value = getBoringGREASEValue(uconn.greaseSeed[:], ssl_grease_extension1) case 1: - ext.Value = GetBoringGREASEValue(uconn.greaseSeed, ssl_grease_extension2) + ext.Value = getBoringGREASEValue(uconn.greaseSeed[:], ssl_grease_extension2) ext.Body = []byte{0} default: return errors.New("at most 2 grease extensions are supported") @@ -3128,7 +3206,13 @@ func (uconn *UConn) ApplyPreset(p *ClientHelloSpec) error { case *SupportedCurvesExtension: for i := range ext.Curves { if isGREASEUint16(uint16(ext.Curves[i])) { - ext.Curves[i] = CurveID(GetBoringGREASEValue(uconn.greaseSeed, ssl_grease_group)) + ext.Curves[i] = CurveID(getBoringGREASEValue(uconn.greaseSeed[:], ssl_grease_group)) + } + } + case *SignatureAlgorithmsExtension: + for i, scheme := range ext.SupportedSignatureAlgorithms { + if isGREASEUint16(uint16(scheme)) { + ext.SupportedSignatureAlgorithms[i] = SignatureScheme(getBoringGREASEValue(uconn.greaseSeed[:], ssl_grease_signature_algorithm)) } } case *KeyShareExtension: @@ -3137,7 +3221,7 @@ func (uconn *UConn) ApplyPreset(p *ClientHelloSpec) error { for i := range ext.KeyShares { curveID := ext.KeyShares[i].Group if isGREASEUint16(uint16(curveID)) { // just in case the user set a GREASE value instead of unGREASEd - ext.KeyShares[i].Group = CurveID(GetBoringGREASEValue(uconn.greaseSeed, ssl_grease_group)) + ext.KeyShares[i].Group = CurveID(getBoringGREASEValue(uconn.greaseSeed[:], ssl_grease_group)) continue } if len(ext.KeyShares[i].Data) > 1 { @@ -3224,7 +3308,7 @@ func (uconn *UConn) ApplyPreset(p *ClientHelloSpec) error { case *SupportedVersionsExtension: for i := range ext.Versions { if isGREASEUint16(ext.Versions[i]) { // just in case the user set a GREASE value instead of unGREASEd - ext.Versions[i] = GetBoringGREASEValue(uconn.greaseSeed, ssl_grease_version) + ext.Versions[i] = getBoringGREASEValue(uconn.greaseSeed[:], ssl_grease_version) } } case *NPNExtension: diff --git a/u_tls_extensions.go b/u_tls_extensions.go index 77ee10ce68..8efe37b3e8 100644 --- a/u_tls_extensions.go +++ b/u_tls_extensions.go @@ -79,6 +79,8 @@ func ExtensionFromID(id uint16) TLSExtension { return &FakeChannelIDExtension{} case utlsExtensionECH: return &GREASEEncryptedClientHelloExtension{} + case utlsExtensionTrustAnchors: + return &TrustAnchorsExtension{} case extensionRenegotiationInfo: return &RenegotiationInfoExtension{} default: @@ -966,9 +968,14 @@ const ( ssl_grease_extension2 ssl_grease_version ssl_grease_ticket_extension - ssl_grease_last_index = ssl_grease_ticket_extension + ssl_grease_ech_config_id + ssl_grease_signature_algorithm + ssl_grease_seed_count ) +// Preserve the array size accepted by the exported GetBoringGREASEValue helper. +const ssl_grease_last_index = ssl_grease_ticket_extension + // it is responsibility of user not to generate multiple grease extensions with same value type UtlsGREASEExtension struct { Value uint16 @@ -981,6 +988,10 @@ func (e *UtlsGREASEExtension) writeToUConn(uc *UConn) error { // will panic if ssl_grease_last_index[index] is out of bounds. func GetBoringGREASEValue(greaseSeed [ssl_grease_last_index]uint16, index int) uint16 { + return getBoringGREASEValue(greaseSeed[:], index) +} + +func getBoringGREASEValue(greaseSeed []uint16, index int) uint16 { // GREASE value is back from deterministic to random. // https://github.com/google/boringssl/blob/a365138ac60f38b64bfc608b493e0f879845cb88/ssl/handshake_client.c#L530 ret := uint16(greaseSeed[index]) diff --git a/u_trust_anchors.go b/u_trust_anchors.go new file mode 100644 index 0000000000..4fc9fb4e98 --- /dev/null +++ b/u_trust_anchors.go @@ -0,0 +1,103 @@ +package tls + +import ( + "encoding/json" + "errors" + "fmt" + "io" + + "golang.org/x/crypto/cryptobyte" +) + +// TrustAnchorsExtension implements the draft trust_anchors ClientHello extension +// (0xca34). Each TrustAnchorID contains 1 to 255 bytes; an empty list is valid. +// The IDs are advertised to the server and do not change Config.RootCAs. +type TrustAnchorsExtension struct { + TrustAnchorIDs [][]byte `json:"trust_anchor_ids"` +} + +func (e *TrustAnchorsExtension) writeToUConn(_ *UConn) error { + return nil +} + +func (e *TrustAnchorsExtension) Len() int { + n := 6 // Extension header and RequestedTrustAnchorList length. + for _, id := range e.TrustAnchorIDs { + n += 1 + len(id) + } + return n +} + +func (e *TrustAnchorsExtension) validate() error { + listLen := 0 + for _, id := range e.TrustAnchorIDs { + if len(id) == 0 || len(id) > 255 { + return fmt.Errorf("tls: trust anchor ID length %d is outside 1..255", len(id)) + } + listLen += 1 + len(id) + // The extension_data length also includes the two-byte list length. + if listLen > (1<<16)-3 { + return errors.New("tls: trust anchors extension data exceeds 65535 bytes") + } + } + return nil +} + +func (e *TrustAnchorsExtension) Read(b []byte) (int, error) { + if err := e.validate(); err != nil { + return 0, err + } + if len(b) < e.Len() { + return 0, io.ErrShortBuffer + } + listLen := e.Len() - 6 + b[0] = byte(utlsExtensionTrustAnchors >> 8) + b[1] = byte(utlsExtensionTrustAnchors & 0xff) + b[2] = byte((2 + listLen) >> 8) + b[3] = byte(2 + listLen) + b[4] = byte(listLen >> 8) + b[5] = byte(listLen) + offset := 6 + for _, id := range e.TrustAnchorIDs { + b[offset] = byte(len(id)) + offset++ + offset += copy(b[offset:], id) + } + return offset, io.EOF +} + +func (e *TrustAnchorsExtension) Write(b []byte) (int, error) { + if len(b) > (1<<16)-1 { + return 0, errors.New("tls: trust anchors extension data exceeds 65535 bytes") + } + extData := cryptobyte.String(b) + var list cryptobyte.String + if !extData.ReadUint16LengthPrefixed(&list) || !extData.Empty() { + return 0, errors.New("tls: unable to read trust anchors extension data") + } + ids := make([][]byte, 0) + for !list.Empty() { + var id cryptobyte.String + if !list.ReadUint8LengthPrefixed(&id) || id.Empty() { + return 0, errors.New("tls: unable to read trust anchor ID") + } + ids = append(ids, append([]byte(nil), id...)) + } + e.TrustAnchorIDs = ids + return len(b), nil +} + +func (e *TrustAnchorsExtension) UnmarshalJSON(data []byte) error { + var value struct { + TrustAnchorIDs [][]byte `json:"trust_anchor_ids"` + } + if err := json.Unmarshal(data, &value); err != nil { + return err + } + parsed := TrustAnchorsExtension{TrustAnchorIDs: value.TrustAnchorIDs} + if err := parsed.validate(); err != nil { + return err + } + e.TrustAnchorIDs = parsed.TrustAnchorIDs + return nil +} diff --git a/u_trust_anchors_test.go b/u_trust_anchors_test.go new file mode 100644 index 0000000000..e1271fb130 --- /dev/null +++ b/u_trust_anchors_test.go @@ -0,0 +1,173 @@ +package tls + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "reflect" + "testing" +) + +func TestTrustAnchorsExtensionRoundTrip(t *testing.T) { + for _, tc := range []struct { + name string + ids [][]byte + wire []byte + }{ + {"empty", nil, []byte{0xca, 0x34, 0, 2, 0, 0}}, + {"single", [][]byte{{0x42}}, []byte{0xca, 0x34, 0, 4, 0, 2, 1, 0x42}}, + {"multiple", [][]byte{{1, 2}, {3}}, []byte{0xca, 0x34, 0, 7, 0, 5, 2, 1, 2, 1, 3}}, + {"maximum ID", [][]byte{bytes.Repeat([]byte{0x81}, 255)}, nil}, + } { + t.Run(tc.name, func(t *testing.T) { + ext := &TrustAnchorsExtension{TrustAnchorIDs: tc.ids} + wire := make([]byte, ext.Len()) + if n, err := ext.Read(wire); n != len(wire) || err != io.EOF { + t.Fatalf("Read = %d, %v; want %d, EOF", n, err, len(wire)) + } + if tc.wire != nil && !bytes.Equal(wire, tc.wire) { + t.Fatalf("wire = %x; want %x", wire, tc.wire) + } + parsed, ok := ExtensionFromID(utlsExtensionTrustAnchors).(*TrustAnchorsExtension) + if !ok { + t.Fatal("trust_anchors is not registered with the fingerprint parser") + } + if n, err := parsed.Write(wire[4:]); n != len(wire)-4 || err != nil { + t.Fatalf("Write = %d, %v; want %d, nil", n, err, len(wire)-4) + } + if len(parsed.TrustAnchorIDs) != len(tc.ids) { + t.Fatalf("parsed %d IDs; want %d", len(parsed.TrustAnchorIDs), len(tc.ids)) + } + for i, id := range tc.ids { + if !bytes.Equal(parsed.TrustAnchorIDs[i], id) { + t.Fatalf("ID %d = %x; want %x", i, parsed.TrustAnchorIDs[i], id) + } + } + encoded := make([]byte, parsed.Len()) + if _, err := parsed.Read(encoded); err != io.EOF { + t.Fatal(err) + } + if !bytes.Equal(encoded, wire) { + t.Fatalf("roundtrip changed wire: %x != %x", encoded, wire) + } + }) + } +} + +func TestTrustAnchorsExtensionParseDoesNotAliasInput(t *testing.T) { + data := []byte{0, 5, 2, 1, 2, 1, 3} + ext := &TrustAnchorsExtension{} + if _, err := ext.Write(data); err != nil { + t.Fatal(err) + } + data[3] = 0xff + if ext.TrustAnchorIDs[0][0] != 1 { + t.Fatal("parsed ID aliases input") + } + ext.TrustAnchorIDs[1][0] = 0xfe + if data[6] != 3 { + t.Fatal("input aliases parsed ID") + } +} + +func TestTrustAnchorsExtensionRejectsMalformedData(t *testing.T) { + for _, data := range [][]byte{ + nil, + {0}, // Truncated list length. + {0, 1}, // Truncated list. + {0, 3, 1, 1}, // List length exceeds available data. + {0, 1, 0}, // Empty ID. + {0, 2, 2, 1}, // Truncated ID. + {0, 0, 1}, // Trailing bytes after the list. + {0, 2, 1, 1, 2}, // Trailing bytes after a nonempty list. + } { + t.Run(fmt.Sprintf("%x", data), func(t *testing.T) { + ext := &TrustAnchorsExtension{TrustAnchorIDs: [][]byte{{0x42}}} + if n, err := ext.Write(data); n != 0 || err == nil { + t.Fatalf("Write = %d, %v; want 0, error", n, err) + } + if !reflect.DeepEqual(ext.TrustAnchorIDs, [][]byte{{0x42}}) { + t.Fatal("failed parsing modified existing IDs") + } + }) + } +} + +func TestTrustAnchorsExtensionEncodingLimits(t *testing.T) { + ids := make([][]byte, 256) + for i := range ids[:255] { + ids[i] = bytes.Repeat([]byte{byte(i)}, 255) + } + ids[255] = bytes.Repeat([]byte{0xff}, 252) + ext := &TrustAnchorsExtension{TrustAnchorIDs: ids} + wire := make([]byte, ext.Len()) + if _, err := ext.Read(wire); err != io.EOF { + t.Fatalf("maximum extension_data failed: %v", err) + } + if len(wire)-4 != 65535 || wire[2] != 0xff || wire[3] != 0xff { + t.Fatalf("maximum extension_data length = %d; header = %x", len(wire)-4, wire[:4]) + } + parsed := &TrustAnchorsExtension{} + if _, err := parsed.Write(wire[4:]); err != nil { + t.Fatalf("maximum extension_data parsing failed: %v", err) + } + for _, ids := range [][][]byte{ + {nil}, + {{}}, + {make([]byte, 256)}, + append(ids[:255:255], make([]byte, 253)), // One byte over the extension_data limit. + } { + ext := &TrustAnchorsExtension{TrustAnchorIDs: ids} + if n, err := ext.Read(make([]byte, ext.Len())); n != 0 || err == nil { + t.Fatalf("invalid IDs Read = %d, %v; want 0, error", n, err) + } + } + if n, err := parsed.Write(make([]byte, 65536)); n != 0 || err == nil { + t.Fatalf("oversize input Write = %d, %v; want 0, error", n, err) + } + if n, err := ext.Read(make([]byte, ext.Len()-1)); n != 0 || err != io.ErrShortBuffer { + t.Fatalf("short buffer Read = %d, %v; want 0, ErrShortBuffer", n, err) + } +} + +func TestTrustAnchorsExtensionJSON(t *testing.T) { + var extensions TLSExtensionsJSONUnmarshaler + if err := json.Unmarshal([]byte(`[{"name":"trust_anchors","trust_anchor_ids":["AQI=","/w=="]}]`), &extensions); err != nil { + t.Fatal(err) + } + exts := extensions.Extensions() + if len(exts) != 1 { + t.Fatalf("parsed %d extensions; want 1", len(exts)) + } + ext, ok := exts[0].(*TrustAnchorsExtension) + if !ok || !reflect.DeepEqual(ext.TrustAnchorIDs, [][]byte{{1, 2}, {0xff}}) { + t.Fatalf("JSON extension = %#v", exts[0]) + } + encoded, err := json.Marshal(ext) + if err != nil { + t.Fatal(err) + } + var roundtrip TrustAnchorsExtension + if err := json.Unmarshal(encoded, &roundtrip); err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(roundtrip.TrustAnchorIDs, ext.TrustAnchorIDs) { + t.Fatalf("JSON roundtrip changed IDs: got %x, want %x", roundtrip.TrustAnchorIDs, ext.TrustAnchorIDs) + } + for _, data := range []string{ + `{"trust_anchor_ids":[""]}`, + `{"trust_anchor_ids":[null]}`, + `{"trust_anchor_ids":["invalid base64"]}`, + } { + if err := json.Unmarshal([]byte(data), ext); err == nil { + t.Fatalf("invalid JSON accepted: %s", data) + } + if !reflect.DeepEqual(ext.TrustAnchorIDs, [][]byte{{1, 2}, {0xff}}) { + t.Fatal("failed JSON parsing modified existing IDs") + } + } + if err := json.Unmarshal([]byte(`{"trust_anchor_ids":[]}`), ext); err != nil || len(ext.TrustAnchorIDs) != 0 { + t.Fatalf("empty JSON list = %#v, %v", ext.TrustAnchorIDs, err) + } +} From 34314739e1c20b1346514b950682b6de83278976 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Wed, 11 Nov 2026 01:45:56 +0300 Subject: [PATCH 25/27] test: build the Chrome 155 tests with Go 1.20 slices is not in the Go 1.20 standard library; use reflect.DeepEqual and a loop instead. (cherry picked from commit a3a3d53c999d6d05250e800dbc07f1eed22d2db3) --- u_chrome155_test.go | 18 ++++++++++++++---- u_mldsa_json_test.go | 4 ++-- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/u_chrome155_test.go b/u_chrome155_test.go index cf1f491c18..557a9ea797 100644 --- a/u_chrome155_test.go +++ b/u_chrome155_test.go @@ -11,7 +11,6 @@ import ( "net" "os" "reflect" - "slices" "sort" "strings" "testing" @@ -113,7 +112,7 @@ func chrome155NormalizeExtension(t *testing.T, id uint16, body []byte) string { outer, kdf, aead := r.number(1), r.number(2), r.number(2) r.take(1) // randomized config_id enc, payload := r.vector(2), r.vector(2) - if outer != 0 || !slices.Contains([]int{144, 176, 208, 240}, len(payload)) { + if outer != 0 || !chrome155ECHPayloadLen(len(payload)) { t.Fatalf("unexpected GREASE ECH shape: outer=%d, payload length=%d", outer, len(payload)) } value = fmt.Sprintf("%d/%d/%d/enc=%d/payload=144,176,208,240", outer, kdf, aead, len(enc)) @@ -251,7 +250,7 @@ func TestChrome155DefaultFingerprintRoundTrip(t *testing.T) { client := chrome155Build(t, HelloCustom, chrome155FixtureServerName(t, raw), spec) got, gotOrder, _ := chrome155ParseWire(t, client.HandshakeState.Hello.Raw) chrome155CompareWire(t, want, got) - if !slices.Equal(gotOrder, wantOrder) { + if !reflect.DeepEqual(gotOrder, wantOrder) { t.Errorf("fingerprint roundtrip reordered extensions: got %x, want %x", gotOrder, wantOrder) } if chrome155TrustAnchors(t, spec.Extensions) == nil { @@ -311,10 +310,21 @@ func TestChrome133CapabilitiesPreserved(t *testing.T) { uint16(ECDSAWithP384AndSHA384), uint16(PSSWithSHA384), uint16(PKCS1WithSHA384), uint16(PSSWithSHA512), uint16(PKCS1WithSHA512), } - if !slices.Equal(got, want) { + if !reflect.DeepEqual(got, want) { t.Fatalf("Chrome 133 signature schemes changed: got %x, want original classical schemes %x", got, want) } if _, ok := raw[0xca34]; ok { t.Fatal("Chrome 155 trust anchor IDs leaked into the Chrome 133 profile") } } + +// chrome155ECHPayloadLen reports a GREASE ECH payload length Chrome uses. A +// loop instead of slices.Contains keeps the tests building with Go 1.20. +func chrome155ECHPayloadLen(n int) bool { + for _, want := range []int{144, 176, 208, 240} { + if n == want { + return true + } + } + return false +} diff --git a/u_mldsa_json_test.go b/u_mldsa_json_test.go index a660e89eca..658454d561 100644 --- a/u_mldsa_json_test.go +++ b/u_mldsa_json_test.go @@ -3,7 +3,7 @@ package tls import ( "encoding/json" "fmt" - "slices" + "reflect" "testing" "github.com/metacubex/utls/dicttls" @@ -46,7 +46,7 @@ func TestMLDSASignatureSchemeJSON(t *testing.T) { t.Fatalf("unexpected extension type %T", ext) } want := []SignatureScheme{GREASE_PLACEHOLDER, MLDSA44, MLDSA65, MLDSA87} - if !slices.Equal(got, want) { + if !reflect.DeepEqual(got, want) { t.Fatalf("signature algorithms = %x, want %x", got, want) } }) From 8bc84a5e4bf00bdbab919925a7c1eed4838ca72e Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Wed, 11 Nov 2026 12:55:55 +0300 Subject: [PATCH 26/27] test: check that ApplyPreset keeps the Chrome 155 preset unshared v1.9 clones the ClientHelloSpec in ApplyPreset, so the preset ownership test from refraction-networking/utls 6ebdceb2 can now be ported: neither the reusable spec nor other connections may see per-connection changes, including the nested trust anchor IDs. --- u_chrome155_test.go | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/u_chrome155_test.go b/u_chrome155_test.go index 557a9ea797..30bf9b7f13 100644 --- a/u_chrome155_test.go +++ b/u_chrome155_test.go @@ -269,6 +269,51 @@ func chrome155TrustAnchors(t *testing.T, extensions []TLSExtension) *TrustAnchor return nil } +// TestChrome155PresetOwnership checks that ApplyPreset clones the spec, so +// neither the reusable preset nor other connections see per-connection +// mutations (ported from refraction-networking/utls 6ebdceb2, which needs +// ClientHelloSpec.clone available since v1.9). +func TestChrome155PresetOwnership(t *testing.T) { + spec, err := UTLSIdToSpec(HelloChrome_155) + if err != nil { + t.Fatal(err) + } + before := spec.clone() + first := chrome155Build(t, HelloCustom, "example.com", &spec) + second := chrome155Build(t, HelloCustom, "example.com", &spec) + if !reflect.DeepEqual(&spec, before) { + t.Fatal("ApplyPreset mutated the reusable Chrome 155 preset") + } + anchors := chrome155TrustAnchors(t, first.Extensions) + if len(anchors.TrustAnchorIDs) == 0 || len(anchors.TrustAnchorIDs[0]) == 0 { + t.Fatal("Chrome 155 capture must contain trust anchor IDs") + } + anchors.TrustAnchorIDs[0][0] ^= 0xff + for _, extension := range first.Extensions { + switch extension := extension.(type) { + case *SignatureAlgorithmsExtension: + extension.SupportedSignatureAlgorithms[0] = PKCS1WithSHA1 + case *SupportedCurvesExtension: + extension.Curves[0] = CurveP384 + } + } + first.HandshakeState.Hello.CipherSuites[0] = TLS_RSA_WITH_AES_256_CBC_SHA + if !reflect.DeepEqual(&spec, before) { + t.Fatal("connection mutations leaked into the reusable Chrome 155 preset") + } + wantAnchors := chrome155TrustAnchors(t, before.Extensions).TrustAnchorIDs + if !reflect.DeepEqual(chrome155TrustAnchors(t, second.Extensions).TrustAnchorIDs, wantAnchors) { + t.Fatal("nested trust anchor mutations leaked between connections") + } + later, err := UTLSIdToSpec(HelloChrome_155) + if err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(chrome155TrustAnchors(t, later.Extensions).TrustAnchorIDs, wantAnchors) { + t.Fatal("trust anchor mutations leaked into future preset instances") + } +} + func TestChrome155SignatureGREASESeed(t *testing.T) { client := UClient(&net.TCPConn{}, &Config{ ServerName: "example.com", From 55f3fd10da488c0d963f877181261f6dafe8bea4 Mon Sep 17 00:00:00 2001 From: Nemu-x Date: Wed, 11 Nov 2026 12:55:55 +0300 Subject: [PATCH 27/27] ci: run on dev-1.9 The v1.9 port lives on dev-1.9 next to dev; test pushes and pull requests there too. go.mod still says go 1.20, so the matrix keeps Go 1.20 and 1.26. --- .github/workflows/ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 847173a70c..3588918254 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,9 +2,9 @@ name: CI on: push: - branches: [main, dev] + branches: [main, dev, dev-1.9] pull_request: - branches: [main, dev] + branches: [main, dev, dev-1.9] concurrency: group: ${{ github.workflow }}-${{ github.ref }}