handshake

Documentation

Index

• Variables
• func GetRetryIntegrityTag(retry []byte, origDestConnID protocol.ConnectionID, ...) *[16]byte
• func NewInitialAEAD(connID protocol.ConnectionID, pers protocol.Perspective, ...) (LongHeaderSealer, LongHeaderOpener)
• type ConnectionState
• type CryptoSetup
  • func NewCryptoSetupClient(connID protocol.ConnectionID, tp *wire.TransportParameters, ...) CryptoSetup
  • func NewCryptoSetupServer(connID protocol.ConnectionID, localAddr, remoteAddr net.Addr, ...) CryptoSetup
• type Event
• type EventKind
• type LongHeaderOpener
• type LongHeaderSealer
• type ShortHeaderOpener
• type ShortHeaderSealer
• type Token
  • func (t *Token) ValidateRemoteAddr(addr net.Addr) bool
• type TokenGenerator
  • func NewTokenGenerator(key TokenProtectorKey) *TokenGenerator
  • func (g *TokenGenerator) DecodeToken(encrypted []byte) (*Token, error)
  • func (g *TokenGenerator) NewRetryToken(raddr net.Addr, origDestConnID protocol.ConnectionID, ...) ([]byte, error)
  • func (g *TokenGenerator) NewToken(raddr net.Addr) ([]byte, error)
• type TokenProtectorKey

Variables

var (
	// ErrKeysNotYetAvailable is returned when an opener or a sealer is requested for an encryption level,
	// but the corresponding opener has not yet been initialized
	// This can happen when packets arrive out of order.
	ErrKeysNotYetAvailable = errors.New("CryptoSetup: keys at this encryption level not yet available")
	// ErrKeysDropped is returned when an opener or a sealer is requested for an encryption level,
	// but the corresponding keys have already been dropped.
	ErrKeysDropped = errors.New("CryptoSetup: keys were already dropped")
	// ErrDecryptionFailed is returned when the AEAD fails to open the packet.
	ErrDecryptionFailed = errors.New("decryption failed")
)

var FirstKeyUpdateInterval uint64 = 100

FirstKeyUpdateInterval is the maximum number of packets we send or receive before initiating the first key update. It's a package-level variable to allow modifying it for testing purposes.

var KeyUpdateInterval uint64 = protocol.KeyUpdateInterval

KeyUpdateInterval is the maximum number of packets we send or receive before initiating a key update. It's a package-level variable to allow modifying it for testing purposes.

var QUICVersionContextKey = &quicVersionContextKey{}

Functions

func GetRetryIntegrityTag

func GetRetryIntegrityTag(retry []byte, origDestConnID protocol.ConnectionID, version protocol.VersionNumber) *[16]byte

GetRetryIntegrityTag calculates the integrity tag on a Retry packet

func NewInitialAEAD

func NewInitialAEAD(connID protocol.ConnectionID, pers protocol.Perspective, v protocol.VersionNumber) (LongHeaderSealer, LongHeaderOpener)

NewInitialAEAD creates a new AEAD for Initial encryption / decryption.

Types

type ConnectionState

type ConnectionState struct {
	tls.ConnectionState
	Used0RTT bool
}

type CryptoSetup

type CryptoSetup interface {
	StartHandshake() error
	io.Closer
	ChangeConnectionID(protocol.ConnectionID)
	GetSessionTicket() ([]byte, error)

	HandleMessage([]byte, protocol.EncryptionLevel) error
	NextEvent() Event

	SetLargest1RTTAcked(protocol.PacketNumber) error
	DiscardInitialKeys()
	SetHandshakeConfirmed()
	ConnectionState() ConnectionState

	// [Psiphon]
	TLSConnectionMetrics() tls.ConnectionMetrics

	GetInitialOpener() (LongHeaderOpener, error)
	GetHandshakeOpener() (LongHeaderOpener, error)
	Get0RTTOpener() (LongHeaderOpener, error)
	Get1RTTOpener() (ShortHeaderOpener, error)

	GetInitialSealer() (LongHeaderSealer, error)
	GetHandshakeSealer() (LongHeaderSealer, error)
	Get0RTTSealer() (LongHeaderSealer, error)
	Get1RTTSealer() (ShortHeaderSealer, error)
}

CryptoSetup handles the handshake and protecting / unprotecting packets

func NewCryptoSetupClient

func NewCryptoSetupClient(
	connID protocol.ConnectionID,
	tp *wire.TransportParameters,
	tlsConf *tls.Config,

	clientHelloSeed *prng.Seed,
	getClientHelloRandom func() ([]byte, error),

	enable0RTT bool,
	rttStats *utils.RTTStats,
	tracer *logging.ConnectionTracer,
	logger utils.Logger,
	version protocol.VersionNumber,
) CryptoSetup

NewCryptoSetupClient creates a new crypto setup for the client

func NewCryptoSetupServer

func NewCryptoSetupServer(
	connID protocol.ConnectionID,
	localAddr, remoteAddr net.Addr,
	tp *wire.TransportParameters,
	tlsConf *tls.Config,
	allow0RTT bool,
	rttStats *utils.RTTStats,
	tracer *logging.ConnectionTracer,
	logger utils.Logger,
	version protocol.VersionNumber,
) CryptoSetup

NewCryptoSetupServer creates a new crypto setup for the server

type Event

type Event struct {
	Kind                EventKind
	Data                []byte
	TransportParameters *wire.TransportParameters
}

Event is a handshake event.

type EventKind

type EventKind uint8

EventKind is the kind of handshake event.

const (
	// EventNoEvent signals that there are no new handshake events
	EventNoEvent EventKind = iota + 1
	// EventWriteInitialData contains new CRYPTO data to send at the Initial encryption level
	EventWriteInitialData
	// EventWriteHandshakeData contains new CRYPTO data to send at the Handshake encryption level
	EventWriteHandshakeData
	// EventReceivedReadKeys signals that new decryption keys are available.
	// It doesn't say which encryption level those keys are for.
	EventReceivedReadKeys
	// EventDiscard0RTTKeys signals that the Handshake keys were discarded.
	EventDiscard0RTTKeys
	// EventReceivedTransportParameters contains the transport parameters sent by the peer.
	EventReceivedTransportParameters
	// EventRestoredTransportParameters contains the transport parameters restored from the session ticket.
	// It is only used for the client.
	EventRestoredTransportParameters
	// EventHandshakeComplete signals that the TLS handshake was completed.
	EventHandshakeComplete
)

type LongHeaderOpener

type LongHeaderOpener interface {
	DecodePacketNumber(wirePN protocol.PacketNumber, wirePNLen protocol.PacketNumberLen) protocol.PacketNumber
	Open(dst, src []byte, pn protocol.PacketNumber, associatedData []byte) ([]byte, error)
	// contains filtered or unexported methods
}

LongHeaderOpener opens a long header packet

type LongHeaderSealer

type LongHeaderSealer interface {
	Seal(dst, src []byte, packetNumber protocol.PacketNumber, associatedData []byte) []byte
	EncryptHeader(sample []byte, firstByte *byte, pnBytes []byte)
	Overhead() int
}

LongHeaderSealer seals a long header packet

type ShortHeaderOpener

type ShortHeaderOpener interface {
	DecodePacketNumber(wirePN protocol.PacketNumber, wirePNLen protocol.PacketNumberLen) protocol.PacketNumber
	Open(dst, src []byte, rcvTime time.Time, pn protocol.PacketNumber, kp protocol.KeyPhaseBit, associatedData []byte) ([]byte, error)
	// contains filtered or unexported methods
}

ShortHeaderOpener opens a short header packet

type ShortHeaderSealer

type ShortHeaderSealer interface {
	LongHeaderSealer
	KeyPhase() protocol.KeyPhaseBit
}

ShortHeaderSealer seals a short header packet

type Token

type Token struct {
	IsRetryToken bool
	SentTime     time.Time

	// only set for retry tokens
	OriginalDestConnectionID protocol.ConnectionID
	RetrySrcConnectionID     protocol.ConnectionID
	// contains filtered or unexported fields
}

A Token is derived from the client address and can be used to verify the ownership of this address.

func (*Token) ValidateRemoteAddr

func (t *Token) ValidateRemoteAddr(addr net.Addr) bool

ValidateRemoteAddr validates the address, but does not check expiration

type TokenGenerator

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

A TokenGenerator generates tokens

func NewTokenGenerator

func NewTokenGenerator(key TokenProtectorKey) *TokenGenerator

NewTokenGenerator initializes a new TokenGenerator

func (*TokenGenerator) DecodeToken

func (g *TokenGenerator) DecodeToken(encrypted []byte) (*Token, error)

DecodeToken decodes a token

func (*TokenGenerator) NewRetryToken

func (g *TokenGenerator) NewRetryToken(
	raddr net.Addr,
	origDestConnID protocol.ConnectionID,
	retrySrcConnID protocol.ConnectionID,
) ([]byte, error)

NewRetryToken generates a new token for a Retry for a given source address

func (*TokenGenerator) NewToken

func (g *TokenGenerator) NewToken(raddr net.Addr) ([]byte, error)

NewToken generates a new token to be sent in a NEW_TOKEN frame

type TokenProtectorKey

type TokenProtectorKey [32]byte

TokenProtectorKey is the key used to encrypt both Retry and session resumption tokens.