quic.go

     1  // Copyright 2023 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package tls
     6  
     7  import (
     8  	"context"
     9  	"errors"
    10  	"fmt"
    11  	"net"
    12  )
    13  
    14  // QUICEncryptionLevel represents a QUIC encryption level used to transmit
    15  // handshake messages.
    16  type QUICEncryptionLevel int
    17  
    18  const (
    19  	QUICEncryptionLevelInitial = QUICEncryptionLevel(iota)
    20  	QUICEncryptionLevelEarly
    21  	QUICEncryptionLevelHandshake
    22  	QUICEncryptionLevelApplication
    23  )
    24  
    25  func (l QUICEncryptionLevel) String() string {
    26  	switch l {
    27  	case QUICEncryptionLevelInitial:
    28  		return "Initial"
    29  	case QUICEncryptionLevelEarly:
    30  		return "Early"
    31  	case QUICEncryptionLevelHandshake:
    32  		return "Handshake"
    33  	case QUICEncryptionLevelApplication:
    34  		return "Application"
    35  	default:
    36  		return fmt.Sprintf("QUICEncryptionLevel(%v)", int(l))
    37  	}
    38  }
    39  
    40  // A QUICConn represents a connection which uses a QUIC implementation as the underlying
    41  // transport as described in RFC 9001.
    42  //
    43  // Methods of QUICConn are not safe for concurrent use.
    44  type QUICConn struct {
    45  	conn *Conn
    46  
    47  	sessionTicketSent bool
    48  }
    49  
    50  // A QUICConfig configures a [QUICConn].
    51  type QUICConfig struct {
    52  	TLSConfig *Config
    53  
    54  	// EnableSessionEvents may be set to true to enable the
    55  	// [QUICStoreSession] and [QUICResumeSession] events for client connections.
    56  	// When this event is enabled, sessions are not automatically
    57  	// stored in the client session cache.
    58  	// The application should use [QUICConn.StoreSession] to store sessions.
    59  	EnableSessionEvents bool
    60  
    61  	// ClientHelloInfoConn is the net.Conn to use for the ClientHelloInfo.Conn field.
    62  	ClientHelloInfoConn net.Conn
    63  }
    64  
    65  // A QUICEventKind is a type of operation on a QUIC connection.
    66  type QUICEventKind int
    67  
    68  const (
    69  	// QUICNoEvent indicates that there are no events available.
    70  	QUICNoEvent QUICEventKind = iota
    71  
    72  	// QUICSetReadSecret and QUICSetWriteSecret provide the read and write
    73  	// secrets for a given encryption level.
    74  	// QUICEvent.Level, QUICEvent.Data, and QUICEvent.Suite are set.
    75  	//
    76  	// Secrets for the Initial encryption level are derived from the initial
    77  	// destination connection ID, and are not provided by the QUICConn.
    78  	QUICSetReadSecret
    79  	QUICSetWriteSecret
    80  
    81  	// QUICWriteData provides data to send to the peer in CRYPTO frames.
    82  	// QUICEvent.Data is set.
    83  	QUICWriteData
    84  
    85  	// QUICTransportParameters provides the peer's QUIC transport parameters.
    86  	// QUICEvent.Data is set.
    87  	QUICTransportParameters
    88  
    89  	// QUICTransportParametersRequired indicates that the caller must provide
    90  	// QUIC transport parameters to send to the peer. The caller should set
    91  	// the transport parameters with QUICConn.SetTransportParameters and call
    92  	// QUICConn.NextEvent again.
    93  	//
    94  	// If transport parameters are set before calling QUICConn.Start, the
    95  	// connection will never generate a QUICTransportParametersRequired event.
    96  	QUICTransportParametersRequired
    97  
    98  	// QUICRejectedEarlyData indicates that the server rejected 0-RTT data even
    99  	// if we offered it. It's returned before QUICEncryptionLevelApplication
   100  	// keys are returned.
   101  	// This event only occurs on client connections.
   102  	QUICRejectedEarlyData
   103  
   104  	// QUICHandshakeDone indicates that the TLS handshake has completed.
   105  	QUICHandshakeDone
   106  
   107  	// QUICResumeSession indicates that a client is attempting to resume a previous session.
   108  	// [QUICEvent.SessionState] is set.
   109  	//
   110  	// For client connections, this event occurs when the session ticket is selected.
   111  	// For server connections, this event occurs when receiving the client's session ticket.
   112  	//
   113  	// The application may set [QUICEvent.SessionState.EarlyData] to false before the
   114  	// next call to [QUICConn.NextEvent] to decline 0-RTT even if the session supports it.
   115  	QUICResumeSession
   116  
   117  	// QUICStoreSession indicates that the server has provided state permitting
   118  	// the client to resume the session.
   119  	// [QUICEvent.SessionState] is set.
   120  	// The application should use [QUICConn.StoreSession] session to store the [SessionState].
   121  	// The application may modify the [SessionState] before storing it.
   122  	// This event only occurs on client connections.
   123  	QUICStoreSession
   124  
   125  	// QUICErrorEvent indicates that a fatal error has occurred.
   126  	// The handshake cannot proceed and the connection must be closed.
   127  	// QUICEvent.Err is set.
   128  	QUICErrorEvent
   129  )
   130  
   131  // A QUICEvent is an event occurring on a QUIC connection.
   132  //
   133  // The type of event is specified by the Kind field.
   134  // The contents of the other fields are kind-specific.
   135  type QUICEvent struct {
   136  	Kind QUICEventKind
   137  
   138  	// Set for QUICSetReadSecret, QUICSetWriteSecret, and QUICWriteData.
   139  	Level QUICEncryptionLevel
   140  
   141  	// Set for QUICTransportParameters, QUICSetReadSecret, QUICSetWriteSecret, and QUICWriteData.
   142  	// The contents are owned by crypto/tls, and are valid until the next NextEvent call.
   143  	Data []byte
   144  
   145  	// Set for QUICSetReadSecret and QUICSetWriteSecret.
   146  	Suite uint16
   147  
   148  	// Set for QUICResumeSession and QUICStoreSession.
   149  	SessionState *SessionState
   150  
   151  	// Set for QUICErrorEvent.
   152  	// The error will wrap AlertError.
   153  	Err error
   154  }
   155  
   156  type quicState struct {
   157  	events    []QUICEvent
   158  	nextEvent int
   159  
   160  	// eventArr is a statically allocated event array, large enough to handle
   161  	// the usual maximum number of events resulting from a single call: transport
   162  	// parameters, Initial data, Early read secret, Handshake write and read
   163  	// secrets, Handshake data, Application write secret, Application data.
   164  	eventArr [8]QUICEvent
   165  
   166  	started  bool
   167  	signalc  chan struct{}   // handshake data is available to be read
   168  	blockedc chan struct{}   // handshake is waiting for data, closed when done
   169  	ctx      context.Context // handshake context
   170  	cancel   context.CancelFunc
   171  
   172  	waitingForDrain bool
   173  	errorReturned   bool
   174  
   175  	// readbuf is shared between HandleData and the handshake goroutine.
   176  	// HandshakeCryptoData passes ownership to the handshake goroutine by
   177  	// reading from signalc, and reclaims ownership by reading from blockedc.
   178  	readbuf []byte
   179  
   180  	transportParams []byte // to send to the peer
   181  
   182  	enableSessionEvents bool
   183  	clientHelloInfoConn net.Conn
   184  }
   185  
   186  // QUICClient returns a new TLS client side connection using QUICTransport as the
   187  // underlying transport. The config cannot be nil.
   188  func QUICClient(config *QUICConfig) *QUICConn {
   189  	return newQUICConn(Client(nil, config.TLSConfig), config)
   190  }
   191  
   192  // QUICServer returns a new TLS server side connection using QUICTransport as the
   193  // underlying transport. The config cannot be nil.
   194  func QUICServer(config *QUICConfig) *QUICConn {
   195  	return newQUICConn(Server(nil, config.TLSConfig), config)
   196  }
   197  
   198  func newQUICConn(conn *Conn, config *QUICConfig) *QUICConn {
   199  	conn.quic = &quicState{
   200  		signalc:             make(chan struct{}),
   201  		blockedc:            make(chan struct{}),
   202  		enableSessionEvents: config.EnableSessionEvents,
   203  		clientHelloInfoConn: config.ClientHelloInfoConn,
   204  	}
   205  	conn.quic.events = conn.quic.eventArr[:0]
   206  	return &QUICConn{
   207  		conn: conn,
   208  	}
   209  }
   210  
   211  // Start starts the client or server handshake protocol.
   212  // It may produce connection events, which may be read with [QUICConn.NextEvent].
   213  //
   214  // Start must be called at most once.
   215  func (q *QUICConn) Start(ctx context.Context) error {
   216  	if q.conn.quic.started {
   217  		return quicError(errors.New("tls: Start called more than once"))
   218  	}
   219  	q.conn.quic.started = true
   220  	go q.conn.HandshakeContext(ctx)
   221  	if _, ok := <-q.conn.quic.blockedc; !ok {
   222  		return q.conn.handshakeErr
   223  	}
   224  	return nil
   225  }
   226  
   227  // NextEvent returns the next event occurring on the connection.
   228  // It returns an event with a Kind of [QUICNoEvent] when no events are available.
   229  func (q *QUICConn) NextEvent() QUICEvent {
   230  	qs := q.conn.quic
   231  	if last := qs.nextEvent - 1; last >= 0 && len(qs.events[last].Data) > 0 {
   232  		// Write over some of the previous event's data,
   233  		// to catch callers erroneously retaining it.
   234  		qs.events[last].Data[0] = 0
   235  	}
   236  	if qs.nextEvent >= len(qs.events) && qs.waitingForDrain {
   237  		qs.waitingForDrain = false
   238  		<-qs.signalc
   239  		<-qs.blockedc
   240  	}
   241  	if err := q.conn.handshakeErr; err != nil {
   242  		if qs.errorReturned {
   243  			return QUICEvent{Kind: QUICNoEvent}
   244  		}
   245  		qs.errorReturned = true
   246  		qs.events = nil
   247  		qs.nextEvent = 0
   248  		return QUICEvent{Kind: QUICErrorEvent, Err: q.conn.handshakeErr}
   249  	}
   250  	if qs.nextEvent >= len(qs.events) {
   251  		qs.events = qs.events[:0]
   252  		qs.nextEvent = 0
   253  		return QUICEvent{Kind: QUICNoEvent}
   254  	}
   255  	e := qs.events[qs.nextEvent]
   256  	qs.events[qs.nextEvent] = QUICEvent{} // zero out references to data
   257  	qs.nextEvent++
   258  	return e
   259  }
   260  
   261  // Close closes the connection and stops any in-progress handshake.
   262  func (q *QUICConn) Close() error {
   263  	if q.conn.quic.ctx == nil {
   264  		return nil // never started
   265  	}
   266  	q.conn.quic.cancel()
   267  	<-q.conn.quic.signalc
   268  	for range q.conn.quic.blockedc {
   269  		// Wait for the handshake goroutine to return.
   270  	}
   271  	return q.conn.handshakeErr
   272  }
   273  
   274  // HandleData handles handshake bytes received from the peer.
   275  // It may produce connection events, which may be read with [QUICConn.NextEvent].
   276  func (q *QUICConn) HandleData(level QUICEncryptionLevel, data []byte) error {
   277  	c := q.conn
   278  	if c.in.level != level {
   279  		return quicError(c.in.setErrorLocked(errors.New("tls: handshake data received at wrong level")))
   280  	}
   281  	c.quic.readbuf = data
   282  	<-c.quic.signalc
   283  	_, ok := <-c.quic.blockedc
   284  	if ok {
   285  		// The handshake goroutine is waiting for more data.
   286  		return nil
   287  	}
   288  	// The handshake goroutine has exited.
   289  	c.handshakeMutex.Lock()
   290  	defer c.handshakeMutex.Unlock()
   291  	c.hand.Write(c.quic.readbuf)
   292  	c.quic.readbuf = nil
   293  	for q.conn.hand.Len() >= 4 && q.conn.handshakeErr == nil {
   294  		b := q.conn.hand.Bytes()
   295  		n := int(b[1])<<16 | int(b[2])<<8 | int(b[3])
   296  		if n > maxHandshake {
   297  			q.conn.handshakeErr = fmt.Errorf("tls: handshake message of length %d bytes exceeds maximum of %d bytes", n, maxHandshake)
   298  			break
   299  		}
   300  		if len(b) < 4+n {
   301  			return nil
   302  		}
   303  		if err := q.conn.handlePostHandshakeMessage(); err != nil {
   304  			q.conn.handshakeErr = err
   305  		}
   306  	}
   307  	if q.conn.handshakeErr != nil {
   308  		return quicError(q.conn.handshakeErr)
   309  	}
   310  	return nil
   311  }
   312  
   313  type QUICSessionTicketOptions struct {
   314  	// EarlyData specifies whether the ticket may be used for 0-RTT.
   315  	EarlyData bool
   316  	Extra     [][]byte
   317  }
   318  
   319  // SendSessionTicket sends a session ticket to the client.
   320  // It produces connection events, which may be read with [QUICConn.NextEvent].
   321  // Currently, it can only be called once.
   322  func (q *QUICConn) SendSessionTicket(opts QUICSessionTicketOptions) error {
   323  	c := q.conn
   324  	if c.config.SessionTicketsDisabled {
   325  		return nil
   326  	}
   327  	if !c.isHandshakeComplete.Load() {
   328  		return quicError(errors.New("tls: SendSessionTicket called before handshake completed"))
   329  	}
   330  	if c.isClient {
   331  		return quicError(errors.New("tls: SendSessionTicket called on the client"))
   332  	}
   333  	if q.sessionTicketSent {
   334  		return quicError(errors.New("tls: SendSessionTicket called multiple times"))
   335  	}
   336  	q.sessionTicketSent = true
   337  	return quicError(c.sendSessionTicket(opts.EarlyData, opts.Extra))
   338  }
   339  
   340  // StoreSession stores a session previously received in a QUICStoreSession event
   341  // in the ClientSessionCache.
   342  // The application may process additional events or modify the SessionState
   343  // before storing the session.
   344  func (q *QUICConn) StoreSession(session *SessionState) error {
   345  	c := q.conn
   346  	if !c.isClient {
   347  		return quicError(errors.New("tls: StoreSessionTicket called on the server"))
   348  	}
   349  	cacheKey := c.clientSessionCacheKey()
   350  	if cacheKey == "" {
   351  		return nil
   352  	}
   353  	cs := &ClientSessionState{session: session}
   354  	c.config.ClientSessionCache.Put(cacheKey, cs)
   355  	return nil
   356  }
   357  
   358  // ConnectionState returns basic TLS details about the connection.
   359  func (q *QUICConn) ConnectionState() ConnectionState {
   360  	return q.conn.ConnectionState()
   361  }
   362  
   363  // SetTransportParameters sets the transport parameters to send to the peer.
   364  //
   365  // Server connections may delay setting the transport parameters until after
   366  // receiving the client's transport parameters. See [QUICTransportParametersRequired].
   367  func (q *QUICConn) SetTransportParameters(params []byte) {
   368  	if params == nil {
   369  		params = []byte{}
   370  	}
   371  	q.conn.quic.transportParams = params
   372  	if q.conn.quic.started {
   373  		<-q.conn.quic.signalc
   374  		<-q.conn.quic.blockedc
   375  	}
   376  }
   377  
   378  // quicError ensures err is an AlertError.
   379  // If err is not already, quicError wraps it with alertInternalError.
   380  func quicError(err error) error {
   381  	if err == nil {
   382  		return nil
   383  	}
   384  	if _, ok := errors.AsType[AlertError](err); ok {
   385  		return err
   386  	}
   387  	a, ok := errors.AsType[alert](err)
   388  	if !ok {
   389  		a = alertInternalError
   390  	}
   391  	// Return an error wrapping the original error and an AlertError.
   392  	// Truncate the text of the alert to 0 characters.
   393  	return fmt.Errorf("%w%.0w", err, AlertError(a))
   394  }
   395  
   396  func (c *Conn) quicReadHandshakeBytes(n int) error {
   397  	for c.hand.Len() < n {
   398  		if err := c.quicWaitForSignal(); err != nil {
   399  			return err
   400  		}
   401  	}
   402  	return nil
   403  }
   404  
   405  func (c *Conn) quicSetReadSecret(level QUICEncryptionLevel, suite uint16, secret []byte) error {
   406  	// Ensure that there are no buffered handshake messages before changing the
   407  	// read keys, since that can cause messages to be parsed that were encrypted
   408  	// using old keys which are no longer appropriate.
   409  	// TODO(roland): we should merge this check with the similar one in setReadTrafficSecret.
   410  	if c.hand.Len() != 0 {
   411  		c.sendAlert(alertUnexpectedMessage)
   412  		return errors.New("tls: handshake buffer not empty before setting read traffic secret")
   413  	}
   414  	c.quic.events = append(c.quic.events, QUICEvent{
   415  		Kind:  QUICSetReadSecret,
   416  		Level: level,
   417  		Suite: suite,
   418  		Data:  secret,
   419  	})
   420  	return nil
   421  }
   422  
   423  func (c *Conn) quicSetWriteSecret(level QUICEncryptionLevel, suite uint16, secret []byte) {
   424  	c.quic.events = append(c.quic.events, QUICEvent{
   425  		Kind:  QUICSetWriteSecret,
   426  		Level: level,
   427  		Suite: suite,
   428  		Data:  secret,
   429  	})
   430  }
   431  
   432  func (c *Conn) quicWriteCryptoData(level QUICEncryptionLevel, data []byte) {
   433  	var last *QUICEvent
   434  	if len(c.quic.events) > 0 {
   435  		last = &c.quic.events[len(c.quic.events)-1]
   436  	}
   437  	if last == nil || last.Kind != QUICWriteData || last.Level != level {
   438  		c.quic.events = append(c.quic.events, QUICEvent{
   439  			Kind:  QUICWriteData,
   440  			Level: level,
   441  		})
   442  		last = &c.quic.events[len(c.quic.events)-1]
   443  	}
   444  	last.Data = append(last.Data, data...)
   445  }
   446  
   447  func (c *Conn) quicResumeSession(session *SessionState) error {
   448  	c.quic.events = append(c.quic.events, QUICEvent{
   449  		Kind:         QUICResumeSession,
   450  		SessionState: session,
   451  	})
   452  	c.quic.waitingForDrain = true
   453  	for c.quic.waitingForDrain {
   454  		if err := c.quicWaitForSignal(); err != nil {
   455  			return err
   456  		}
   457  	}
   458  	return nil
   459  }
   460  
   461  func (c *Conn) quicStoreSession(session *SessionState) {
   462  	c.quic.events = append(c.quic.events, QUICEvent{
   463  		Kind:         QUICStoreSession,
   464  		SessionState: session,
   465  	})
   466  }
   467  
   468  func (c *Conn) quicSetTransportParameters(params []byte) {
   469  	c.quic.events = append(c.quic.events, QUICEvent{
   470  		Kind: QUICTransportParameters,
   471  		Data: params,
   472  	})
   473  }
   474  
   475  func (c *Conn) quicGetTransportParameters() ([]byte, error) {
   476  	if c.quic.transportParams == nil {
   477  		c.quic.events = append(c.quic.events, QUICEvent{
   478  			Kind: QUICTransportParametersRequired,
   479  		})
   480  	}
   481  	for c.quic.transportParams == nil {
   482  		if err := c.quicWaitForSignal(); err != nil {
   483  			return nil, err
   484  		}
   485  	}
   486  	return c.quic.transportParams, nil
   487  }
   488  
   489  func (c *Conn) quicHandshakeComplete() {
   490  	c.quic.events = append(c.quic.events, QUICEvent{
   491  		Kind: QUICHandshakeDone,
   492  	})
   493  }
   494  
   495  func (c *Conn) quicRejectedEarlyData() {
   496  	c.quic.events = append(c.quic.events, QUICEvent{
   497  		Kind: QUICRejectedEarlyData,
   498  	})
   499  }
   500  
   501  // quicWaitForSignal notifies the QUICConn that handshake progress is blocked,
   502  // and waits for a signal that the handshake should proceed.
   503  //
   504  // The handshake may become blocked waiting for handshake bytes
   505  // or for the user to provide transport parameters.
   506  func (c *Conn) quicWaitForSignal() error {
   507  	// Drop the handshake mutex while blocked to allow the user
   508  	// to call ConnectionState before the handshake completes.
   509  	c.handshakeMutex.Unlock()
   510  	defer c.handshakeMutex.Lock()
   511  	// Send on blockedc to notify the QUICConn that the handshake is blocked.
   512  	// Exported methods of QUICConn wait for the handshake to become blocked
   513  	// before returning to the user.
   514  	c.quic.blockedc <- struct{}{}
   515  	// The QUICConn reads from signalc to notify us that the handshake may
   516  	// be able to proceed. (The QUICConn reads, because we close signalc to
   517  	// indicate that the handshake has completed.)
   518  	c.quic.signalc <- struct{}{}
   519  	if c.quic.ctx.Err() != nil {
   520  		// The connection has been canceled.
   521  		return c.sendAlertLocked(alertCloseNotify)
   522  	}
   523  	c.hand.Write(c.quic.readbuf)
   524  	c.quic.readbuf = nil
   525  	return nil
   526  }
   527
View as plain text