tlsutil

README

tlsutil

Used for lower-level TLS operations. Largely adapted from crypto/tls in the standard library.

Documentation

Overview

Package tlsutil is used for lower-level TLS operations. The code in this package is largely adapted from crypto/tls in the standard library.

Index

• func ReadRecord(r io.Reader, cs *ConnectionState) (data []byte, unprocessed []byte, err error)
• func TestOverAllSuites(t *testing.T, testFn func(t *testing.T, version, suite uint16))
• func ValidateClientHello(b []byte) (n int, err error)
• func WriteRecord(w io.Writer, data []byte, cs *ConnectionState) (int, error)
• func WriteRecords(w io.Writer, data []byte, cs *ConnectionState) (int, error)
• type Alert
  • func (e Alert) Error() string
  • func (e Alert) String() string
• type ConnectionState
  • func NewConnectionState(version, cipherSuite uint16, secret [52]byte, iv [16]byte, seq [8]byte) (*ConnectionState, error)
• type DecryptError
  • func (e DecryptError) Error() string
  • func (e DecryptError) Unwrap() error
• type LargePayloadError
  • func (e LargePayloadError) Error() string
• type ReadResult
  • func ReadRecords(r io.Reader, cs *ConnectionState) ([]ReadResult, error)
• type ServerHello
  • func ParseServerHello(b []byte) (*ServerHello, error)
• type UnexpectedAlertError
  • func (e UnexpectedAlertError) Error() string

Functions

func ReadRecord

func ReadRecord(r io.Reader, cs *ConnectionState) (data []byte, unprocessed []byte, err error)

ReadRecord reads a TLS record from the input reader. The input secret is broken up into a session key and MAC key as needed for the connection's cipher suite.

ReadRecord may "over-read" from r. In this case, unprocessed data is returned along with the record data or error.

func TestOverAllSuites

func TestOverAllSuites(t *testing.T, testFn func(t *testing.T, version, suite uint16))

TestOverAllSuites runs a test function over all combinations of suite and version supported by this package. As of Go 1.15, this includes every suite and version supported by crypto/tls.

func ValidateClientHello

func ValidateClientHello(b []byte) (n int, err error)

ValidateClientHello can be used to identify the input bytes as a TLS ClientHello message. Returns an error iff the input message cannot be parsed as a ClientHello. Returns io.UnexpectedEOF if the message is well-formed, but incomplete. When b contains a complete ClientHello, the return value n indicates that the first n bytes of b contain the record. Returns ErrorUnexpectedAlert if b begins with an alert record.

func WriteRecord

func WriteRecord(w io.Writer, data []byte, cs *ConnectionState) (int, error)

WriteRecord writes the data to the input writer. Unlike WriteRecords, this function returns a LargePayloadError if the data cannot fit into a single record. In general, WriteRecords should be used unless containing the write to a single record is a requirement.

func WriteRecords

func WriteRecords(w io.Writer, data []byte, cs *ConnectionState) (int, error)

WriteRecords writes the data to the input writer. The payload will be broken up into multiple records as needed (the cipher suite has a maximum payload size).

This function is adapted from tls.Conn.writeRecordLocked.

Types

type Alert

type Alert uint8

Alert represents a TLS alert, sent by the peer. See https://datatracker.ietf.org/doc/html/rfc5246#section-7.2

const (
	AlertCloseNotify                  Alert = 0
	AlertUnexpectedMessage            Alert = 10
	AlertBadRecordMAC                 Alert = 20
	AlertDecryptionFailed             Alert = 21
	AlertRecordOverflow               Alert = 22
	AlertDecompressionFailure         Alert = 30
	AlertHandshakeFailure             Alert = 40
	AlertBadCertificate               Alert = 42
	AlertUnsupportedCertificate       Alert = 43
	AlertCertificateRevoked           Alert = 44
	AlertCertificateExpired           Alert = 45
	AlertCertificateUnknown           Alert = 46
	AlertIllegalParameter             Alert = 47
	AlertUnknownCA                    Alert = 48
	AlertAccessDenied                 Alert = 49
	AlertDecodeError                  Alert = 50
	AlertDecryptError                 Alert = 51
	AlertExportRestriction            Alert = 60
	AlertProtocolVersion              Alert = 70
	AlertInsufficientSecurity         Alert = 71
	AlertInternalError                Alert = 80
	AlertInappropriateFallback        Alert = 86
	AlertUserCanceled                 Alert = 90
	AlertNoRenegotiation              Alert = 100
	AlertMissingExtension             Alert = 109
	AlertUnsupportedExtension         Alert = 110
	AlertCertificateUnobtainable      Alert = 111
	AlertUnrecognizedName             Alert = 112
	AlertBadCertificateStatusResponse Alert = 113
	AlertBadCertificateHashValue      Alert = 114
	AlertUnknownPSKIdentity           Alert = 115
	AlertCertificateRequired          Alert = 116
	AlertNoApplicationProtocol        Alert = 120
)

Possible Alerts. See https://datatracker.ietf.org/doc/html/rfc5246#section-7.2

func (Alert) Error

func (e Alert) Error() string

func (Alert) String

func (e Alert) String() string

type ConnectionState

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

ConnectionState tracks the state of a TLS connection. This reflects a subset of the information usually held internally on the tls.Conn type.

func NewConnectionState

func NewConnectionState(version, cipherSuite uint16, secret [52]byte, iv [16]byte, seq [8]byte) (
	*ConnectionState, error)

NewConnectionState creates a connection state based on the input version and cipher suite. The suite should be represented in https://golang.org/pkg/crypto/tls/#pkg-constants.

The secret, IV, and sequence number will be used as needed as parameters for the cipher suite. The sequence number is sometimes used as a nonce and should thus be unique per-connection. All parameters should be agreed upon by both client and server.

type DecryptError

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

A DecryptError is returned by ReadRecord if the payload could not be successfully decrypted.

func (DecryptError) Error

func (e DecryptError) Error() string

func (DecryptError) Unwrap

func (e DecryptError) Unwrap() error

type LargePayloadError

type LargePayloadError struct {
	MaxSizeForCipherSuite int
	// contains filtered or unexported fields
}

A LargePayloadError is returned by WriteRecord if the payload is too large for a single record.

func (LargePayloadError) Error

func (e LargePayloadError) Error() string

type ReadResult

type ReadResult struct {
	Data []byte

	// N is the total number of bytes read off the reader up to and including this record.
	N int
}

ReadResult is the result of an attempt to read a TLS record.

func ReadRecords

func ReadRecords(r io.Reader, cs *ConnectionState) ([]ReadResult, error)

ReadRecords is like ReadRecord, but attempts to read all records in r. Results will be returned in a slice.

This function is adapted from tls.Conn.readRecordOrCCS.

type ServerHello

type ServerHello struct {
	Version, Suite uint16
	Random         []byte
}

A ServerHello message. Only includes a subset of fields on the message.

func ParseServerHello

func ParseServerHello(b []byte) (*ServerHello, error)

ParseServerHello parses a ServerHello message. Returns ErrorUnexpectedAlert if b starts with an alert record.

type UnexpectedAlertError

type UnexpectedAlertError struct {
	Alert Alert
}

UnexpectedAlertError is returned in some cases when an alert record is encountered unexpectedly.

func (UnexpectedAlertError) Error

func (e UnexpectedAlertError) Error() string