tlsx

README

Introduction

This is a fork of the bradleyfalzon/tlsx package, that was updated to store TLS extensions in the client hello message in the order they were encountered during parsing. It was further extended with unit tests, benchmarks and parsing code to extract the TLS server hello message.

This package is used to create JA3 hashes, for fingerprinting TLS client and server hellos in dreadl0ck/ja3 Since not all values produced by parsing the hello messages are required to calculate the fingerprint, two variations of the data structures are provided for both client and server: XXXHello() and XXXHelloBasic(). The basic datatype contains less fields and does less parsing, which makes it faster and causes less allocations.

API

package tlsx // import "github.com/dreadl0ck/tlsx"

const SNINameTypeDNS uint8 = 0 ...
const ClientHelloRandomLen = 32
const ServerHelloRandomLen = 32
var ErrHandshakeWrongType = errors.New("handshake is of wrong type, or not a handshake message") ...
var CipherSuiteReg = map[CipherSuite]string{ ... }
var ExtensionReg = map[Extension]string{ ... }
var VersionReg = map[Version]string{ ... }
type CipherSuite uint16
type ClientHello struct{ ... }
    func GetClientHello(packet gopacket.Packet) *ClientHello
type ClientHelloBasic struct{ ... }
    func GetClientHelloBasic(packet gopacket.Packet) *ClientHelloBasic
type CurveID uint16
type Extension uint16
    const ExtServerName Extension = 0 ...
type ServerHello struct{ ... }
    func GetServerHello(packet gopacket.Packet) *ServerHello
type ServerHelloBasic struct{ ... }
    func GetServerHelloBasic(packet gopacket.Packet) *ServerHelloBasic
type TLSMessage struct{ ... }
type Version uint16
    const VerSSL30 Version = 0x300 ...

Tests and Benchmarks

$ go test -v -bench=.
=== RUN   TestClientHello
--- PASS: TestClientHello (0.00s)
=== RUN   TestClientHelloBasic
--- PASS: TestClientHelloBasic (0.00s)
=== RUN   TestServerHello
--- PASS: TestServerHello (0.00s)
=== RUN   TestGetServerHelloBasic
--- PASS: TestGetServerHelloBasic (0.00s)
goos: darwin
goarch: amd64
pkg: github.com/yarochewsky/tlsx
BenchmarkGetClientHello
BenchmarkGetClientHello-12         	 1000000	      1090 ns/op	     656 B/op	      16 allocs/op
BenchmarkGetClientHelloBasic
BenchmarkGetClientHelloBasic-12    	 2621624	       451 ns/op	     312 B/op	       8 allocs/op
BenchmarkGetServerHello
BenchmarkGetServerHello-12         	 3543003	       348 ns/op	     304 B/op	       3 allocs/op
BenchmarkGetServerHelloBasic
BenchmarkGetServerHelloBasic-12    	 5287196	       223 ns/op	     104 B/op	       2 allocs/op
PASS
ok  	github.com/yarochewsky/tlsx	5.834s

Documentation

Index

• Constants
• Variables
• type CipherSuite
  • func (cs CipherSuite) String() string
• type ClientHello
  • func GetClientHello(packet gopacket.Packet) *ClientHello
  • func (ch ClientHello) String() string
  • func (ch *ClientHello) Unmarshal(payload []byte) error
• type ClientHelloBasic
  • func GetClientHelloBasic(packet gopacket.Packet) *ClientHelloBasic
  • func (ch ClientHelloBasic) String() string
  • func (ch *ClientHelloBasic) Unmarshal(payload []byte) error
• type CurveID
• type Extension
  • func (e Extension) String() string
• type ServerHello
  • func GetServerHello(packet gopacket.Packet) *ServerHello
  • func (ch ServerHello) String() string
  • func (m *ServerHello) Unmarshal(data []byte) error
• type ServerHelloBasic
  • func GetServerHelloBasic(packet gopacket.Packet) *ServerHelloBasic
  • func (ch ServerHelloBasic) String() string
  • func (m *ServerHelloBasic) Unmarshal(data []byte) error
• type TLSMessage
• type Version
  • func (v Version) String() string

Constants

const (
	SNINameTypeDNS    uint8 = 0
	OCSPStatusRequest uint8 = 1
)

const (
	ClientHelloRandomLen = 32
)

const (
	ServerHelloRandomLen = 32
)

Variables

var (
	ErrHandshakeWrongType    = errors.New("handshake is of wrong type, or not a handshake message")
	ErrHandshakeBadLength    = errors.New("handshake has a malformed length")
	ErrHandshakeExtBadLength = errors.New("handshake extension has a malformed length")
)

var CipherSuiteReg = map[CipherSuite]string{}/* 344 elements not displayed */

var ExtensionReg = map[Extension]string{
	ExtServerName:           "server_name",
	ExtMaxFragLen:           "max_fragment_length",
	ExtClientCertURL:        "client_certificate_url",
	ExtTrustedCAKeys:        "trusted_ca_keys",
	ExtTruncatedHMAC:        "truncated_hmac",
	ExtStatusRequest:        "status_request",
	ExtUserMapping:          "user_mapping",
	ExtClientAuthz:          "client_authz",
	ExtServerAuthz:          "server_authz",
	ExtCertType:             "cert_type",
	ExtSupportedGroups:      "supported_groups",
	ExtECPointFormats:       "ec_point_formats",
	ExtSRP:                  "srp",
	ExtSignatureAlgs:        "signature_algorithms",
	ExtUseSRTP:              "use_srtp",
	ExtHeartbeat:            "heartbeat",
	ExtALPN:                 "application_layer_protocol_negotiation",
	ExtStatusRequestV2:      "status_request_v2",
	ExtSignedCertTS:         "signed_certificate_timestamp",
	ExtClientCertType:       "client_certificate_type",
	ExtServerCertType:       "server_certificate_type",
	ExtPadding:              "padding",
	ExtEncryptThenMAC:       "encrypt_then_mac",
	ExtExtendedMasterSecret: "extended_master_secret",
	ExtSessionTicket:        "SessionTicket TLS",
	ExtNPN:                  "next_protocol_negotiation",
	ExtRenegotiationInfo:    "renegotiation_info",
}

var VersionReg = map[Version]string{
	VerSSL30: "SSL 3.0",
	VerTLS10: "TLS 1.0",
	VerTLS11: "TLS 1.1",
	VerTLS12: "TLS 1.2",
	VerTLS13: "TLS 1.3",
}

Types

type CipherSuite

type CipherSuite uint16

func (CipherSuite) String

func (cs CipherSuite) String() string

type ClientHello

type ClientHello struct {
	TLSMessage
	ClientHelloBasic

	Random          []byte
	SessionID       []byte
	CompressMethods []uint8
	Extensions      map[Extension]uint16 // [Type]Length
	SignatureAlgs   []uint16
	OSCP            bool
	ALPNs           []string
}

func GetClientHello

func GetClientHello(packet gopacket.Packet) *ClientHello

GetClientHello returns a client hello message if the gopacket contains one

func (ClientHello) String

func (ch ClientHello) String() string

func (*ClientHello) Unmarshal

func (ch *ClientHello) Unmarshal(payload []byte) error

type ClientHelloBasic

type ClientHelloBasic struct {
	TLSMessage
	HandshakeType    uint8
	HandshakeLen     uint32
	HandshakeVersion Version
	SessionIDLen     uint32
	CipherSuiteLen   uint16
	CipherSuites     []CipherSuite
	ExtensionLen     uint16
	SNI              string
	SupportedGroups  []uint16
	SupportedPoints  []uint8
	AllExtensions    []uint16
}

func GetClientHelloBasic

func GetClientHelloBasic(packet gopacket.Packet) *ClientHelloBasic

GetClientHelloMinimal returns a client hello message if the gopacket contains one this variant only parses the fields necessary to generate a JA client hash

func (ClientHelloBasic) String

func (ch ClientHelloBasic) String() string

func (*ClientHelloBasic) Unmarshal

func (ch *ClientHelloBasic) Unmarshal(payload []byte) error

UnmarshalBasic only parses the fields needed for JA3 fingerprinting to avoids unnecessary allocations

type CurveID

type CurveID uint16

CurveID is the type of a TLS identifier for an elliptic curve. See https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-8.

type Extension

type Extension uint16

const (
	ExtServerName           Extension = 0
	ExtMaxFragLen           Extension = 1
	ExtClientCertURL        Extension = 2
	ExtTrustedCAKeys        Extension = 3
	ExtTruncatedHMAC        Extension = 4
	ExtStatusRequest        Extension = 5
	ExtUserMapping          Extension = 6
	ExtClientAuthz          Extension = 7
	ExtServerAuthz          Extension = 8
	ExtCertType             Extension = 9
	ExtSupportedGroups      Extension = 10
	ExtECPointFormats       Extension = 11
	ExtSRP                  Extension = 12
	ExtSignatureAlgs        Extension = 13
	ExtUseSRTP              Extension = 14
	ExtHeartbeat            Extension = 15
	ExtALPN                 Extension = 16 // Replaced NPN
	ExtStatusRequestV2      Extension = 17
	ExtSignedCertTS         Extension = 18 // Certificate Transparency
	ExtClientCertType       Extension = 19
	ExtServerCertType       Extension = 20
	ExtPadding              Extension = 21 // Temp http://www.iana.org/go/draft-ietf-tls-padding
	ExtEncryptThenMAC       Extension = 22
	ExtExtendedMasterSecret Extension = 23
	ExtSessionTicket        Extension = 35
	ExtNPN                  Extension = 13172 // Next Protocol Negotiation not ratified and replaced by ALPN
	ExtRenegotiationInfo    Extension = 65281
)

TLS Extensions http://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml

func (Extension) String

func (e Extension) String() string

String method for a TLS Extension See: http://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml

type ServerHello

type ServerHello struct {
	ServerHelloBasic

	NextProtoNeg                 bool
	NextProtos                   []string
	OCSPStapling                 bool
	TicketSupported              bool
	SecureRenegotiationSupported bool
	SecureRenegotiation          []byte
	AlpnProtocol                 string
	Ems                          bool
	Scts                         [][]byte
	SupportedVersion             uint16
	ServerShare                  keyShare
	SelectedIdentityPresent      bool
	SelectedIdentity             uint16

	// HelloRetryRequest extensions
	Cookie []byte
}

func GetServerHello

func GetServerHello(packet gopacket.Packet) *ServerHello

GetServerHello returns a server hello message if the gopacket contains one

func (ServerHello) String

func (ch ServerHello) String() string

func (*ServerHello) Unmarshal

func (m *ServerHello) Unmarshal(data []byte) error

type ServerHelloBasic

type ServerHelloBasic struct {
	Vers              uint16
	Random            []byte
	SessionID         []byte
	CipherSuite       uint16
	CompressionMethod uint8
	SelectedGroup     CurveID
	Extensions        []uint16
}

func GetServerHelloBasic

func GetServerHelloBasic(packet gopacket.Packet) *ServerHelloBasic

GetServerHelloMinimal returns a server hello message if the gopacket contains one this variant only parses the fields necessary to generate a JA client hash

func (ServerHelloBasic) String

func (ch ServerHelloBasic) String() string

func (*ServerHelloBasic) Unmarshal

func (m *ServerHelloBasic) Unmarshal(data []byte) error

Unmarshal only parses the fields needed for JA3 fingerprinting to avoids unnecessary allocations

type TLSMessage

type TLSMessage struct {
	//Raw        []byte
	Type       uint8
	Version    Version
	MessageLen uint16
}

type Version

type Version uint16 // TLS Record Version, also handshake version

const (
	VerSSL30 Version = 0x300
	VerTLS10 Version = 0x301
	VerTLS11 Version = 0x302
	VerTLS12 Version = 0x303
	VerTLS13 Version = 0x304
)

func (Version) String

func (v Version) String() string

String method to return string of TLS version