tlsparse

type CipherProperties struct {
	Name string `json:"name"`
	// KeyExchange is "ECDHE", "DHE", "RSA", "DH_anon", ... or "" for TLS 1.3
	// suites, where key exchange is negotiated by extension instead.
	KeyExchange string `json:"key_exchange,omitempty"`
	// Authentication is the signature algorithm family implied by the suite:
	// "RSA", "ECDSA", "DSS", "anon", or "" for TLS 1.3.
	Authentication string `json:"authentication,omitempty"`
	Encryption     string `json:"encryption"`
	MAC            string `json:"mac"`
	ForwardSecrecy bool   `json:"forward_secrecy"`
	AEAD           bool   `json:"aead"`
	Export         bool   `json:"export,omitempty"`
	Anonymous      bool   `json:"anonymous,omitempty"`
	TLS13          bool   `json:"tls13,omitempty"`
	Signalling     bool   `json:"signalling,omitempty"`
	// Known is false when the codepoint is not in the table; Name is then
	// the hex form and every other field is zero.
	Known bool `json:"known"`
}

type ClientHello struct {
	LegacyVersion      uint16   `json:"legacy_version"`
	SessionIDLen       int      `json:"session_id_len"`
	CipherSuites       []uint16 `json:"cipher_suites"`
	CompressionMethods []uint8  `json:"compression_methods"`
	// Extensions lists extension codepoints in the order they appeared.
	Extensions []uint16 `json:"extensions"`

	ServerName        string   `json:"server_name,omitempty"`
	ALPN              []string `json:"alpn,omitempty"`
	SupportedVersions []uint16 `json:"supported_versions,omitempty"`
	SupportedGroups   []uint16 `json:"supported_groups,omitempty"`

	// KeyShareGroups are the groups the client actually sent a key share
	// for, in offer order.
	//
	// This is not the same signal as SupportedGroups and the difference is
	// the whole point of a PQ-readiness inventory. SupportedGroups says what
	// the client would accept; KeyShareGroups says what it spent bytes
	// betting on. A client that advertises X25519MLKEM768 in supported
	// groups but only key-shares x25519 will complete a classical handshake
	// against any server that takes the offer, and is not post-quantum in
	// practice.
	KeyShareGroups []uint16 `json:"key_share_groups,omitempty"`

	SignatureAlgorithms     []uint16 `json:"signature_algorithms,omitempty"`
	SignatureAlgorithmsCert []uint16 `json:"signature_algorithms_cert,omitempty"`
	PSKKeyExchangeModes     []uint8  `json:"psk_key_exchange_modes,omitempty"`

	HasPreSharedKey         bool `json:"has_pre_shared_key,omitempty"`
	HasEarlyData            bool `json:"has_early_data,omitempty"`
	HasSessionTicket        bool `json:"has_session_ticket,omitempty"`
	HasExtendedMasterSecret bool `json:"has_extended_master_secret,omitempty"`
	HasRenegotiationInfo    bool `json:"has_renegotiation_info,omitempty"`
	HasStatusRequest        bool `json:"has_status_request,omitempty"`
	// QUIC is true when quic_transport_parameters is present, which marks
	// this as a QUIC handshake rather than TLS over TCP. It feeds the
	// protocol character of JA4.
	QUIC bool `json:"quic,omitempty"`

	// ECH is set when an encrypted_client_hello extension was present. When
	// it is, ServerName is the public outer name, not the real destination.
	ECH *ECHInfo `json:"ech,omitempty"`

	// GREASE reports whether any GREASE codepoint was observed. Its absence
	// is itself informative: most modern browsers always send it.
	GREASE bool `json:"grease"`

	// Truncated is true when the extension block ran past the available
	// bytes. Fields decoded before that point are still valid.
	Truncated bool `json:"truncated,omitempty"`
}

type ECHInfo struct {
	// Outer is true for ClientHelloOuter (the handshake visible on the
	// wire), false for ClientHelloInner (only seen after decryption, so
	// effectively never in passive capture).
	Outer    bool   `json:"outer"`
	KDFID    uint16 `json:"kdf_id,omitempty"`
	AEADID   uint16 `json:"aead_id,omitempty"`
	ConfigID uint8  `json:"config_id,omitempty"`
}

type GroupProperties struct {
	Name string `json:"name"`
	// PostQuantum is true when the group contributes a post-quantum KEM to
	// the shared secret, whether or not it is hybrid.
	PostQuantum bool `json:"post_quantum"`
	// Hybrid is true when a classical and a post-quantum component are
	// combined. Hybrid is the deployable form today; a pure KEM group means
	// classical security has been dropped entirely.
	Hybrid bool `json:"hybrid,omitempty"`
	Known  bool `json:"known"`
}

type HandshakeMessage struct {
	Type uint8
	Body []byte
}

type ServerHello struct {
	LegacyVersion     uint16   `json:"legacy_version"`
	CipherSuite       uint16   `json:"cipher_suite"`
	CompressionMethod uint8    `json:"compression_method"`
	Extensions        []uint16 `json:"extensions"`

	// SelectedVersion is the supported_versions value when present. It is
	// authoritative over LegacyVersion, which a TLS 1.3 server pins to
	// TLS 1.2 for middlebox compatibility.
	SelectedVersion uint16 `json:"selected_version,omitempty"`

	// Group is the negotiated key exchange group, and GroupSource records
	// where it was read from.
	Group       uint16 `json:"group,omitempty"`
	GroupSource string `json:"group_source,omitempty"`

	SelectedALPN string `json:"selected_alpn,omitempty"`

	IsHelloRetryRequest bool `json:"is_hello_retry_request,omitempty"`
	HasPreSharedKey     bool `json:"has_pre_shared_key,omitempty"`

	// FlightComplete reports that the server has said everything it will
	// ever say in the clear, so nothing is gained by waiting for more
	// bytes on this connection.
	//
	// Under TLS 1.3 that is the ServerHello itself: Certificate,
	// CertificateVerify and EncryptedExtensions all move under handshake
	// encryption. Under TLS 1.2 it is ServerHelloDone, which closes the
	// server's flight after Certificate and ServerKeyExchange.
	//
	// It exists so an observation can be reported as soon as it is
	// complete rather than when the connection closes. A browser holds
	// connections open for minutes, so waiting for the close means a live
	// capture shows nothing for minutes after the handshake it just saw.
	//
	// A resumed TLS 1.2 session sends no ServerHelloDone — the server goes
	// straight to ChangeCipherSpec — so those stay false and are reported
	// when the connection ends. That is a latency cost on an uncommon case,
	// not a loss.
	FlightComplete bool `json:"flight_complete,omitempty"`

	// CertificateChain holds the raw DER of the server's certificate chain,
	// leaf first. Populated for TLS 1.2 and below only.
	CertificateChain [][]byte `json:"-"`

	Truncated bool `json:"truncated,omitempty"`
}