tlsx

README

Introduction

tlsx was a private library I was using to analyse TLS Client Hello messages sent by browsers.

I didn't continue to the project, but others asked about it, so I thought I'd open source it without warranty.

The library requires the TCP payload of a TLS Client Hello message, which can be provided by (gopacket)[https://github.com/google/gopacket] (see example).

This program is not used internally by myself anymore, and may not have an updated list of ciphers, extensions etc. But it may work for you. It was written when I was first learning Go, and there's no tests.

Example usage

Run an example program, which listens on an interface for inbound or outbound packets on port 443.

cd example; go build; sudo ./example -iface br0

Make a connection:

curl https://www.google.com.au

Review the output:

2017/06/24 21:30:48 Client hello from port 37066 to 443(https)
Version: TLS 1.0
Handshake Type: 1
Handshake Version: TLS 1.2
SessionID: []byte(nil)
Cipher Suites (54): [TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 TLS_DHE_RSA_WITH_AES_256_CBC_SHA TLS_DHE_DSS_WITH_AES_256_CBC_SHA
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 TLS_DHE_RSA_WITH_AES_128_CBC_SHA
TLS_DHE_DSS_WITH_AES_128_CBC_SHA TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA TLS_RSA_WITH_AES_256_GCM_SHA384 TLS_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_RSA_WITH_AES_128_GCM_SHA256 TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_3DES_EDE_CBC_SHA TLS_RSA_WITH_RC4_128_SHA TLS_RSA_WITH_RC4_128_MD5]
Compression Methods: [0]
Extensions: map[renegotiation_info:1]
SNI: "google.com.au"
Signature Algorithms: []uint16{0x403, 0x503, 0x603, 0x203, 0x401, 0x501, 0x601, 0x201, 0x402, 0x502, 0x602, 0x202}
Groups: []uint16{0x17, 0x18, 0x19}
Points: []byte{0x0}
OSCP: false
ALPNs: []

Chrome example:

2017/06/24 21:26:32 Client hello from port 61746 to 443(https)
Version: TLS 1.0
Handshake Type: 1
Handshake Version: TLS 1.2
SessionID: []byte(nil)
Cipher Suites (32): [0x8a8a (unknown) TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 0xcca9 (unknown) 0xcca8 (unknown) 0xcc14 (unknown) 0xcc13 (unknown) TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_128_GCM_SHA256 TLS_RSA_WITH_AES_256_GCM_SHA384 TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_3DES_EDE_CBC_SHA]
Compression Methods: [0]
Extensions: map[0x7550 (unknown):0 0x7a7a (unknown):1 0xfafa (unknown):0 renegotiation_info:1 extended_master_secret:0 SessionTicket TLS:0 signed_certificate_timestamp:0]
SNI: "example.com"
Signature Algorithms: []uint16{0x403, 0x804, 0x401, 0x503, 0x805, 0x501, 0x806, 0x601, 0x201}
Groups: []uint16{0x6a6a, 0x1d, 0x17, 0x18}
Points: []byte{0x0}
OSCP: true
ALPNs: [h2 http/1.1]

Documentation

Index

• Constants
• Variables
• type CipherSuite
  • func (cs CipherSuite) String() string
• type ClientHello
  • func (ch ClientHello) String() string
  • func (ch *ClientHello) Unmarshall(payload []byte) error
• type Extension
  • func (e Extension) String() string
• type TLSMessage
• type Version
  • func (v Version) String() string

Constants

const (
	ClientHelloRandomLen = 32
)

const (
	OCSPStatusRequest uint8 = 1
)

const (
	SNINameTypeDNS uint8 = 0
)

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{}/* 319 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
	HandshakeType    uint8
	HandshakeLen     uint32
	HandshakeVersion Version
	Random           []byte
	SessionIDLen     uint32
	SessionID        []byte
	CipherSuiteLen   uint16
	CipherSuites     []CipherSuite
	CompressMethods  []uint8
	ExtensionLen     uint16
	Extensions       map[Extension]uint16 // [Type]Length
	SNI              string
	SignatureAlgs    []uint16
	SupportedGroups  []uint16
	SupportedPoints  []uint8
	OSCP             bool
	ALPNs            []string
}

func (ClientHello) String

func (ch ClientHello) String() string

func (*ClientHello) Unmarshall

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

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 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