tls: add pcap capturing

internet/pcap/capture.go

@@ -52,11 +52,12 @@ type PacketBreakdown struct {
 //	0: Ethernet (3 base + VLAN tag = 4)
 //	1: L3 max(IPv4=12, ARP=9, IPv6=8) = 12
 //	2: L4 max(TCP=10, ICMP=8, UDP=4) = 10
-//	3: App max(DHCP=15, NTP=13, HTTP=2, DNS=1) = 16
-//	4-5: overflow/remaining = 2
+//	3: App max(DHCP=15, NTP=13, HTTP=2, DNS=1, TLS record=4) = 16
+//	4: TLS handshake message (ClientHello=8) = 8
+//	5-7: extra TLS records/overflow/remaining = 4,2,2
 func (pc *PacketBreakdown) initFrames() []Frame {
-	const nframes = 6
-	var fieldCaps = [nframes]int{4, 12, 10, 16, 2, 2}
+	const nframes = 8
+	var fieldCaps = [nframes]int{4, 12, 10, 16, 8, 4, 2, 2}
 	frames := make([]Frame, nframes)
 	for i := range frames {
 		frames[i].Fields = make([]FrameField, 0, fieldCaps[i])
@@ -328,9 +329,18 @@ func (pc *PacketBreakdown) CaptureTCP(dst []Frame, pkt []byte, bitOffset int) ([
 	}
 	payload := tfrm.Payload()
 	if len(payload) > 0 {
-		debuglog("pcap:tcp:http-start")
-		dst, err = pc.CaptureHTTP(dst, pkt, end)
-		debuglog("pcap:tcp:http-done")
+		// Application protocol is picked by inspecting the payload rather than
+		// by port, so that TLS on a port other than 443 and HTTP on a port
+		// other than 80 are both broken down correctly.
+		if payloadIsTLS(payload) {
+			debuglog("pcap:tcp:tls-start")
+			dst, err = pc.CaptureTLS(dst, pkt, end)
+			debuglog("pcap:tcp:tls-done")
+		} else {
+			debuglog("pcap:tcp:http-start")
+			dst, err = pc.CaptureHTTP(dst, pkt, end)
+			debuglog("pcap:tcp:http-done")
+		}
 		if err != nil {
 			reclaimRemainingFrame(&dst, unknownPayloadProto, FieldClassPayload, end, octet*len(pkt))
 		}
@@ -835,10 +845,13 @@ const (
 	// FlagContainer is used for [FrameField]s whose SubFields represent
 	// the entirety of the FrameField's data. i.e: DNS Questions/Answers.
 	FlagContainer
+	// FlagEncrypted marks fields whose bytes are ciphertext. i.e: TLS application_data fragment.
+	FlagEncrypted
 )
 
 func (ff Flags) IsLegacy() bool       { return ff&FlagLegacy != 0 }
 func (ff Flags) IsRightAligned() bool { return ff&FlagRightAligned != 0 }
+func (ff Flags) IsEncrypted() bool    { return ff&FlagEncrypted != 0 }
 
 type Frame struct {
 	PacketBitOffset int
@@ -1009,6 +1022,9 @@ func (frm Frame) LenBits() (totalBitlen int) {
 
 func (ff FrameField) String() string {
 	if ff.Class == FieldClassPayload {
+		if ff.Flags.IsEncrypted() {
+			return "Encrypted len=" + strconv.Itoa(ff.BitLength/8)
+		}
 		return "Payload len=" + strconv.Itoa(ff.BitLength/8)
 	}
 	if ff.Name != "" {

internet/pcap/capture_bench_test.go

@@ -9,6 +9,7 @@ import (
 	"github.com/soypat/lneto/dns"
 	"github.com/soypat/lneto/ethernet"
 	"github.com/soypat/lneto/ipv4"
+	"github.com/soypat/lneto/tcp"
 	"github.com/soypat/lneto/udp"
 )
 
@@ -106,6 +107,39 @@ func buildDNSPacket(b testing.TB) []byte {
 	return pkt
 }
 
+// buildTLSPacket builds an Ethernet+IPv4+TCP packet carrying a real
+// ClientHello record, exercising the string-heavy TLS path: cipher suite and
+// extension subfields, SNI and ALPN text.
+func buildTLSPacket(b testing.TB) []byte {
+	const (
+		ethSize  = 14
+		ipv4Size = 20
+		tcpSize  = 20
+	)
+	hello := captureClientHelloRecord(b, "example.com", []string{"h2", "http/1.1"})
+	pkt := make([]byte, ethSize+ipv4Size+tcpSize+len(hello))
+
+	efrm, _ := ethernet.NewFrame(pkt)
+	*efrm.DestinationHardwareAddr() = [6]byte{0xde, 0xad, 0xbe, 0xef, 0xca, 0xfe}
+	*efrm.SourceHardwareAddr() = [6]byte{0xff, 0xff, 0xff, 0xff, 0xff, 0xff}
+	efrm.SetEtherType(ethernet.TypeIPv4)
+
+	ifrm, _ := ipv4.NewFrame(pkt[ethSize:])
+	ifrm.SetVersionAndIHL(4, 5)
+	ifrm.SetID(0x1234)
+	ifrm.SetTTL(64)
+	ifrm.SetProtocol(lneto.IPProtoTCP)
+	ifrm.SetTotalLength(uint16(ipv4Size + tcpSize + len(hello)))
+
+	tfrm, _ := tcp.NewFrame(pkt[ethSize+ipv4Size:])
+	tfrm.SetSourcePort(51000)
+	tfrm.SetDestinationPort(443)
+	tfrm.SetOffsetAndFlags(5, tcp.FlagPSH|tcp.FlagACK)
+
+	copy(pkt[ethSize+ipv4Size+tcpSize:], hello)
+	return pkt
+}
+
 func configureBenchFormatter(f *Formatter) {
 	f.SubfieldLimit = benchSubfieldLimit
 	f.FrameSep = "\n"
@@ -123,6 +157,7 @@ func BenchmarkPcap(b *testing.B) {
 	}{
 		{"DHCP", buildDHCPPacket(b)},
 		{"DNS", buildDNSPacket(b)},
+		{"TLS", buildTLSPacket(b)},
 	}
 	for _, tc := range cases {
 		b.Run(tc.name, func(b *testing.B) {
@@ -182,6 +217,7 @@ func BenchmarkPcapPhases(b *testing.B) {
 	}{
 		{"DHCP", buildDHCPPacket(b)},
 		{"DNS", buildDNSPacket(b)},
+		{"TLS", buildTLSPacket(b)},
 	}
 	for _, tc := range cases {
 		b.Run(tc.name, func(b *testing.B) {

internet/pcap/capture_tls.go

@@ -0,0 +1,483 @@
+package pcap
+
+import (
+	"encoding/binary"
+
+	"github.com/soypat/lneto"
+	"github.com/soypat/lneto/internal"
+	"github.com/soypat/lneto/x/tls"
+)
+
+// maxTLSRecordsPerPacket bounds how many record frames a single packet may
+// produce. A TCP segment commonly coalesces several small records, but without
+// a bound a segment full of 5-byte empty records would produce thousands of
+// frames.
+const maxTLSRecordsPerPacket = 8
+
+// payloadIsTLS reports whether payload begins with what could be a TLS record
+// header. TLS has no magic number, so this is a heuristic: the content type
+// must be one of the four TLS 1.3 defines, the legacy record version must be
+// 0x03xx and the declared fragment length must be legal.
+//
+// It is what lets TLS be captured on any port instead of only on 443, and it
+// does not collide with HTTP, whose first byte is a method or version letter
+// and never a valid content type.
+func payloadIsTLS(payload []byte) bool {
+	if len(payload) < tls.SizeHeaderRecord {
+		return false
+	}
+	switch tls.ContentType(payload[0]) {
+	case tls.ContentTypeChangeCipherSpec, tls.ContentTypeAlert,
+		tls.ContentTypeHandshake, tls.ContentTypeApplicationData:
+	default:
+		return false
+	}
+	if payload[1] != 0x03 || payload[2] > 0x04 {
+		// Every record version in use is 3.x: TLS 1.0 through 1.3 inclusive.
+		return false
+	}
+	n := int(binary.BigEndian.Uint16(payload[3:5]))
+	return n > 0 && n <= tls.MaxCiphertext
+}
+
+// CaptureTLS breaks down the TLS records starting at bitOffset. A single entry
+// point handles every kind of TLS traffic: a record names its own content type,
+// so the caller does not need to know whether it is looking at a handshake, an
+// alert or application data, which is what makes capturing a whole port 443
+// conversation possible without tracking connection state.
+//
+// One [Frame] is produced per record, plus one more per cleartext handshake
+// message carried inside a handshake record. Everything after the ServerHello
+// is encrypted and appears on the wire as application_data; its fragment is
+// reported as an opaque payload, since decrypting it needs keys a capture does
+// not have.
+//
+// TLS is a byte stream: a record may span TCP segments and a handshake message
+// may span records. Whatever arrived is reported and the affected frame carries
+// [tls.ErrNeedMore]; reassembly is out of scope for a stateless breakdown.
+func (pc *PacketBreakdown) CaptureTLS(dst []Frame, pkt []byte, bitOffset int) ([]Frame, error) {
+	debuglog("pcap:tls:start")
+	if bitOffset%8 != 0 {
+		return dst, errNotByteAligned
+	}
+	off := bitOffset / 8
+	for nrec := 0; off < len(pkt); nrec++ {
+		if nrec == maxTLSRecordsPerPacket {
+			reclaimRemainingFrame(&dst, "TLS records?", FieldClassPayload, off*octet, octet*len(pkt))
+			break
+		}
+		newdst, consumed, err := pc.captureTLSRecord(dst, pkt, off*octet)
+		dst = newdst
+		if err != nil {
+			if nrec == 0 {
+				// Not TLS after all; let the caller frame the payload.
+				return dst, err
+			}
+			// Bytes trailing the last complete record that are too few or too
+			// malformed to be a record header of their own.
+			reclaimRemainingFrame(&dst, unknownPayloadProto, FieldClassPayload, off*octet, octet*len(pkt))
+			break
+		}
+		off += consumed
+	}
+	debuglog("pcap:tls:done")
+	return dst, nil
+}
+
+// captureTLSRecord appends the frames of the single record at bitOffset and
+// returns how many bytes of pkt the record occupied.
+func (pc *PacketBreakdown) captureTLSRecord(dst []Frame, pkt []byte, bitOffset int) ([]Frame, int, error) {
+	rec := pkt[bitOffset/8:]
+	rfrm, err := tls.NewRecordFrame(rec)
+	if err != nil {
+		return dst, 0, err
+	}
+	rfrm.ValidateSize(pc.validator())
+	if pc.validator().HasError() {
+		return dst, 0, pc.validator().ErrPop()
+	}
+	debuglog("pcap:tls:validated")
+	const fragOff = tls.SizeHeaderRecord * octet
+	ctype := rfrm.ContentType()
+	finfo := reclaimFrame(&dst, "TLS", bitOffset, baseTLSRecordFields[:])
+	finfo.Fields[0].Name = ctype.StringConst()
+	frag := rfrm.Payload()
+	if frag == nil {
+		// Fragment continues in a later segment. Report what arrived.
+		avail := len(rec) - tls.SizeHeaderRecord
+		finfo.Errors = append(finfo.Errors, tls.ErrNeedMore)
+		if avail > 0 {
+			var flags Flags
+			if ctype == tls.ContentTypeApplicationData {
+				flags = FlagEncrypted
+			}
+			finfo.Fields = append(finfo.Fields, FrameField{
+				Class:          FieldClassPayload,
+				FrameBitOffset: fragOff,
+				BitLength:      avail * octet,
+				Flags:          flags,
+			})
+		}
+		return dst, len(rec), nil
+	}
+
+	switch ctype {
+	case tls.ContentTypeHandshake:
+		// Handshake messages get frames of their own. finfo must not be touched
+		// past this point: appending to dst may move the Frame it points at.
+		dst = pc.captureTLSHandshake(dst, pkt, bitOffset+fragOff, len(frag))
+
+	case tls.ContentTypeAlert:
+		if len(frag) < 2 {
+			finfo.Errors = append(finfo.Errors, lneto.ErrTruncatedFrame)
+			break
+		}
+		// The level byte is advisory only: in TLS 1.3 every alert except
+		// close_notify and user_canceled is fatal whatever it says.
+		finfo.Fields = append(finfo.Fields, FrameField{
+			Name:           tls.AlertLevel(frag[0]).StringConst(),
+			Class:          FieldClassType,
+			FrameBitOffset: fragOff,
+			BitLength:      octet,
+			Flags:          FlagLegacy,
+		}, FrameField{
+			Name:           tls.AlertDescription(frag[1]).StringConst(),
+			Class:          FieldClassType,
+			FrameBitOffset: fragOff + octet,
+			BitLength:      octet,
+		})
+
+	case tls.ContentTypeApplicationData:
+		// Either genuine application data or a protected handshake or alert
+		// record; which of the three is only knowable after decryption.
+		finfo.Fields = append(finfo.Fields, FrameField{
+			Class:          FieldClassPayload,
+			FrameBitOffset: fragOff,
+			BitLength:      len(frag) * octet,
+			Flags:          FlagEncrypted,
+		})
+
+	default: // change_cipher_spec and unrecognized content types.
+		finfo.Fields = append(finfo.Fields, FrameField{
+			Class:          FieldClassPayload,
+			FrameBitOffset: fragOff,
+			BitLength:      len(frag) * octet,
+		})
+	}
+	return dst, rfrm.RecordLength(), nil
+}
+
+// captureTLSHandshake appends one frame per handshake message found in the
+// fragLen bytes of handshake record fragment starting at bitOffset.
+func (pc *PacketBreakdown) captureTLSHandshake(dst []Frame, pkt []byte, bitOffset, fragLen int) []Frame {
+	debuglog("pcap:tls:hs-start")
+	const hdr = tls.SizeHeaderHandshake
+	frag := pkt[bitOffset/8:][:fragLen]
+	fragEnd := bitOffset + fragLen*octet
+	for off := 0; off < fragLen; {
+		msgBitOff := bitOffset + off*octet
+		hfrm, err := tls.NewHandshakeFrame(frag[off:])
+		if err != nil {
+			// Fewer than 4 bytes left: a message header split across records.
+			reclaimRemainingFrame(&dst, "TLS Handshake?", FieldClassPayload, msgBitOff, fragEnd)
+			return dst
+		}
+		mtype := hfrm.MsgType()
+		finfo := reclaimFrame(&dst, tlsHandshakeProto(mtype), msgBitOff, baseTLSHandshakeFields[:])
+		finfo.Fields[0].Name = mtype.StringConst()
+		body := hfrm.Body()
+		if body == nil {
+			// Message body continues in the next record.
+			finfo.Errors = append(finfo.Errors, tls.ErrNeedMore)
+			if avail := fragLen - off - hdr; avail > 0 {
+				finfo.Fields = append(finfo.Fields, FrameField{
+					Class:          FieldClassPayload,
+					FrameBitOffset: hdr * octet,
+					BitLength:      avail * octet,
+				})
+			}
+			return dst
+		}
+		switch mtype {
+		case tls.HandshakeTypeClientHello:
+			pc.captureTLSHello(finfo, body, true)
+		case tls.HandshakeTypeServerHello:
+			pc.captureTLSHello(finfo, body, false)
+		default:
+			if len(body) > 0 {
+				finfo.Fields = append(finfo.Fields, FrameField{
+					Class:          FieldClassPayload,
+					FrameBitOffset: hdr * octet,
+					BitLength:      len(body) * octet,
+				})
+			}
+		}
+		off += hfrm.MessageLength()
+	}
+	debuglog("pcap:tls:hs-done")
+	return dst
+}
+
+// captureTLSHello appends the fields of a ClientHello (isClient) or ServerHello
+// body to finfo. The two differ only in that the client offers vectors of
+// cipher suites and compression methods where the server names exactly one of
+// each. Offsets are relative to the start of the handshake message, so the
+// handshake header size is added throughout.
+//
+// The walk is deliberately more permissive than [tls.NewClientHelloFrame]: a
+// capture must show what a malformed hello contains, so it reports the fields
+// it did decode and stops at the first inconsistent length instead of
+// discarding the message.
+func (pc *PacketBreakdown) captureTLSHello(finfo *Frame, body []byte, isClient bool) {
+	const hdr = tls.SizeHeaderHandshake
+	const fixed = 2 + tls.SizeRandom + 1 // legacy_version + random + session id length
+	if len(body) < fixed {
+		finfo.Errors = append(finfo.Errors, lneto.ErrTruncatedFrame)
+		return
+	}
+	finfo.Fields = append(finfo.Fields, FrameField{
+		// Pinned to 0x0303 by TLS 1.3 whatever version is really negotiated;
+		// the real version travels in the supported_versions extension.
+		Class:          FieldClassVersion,
+		FrameBitOffset: hdr * octet,
+		BitLength:      2 * octet,
+		Flags:          FlagLegacy,
+	}, FrameField{
+		Name:           "Random",
+		Class:          FieldClassID,
+		FrameBitOffset: (hdr + 2) * octet,
+		BitLength:      tls.SizeRandom * octet,
+	})
+
+	off := 2 + tls.SizeRandom
+	sidLen := int(body[off])
+	off++
+	if sidLen > len(body)-off {
+		finfo.Errors = append(finfo.Errors, lneto.ErrTruncatedFrame)
+		return
+	}
+	if sidLen > 0 {
+		// TLS 1.3 has no session resumption by ID; a non-empty value means
+		// middlebox compatibility mode, echoed verbatim by the server.
+		finfo.Fields = append(finfo.Fields, FrameField{
+			Name:           "Session ID",
+			Class:          FieldClassID,
+			FrameBitOffset: (hdr + off) * octet,
+			BitLength:      sidLen * octet,
+		})
+	}
+	off += sidLen
+
+	if isClient {
+		if len(body)-off < 2 {
+			finfo.Errors = append(finfo.Errors, lneto.ErrTruncatedFrame)
+			return
+		}
+		suitesLen := int(binary.BigEndian.Uint16(body[off:]))
+		off += 2
+		if suitesLen > len(body)-off {
+			finfo.Errors = append(finfo.Errors, lneto.ErrTruncatedFrame)
+			return
+		}
+		pc.appendTLSCipherSuites(finfo, body[off:off+suitesLen], hdr+off)
+		off += suitesLen
+
+		compLen := int(body[off])
+		off++
+		if compLen > len(body)-off {
+			finfo.Errors = append(finfo.Errors, lneto.ErrTruncatedFrame)
+			return
+		}
+		finfo.Fields = append(finfo.Fields, FrameField{
+			Name:           "compression methods",
+			Class:          FieldClassOptions,
+			FrameBitOffset: (hdr + off) * octet,
+			BitLength:      compLen * octet,
+			Flags:          FlagLegacy,
+		})
+		off += compLen
+	} else {
+		if len(body)-off < 3 {
+			finfo.Errors = append(finfo.Errors, lneto.ErrTruncatedFrame)
+			return
+		}
+		suite := tls.CipherSuite(binary.BigEndian.Uint16(body[off:]))
+		finfo.Fields = append(finfo.Fields, FrameField{
+			Name:           suite.StringConst(),
+			Class:          FieldClassType,
+			FrameBitOffset: (hdr + off) * octet,
+			BitLength:      2 * octet,
+		}, FrameField{
+			Name:           "compression method",
+			Class:          FieldClassOptions,
+			FrameBitOffset: (hdr + off + 2) * octet,
+			BitLength:      octet,
+			Flags:          FlagLegacy,
+		})
+		off += 3
+	}
+
+	if len(body)-off < 2 {
+		return // No extensions block. Not a legal 1.3 hello, but not a framing error either.
+	}
+	extsLen := int(binary.BigEndian.Uint16(body[off:]))
+	off += 2
+	if extsLen > len(body)-off {
+		finfo.Errors = append(finfo.Errors, lneto.ErrTruncatedFrame)
+		extsLen = len(body) - off
+	}
+	pc.appendTLSExtensions(finfo, body[off:off+extsLen], hdr+off)
+}
+
+// appendTLSCipherSuites appends a cipher_suites container field whose subfields
+// name each offered suite. base is the byte offset of suites within the frame.
+// GREASE values show up as their numeric type, which is what a capture should
+// display: they carry no meaning and are not an error.
+func (pc *PacketBreakdown) appendTLSCipherSuites(finfo *Frame, suites []byte, base int) {
+	// Reclaim from the Fields backing array to reuse its SubFields backing array.
+	sfield := internal.SliceReclaim(&finfo.Fields)
+	*sfield = FrameField{
+		Name:           "cipher suites",
+		Class:          FieldClassOptions,
+		SubFields:      sfield.SubFields[:0],
+		FrameBitOffset: base * octet,
+		BitLength:      len(suites) * octet,
+	}
+	if pc.SubfieldLimit <= 0 {
+		return
+	}
+	for off := 0; off+2 <= len(suites); off += 2 {
+		if len(sfield.SubFields) >= pc.SubfieldLimit {
+			finfo.Errors = append(finfo.Errors, ErrLimitExceeded)
+			return
+		}
+		suite := tls.CipherSuite(binary.BigEndian.Uint16(suites[off:]))
+		sfield.SubFields = append(sfield.SubFields, FrameField{
+			Name:           suite.StringConst(),
+			Class:          FieldClassType,
+			FrameBitOffset: (base + off) * octet,
+			BitLength:      2 * octet,
+		})
+	}
+}
+
+// appendTLSExtensions appends an extensions container field whose subfields are
+// the individual extensions. base is the byte offset of exts within the frame.
+func (pc *PacketBreakdown) appendTLSExtensions(finfo *Frame, exts []byte, base int) {
+	extfield := internal.SliceReclaim(&finfo.Fields)
+	*extfield = FrameField{
+		Name:           "extensions",
+		Class:          FieldClassOptions,
+		SubFields:      extfield.SubFields[:0],
+		FrameBitOffset: base * octet,
+		BitLength:      len(exts) * octet,
+	}
+	if pc.SubfieldLimit <= 0 {
+		return
+	}
+	for off := 0; off+4 <= len(exts); {
+		ext := tls.ExtensionType(binary.BigEndian.Uint16(exts[off:]))
+		n := int(binary.BigEndian.Uint16(exts[off+2:]))
+		off += 4
+		if n > len(exts)-off {
+			finfo.Errors = append(finfo.Errors, lneto.ErrTruncatedFrame)
+			return
+		}
+		if len(extfield.SubFields) >= pc.SubfieldLimit {
+			finfo.Errors = append(finfo.Errors, ErrLimitExceeded)
+			return
+		}
+		extfield.SubFields = append(extfield.SubFields, tlsExtensionField(ext, exts[off:off+n], base+off))
+		off += n
+	}
+}
+
+// tlsExtensionField describes a single hello extension. Extensions carrying a
+// human readable value point at that value instead of at the whole extension
+// body, and the bulky opaque ones are classed as payload so that a
+// [Formatter.FilterClasses] can drop them without losing the rest of the hello.
+func tlsExtensionField(ext tls.ExtensionType, data []byte, base int) FrameField {
+	field := FrameField{
+		Name:           ext.StringConst(),
+		Class:          FieldClassOptions,
+		FrameBitOffset: base * octet,
+		BitLength:      len(data) * octet,
+	}
+	switch ext {
+	case tls.ExtServerName:
+		// server_name_list(2) + name_type(1) + HostName length(2), then the name.
+		// Only host_name(0) is defined, and no client has ever sent a second entry.
+		const nameOff = 5
+		if len(data) >= nameOff && data[2] == 0 {
+			n := int(binary.BigEndian.Uint16(data[3:5]))
+			if n <= len(data)-nameOff {
+				field.Class = FieldClassText
+				field.FrameBitOffset = (base + nameOff) * octet
+				field.BitLength = n * octet
+			}
+		}
+
+	case tls.ExtALPN:
+		// Each protocol name is length prefixed. Quoting the whole list keeps
+		// every name visible, with the length bytes showing up as escapes.
+		if len(data) >= 2 {
+			field.Class = FieldClassText
+			field.FrameBitOffset = (base + 2) * octet
+			field.BitLength = (len(data) - 2) * octet
+		}
+
+	case tls.ExtKeyShare, tls.ExtPreSharedKey, tls.ExtPadding, tls.ExtSessionTicket,
+		tls.ExtCookie, tls.ExtEncryptedClientHello, tls.ExtSignedCertificateTimestamp:
+		// Opaque and large: a post-quantum key share alone runs past 1kB.
+		field.Class = FieldClassPayload
+	}
+	return field
+}
+
+// tlsHandshakeProto names the frame of a handshake message. Only the messages a
+// capture can see in cleartext get a name of their own; the rest travel inside
+// a protected record and never reach here undecrypted.
+func tlsHandshakeProto(t tls.HandshakeType) string {
+	switch t {
+	case tls.HandshakeTypeClientHello:
+		return "TLS ClientHello"
+	case tls.HandshakeTypeServerHello:
+		return "TLS ServerHello"
+	}
+	return "TLS Handshake"
+}
+
+var baseTLSRecordFields = [...]FrameField{
+	{
+		// Name is filled in with the content type's name by captureTLSRecord.
+		Class:          FieldClassType,
+		FrameBitOffset: 0,
+		BitLength:      1 * octet,
+	},
+	{
+		// legacy_record_version, which TLS 1.3 receivers ignore entirely.
+		Class:          FieldClassVersion,
+		FrameBitOffset: 1 * octet,
+		BitLength:      2 * octet,
+		Flags:          FlagLegacy,
+	},
+	{
+		Class:          FieldClassSize,
+		FrameBitOffset: 3 * octet,
+		BitLength:      2 * octet,
+	},
+}
+
+var baseTLSHandshakeFields = [...]FrameField{
+	{
+		// Name is filled in with the message type's name by captureTLSHandshake.
+		Class:          FieldClassType,
+		FrameBitOffset: 0,
+		BitLength:      1 * octet,
+	},
+	{
+		Class:          FieldClassSize,
+		FrameBitOffset: 1 * octet,
+		BitLength:      3 * octet,
+	},
+}

internet/pcap/capture_tls_test.go

@@ -0,0 +1,414 @@
+package pcap
+
+import (
+	stdtls "crypto/tls"
+	"math/rand"
+	"net"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/soypat/lneto/ethernet"
+	"github.com/soypat/lneto/internal/ltesto"
+	"github.com/soypat/lneto/tcp"
+	"github.com/soypat/lneto/x/tls"
+)
+
+// captureClientHelloRecord drives a standard library TLS client far enough to
+// emit its first flight and returns the complete handshake record, header
+// included. A real client gives realistic extension ordering, a 32-byte
+// middlebox compatibility session ID and a post-quantum key share.
+func captureClientHelloRecord(t testing.TB, serverName string, protos []string) []byte {
+	t.Helper()
+	client, server := net.Pipe()
+	defer client.Close()
+	defer server.Close()
+	go func() {
+		c := stdtls.Client(client, &stdtls.Config{
+			ServerName: serverName,
+			MinVersion: stdtls.VersionTLS13,
+			MaxVersion: stdtls.VersionTLS13,
+			NextProtos: protos,
+		})
+		_ = c.Handshake() // Will fail; only the first flight is needed.
+	}()
+	server.SetReadDeadline(time.Now().Add(10 * time.Second))
+	var buf [4096]byte
+	n, err := server.Read(buf[:])
+	if err != nil {
+		t.Fatalf("reading ClientHello: %v", err)
+	}
+	rec, err := tls.NewRecordFrame(buf[:n])
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !rec.Complete() {
+		t.Fatalf("ClientHello record split across reads: have %d want %d", n, rec.RecordLength())
+	}
+	return append([]byte{}, rec.RawData()...)
+}
+
+// TestCaptureTLSClientHello runs a real ClientHello through the full
+// Ethernet/IPv4/TCP path to check that TLS is detected by payload content
+// rather than by port, and that the SNI hostname is recovered.
+func TestCaptureTLSClientHello(t *testing.T) {
+	const mtu = ethernet.MaxMTU
+	const serverName = "example.com"
+	payload := captureClientHelloRecord(t, serverName, []string{"h2", "http/1.1"})
+
+	var buf [mtu]byte
+	var gen ltesto.PacketGen
+	rng := rand.New(rand.NewSource(1))
+	gen.RandomizeAddrs(rng)
+	pkt := gen.AppendRandomIPv4TCPPacket(buf[:0], rng, tcp.Segment{
+		SEQ:     100,
+		ACK:     200,
+		DATALEN: tcp.Size(len(payload)),
+		WND:     1024,
+		Flags:   tcp.FlagPSH | tcp.FlagACK,
+	})
+	copy(pkt[len(pkt)-len(payload):], payload)
+
+	var pbreak PacketBreakdown
+	pbreak.SubfieldLimit = 32
+	frames, err := pbreak.CaptureEthernet(nil, pkt, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Ethernet+IPv4+TCP+TLS record+TLS ClientHello = 5 frames.
+	if len(frames) != 5 {
+		for i := range frames {
+			t.Logf("frame[%d]=%s", i, frames[i].String())
+		}
+		t.Fatalf("want 5 frames, got %d", len(frames))
+	}
+	if frames[3].Protocol != "TLS" {
+		t.Errorf("frame 3 protocol=%q want TLS", frames[3].Protocol)
+	}
+	if frames[4].Protocol != "TLS ClientHello" {
+		t.Errorf("frame 4 protocol=%q want TLS ClientHello", frames[4].Protocol)
+	}
+	if len(frames[3].Errors) > 0 || len(frames[4].Errors) > 0 {
+		t.Errorf("unexpected errors: %v %v", frames[3].Errors, frames[4].Errors)
+	}
+	// A handshake record frame describes the record header only; its fragment is
+	// broken down by the handshake frame that follows, so that no bytes are
+	// claimed by two frames at once.
+	if got := frames[3].LenBits() / 8; got != tls.SizeHeaderRecord {
+		t.Errorf("TLS record frame len=%d want %d", got, tls.SizeHeaderRecord)
+	}
+	if got := frames[4].LenBits() / 8; got != len(payload)-tls.SizeHeaderRecord {
+		t.Errorf("handshake frame len=%d want %d", got, len(payload)-tls.SizeHeaderRecord)
+	}
+
+	ctype := fieldByName(frames[3], "handshake")
+	if ctype == nil {
+		t.Fatal("no handshake content type field")
+	}
+	if v, _ := frames[3].FieldAsUint(indexOfField(frames[3], "handshake"), pkt); v != uint64(tls.ContentTypeHandshake) {
+		t.Errorf("content type=%d want %d", v, tls.ContentTypeHandshake)
+	}
+
+	// SNI and ALPN live as subfields of the extensions container.
+	exts := fieldByName(frames[4], "extensions")
+	if exts == nil {
+		t.Fatal("no extensions field in ClientHello")
+	}
+	var sni, alpn *FrameField
+	for i := range exts.SubFields {
+		switch exts.SubFields[i].Name {
+		case tls.ExtServerName.String():
+			sni = &exts.SubFields[i]
+		case tls.ExtALPN.String():
+			alpn = &exts.SubFields[i]
+		}
+	}
+	if sni == nil {
+		t.Fatal("no server_name extension field")
+	}
+	got := string(pkt[(frames[4].PacketBitOffset+sni.FrameBitOffset)/8:][:sni.BitLength/8])
+	if got != serverName {
+		t.Errorf("server_name=%q want %q", got, serverName)
+	}
+	if alpn == nil {
+		t.Error("no application_layer_protocol_negotiation extension field")
+	}
+
+	// Formatted output is the point of the exercise: the hostname and the
+	// negotiated suites must be readable in one line.
+	var f Formatter
+	f.SubfieldLimit = 32
+	out, err := f.FormatFrames(nil, frames, pkt)
+	if err != nil {
+		t.Fatal(err)
+	}
+	str := string(out)
+	for _, want := range []string{"TLS", "handshake=", "client_hello=", serverName,
+		"TLS_AES_128_GCM_SHA256", "http/1.1"} {
+		if !strings.Contains(str, want) {
+			t.Errorf("formatted output missing %q:\n%s", want, str)
+		}
+	}
+}
+
+// TestCaptureTLSRecordSequence checks the multi-record path: a server flight
+// coalesces ServerHello, the compatibility ChangeCipherSpec and the first
+// protected record into a single segment.
+func TestCaptureTLSRecordSequence(t *testing.T) {
+	var b tls.Builder
+	var buf [512]byte
+	b.Reset(buf[:])
+
+	// ServerHello record.
+	b.AddU8(uint8(tls.ContentTypeHandshake))
+	b.AddU16(tls.VersionTLS12)
+	b.OpenU16()
+	b.AddU8(uint8(tls.HandshakeTypeServerHello))
+	b.OpenU24()
+	b.AddU16(tls.VersionTLS12) // legacy_version
+	for range tls.SizeRandom {
+		b.AddU8(0xab) // server_random
+	}
+	b.OpenU8() // legacy_session_id echo
+	for range 32 {
+		b.AddU8(0xcd)
+	}
+	b.Close()
+	b.AddU16(uint16(tls.SuiteAES128GCMSHA256))
+	b.AddU8(0)  // legacy_compression_method
+	b.OpenU16() // extensions
+	b.AddU16(uint16(tls.ExtSupportedVersions))
+	b.OpenU16()
+	b.AddU16(tls.VersionTLS13)
+	b.Close()
+	b.AddU16(uint16(tls.ExtKeyShare))
+	b.OpenU16()
+	b.AddU16(uint16(tls.GroupX25519))
+	b.OpenU16()
+	for range 32 {
+		b.AddU8(0xee)
+	}
+	b.Close()
+	b.Close()
+	b.Close() // extensions
+	b.Close() // handshake body
+	b.Close() // record fragment
+
+	// change_cipher_spec record.
+	b.AddU8(uint8(tls.ContentTypeChangeCipherSpec))
+	b.AddU16(tls.VersionTLS12)
+	b.OpenU16()
+	b.AddU8(1)
+	b.Close()
+
+	// First protected record: outwardly application_data.
+	b.AddU8(uint8(tls.ContentTypeApplicationData))
+	b.AddU16(tls.VersionTLS12)
+	b.OpenU16()
+	for range 24 {
+		b.AddU8(0x5a)
+	}
+	b.Close()
+
+	pkt, err := b.Bytes()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !payloadIsTLS(pkt) {
+		t.Fatal("payloadIsTLS did not recognize a ServerHello record")
+	}
+
+	var pbreak PacketBreakdown
+	pbreak.SubfieldLimit = 8
+	frames, err := pbreak.CaptureTLS(nil, pkt, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []string{"TLS", "TLS ServerHello", "TLS", "TLS"}
+	if len(frames) != len(want) {
+		for i := range frames {
+			t.Logf("frame[%d]=%s", i, frames[i].String())
+		}
+		t.Fatalf("got %d frames want %d", len(frames), len(want))
+	}
+	for i, wantProto := range want {
+		if frames[i].Protocol != wantProto {
+			t.Errorf("frame[%d] protocol=%q want %q", i, frames[i].Protocol, wantProto)
+		}
+		if len(frames[i].Errors) > 0 {
+			t.Errorf("frame[%d] errors=%v", i, frames[i].Errors)
+		}
+	}
+	if fieldByName(frames[1], tls.SuiteAES128GCMSHA256.String()) == nil {
+		t.Error("ServerHello cipher suite field not named after the selected suite")
+	}
+	i, err := frames[3].FieldByClass(FieldClassPayload)
+	if err != nil {
+		t.Error("no payload field in application_data record:", err)
+	} else if !frames[3].Fields[i].Flags.IsEncrypted() {
+		t.Error("application_data fragment not flagged as encrypted")
+	}
+	// Record frames must start exactly where the previous record ended, and the
+	// last one must end at the packet end: no record skipped, none double read.
+	off := 0
+	for i := range frames {
+		if frames[i].Protocol != "TLS" {
+			continue
+		}
+		if frames[i].PacketBitOffset != off*octet {
+			t.Errorf("frame[%d] starts at bit %d want %d", i, frames[i].PacketBitOffset, off*octet)
+		}
+		rec, err := tls.NewRecordFrame(pkt[off:])
+		if err != nil {
+			t.Fatal(err)
+		}
+		off += rec.RecordLength()
+	}
+	if off != len(pkt) {
+		t.Errorf("records cover %d bytes of %d", off, len(pkt))
+	}
+}
+
+// TestCaptureTLSIncomplete checks the stream cases a stateless breakdown cannot
+// reassemble: a record whose fragment continues in the next TCP segment, and a
+// handshake message whose body continues in the next record.
+func TestCaptureTLSIncomplete(t *testing.T) {
+	t.Run("record", func(t *testing.T) {
+		pkt := []byte{byte(tls.ContentTypeApplicationData), 0x03, 0x03, 0x04, 0x00, 1, 2, 3}
+		var pbreak PacketBreakdown
+		frames, err := pbreak.CaptureTLS(nil, pkt, 0)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if len(frames) != 1 {
+			t.Fatalf("got %d frames want 1", len(frames))
+		}
+		if len(frames[0].Errors) != 1 || frames[0].Errors[0] != tls.ErrNeedMore {
+			t.Errorf("errors=%v want %v", frames[0].Errors, tls.ErrNeedMore)
+		}
+		if got := frames[0].LenBits() / 8; got != len(pkt) {
+			t.Errorf("frame covers %d bytes want %d", got, len(pkt))
+		}
+	})
+	t.Run("handshake", func(t *testing.T) {
+		// A 5-byte record carrying a Certificate message header that declares a
+		// 1000-byte body: the rest arrives in later records.
+		pkt := []byte{
+			byte(tls.ContentTypeHandshake), 0x03, 0x03, 0x00, 0x06,
+			byte(tls.HandshakeTypeCertificate), 0x00, 0x03, 0xe8, 0xaa, 0xbb,
+		}
+		var pbreak PacketBreakdown
+		frames, err := pbreak.CaptureTLS(nil, pkt, 0)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if len(frames) != 2 {
+			t.Fatalf("got %d frames want 2", len(frames))
+		}
+		if frames[1].Protocol != "TLS Handshake" {
+			t.Errorf("protocol=%q want TLS Handshake", frames[1].Protocol)
+		}
+		if len(frames[1].Errors) != 1 || frames[1].Errors[0] != tls.ErrNeedMore {
+			t.Errorf("errors=%v want %v", frames[1].Errors, tls.ErrNeedMore)
+		}
+		if got := frames[1].LenBits() / 8; got != 6 {
+			t.Errorf("handshake frame covers %d bytes want 6", got)
+		}
+	})
+}
+
+// TestCaptureTLSAlert checks the cleartext alert path, which is the only way a
+// TLS 1.3 handshake failure is visible to a capture.
+func TestCaptureTLSAlert(t *testing.T) {
+	pkt := []byte{
+		byte(tls.ContentTypeAlert), 0x03, 0x03, 0x00, 0x02,
+		byte(tls.AlertLevelFatal), byte(tls.AlertHandshakeFailure),
+	}
+	var pbreak PacketBreakdown
+	frames, err := pbreak.CaptureTLS(nil, pkt, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(frames) != 1 {
+		t.Fatalf("got %d frames want 1", len(frames))
+	}
+	if fieldByName(frames[0], tls.AlertHandshakeFailure.String()) == nil {
+		t.Errorf("no field named %q in %s", tls.AlertHandshakeFailure.String(), frames[0].String())
+	}
+	var f Formatter
+	f.DisableLegacyFilter = true
+	out, err := f.FormatFrame(nil, frames[0], pkt)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(out), "handshake_failure") {
+		t.Errorf("formatted alert missing description: %s", out)
+	}
+}
+
+// TestPayloadIsTLS guards the heuristic that routes a TCP payload to CaptureTLS
+// against the HTTP traffic it shares the datapath with.
+func TestPayloadIsTLS(t *testing.T) {
+	for _, tc := range []struct {
+		name    string
+		payload []byte
+		want    bool
+	}{
+		{"client hello", []byte{22, 3, 1, 0, 10}, true},
+		{"app data", []byte{23, 3, 3, 0x40, 0x00}, true},
+		{"alert", []byte{21, 3, 3, 0, 2}, true},
+		{"http request", []byte("GET / HTTP/1.1\r\n"), false},
+		{"http response", []byte("HTTP/1.1 200 OK\r\n"), false},
+		{"bad content type", []byte{25, 3, 3, 0, 10}, false},
+		{"bad version", []byte{22, 2, 1, 0, 10}, false},
+		{"future version", []byte{22, 3, 5, 0, 10}, false},
+		{"zero length", []byte{22, 3, 3, 0, 0}, false},
+		{"oversize length", []byte{23, 3, 3, 0xff, 0xff}, false},
+		{"short", []byte{22, 3, 3}, false},
+	} {
+		if got := payloadIsTLS(tc.payload); got != tc.want {
+			t.Errorf("%s: payloadIsTLS=%v want %v", tc.name, got, tc.want)
+		}
+	}
+}
+
+// TestCaptureTLSRecordLimit checks that a segment packed with tiny records
+// cannot make a single packet produce unbounded frames.
+func TestCaptureTLSRecordLimit(t *testing.T) {
+	var pkt []byte
+	for range maxTLSRecordsPerPacket + 3 {
+		pkt = append(pkt, byte(tls.ContentTypeApplicationData), 3, 3, 0, 1, 0x99)
+	}
+	var pbreak PacketBreakdown
+	frames, err := pbreak.CaptureTLS(nil, pkt, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(frames) != maxTLSRecordsPerPacket+1 {
+		t.Fatalf("got %d frames want %d", len(frames), maxTLSRecordsPerPacket+1)
+	}
+	last := frames[len(frames)-1]
+	if last.Protocol != "TLS records?" {
+		t.Errorf("last frame protocol=%q want TLS records?", last.Protocol)
+	}
+	if end := (last.PacketBitOffset + last.LenBits()) / 8; end != len(pkt) {
+		t.Errorf("remaining frame ends at %d want %d", end, len(pkt))
+	}
+}
+
+func fieldByName(frm Frame, name string) *FrameField {
+	i := indexOfField(frm, name)
+	if i < 0 {
+		return nil
+	}
+	return &frm.Fields[i]
+}
+
+func indexOfField(frm Frame, name string) int {
+	for i := range frm.Fields {
+		if frm.Fields[i].Name == name {
+			return i
+		}
+	}
+	return -1
+}

internet/pcap/format.go

@@ -136,6 +136,9 @@ func (f *Formatter) formatField(dst []byte, pktStartOff int, field FrameField, p
 	name := field.Name
 	if name == "" {
 		name = field.Class.String()
+		if field.Flags.IsEncrypted() {
+			name = "encrypted"
+		}
 	}
 	hasSpaces := strings.IndexByte(name, ' ') >= 0
 	if hasSpaces {
@@ -191,8 +194,10 @@ func (f *Formatter) formatField(dst []byte, pktStartOff int, field FrameField, p
 		nameOff := field.FrameBitOffset / 8
 		dst = dnsAppendDottedName(dst, dnsMsg, nameOff)
 	case FieldClassDst, FieldClassSrc, FieldClassSize, FieldClassAddress, FieldClassOperation:
-		// IP, MAC addresses and ports.
-		if field.BitLength <= 16 {
+		// IP, MAC addresses and ports. Sizes are always numbers, never
+		// addresses, so a wide one such as the TLS 24-bit handshake length is
+		// still printed in decimal.
+		if field.BitLength <= 16 || field.Class == FieldClassSize && field.BitLength <= 64 {
 			v, err := f.fieldAsUint(pkt, fieldBitStart, field.BitLength, field.Flags.IsRightAligned())
 			if err != nil {
 				return dst, err