tlsutil

Documentation

Overview

Package tlsutil defines an API to analyze, classify and archive information related to the TLS protocol.

This package is a work in progress and makes no API stability promises.

Index

• Constants
• Variables
• type Analyzer
• type AnalyzerFactory
• type Archiver
• type CertSummary
• type CertificateData
  • func (c *CertificateData) Summary() CertSummary
• type CiphertextSummary
• type Classifier
• type ClassifyResponse
• type ClassifyResult
• type ClientHelloData
• type ConnectionData
• type ConnectionInfo
• type DecodedInfo
• type ExtensionItem
• type HandshakeItem
• type Msg
  • func (m *Msg) String() string
• type MsgData
  • func (m *MsgData) String() string
• type MsgOpen
  • func (m *MsgOpen) String() string
• type MsgType
  • func (m MsgType) String() string
• type Notary
• type PlaintextSummary
• type RecordData
• type ServerHelloData
• type StreamData
• type StreamInfo
• type VerifyResponse

Constants

const NeverCache = -1

NeverCache is a special value for TTL. If TTLs has this value, caches should not store the response.

Variables

var (
	ErrCanceledRequest = errors.New("tlsutil: canceled request")
	ErrBadRequest      = errors.New("tlsutil: bad request")
	ErrNotSupported    = errors.New("tlsutil: not supported")
	ErrUnavailable     = errors.New("tlsutil: not available")
	ErrInternal        = errors.New("tlsutil: internal error")
	// specific interface Analyze
	ErrTimeOutOfSync    = errors.New("tlsutil: time out of sync")
	ErrMsgOutOfOrder    = errors.New("tlsutil: message time out of order")
	ErrStreamNotFound   = errors.New("tlsutil: stream not found")
	ErrDuplicatedStream = errors.New("tlsutil: duplicated stream")
	ErrAnalyzerExists   = errors.New("tlsutil: analyzer with name exists")
	// specific interface Notary
	ErrDialingWithServer = errors.New("tlsutil: dialing with server")
	ErrChainNotFound     = errors.New("tlsutil: chain not found")
	ErrCertNotFound      = errors.New("tlsutil: certificate not found")
)

Some standard errors returned by interfaces.

Types

type Analyzer

type Analyzer interface {
	SendMessage(m *Msg) error
	Close() error
}

Analyzer interface defines analyzer methods.

type AnalyzerFactory

type AnalyzerFactory interface {
	NewAnalyzer(name string) (Analyzer, error)
}

AnalyzerFactory interface is used for create Analyzer services.

type Archiver

type Archiver interface {
	SaveConnection(context.Context, *ConnectionData) (string, error)
	SaveCertificate(context.Context, *CertificateData) (string, error)
	//async write
	StoreRecord(*RecordData) error
}

Archiver is the main interface that must be implemented by storage backends.

type CertSummary

type CertSummary struct {
	Digest  string `json:"digest"`
	Issuer  string `json:"issuer"`
	Subject string `json:"subject"`
	IsCA    bool   `json:"isCA"`
}

CertSummary stores basic information of certification

type CertificateData

type CertificateData struct {
	ID     string            `json:"id"`
	Digest string            `json:"digest"`
	Data   *x509.Certificate `json:"data"`
}

CertificateData stores certificate information

func (*CertificateData) Summary

func (c *CertificateData) Summary() CertSummary

Summary returns certificate summary

type CiphertextSummary

type CiphertextSummary struct {
	HskRecords     int64 `json:"hskRecords"`
	HskBytes       int64 `json:"hskBytes"`
	AlertRecords   int64 `json:"alertRecords"`
	AlertBytes     int64 `json:"alertBytes"`
	CCTRecords     int64 `json:"cctRecords"`
	CCTBytes       int64 `json:"cctBytes"`
	AppDataRecords int64 `json:"appDataRecords"`
	AppDataBytes   int64 `json:"appDataBytes"`
}

CiphertextSummary stores summary of ciphertext traffic

type Classifier

type Classifier interface {
	// ClassifyConnections must returns responses in the same order
	ClassifyConnections(context.Context, []*ConnectionData) ([]ClassifyResponse, error)
}

Classifier for tls protocol data.

type ClassifyResponse

type ClassifyResponse struct {
	Results []ClassifyResult
	Err     error
}

ClassifyResponse stores classification results.

type ClassifyResult

type ClassifyResult struct {
	Label string
	Prob  float32
}

ClassifyResult stores label and probability.

type ClientHelloData

type ClientHelloData struct {
	ClientVersion   tlslayer.ProtocolVersion     `json:"clientVersion"`
	RandomLen       int                          `json:"randomLen"`
	SessionIDLen    int                          `json:"sessionIDLen"`
	SessionID       []byte                       `json:"sessionID,omitempty" bson:",omitempty"`
	CipherSuitesLen int                          `json:"cipherSuitesLen"`
	CipherSuites    []tlsproto.CipherSuite       `json:"cipherSuites"`
	CompressMethods []tlsproto.CompressionMethod `json:"compressMethods"`

	ExtensionLen  int             `json:"extensionLen"`
	Extensions    []ExtensionItem `json:"extensions,omitempty" bson:",omitempty"`
	ExtensionInfo *DecodedInfo    `json:"extensionInfo,omitempty" bson:",omitempty"`

	UseGREASE bool   `json:"useGREASE"`
	JA3       string `json:"ja3"`
	JA3digest string `json:"ja3digest"`
}

ClientHelloData stores clienthello information

type ConnectionData

type ConnectionData struct {
	ID   string          `json:"id" bson:"_id"`
	Info *ConnectionInfo `json:"info,omitempty" bson:",omitempty"`

	SendStream *StreamData `json:"sendStream,omitempty" bson:",omitempty"`
	RcvdStream *StreamData `json:"rcvdStream,omitempty" bson:",omitempty"`

	ClientHello *ClientHelloData `json:"clientHello,omitempty" bson:",omitempty"`
	ServerHello *ServerHelloData `json:"serverHello,omitempty" bson:",omitempty"`

	ClientCerts []CertSummary `json:"clientCerts,omitempty" bson:",omitempty"`
	ServerCerts []CertSummary `json:"serverCerts,omitempty" bson:",omitempty"`

	Tags []string `json:"tags,omitempty" bson:",omitempty"`
}

ConnectionData stores information from tls connections

type ConnectionInfo

type ConnectionInfo struct {
	Start    time.Time     `json:"start"`
	End      time.Time     `json:"end"`
	Duration time.Duration `json:"duration"`

	ClientIP   string `json:"clientIP"`
	ClientPort int    `json:"clientPort"`
	ServerIP   string `json:"serverIP"`
	ServerPort int    `json:"serverPort"`

	Uncompleted        bool `json:"uncompleted"`
	DetectedError      bool `json:"detectedError"`
	CompletedHandshake bool `json:"completedHandshake"`
}

ConnectionInfo stores main information from a tls connection

type DecodedInfo

type DecodedInfo struct {
	SNI                 string                        `json:"sni,omitempty" bson:",omitempty"`
	SignatureSchemes    []tlsproto.SignatureScheme    `json:"signatureSchemes,omitempty" bson:",omitempty"`
	SupportedVersions   []tlsproto.SupportedVersion   `json:"supportedVersions,omitempty" bson:",omitempty"`
	SupportedGroups     []tlsproto.SupportedGroup     `json:"supportedGroups,omitempty" bson:",omitempty"`
	ECPointFormats      []tlsproto.ECPointFormat      `json:"ecPointFormats,omitempty" bson:",omitempty"`
	OSCP                bool                          `json:"oscp"`
	ALPNs               []string                      `json:"alpns,omitempty" bson:",omitempty"`
	KeyShareEntries     []tlsproto.KeyShareEntry      `json:"keyShareEntries,omitempty" bson:",omitempty"`
	PSKKeyExchangeModes []tlsproto.PSKKeyExchangeMode `json:"pskKeyExchangeModes,omitempty" bson:",omitempty"`
}

DecodedInfo stores information of extensions

type ExtensionItem

type ExtensionItem struct {
	Type tlsproto.ExtensionType `json:"type"`
	Len  uint16                 `json:"len"`
}

ExtensionItem stores metadata information of extensions

type HandshakeItem

type HandshakeItem struct {
	Type tlsproto.HandshakeType `json:"type"`
	Len  uint32                 `json:"len"`
}

HandshakeItem stores handshake metadata information

type Msg

type Msg struct {
	Type     MsgType
	StreamID int64
	Open     *MsgOpen
	Data     *MsgData
}

Msg defines message for analyzer.

func (*Msg) String

func (m *Msg) String() string

type MsgData

type MsgData struct {
	Timestamp        time.Time
	Bytes            int
	SawStart, SawEnd bool
	Records          [][]byte
	Error            error
}

MsgData stores required data by the data message.

func (*MsgData) String

func (m *MsgData) String() string

type MsgOpen

type MsgOpen struct {
	SrcIP, DstIP     net.IP
	SrcPort, DstPort int
}

MsgOpen stores required data by the open message.

func (*MsgOpen) String

func (m *MsgOpen) String() string

type MsgType

type MsgType int8

MsgType defines message types.

const (
	DataMsg MsgType = iota
	OpenMsg
	CloseMsg
)

Type possible values.

func (MsgType) String

func (m MsgType) String() string

type Notary

type Notary interface {
	GetServerChain(ctx context.Context, ip net.IP, port int, sni, profile string) (string, error)
	VerifyChain(ctx context.Context, chain string, dnsname string, force bool) (VerifyResponse, error)
	DownloadCerts(ctx context.Context, chain string) ([]*x509.Certificate, error)
	//danger methods
	SetServerChain(ctx context.Context, ip net.IP, port int, sni, profile string, chain string) error
	UploadCerts(ctx context.Context, certs []*x509.Certificate) (string, error)
}

Notary is the main interface that must be implemented by notary services.

type PlaintextSummary

type PlaintextSummary struct {
	HskRecords          int64 `json:"hskRecords"`
	HskBytes            int64 `json:"hskBytes"`
	AlertRecords        int64 `json:"alertRecords"`
	AlertBytes          int64 `json:"alertBytes"`
	CCTRecords          int64 `json:"cctRecords"`
	CCTBytes            int64 `json:"cctBytes"`
	AppDataRecords      int64 `json:"appDataRecords"`
	AppDataBytes        int64 `json:"appDataBytes"`
	FragmentedRecords   int   `json:"fragmentedRecords"`
	MaxMessagesInRecord int   `json:"maxMessagesInRecord"`
}

PlaintextSummary stores summary of plaintext traffic

type RecordData

type RecordData struct {
	StreamID   string               `json:"streamID"`
	Timestamp  time.Time            `json:"timestamp"`
	Type       tlslayer.ContentType `json:"type"`
	Len        uint16               `json:"len"`
	Ciphered   bool                 `json:"ciphered"`
	Fragmented bool                 `json:"fragmented" bson:",omitempty"`
	NumMsg     int                  `json:"numMsg" bson:",omitempty"`
}

RecordData stores metadata of tls records

type ServerHelloData

type ServerHelloData struct {
	ServerVersion     tlslayer.ProtocolVersion   `json:"serverVersion"`
	RandomLen         int                        `json:"randomLen"`
	SessionIDLen      int                        `json:"sessionIDLen"`
	SessionID         []byte                     `json:"sessionID,omitempty" bson:",omitempty"`
	CipherSuiteSel    tlsproto.CipherSuite       `json:"cipherSuiteSel"`
	CompressMethodSel tlsproto.CompressionMethod `json:"compressMethodSel"`

	ExtensionLen  int             `json:"extensionLen"`
	Extensions    []ExtensionItem `json:"extensions,omitempty" bson:",omitempty"`
	ExtensionInfo *DecodedInfo    `json:"extensionInfo,omitempty" bson:",omitempty"`
}

ServerHelloData stores serverhello information

type StreamData

type StreamData struct {
	ID   string      `json:"id" bson:"_id"`
	Info *StreamInfo `json:"info"`

	PlaintextAcc  *PlaintextSummary  `json:"plaintextAcc,omitempty" bson:",omitempty"`
	CiphertextAcc *CiphertextSummary `json:"ciphertextAcc,omitempty" bson:",omitempty"`

	HandshakeSeq []HandshakeItem `json:"handshakeSeq,omitempty" bson:",omitempty"`
	HandshakeSum int             `json:"handshakeSum,omitempty" bson:",omitempty"`
}

StreamData stores data of tls streams

type StreamInfo

type StreamInfo struct {
	Start    time.Time     `json:"start"`
	End      time.Time     `json:"end"`
	Duration time.Duration `json:"duration"`
	SawStart bool          `json:"sawStart"`
	SawEnd   bool          `json:"sawEnd"`

	DetectedError bool      `json:"detectedError"`
	ErrorType     string    `json:"errorType,omitempty" bson:",omitempty"`
	ErrorTime     time.Time `json:"errorTime,omitempty" bson:",omitempty"`

	SrcIP4  string `json:"srcIP"`
	DstIP4  string `json:"dstIP"`
	SrcPort int    `json:"srcPort"`
	DstPort int    `json:"dstPort"`

	Bytes   int64   `json:"bytes"`
	Packets int64   `json:"packets"`
	BPS     float32 `json:"bps"`
	PPS     float32 `json:"pps"`
}

StreamInfo stores information of stream

type VerifyResponse

type VerifyResponse struct {
	// Invalid is true if the chain and dnsname is invalid
	Invalid bool `json:"invalid"`
	// Reason stores the reason why it's invalid
	Reason string `json:"reason,omitempty"`
	// TTL is a number in seconds used for caching
	TTL int `json:"ttl"`
}

VerifyResponse stores information about the service's verification responses.