tls13

README

TLS 1.3 implementation (https://tools.ietf.org/html/rfc8446)

Modified from Go TLS https://golang.org/pkg/crypto/tls/

Documentation

Index

• Variables
• func NewLRUClientSessionCache(capacity int) tls.ClientSessionCache
• type CipherSuite
  • func CipherSuiteByID(id uint16) CipherSuite
• type ClientSessionCache
• type ClientSessionState
• type Conn
  • func Client(conn Transport, config *tls.Config) *Conn
  • func Server(conn Transport, config *tls.Config) *Conn
  • func (c *Conn) Alert() uint8
  • func (c *Conn) ConnectionState() tls.ConnectionState
  • func (c *Conn) Handshake() error
  • func (c *Conn) PeerQUICTransportParams() []byte
  • func (c *Conn) SetQUICTransportParams(b []byte)
• type EncryptionLevel
• type Transport
• Bugs

Variables

var ErrWantRead = errors.New("tls: want read")

ErrWantRead is returned when the connection needs to read a handshake message.

Functions

func NewLRUClientSessionCache

func NewLRUClientSessionCache(capacity int) tls.ClientSessionCache

NewLRUClientSessionCache returns a ClientSessionCache with the given capacity that uses an LRU strategy. If capacity is < 1, a default capacity is used instead.

Types

type CipherSuite

type CipherSuite interface {
	ID() uint16
	KeyLen() int
	AEAD(key, nonce []byte) cipher.AEAD
	Hash() crypto.Hash
	ExpandLabel(secret []byte, label string, length int) []byte
	Extract(newSecret, currentSecret []byte) []byte
}

CipherSuite is the exported cipherSuiteTLS13 for QUIC usage.

func CipherSuiteByID

func CipherSuiteByID(id uint16) CipherSuite

CipherSuiteByID is the exported cipherSuiteTLS13ByID for QUIC usage.

type ClientSessionCache

type ClientSessionCache interface {
	// GetClientSession searches for a ClientSessionState associated with the given key.
	// On return, ok is true if one was found.
	GetClientSession(sessionKey string) (session *ClientSessionState, ok bool)

	// PutClientSession adds the ClientSessionState to the cache with the given key. It might
	// get called multiple times in a connection if a TLS 1.3 server provides
	// more than one session ticket. If called with a nil *ClientSessionState,
	// it should remove the cache entry.
	PutClientSession(sessionKey string, cs *ClientSessionState)
}

ClientSessionCache is a cache of ClientSessionState objects that can be used by a client to resume a TLS session with a given server. ClientSessionCache implementations should expect to be called concurrently from different goroutines. Up to TLS 1.2, only ticket-based resumption is supported, not SessionID-based resumption. In TLS 1.3 they were merged into PSK modes, which are supported via this interface.

type ClientSessionState

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

ClientSessionState contains the state needed by clients to resume TLS sessions.

type Conn

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

A Conn represents a secured connection. It implements the net.Conn interface.

func Client

func Client(conn Transport, config *tls.Config) *Conn

Client returns a new TLS client side connection using conn as the underlying transport. The config cannot be nil: users must set either ServerName or InsecureSkipVerify in the config.

func Server

func Server(conn Transport, config *tls.Config) *Conn

Server returns a new TLS server side connection using conn as the underlying transport. The configuration config must be non-nil and must include at least one certificate or else set GetCertificate.

func (*Conn) Alert

func (c *Conn) Alert() uint8

func (*Conn) ConnectionState

func (c *Conn) ConnectionState() tls.ConnectionState

ConnectionState returns basic TLS details about the connection.

func (*Conn) Handshake

func (c *Conn) Handshake() error

Handshake runs the client or server handshake protocol if it has not yet been run.

Most uses of this package need not call Handshake explicitly: the first Read or Write will call it automatically.

For control over canceling or setting a timeout on a handshake, use HandshakeContext or the Dialer's DialContext method instead.

func (*Conn) PeerQUICTransportParams

func (c *Conn) PeerQUICTransportParams() []byte

func (*Conn) SetQUICTransportParams

func (c *Conn) SetQUICTransportParams(b []byte)

type EncryptionLevel

type EncryptionLevel int

EncryptionLevel is QUIC encryption space.

const (
	EncryptionLevelInitial EncryptionLevel = iota
	EncryptionLevelHandshake
	EncryptionLevelApplication
)

Encryption levels

type Transport

type Transport interface {
	ReadRecord(EncryptionLevel, []byte) (int, error)
	WriteRecord(EncryptionLevel, []byte) (int, error)
	SetReadSecret(level EncryptionLevel, readSecret []byte) error
	SetWriteSecret(level EncryptionLevel, writeSecret []byte) error
}

Transport is the connection callback for reading and writing TLS records.

Notes

Bugs

• The crypto/tls package only implements some countermeasures against Lucky13 attacks on CBC-mode encryption, and only on SHA1 variants. See http://www.isg.rhul.ac.uk/tls/TLStiming.pdf and https://www.imperialviolet.org/2013/02/04/luckythirteen.html.