diff --git a/server/cmd/echolot-server/main.go b/server/cmd/echolot-server/main.go index 268c443..029fde8 100644 --- a/server/cmd/echolot-server/main.go +++ b/server/cmd/echolot-server/main.go @@ -103,11 +103,14 @@ func serve(cfg *config.Config) error { sessions := session.NewManager(15 * time.Minute) dp := &dataplane.Server{Sessions: sessions} - tcpSrv := &tcpecho.Server{} + // TCP echo shares the control cert for its elt-echo TLS variant. + tcpSrv := &tcpecho.Server{ + TLSConfig: &tls.Config{Certificates: []tls.Certificate{cert}, MinVersion: tls.VersionTLS12}, + } caps := []string{"udp-probe", "delayed-echo", "connect-back", "http-echo"} if len(config.Addrs(cfg.TCPListen)) > 0 { - caps = append(caps, "tcp-echo") + caps = append(caps, "tcp-echo", "tls-echo") } ctl := &control.Server{ diff --git a/server/internal/tcpecho/ja4.go b/server/internal/tcpecho/ja4.go new file mode 100644 index 0000000..6b97d4d --- /dev/null +++ b/server/internal/tcpecho/ja4.go @@ -0,0 +1,286 @@ +// SPDX-FileCopyrightText: 2026 Echolot contributors +// SPDX-License-Identifier: GPL-3.0-or-later + +package tcpecho + +import ( + "crypto/sha256" + "encoding/binary" + "encoding/hex" + "fmt" + "sort" + "strings" +) + +// clientHello holds the fields JA4 needs from a parsed TLS ClientHello. +type clientHello struct { + legacyVersion uint16 + cipherSuites []uint16 + extensions []uint16 // in wire order + hasSNI bool + alpns []string + supportedVersions []uint16 + sigAlgs []uint16 // in wire order +} + +// isGREASE reports whether a code point is a GREASE value (RFC 8701): both +// bytes equal and of the form 0x?a. JA4 excludes these everywhere. +func isGREASE(v uint16) bool { + return v&0x0f0f == 0x0a0a && v>>8 == v&0xff +} + +// parseClientHello parses a full TLS record (starting at the 0x16 record +// header) and extracts the ClientHello fields. Returns false if the bytes are +// not a well-formed ClientHello. +func parseClientHello(rec []byte) (*clientHello, bool) { + // Record header: type(1)=0x16, version(2), length(2). + if len(rec) < 5 || rec[0] != 0x16 { + return nil, false + } + recLen := int(binary.BigEndian.Uint16(rec[3:5])) + if len(rec) < 5+recLen { + return nil, false + } + b := rec[5 : 5+recLen] + // Handshake header: msg_type(1)=0x01 ClientHello, length(3). + if len(b) < 4 || b[0] != 0x01 { + return nil, false + } + hsLen := int(b[1])<<16 | int(b[2])<<8 | int(b[3]) + b = b[4:] + if len(b) < hsLen { + return nil, false + } + b = b[:hsLen] + + h := &clientHello{} + // client_version(2), random(32). + if len(b) < 34 { + return nil, false + } + h.legacyVersion = binary.BigEndian.Uint16(b[0:2]) + b = b[34:] + // session_id. + if len(b) < 1 || len(b) < 1+int(b[0]) { + return nil, false + } + b = b[1+int(b[0]):] + // cipher_suites. + if len(b) < 2 { + return nil, false + } + cslen := int(binary.BigEndian.Uint16(b[0:2])) + b = b[2:] + if len(b) < cslen || cslen%2 != 0 { + return nil, false + } + for i := 0; i < cslen; i += 2 { + h.cipherSuites = append(h.cipherSuites, binary.BigEndian.Uint16(b[i:i+2])) + } + b = b[cslen:] + // compression_methods. + if len(b) < 1 || len(b) < 1+int(b[0]) { + return nil, false + } + b = b[1+int(b[0]):] + // extensions (optional). + if len(b) < 2 { + return h, true + } + extTotal := int(binary.BigEndian.Uint16(b[0:2])) + b = b[2:] + if len(b) < extTotal { + return nil, false + } + ext := b[:extTotal] + for len(ext) >= 4 { + etype := binary.BigEndian.Uint16(ext[0:2]) + elen := int(binary.BigEndian.Uint16(ext[2:4])) + if len(ext) < 4+elen { + break + } + data := ext[4 : 4+elen] + h.extensions = append(h.extensions, etype) + switch etype { + case 0x0000: // server_name + h.hasSNI = true + case 0x0010: // ALPN + h.alpns = append(h.alpns, parseALPN(data)...) + case 0x002b: // supported_versions + h.supportedVersions = parseSupportedVersions(data) + case 0x000d: // signature_algorithms + h.sigAlgs = parseU16List(data) + } + ext = ext[4+elen:] + } + return h, true +} + +func parseALPN(d []byte) []string { + if len(d) < 2 { + return nil + } + listLen := int(binary.BigEndian.Uint16(d[0:2])) + d = d[2:] + if len(d) < listLen { + return nil + } + var out []string + for len(d) >= 1 { + n := int(d[0]) + if len(d) < 1+n { + break + } + out = append(out, string(d[1:1+n])) + d = d[1+n:] + } + return out +} + +func parseSupportedVersions(d []byte) []uint16 { + if len(d) < 1 { + return nil + } + n := int(d[0]) + d = d[1:] + if len(d) < n || n%2 != 0 { + return nil + } + var out []uint16 + for i := 0; i < n; i += 2 { + out = append(out, binary.BigEndian.Uint16(d[i:i+2])) + } + return out +} + +// parseU16List parses a 2-byte-length-prefixed list of u16 values (used for +// signature_algorithms). +func parseU16List(d []byte) []uint16 { + if len(d) < 2 { + return nil + } + n := int(binary.BigEndian.Uint16(d[0:2])) + d = d[2:] + if len(d) < n || n%2 != 0 { + return nil + } + var out []uint16 + for i := 0; i < n; i += 2 { + out = append(out, binary.BigEndian.Uint16(d[i:i+2])) + } + return out +} + +// ja4 computes the JA4 TLS client fingerprint (FoxIO spec) from a parsed +// ClientHello: a_b_c where a is a human-readable prefix, b hashes the sorted +// cipher list, c hashes the sorted extensions + signature algorithms. +func ja4(h *clientHello) string { + // --- a --- + ver := ja4Version(h) + sni := "i" + if h.hasSNI { + sni = "d" + } + nCiphers := countNonGREASE(h.cipherSuites) + nExts := countNonGREASE(h.extensions) // count includes SNI + ALPN + alpn := "00" + if len(h.alpns) > 0 && h.alpns[0] != "" { + a := h.alpns[0] + alpn = string(a[0]) + string(a[len(a)-1]) + } + a := fmt.Sprintf("t%s%s%02d%02d%s", ver, sni, capAt99(nCiphers), capAt99(nExts), alpn) + + // --- b: sorted non-GREASE cipher suites, lowercase hex, comma-joined --- + b := hash12(strings.Join(sortedHex(nonGREASE(h.cipherSuites)), ",")) + + // --- c: sorted non-GREASE extensions (minus SNI 0000 and ALPN 0010), + // then "_", then signature algorithms IN ORDER (non-GREASE) --- + extsForC := filterOut(nonGREASE(h.extensions), 0x0000, 0x0010) + cInput := strings.Join(sortedHex(extsForC), ",") + "_" + strings.Join(hexList(nonGREASE(h.sigAlgs)), ",") + c := hash12(cInput) + + return a + "_" + b + "_" + c +} + +// ja4Version picks the highest offered version (supported_versions if present, +// else the legacy field) mapped to JA4's two-char code. +func ja4Version(h *clientHello) string { + best := h.legacyVersion + for _, v := range h.supportedVersions { + if isGREASE(v) { + continue + } + if v > best { + best = v + } + } + switch best { + case 0x0304: + return "13" + case 0x0303: + return "12" + case 0x0302: + return "11" + case 0x0301: + return "10" + case 0x0300: + return "s3" + } + return "00" +} + +func nonGREASE(in []uint16) []uint16 { + out := make([]uint16, 0, len(in)) + for _, v := range in { + if !isGREASE(v) { + out = append(out, v) + } + } + return out +} + +func countNonGREASE(in []uint16) int { return len(nonGREASE(in)) } + +func filterOut(in []uint16, drop ...uint16) []uint16 { + out := make([]uint16, 0, len(in)) + for _, v := range in { + skip := false + for _, d := range drop { + if v == d { + skip = true + } + } + if !skip { + out = append(out, v) + } + } + return out +} + +func sortedHex(in []uint16) []string { + cp := append([]uint16(nil), in...) + sort.Slice(cp, func(i, j int) bool { return cp[i] < cp[j] }) + return hexList(cp) +} + +func hexList(in []uint16) []string { + out := make([]string, len(in)) + for i, v := range in { + var b [2]byte + binary.BigEndian.PutUint16(b[:], v) + out[i] = hex.EncodeToString(b[:]) + } + return out +} + +func hash12(s string) string { + sum := sha256.Sum256([]byte(s)) + return hex.EncodeToString(sum[:])[:12] +} + +func capAt99(n int) int { + if n > 99 { + return 99 + } + return n +} diff --git a/server/internal/tcpecho/ja4_test.go b/server/internal/tcpecho/ja4_test.go new file mode 100644 index 0000000..9be2e48 --- /dev/null +++ b/server/internal/tcpecho/ja4_test.go @@ -0,0 +1,111 @@ +// SPDX-FileCopyrightText: 2026 Echolot contributors +// SPDX-License-Identifier: GPL-3.0-or-later + +package tcpecho + +import ( + "encoding/binary" + "strings" + "testing" +) + +// buildClientHello assembles a minimal but valid TLS ClientHello record for +// tests: TLS1.2 legacy version, the given ciphers, and extensions SNI, ALPN +// (h2), supported_versions (1.3), signature_algorithms (0x0403). +func buildClientHello(ciphers []uint16) []byte { + u16 := func(v uint16) []byte { b := make([]byte, 2); binary.BigEndian.PutUint16(b, v); return b } + + var body []byte + body = append(body, u16(0x0303)...) // client_version TLS1.2 + body = append(body, make([]byte, 32)...) // random + body = append(body, 0) // session_id len 0 + // cipher suites + cs := []byte{} + for _, c := range ciphers { + cs = append(cs, u16(c)...) + } + body = append(body, u16(uint16(len(cs)))...) + body = append(body, cs...) + body = append(body, 1, 0) // compression: 1 method, null + + // extensions + var exts []byte + addExt := func(typ uint16, data []byte) { + exts = append(exts, u16(typ)...) + exts = append(exts, u16(uint16(len(data)))...) + exts = append(exts, data...) + } + // SNI: server_name_list -> host_name "x" + sni := append(u16(3), 0) // list len 3, name_type host_name(0) + sni = append(sni, u16(1)...) // name len 1 + sni = append(sni, 'x') + addExt(0x0000, sni) + // ALPN: protocol_name_list -> "h2" + alpn := append(u16(3), 2, 'h', '2') // list len 3, strlen 2, "h2" + addExt(0x0010, alpn) + // supported_versions: list len 2, 0x0304 + addExt(0x002b, append([]byte{2}, u16(0x0304)...)) + // signature_algorithms: list len 2, 0x0403 + addExt(0x000d, append(u16(2), u16(0x0403)...)) + + body = append(body, u16(uint16(len(exts)))...) + body = append(body, exts...) + + // handshake header + hs := []byte{0x01, byte(len(body) >> 16), byte(len(body) >> 8), byte(len(body))} + hs = append(hs, body...) + // record header + rec := []byte{0x16, 0x03, 0x01, byte(len(hs) >> 8), byte(len(hs))} + return append(rec, hs...) +} + +func TestParseAndJA4(t *testing.T) { + rec := buildClientHello([]uint16{0x1301, 0x1302}) + h, ok := parseClientHello(rec) + if !ok { + t.Fatal("parse failed") + } + if len(h.cipherSuites) != 2 || !h.hasSNI || len(h.alpns) != 1 || h.alpns[0] != "h2" { + t.Fatalf("parsed fields wrong: %+v", h) + } + if len(h.supportedVersions) != 1 || h.supportedVersions[0] != 0x0304 { + t.Fatalf("supported_versions: %v", h.supportedVersions) + } + + got := ja4(h) + // _a: t + 13 (supported_versions 1.3) + d (SNI) + 02 ciphers + 04 exts + h2 + wantA := "t13d0204h2" + parts := strings.Split(got, "_") + if len(parts) != 3 { + t.Fatalf("JA4 not 3 parts: %s", got) + } + if parts[0] != wantA { + t.Fatalf("JA4_a = %s, want %s (full %s)", parts[0], wantA, got) + } + if len(parts[1]) != 12 || len(parts[2]) != 12 { + t.Fatalf("JA4 hash parts not 12 hex: %s", got) + } + // determinism + if ja4(h) != got { + t.Fatal("JA4 not deterministic") + } +} + +func TestJA4GREASEExcluded(t *testing.T) { + // Same hello but with a GREASE cipher inserted; cipher count and _b hash + // must be identical to the non-GREASE version. + base := ja4(mustParse(t, buildClientHello([]uint16{0x1301, 0x1302}))) + withGrease := ja4(mustParse(t, buildClientHello([]uint16{0x0a0a, 0x1301, 0x1302}))) + if base != withGrease { + t.Fatalf("GREASE changed JA4:\n base=%s\n grease=%s", base, withGrease) + } +} + +func mustParse(t *testing.T, rec []byte) *clientHello { + t.Helper() + h, ok := parseClientHello(rec) + if !ok { + t.Fatal("parse failed") + } + return h +} diff --git a/server/internal/tcpecho/tcpecho.go b/server/internal/tcpecho/tcpecho.go index d0b6f84..0ccf7f6 100644 --- a/server/internal/tcpecho/tcpecho.go +++ b/server/internal/tcpecho/tcpecho.go @@ -1,16 +1,17 @@ // SPDX-FileCopyrightText: 2026 Echolot contributors // SPDX-License-Identifier: GPL-3.0-or-later -// Package tcpecho implements the spec §4 TCP echo: after connect the server -// sends one JSON line with what it observed (source address/port, negotiated -// MSS and TCP options from TCP_INFO), then byte-echoes until FIN. This is the -// evidence source for mtu.mss_observed. -// -// The TLS/ALPN "elt-echo" variant (ClientHello capture + JA4) is not -// implemented yet. +// Package tcpecho implements spec §4 TCP echo and its TLS variant on the same +// port. Plain connections get a JSON greeting (observed source, negotiated +// MSS and TCP options from TCP_INFO — the mtu.mss_observed evidence) then a +// byte echo. A connection that opens with a TLS handshake (first byte 0x16) +// and ALPN "elt-echo" gets, additionally, the ClientHello it sent back raw + +// as a JA4 fingerprint (sec.clienthello_echo) before the echo. package tcpecho import ( + "crypto/tls" + "encoding/base64" "encoding/json" "io" "net" @@ -24,9 +25,16 @@ type ConnRecord struct { Src string `json:"src"` MSS int `json:"mss"` Options []string `json:"options"` + TLS bool `json:"tls"` + JA4 string `json:"ja4,omitempty"` + ALPN string `json:"alpn,omitempty"` } type Server struct { + // TLSConfig enables the elt-echo TLS variant; nil disables it (plain echo + // only). "elt-echo" is appended to NextProtos at Serve time. + TLSConfig *tls.Config + mu sync.Mutex recent []ConnRecord // ring, newest last } @@ -65,27 +73,120 @@ func (s *Server) Serve(ln net.Listener) error { } } +// prefixConn replays already-read bytes before continuing with the underlying +// connection — used to hand the peeked ClientHello record to tls.Server. +type prefixConn struct { + net.Conn + prefix []byte +} + +func (p *prefixConn) Read(b []byte) (int, error) { + if len(p.prefix) > 0 { + n := copy(b, p.prefix) + p.prefix = p.prefix[n:] + return n, nil + } + return p.Conn.Read(b) +} + func (s *Server) handle(conn net.Conn) { defer conn.Close() _ = conn.SetDeadline(time.Now().Add(5 * time.Minute)) - info := tcpInfo(conn) // platform-specific; zero values off-Linux + // TCP_INFO must be read from the raw *net.TCPConn, before any wrapping. + info := tcpInfo(conn) rec := ConnRecord{ ConnectedAt: time.Now().UTC(), Src: conn.RemoteAddr().String(), MSS: info.MSS, Options: info.Options, } + + // Multiplex TLS vs plain on one port. Plain echo is server-speaks-first + // (the client waits for the greeting), while a TLS client sends its + // ClientHello immediately — so peek the first byte with a short deadline: + // a byte that arrives fast and is 0x16 means TLS; a timeout means a plain + // client waiting to be greeted. + // 500ms tolerates ~1s RTT (incl. satellite) before a TLS ClientHello would + // be misread as a silent plain client; plain clients simply wait this long + // for the greeting they're already waiting for. + first := make([]byte, 1) + _ = conn.SetReadDeadline(time.Now().Add(500 * time.Millisecond)) + n, err := io.ReadFull(conn, first) + _ = conn.SetDeadline(time.Now().Add(5 * time.Minute)) // reset for the session + switch { + case err == nil && first[0] == 0x16 && s.TLSConfig != nil: + s.handleTLS(conn, first, rec) + return + case err == nil: + s.plainEcho(conn, first, rec) // client spoke first (rare) — replay it + return + case n == 0 && isTimeout(err): + s.plainEcho(conn, nil, rec) // client waiting for greeting — normal path + return + default: + return // EOF or a real error + } +} + +func (s *Server) plainEcho(conn net.Conn, peeked []byte, rec ConnRecord) { + pc := &prefixConn{Conn: conn, prefix: peeked} + s.record(rec) + greeting, _ := json.Marshal(map[string]any{ + "observed_src": rec.Src, "mss": rec.MSS, "options": rec.Options, "tls": false, + }) + if _, err := pc.Write(append(greeting, '\n')); err != nil { + return + } + _, _ = io.Copy(pc, pc) +} + +func isTimeout(err error) bool { + ne, ok := err.(net.Error) + return ok && ne.Timeout() +} + +// handleTLS captures the full ClientHello record, computes JA4, completes the +// handshake, then greets with the ClientHello (raw + JA4) and echoes over TLS. +func (s *Server) handleTLS(conn net.Conn, first []byte, rec ConnRecord) { + // Read the rest of the record header (version[2], length[2]) and the body. + hdr := make([]byte, 4) + if _, err := io.ReadFull(conn, hdr); err != nil { + return + } + recLen := int(hdr[2])<<8 | int(hdr[3]) + body := make([]byte, recLen) + if _, err := io.ReadFull(conn, body); err != nil { + return + } + full := append(append(append([]byte{}, first...), hdr...), body...) + + rec.TLS = true + if h, ok := parseClientHello(full); ok { + rec.JA4 = ja4(h) + } + + // Replay the captured ClientHello into the TLS server. + cfg := s.TLSConfig.Clone() + cfg.NextProtos = append([]string{"elt-echo"}, cfg.NextProtos...) + tconn := tls.Server(&prefixConn{Conn: conn, prefix: full}, cfg) + if err := tconn.Handshake(); err != nil { + return + } + rec.ALPN = tconn.ConnectionState().NegotiatedProtocol s.record(rec) greeting, _ := json.Marshal(map[string]any{ - "observed_src": rec.Src, - "mss": rec.MSS, - "options": rec.Options, + "observed_src": rec.Src, + "mss": rec.MSS, + "options": rec.Options, + "tls": true, + "alpn": rec.ALPN, + "ja4": rec.JA4, + "clienthello_b64": base64.StdEncoding.EncodeToString(full), }) - if _, err := conn.Write(append(greeting, '\n')); err != nil { + if _, err := tconn.Write(append(greeting, '\n')); err != nil { return } - // Byte-echo until FIN; the client's data is its own to interpret. - _, _ = io.Copy(conn, conn) + _, _ = io.Copy(tconn, tconn) } diff --git a/server/internal/tcpecho/tcpecho_test.go b/server/internal/tcpecho/tcpecho_test.go new file mode 100644 index 0000000..9dfb8f3 --- /dev/null +++ b/server/internal/tcpecho/tcpecho_test.go @@ -0,0 +1,53 @@ +// SPDX-FileCopyrightText: 2026 Echolot contributors +// SPDX-License-Identifier: GPL-3.0-or-later + +package tcpecho + +import ( + "bufio" + "encoding/json" + "net" + "testing" + "time" +) + +// Plain echo must be server-speaks-first: a client that sends nothing still +// gets the greeting (via the peek timeout), then its bytes are echoed. +func TestPlainEchoServerSpeaksFirst(t *testing.T) { + ln, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + defer ln.Close() + go (&Server{}).Serve(ln) + + c, err := net.Dial("tcp", ln.Addr().String()) + if err != nil { + t.Fatal(err) + } + defer c.Close() + c.SetDeadline(time.Now().Add(3 * time.Second)) + + line, err := bufio.NewReader(c).ReadBytes('\n') + if err != nil { + t.Fatalf("no greeting: %v", err) + } + var g struct { + TLS bool `json:"tls"` + Src string `json:"observed_src"` + } + if err := json.Unmarshal(line, &g); err != nil { + t.Fatal(err) + } + if g.TLS { + t.Fatal("plain connection reported tls=true") + } + if g.Src == "" { + t.Fatal("greeting missing observed_src") + } + c.Write([]byte("xyz")) + buf := make([]byte, 3) + if _, err := c.Read(buf); err != nil || string(buf) != "xyz" { + t.Fatalf("echo failed: %q %v", buf, err) + } +}