github.com/apernet/quic-go@v0.43.1-0.20240515053213-5e9e635fd9f0/internal/handshake/interface.go (about)

     1  package handshake
     2  
     3  import (
     4  	"crypto/tls"
     5  	"errors"
     6  	"io"
     7  	"time"
     8  
     9  	"github.com/apernet/quic-go/internal/protocol"
    10  	"github.com/apernet/quic-go/internal/wire"
    11  )
    12  
    13  var (
    14  	// ErrKeysNotYetAvailable is returned when an opener or a sealer is requested for an encryption level,
    15  	// but the corresponding opener has not yet been initialized
    16  	// This can happen when packets arrive out of order.
    17  	ErrKeysNotYetAvailable = errors.New("CryptoSetup: keys at this encryption level not yet available")
    18  	// ErrKeysDropped is returned when an opener or a sealer is requested for an encryption level,
    19  	// but the corresponding keys have already been dropped.
    20  	ErrKeysDropped = errors.New("CryptoSetup: keys were already dropped")
    21  	// ErrDecryptionFailed is returned when the AEAD fails to open the packet.
    22  	ErrDecryptionFailed = errors.New("decryption failed")
    23  )
    24  
    25  type headerDecryptor interface {
    26  	DecryptHeader(sample []byte, firstByte *byte, pnBytes []byte)
    27  }
    28  
    29  // LongHeaderOpener opens a long header packet
    30  type LongHeaderOpener interface {
    31  	headerDecryptor
    32  	DecodePacketNumber(wirePN protocol.PacketNumber, wirePNLen protocol.PacketNumberLen) protocol.PacketNumber
    33  	Open(dst, src []byte, pn protocol.PacketNumber, associatedData []byte) ([]byte, error)
    34  }
    35  
    36  // ShortHeaderOpener opens a short header packet
    37  type ShortHeaderOpener interface {
    38  	headerDecryptor
    39  	DecodePacketNumber(wirePN protocol.PacketNumber, wirePNLen protocol.PacketNumberLen) protocol.PacketNumber
    40  	Open(dst, src []byte, rcvTime time.Time, pn protocol.PacketNumber, kp protocol.KeyPhaseBit, associatedData []byte) ([]byte, error)
    41  }
    42  
    43  // LongHeaderSealer seals a long header packet
    44  type LongHeaderSealer interface {
    45  	Seal(dst, src []byte, packetNumber protocol.PacketNumber, associatedData []byte) []byte
    46  	EncryptHeader(sample []byte, firstByte *byte, pnBytes []byte)
    47  	Overhead() int
    48  }
    49  
    50  // ShortHeaderSealer seals a short header packet
    51  type ShortHeaderSealer interface {
    52  	LongHeaderSealer
    53  	KeyPhase() protocol.KeyPhaseBit
    54  }
    55  
    56  type ConnectionState struct {
    57  	tls.ConnectionState
    58  	Used0RTT bool
    59  }
    60  
    61  // EventKind is the kind of handshake event.
    62  type EventKind uint8
    63  
    64  const (
    65  	// EventNoEvent signals that there are no new handshake events
    66  	EventNoEvent EventKind = iota + 1
    67  	// EventWriteInitialData contains new CRYPTO data to send at the Initial encryption level
    68  	EventWriteInitialData
    69  	// EventWriteHandshakeData contains new CRYPTO data to send at the Handshake encryption level
    70  	EventWriteHandshakeData
    71  	// EventReceivedReadKeys signals that new decryption keys are available.
    72  	// It doesn't say which encryption level those keys are for.
    73  	EventReceivedReadKeys
    74  	// EventDiscard0RTTKeys signals that the Handshake keys were discarded.
    75  	EventDiscard0RTTKeys
    76  	// EventReceivedTransportParameters contains the transport parameters sent by the peer.
    77  	EventReceivedTransportParameters
    78  	// EventRestoredTransportParameters contains the transport parameters restored from the session ticket.
    79  	// It is only used for the client.
    80  	EventRestoredTransportParameters
    81  	// EventHandshakeComplete signals that the TLS handshake was completed.
    82  	EventHandshakeComplete
    83  )
    84  
    85  // Event is a handshake event.
    86  type Event struct {
    87  	Kind                EventKind
    88  	Data                []byte
    89  	TransportParameters *wire.TransportParameters
    90  }
    91  
    92  // CryptoSetup handles the handshake and protecting / unprotecting packets
    93  type CryptoSetup interface {
    94  	StartHandshake() error
    95  	io.Closer
    96  	ChangeConnectionID(protocol.ConnectionID)
    97  	GetSessionTicket() ([]byte, error)
    98  
    99  	HandleMessage([]byte, protocol.EncryptionLevel) error
   100  	NextEvent() Event
   101  
   102  	SetLargest1RTTAcked(protocol.PacketNumber) error
   103  	DiscardInitialKeys()
   104  	SetHandshakeConfirmed()
   105  	ConnectionState() ConnectionState
   106  
   107  	GetInitialOpener() (LongHeaderOpener, error)
   108  	GetHandshakeOpener() (LongHeaderOpener, error)
   109  	Get0RTTOpener() (LongHeaderOpener, error)
   110  	Get1RTTOpener() (ShortHeaderOpener, error)
   111  
   112  	GetInitialSealer() (LongHeaderSealer, error)
   113  	GetHandshakeSealer() (LongHeaderSealer, error)
   114  	Get0RTTSealer() (LongHeaderSealer, error)
   115  	Get1RTTSealer() (ShortHeaderSealer, error)
   116  }