From d569d9eba72eed81f4803781b97ffa12ab08076d Mon Sep 17 00:00:00 2001 From: CatMsg <16541851+CatMsg@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:57:54 +0800 Subject: [PATCH] feat: support optional userkey for Snell v6 outbound (#3460) --- adapter/outbound/snell.go | 14 +++++- docs/config.yaml | 1 + transport/snell/snell.go | 32 ++++++++++++-- transport/snell/v4_test.go | 90 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 132 insertions(+), 5 deletions(-) diff --git a/adapter/outbound/snell.go b/adapter/outbound/snell.go index ce5c58c0..679a4622 100644 --- a/adapter/outbound/snell.go +++ b/adapter/outbound/snell.go @@ -20,6 +20,7 @@ type Snell struct { *Base option *SnellOption psk []byte + userKey []byte pool *snell.Pool obfsOption *simpleObfsOption shadowTLSOption *shadowtls.ShadowTLSOption @@ -36,6 +37,7 @@ type SnellOption struct { Server string `proxy:"server"` Port int `proxy:"port"` Psk string `proxy:"psk"` + UserKey string `proxy:"userkey,omitempty"` UDP bool `proxy:"udp,omitempty"` Version int `proxy:"version,omitempty"` Reuse bool `proxy:"reuse,omitempty"` @@ -91,7 +93,7 @@ func (s *Snell) writeHeaderContext(ctx context.Context, c net.Conn, metadata *C. } if metadata.NetWork == C.UDP { - err = snell.WriteUDPHeader(c, s.version) + err = snell.WriteUDPHeaderWithClientID(c, s.version, s.userKey) if err == nil && s.version >= snell.Version4 { if sc, ok := c.(*snell.Snell); ok { err = sc.ReadReply() @@ -99,7 +101,7 @@ func (s *Snell) writeHeaderContext(ctx context.Context, c net.Conn, metadata *C. } return } - err = snell.WriteHeaderWithReuse(c, metadata.String(), uint(metadata.DstPort), s.version, s.reuse) + err = snell.WriteHeaderWithReuseAndClientID(c, metadata.String(), uint(metadata.DstPort), s.version, s.reuse, s.userKey) return } @@ -254,6 +256,13 @@ func NewSnell(option SnellOption) (*Snell, error) { // Snell v5 servers are backward-compatible with v4 clients. option.Version = snell.Version4 } + userKey := []byte(option.UserKey) + if len(userKey) > snell.MaxClientIDLength { + return nil, fmt.Errorf("snell %s userkey must be at most 255 bytes", addr) + } + if len(userKey) > 0 && option.Version != snell.Version6 { + return nil, fmt.Errorf("snell %s userkey is only supported on version 6", addr) + } reuse := option.Version == snell.Version2 || ((option.Version == snell.Version4 || option.Version == snell.Version6) && option.Reuse) var v6Mode snell.V6Mode @@ -299,6 +308,7 @@ func NewSnell(option SnellOption) (*Snell, error) { }), option: &option, psk: psk, + userKey: userKey, obfsOption: obfsOption, shadowTLSOption: shadowTLSOpt, restlsConfig: restlsConfig, diff --git a/docs/config.yaml b/docs/config.yaml index 944e570b..8f3bf323 100644 --- a/docs/config.yaml +++ b/docs/config.yaml @@ -414,6 +414,7 @@ proxies: # socks5 server: server port: 44046 psk: yourpsk + # userkey: per-user-client-id # v6 only; sent as the Snell ClientID # version: 4 # support 1/2/3/4/5/6 # udp: true # support UDP on version 3/4/5/6 # reuse: false # v4/5/6 only diff --git a/transport/snell/snell.go b/transport/snell/snell.go index a05a3d9f..dd06cc40 100644 --- a/transport/snell/snell.go +++ b/transport/snell/snell.go @@ -39,6 +39,9 @@ const ( CommandError byte = 2 Version byte = 1 + + // MaxClientIDLength is the maximum ClientID length encoded in a Snell request header. + MaxClientIDLength = 255 ) var endSignal = []byte{} @@ -102,6 +105,16 @@ func WriteHeader(conn net.Conn, host string, port uint, version int) error { } func WriteHeaderWithReuse(conn net.Conn, host string, port uint, version int, reuse bool) error { + return WriteHeaderWithReuseAndClientID(conn, host, port, version, reuse, nil) +} + +func WriteHeaderWithReuseAndClientID(conn net.Conn, host string, port uint, version int, reuse bool, clientID []byte) error { + if len(clientID) > MaxClientIDLength { + return errors.New("snell client ID too long") + } + if len(clientID) > 0 && version != Version6 { + return errors.New("snell client ID is only supported on version 6") + } buf := pool.GetBuffer() defer pool.PutBuffer(buf) buf.WriteByte(Version) @@ -112,7 +125,8 @@ func WriteHeaderWithReuse(conn net.Conn, host string, port uint, version int, re } // clientID length & id - buf.WriteByte(0) + buf.WriteByte(uint8(len(clientID))) + buf.Write(clientID) // host & port buf.WriteByte(uint8(len(host))) @@ -127,12 +141,24 @@ func WriteHeaderWithReuse(conn net.Conn, host string, port uint, version int, re } func WriteUDPHeader(conn net.Conn, version int) error { + return WriteUDPHeaderWithClientID(conn, version, nil) +} + +func WriteUDPHeaderWithClientID(conn net.Conn, version int, clientID []byte) error { if version < Version3 { return errors.New("unsupport UDP version") } + if len(clientID) > MaxClientIDLength { + return errors.New("snell client ID too long") + } + if len(clientID) > 0 && version != Version6 { + return errors.New("snell client ID is only supported on version 6") + } - // version, command, clientID length - _, err := conn.Write([]byte{Version, CommandUDP, 0x00}) + // version, command, client ID length, and optional per-user identity + header := []byte{Version, CommandUDP, uint8(len(clientID))} + header = append(header, clientID...) + _, err := conn.Write(header) return err } diff --git a/transport/snell/v4_test.go b/transport/snell/v4_test.go index 9d59be84..6b1ecb1c 100644 --- a/transport/snell/v4_test.go +++ b/transport/snell/v4_test.go @@ -315,6 +315,96 @@ func TestSnellWriteHeaderConnectCommand(t *testing.T) { } } +func TestSnellV6ClientIDHeaders(t *testing.T) { + clientID := []byte("alice-key") + + for _, tt := range []struct { + name string + reuse bool + cmd byte + }{ + {name: "connect", cmd: CommandConnect}, + {name: "reuse", reuse: true, cmd: CommandConnectV2}, + } { + t.Run(tt.name, func(t *testing.T) { + conn := &bufferConn{} + if err := WriteHeaderWithReuseAndClientID(conn, "example.com", 443, Version6, tt.reuse, clientID); err != nil { + t.Fatal(err) + } + + want := []byte{Version, tt.cmd, byte(len(clientID))} + want = append(want, clientID...) + want = append(want, byte(len("example.com"))) + want = append(want, "example.com"...) + want = append(want, 0x01, 0xbb) + if !bytes.Equal(conn.Bytes(), want) { + t.Fatalf("TCP header = %x, want %x", conn.Bytes(), want) + } + }) + } + + udpConn := &bufferConn{} + if err := WriteUDPHeaderWithClientID(udpConn, Version6, clientID); err != nil { + t.Fatal(err) + } + wantUDP := append([]byte{Version, CommandUDP, byte(len(clientID))}, clientID...) + if !bytes.Equal(udpConn.Bytes(), wantUDP) { + t.Fatalf("UDP header = %x, want %x", udpConn.Bytes(), wantUDP) + } +} + +func TestSnellClientIDValidation(t *testing.T) { + maxID := bytes.Repeat([]byte{'k'}, MaxClientIDLength) + tcpConn := &bufferConn{} + if err := WriteHeaderWithReuseAndClientID(tcpConn, "example.com", 443, Version6, false, maxID); err != nil { + t.Fatalf("TCP header rejected a %d-byte client ID: %v", MaxClientIDLength, err) + } + if got := tcpConn.Bytes()[2]; got != 0xff { + t.Fatalf("TCP client ID length = %d, want 255", got) + } + udpConn := &bufferConn{} + if err := WriteUDPHeaderWithClientID(udpConn, Version6, maxID); err != nil { + t.Fatalf("UDP header rejected a %d-byte client ID: %v", MaxClientIDLength, err) + } + if got := udpConn.Bytes()[2]; got != 0xff { + t.Fatalf("UDP client ID length = %d, want 255", got) + } + + oversizedID := make([]byte, 256) + if err := WriteHeaderWithReuseAndClientID(&bufferConn{}, "example.com", 443, Version6, false, oversizedID); err == nil { + t.Fatal("TCP header accepted a client ID longer than 255 bytes") + } + if err := WriteUDPHeaderWithClientID(&bufferConn{}, Version6, oversizedID); err == nil { + t.Fatal("UDP header accepted a client ID longer than 255 bytes") + } + + clientID := []byte("alice-key") + if err := WriteHeaderWithReuseAndClientID(&bufferConn{}, "example.com", 443, Version4, false, clientID); err == nil { + t.Fatal("TCP header accepted a client ID for Snell v4") + } + if err := WriteUDPHeaderWithClientID(&bufferConn{}, Version4, clientID); err == nil { + t.Fatal("UDP header accepted a client ID for Snell v4") + } +} + +func TestSnellEmptyClientIDRemainsCompatible(t *testing.T) { + tcpConn := &bufferConn{} + if err := WriteHeaderWithReuse(tcpConn, "example.com", 443, Version6, true); err != nil { + t.Fatal(err) + } + if got := tcpConn.Bytes()[2]; got != 0 { + t.Fatalf("legacy TCP client ID length = %d, want 0", got) + } + + udpConn := &bufferConn{} + if err := WriteUDPHeader(udpConn, Version6); err != nil { + t.Fatal(err) + } + if want := []byte{Version, CommandUDP, 0}; !bytes.Equal(udpConn.Bytes(), want) { + t.Fatalf("legacy UDP header = %x, want %x", udpConn.Bytes(), want) + } +} + func TestSnellReadReplyPreservesBufferedPayload(t *testing.T) { conn := &Snell{Conn: &bufferConn{}} conn.Conn.(*bufferConn).Write([]byte{CommandTunnel, 'o', 'k'})