tlslog

README

#TLSLog

Introduction

TLSLog is a Golang library used to debug SSL application data for Wireshark.

If ECDHE is used in Key-Exchange, Wireshark cannot decrypt the application data only by set the server private key. But Wireshark supports NSS key log format that store all information needed in application data decryption process.

NSS key log format is supported by Chrome and Firefox but not Golang. When using Golang crypto/tls library, it's difficult to debug encrypted data sent and received by SSL.

But Golang crypto/tls library does store these information internally. Thus, TLSLog hooks config.Rand and uses reflection to get master secret from crypto/tls library.

CAUTION：Only client side function is implemented, which means that TLSLog can not be used to build a SSL server.

Usage

Install

go get github.com/123hurray/tlslog/tlslog.go

Dial

Dial is the most commonly way to build an SSL client.

config := tls.Config{InsecureSkipVerify: true}

// Get a TLSLog
tlsLog, err := NewTLSLog("log.txt")
if err != nil {
	fmt.Println("Unable to create TlsLog:", err.Error())
}

// Use TLSLog.Dial instead of tls.Dial
conn, err := tlsLog.Dial("tcp", "127.0.0.1:32123", &config)

// conn is tls.Conn, just used as is documented in tls library

Client

Client is another way to build an SSL client.

config := tls.Config{InsecureSkipVerify: true}
tlsLog, err := NewTLSLog("log.txt")
// Make net.conn
c, s := net.Pipe()
// use TLSLog.Client instead of tls.Client
logCli := tlsLog.Client(c, &config)
// Do handshake
conn, err = logCli.Handshake()
// conn is tls.Conn, just used as is documented in tls library

Decrypt application data using Wireshark

See the articles below:

• Wireshark WIKI:Using the (Pre)-Master-Secret
• Decrypting TLS Browser Traffic With Wireshark – The Easy Way!

TODO

• Server side key log

Documentation

Index

• type Conn
  • func (c *Conn) Handshake() (*tls.Conn, error)
• type TLSLog
  • func NewTLSLog(logFile string) (*TLSLog, error)
  • func (l *TLSLog) Client(conn net.Conn, config *tls.Config) *Conn
  • func (l *TLSLog) Dial(network, addr string, config *tls.Config) (*tls.Conn, error)
  • func (l *TLSLog) DialWithDialer(dialer *net.Dialer, network, addr string, config *tls.Config) (*tls.Conn, error)
  • func (l *TLSLog) Listen(network, laddr string, config *tls.Config) (net.Listener, error)
  • func (l *TLSLog) Server(conn net.Conn, config *tls.Config) *Conn

Types

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

Conn is returned by Server/Client, it stores tls.Conn and tls.Config used in Handshark

func (*Conn) Handshake

func (c *Conn) Handshake() (*tls.Conn, error)

Handshake uses tls.Conn.Handshake to perform server/client handshake and write masterSecret and client random to log file.

type TLSLog

type TLSLog struct {
	// contains filtered or unexported fields
}

TLSLog is a wrapper of tls. TlsLog can dial to the tls server and log client random and masterSecret to specific file which can be used to decrypt ssl application data in wireshark

func NewTLSLog

func NewTLSLog(logFile string) (*TLSLog, error)

NewTLSLog returns a TLSLog with logFile set. logFile is the file path to store client random and masterSecret If logFile is empty, then the environment variable SSLKEYLOGFILE will be used instead

func (*TLSLog) Client

func (l *TLSLog) Client(conn net.Conn, config *tls.Config) *Conn

Client use tls.Client to build a tls.Conn and return a TlsLog.Conn for Handshake

func (*TLSLog) Dial

func (l *TLSLog) Dial(network, addr string, config *tls.Config) (*tls.Conn, error)

Dial uses tls.Dial to connect to tls server and write master secret and client to log file.

func (*TLSLog) DialWithDialer

func (l *TLSLog) DialWithDialer(dialer *net.Dialer, network, addr string, config *tls.Config) (*tls.Conn, error)

DialWithDialer uses tls.DialWithDialer to connect to tls server and write master secret and client to log file.

func (*TLSLog) Listen

func (l *TLSLog) Listen(network, laddr string, config *tls.Config) (net.Listener, error)

Listen function is unimplemented

func (*TLSLog) Server

func (l *TLSLog) Server(conn net.Conn, config *tls.Config) *Conn

Server function is unimplemented