ticket.go

Documentation: crypto/tls

     1  // Copyright 2012 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  	"crypto/aes"
     9  	"crypto/cipher"
    10  	"crypto/hmac"
    11  	"crypto/sha256"
    12  	"crypto/subtle"
    13  	"crypto/x509"
    14  	"errors"
    15  	"io"
    16  
    17  	"golang.org/x/crypto/cryptobyte"
    18  )
    19  
    20  // A SessionState is a resumable session.
    21  type SessionState struct {
    22  	// Encoded as a SessionState (in the language of RFC 8446, Section 3).
    23  	//
    24  	//   enum { server(1), client(2) } SessionStateType;
    25  	//
    26  	//   opaque Certificate<1..2^24-1>;
    27  	//
    28  	//   Certificate CertificateChain<0..2^24-1>;
    29  	//
    30  	//   opaque Extra<0..2^24-1>;
    31  	//
    32  	//   struct {
    33  	//       uint16 version;
    34  	//       SessionStateType type;
    35  	//       uint16 cipher_suite;
    36  	//       uint64 created_at;
    37  	//       opaque secret<1..2^8-1>;
    38  	//       Extra extra<0..2^24-1>;
    39  	//       uint8 ext_master_secret = { 0, 1 };
    40  	//       uint8 early_data = { 0, 1 };
    41  	//       CertificateEntry certificate_list<0..2^24-1>;
    42  	//       CertificateChain verified_chains<0..2^24-1>; /* excluding leaf */
    43  	//       select (SessionState.early_data) {
    44  	//           case 0: Empty;
    45  	//           case 1: opaque alpn<1..2^8-1>;
    46  	//       };
    47  	//       select (SessionState.type) {
    48  	//           case server: Empty;
    49  	//           case client: struct {
    50  	//               select (SessionState.version) {
    51  	//                   case VersionTLS10..VersionTLS12: Empty;
    52  	//                   case VersionTLS13: struct {
    53  	//                       uint64 use_by;
    54  	//                       uint32 age_add;
    55  	//                   };
    56  	//               };
    57  	//           };
    58  	//       };
    59  	//   } SessionState;
    60  	//
    61  
    62  	// Extra is ignored by crypto/tls, but is encoded by [SessionState.Bytes]
    63  	// and parsed by [ParseSessionState].
    64  	//
    65  	// This allows [Config.UnwrapSession]/[Config.WrapSession] and
    66  	// [ClientSessionCache] implementations to store and retrieve additional
    67  	// data alongside this session.
    68  	//
    69  	// To allow different layers in a protocol stack to share this field,
    70  	// applications must only append to it, not replace it, and must use entries
    71  	// that can be recognized even if out of order (for example, by starting
    72  	// with an id and version prefix).
    73  	Extra [][]byte
    74  
    75  	// EarlyData indicates whether the ticket can be used for 0-RTT in a QUIC
    76  	// connection. The application may set this to false if it is true to
    77  	// decline to offer 0-RTT even if supported.
    78  	EarlyData bool
    79  
    80  	version     uint16
    81  	isClient    bool
    82  	cipherSuite uint16
    83  	// createdAt is the generation time of the secret on the sever (which for
    84  	// TLS 1.0–1.2 might be earlier than the current session) and the time at
    85  	// which the ticket was received on the client.
    86  	createdAt         uint64 // seconds since UNIX epoch
    87  	secret            []byte // master secret for TLS 1.2, or the PSK for TLS 1.3
    88  	extMasterSecret   bool
    89  	peerCertificates  []*x509.Certificate
    90  	activeCertHandles []*activeCert
    91  	ocspResponse      []byte
    92  	scts              [][]byte
    93  	verifiedChains    [][]*x509.Certificate
    94  	alpnProtocol      string // only set if EarlyData is true
    95  
    96  	// Client-side TLS 1.3-only fields.
    97  	useBy  uint64 // seconds since UNIX epoch
    98  	ageAdd uint32
    99  }
   100  
   101  // Bytes encodes the session, including any private fields, so that it can be
   102  // parsed by [ParseSessionState]. The encoding contains secret values critical
   103  // to the security of future and possibly past sessions.
   104  //
   105  // The specific encoding should be considered opaque and may change incompatibly
   106  // between Go versions.
   107  func (s *SessionState) Bytes() ([]byte, error) {
   108  	var b cryptobyte.Builder
   109  	b.AddUint16(s.version)
   110  	if s.isClient {
   111  		b.AddUint8(2) // client
   112  	} else {
   113  		b.AddUint8(1) // server
   114  	}
   115  	b.AddUint16(s.cipherSuite)
   116  	addUint64(&b, s.createdAt)
   117  	b.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) {
   118  		b.AddBytes(s.secret)
   119  	})
   120  	b.AddUint24LengthPrefixed(func(b *cryptobyte.Builder) {
   121  		for _, extra := range s.Extra {
   122  			b.AddUint24LengthPrefixed(func(b *cryptobyte.Builder) {
   123  				b.AddBytes(extra)
   124  			})
   125  		}
   126  	})
   127  	if s.extMasterSecret {
   128  		b.AddUint8(1)
   129  	} else {
   130  		b.AddUint8(0)
   131  	}
   132  	if s.EarlyData {
   133  		b.AddUint8(1)
   134  	} else {
   135  		b.AddUint8(0)
   136  	}
   137  	marshalCertificate(&b, Certificate{
   138  		Certificate:                 certificatesToBytesSlice(s.peerCertificates),
   139  		OCSPStaple:                  s.ocspResponse,
   140  		SignedCertificateTimestamps: s.scts,
   141  	})
   142  	b.AddUint24LengthPrefixed(func(b *cryptobyte.Builder) {
   143  		for _, chain := range s.verifiedChains {
   144  			b.AddUint24LengthPrefixed(func(b *cryptobyte.Builder) {
   145  				// We elide the first certificate because it's always the leaf.
   146  				if len(chain) == 0 {
   147  					b.SetError(errors.New("tls: internal error: empty verified chain"))
   148  					return
   149  				}
   150  				for _, cert := range chain[1:] {
   151  					b.AddUint24LengthPrefixed(func(b *cryptobyte.Builder) {
   152  						b.AddBytes(cert.Raw)
   153  					})
   154  				}
   155  			})
   156  		}
   157  	})
   158  	if s.EarlyData {
   159  		b.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) {
   160  			b.AddBytes([]byte(s.alpnProtocol))
   161  		})
   162  	}
   163  	if s.isClient {
   164  		if s.version >= VersionTLS13 {
   165  			addUint64(&b, s.useBy)
   166  			b.AddUint32(s.ageAdd)
   167  		}
   168  	}
   169  	return b.Bytes()
   170  }
   171  
   172  func certificatesToBytesSlice(certs []*x509.Certificate) [][]byte {
   173  	s := make([][]byte, 0, len(certs))
   174  	for _, c := range certs {
   175  		s = append(s, c.Raw)
   176  	}
   177  	return s
   178  }
   179  
   180  // ParseSessionState parses a [SessionState] encoded by [SessionState.Bytes].
   181  func ParseSessionState(data []byte) (*SessionState, error) {
   182  	ss := &SessionState{}
   183  	s := cryptobyte.String(data)
   184  	var typ, extMasterSecret, earlyData uint8
   185  	var cert Certificate
   186  	var extra cryptobyte.String
   187  	if !s.ReadUint16(&ss.version) ||
   188  		!s.ReadUint8(&typ) ||
   189  		(typ != 1 && typ != 2) ||
   190  		!s.ReadUint16(&ss.cipherSuite) ||
   191  		!readUint64(&s, &ss.createdAt) ||
   192  		!readUint8LengthPrefixed(&s, &ss.secret) ||
   193  		!s.ReadUint24LengthPrefixed(&extra) ||
   194  		!s.ReadUint8(&extMasterSecret) ||
   195  		!s.ReadUint8(&earlyData) ||
   196  		len(ss.secret) == 0 ||
   197  		!unmarshalCertificate(&s, &cert) {
   198  		return nil, errors.New("tls: invalid session encoding")
   199  	}
   200  	for !extra.Empty() {
   201  		var e []byte
   202  		if !readUint24LengthPrefixed(&extra, &e) {
   203  			return nil, errors.New("tls: invalid session encoding")
   204  		}
   205  		ss.Extra = append(ss.Extra, e)
   206  	}
   207  	switch extMasterSecret {
   208  	case 0:
   209  		ss.extMasterSecret = false
   210  	case 1:
   211  		ss.extMasterSecret = true
   212  	default:
   213  		return nil, errors.New("tls: invalid session encoding")
   214  	}
   215  	switch earlyData {
   216  	case 0:
   217  		ss.EarlyData = false
   218  	case 1:
   219  		ss.EarlyData = true
   220  	default:
   221  		return nil, errors.New("tls: invalid session encoding")
   222  	}
   223  	for _, cert := range cert.Certificate {
   224  		c, err := globalCertCache.newCert(cert)
   225  		if err != nil {
   226  			return nil, err
   227  		}
   228  		ss.activeCertHandles = append(ss.activeCertHandles, c)
   229  		ss.peerCertificates = append(ss.peerCertificates, c.cert)
   230  	}
   231  	ss.ocspResponse = cert.OCSPStaple
   232  	ss.scts = cert.SignedCertificateTimestamps
   233  	var chainList cryptobyte.String
   234  	if !s.ReadUint24LengthPrefixed(&chainList) {
   235  		return nil, errors.New("tls: invalid session encoding")
   236  	}
   237  	for !chainList.Empty() {
   238  		var certList cryptobyte.String
   239  		if !chainList.ReadUint24LengthPrefixed(&certList) {
   240  			return nil, errors.New("tls: invalid session encoding")
   241  		}
   242  		var chain []*x509.Certificate
   243  		if len(ss.peerCertificates) == 0 {
   244  			return nil, errors.New("tls: invalid session encoding")
   245  		}
   246  		chain = append(chain, ss.peerCertificates[0])
   247  		for !certList.Empty() {
   248  			var cert []byte
   249  			if !readUint24LengthPrefixed(&certList, &cert) {
   250  				return nil, errors.New("tls: invalid session encoding")
   251  			}
   252  			c, err := globalCertCache.newCert(cert)
   253  			if err != nil {
   254  				return nil, err
   255  			}
   256  			ss.activeCertHandles = append(ss.activeCertHandles, c)
   257  			chain = append(chain, c.cert)
   258  		}
   259  		ss.verifiedChains = append(ss.verifiedChains, chain)
   260  	}
   261  	if ss.EarlyData {
   262  		var alpn []byte
   263  		if !readUint8LengthPrefixed(&s, &alpn) {
   264  			return nil, errors.New("tls: invalid session encoding")
   265  		}
   266  		ss.alpnProtocol = string(alpn)
   267  	}
   268  	if isClient := typ == 2; !isClient {
   269  		if !s.Empty() {
   270  			return nil, errors.New("tls: invalid session encoding")
   271  		}
   272  		return ss, nil
   273  	}
   274  	ss.isClient = true
   275  	if len(ss.peerCertificates) == 0 {
   276  		return nil, errors.New("tls: no server certificates in client session")
   277  	}
   278  	if ss.version < VersionTLS13 {
   279  		if !s.Empty() {
   280  			return nil, errors.New("tls: invalid session encoding")
   281  		}
   282  		return ss, nil
   283  	}
   284  	if !s.ReadUint64(&ss.useBy) || !s.ReadUint32(&ss.ageAdd) || !s.Empty() {
   285  		return nil, errors.New("tls: invalid session encoding")
   286  	}
   287  	return ss, nil
   288  }
   289  
   290  // sessionState returns a partially filled-out [SessionState] with information
   291  // from the current connection.
   292  func (c *Conn) sessionState() (*SessionState, error) {
   293  	return &SessionState{
   294  		version:           c.vers,
   295  		cipherSuite:       c.cipherSuite,
   296  		createdAt:         uint64(c.config.time().Unix()),
   297  		alpnProtocol:      c.clientProtocol,
   298  		peerCertificates:  c.peerCertificates,
   299  		activeCertHandles: c.activeCertHandles,
   300  		ocspResponse:      c.ocspResponse,
   301  		scts:              c.scts,
   302  		isClient:          c.isClient,
   303  		extMasterSecret:   c.extMasterSecret,
   304  		verifiedChains:    c.verifiedChains,
   305  	}, nil
   306  }
   307  
   308  // EncryptTicket encrypts a ticket with the [Config]'s configured (or default)
   309  // session ticket keys. It can be used as a [Config.WrapSession] implementation.
   310  func (c *Config) EncryptTicket(cs ConnectionState, ss *SessionState) ([]byte, error) {
   311  	ticketKeys := c.ticketKeys(nil)
   312  	stateBytes, err := ss.Bytes()
   313  	if err != nil {
   314  		return nil, err
   315  	}
   316  	return c.encryptTicket(stateBytes, ticketKeys)
   317  }
   318  
   319  func (c *Config) encryptTicket(state []byte, ticketKeys []ticketKey) ([]byte, error) {
   320  	if len(ticketKeys) == 0 {
   321  		return nil, errors.New("tls: internal error: session ticket keys unavailable")
   322  	}
   323  
   324  	encrypted := make([]byte, aes.BlockSize+len(state)+sha256.Size)
   325  	iv := encrypted[:aes.BlockSize]
   326  	ciphertext := encrypted[aes.BlockSize : len(encrypted)-sha256.Size]
   327  	authenticated := encrypted[:len(encrypted)-sha256.Size]
   328  	macBytes := encrypted[len(encrypted)-sha256.Size:]
   329  
   330  	if _, err := io.ReadFull(c.rand(), iv); err != nil {
   331  		return nil, err
   332  	}
   333  	key := ticketKeys[0]
   334  	block, err := aes.NewCipher(key.aesKey[:])
   335  	if err != nil {
   336  		return nil, errors.New("tls: failed to create cipher while encrypting ticket: " + err.Error())
   337  	}
   338  	cipher.NewCTR(block, iv).XORKeyStream(ciphertext, state)
   339  
   340  	mac := hmac.New(sha256.New, key.hmacKey[:])
   341  	mac.Write(authenticated)
   342  	mac.Sum(macBytes[:0])
   343  
   344  	return encrypted, nil
   345  }
   346  
   347  // DecryptTicket decrypts a ticket encrypted by [Config.EncryptTicket]. It can
   348  // be used as a [Config.UnwrapSession] implementation.
   349  //
   350  // If the ticket can't be decrypted or parsed, DecryptTicket returns (nil, nil).
   351  func (c *Config) DecryptTicket(identity []byte, cs ConnectionState) (*SessionState, error) {
   352  	ticketKeys := c.ticketKeys(nil)
   353  	stateBytes := c.decryptTicket(identity, ticketKeys)
   354  	if stateBytes == nil {
   355  		return nil, nil
   356  	}
   357  	s, err := ParseSessionState(stateBytes)
   358  	if err != nil {
   359  		return nil, nil // drop unparsable tickets on the floor
   360  	}
   361  	return s, nil
   362  }
   363  
   364  func (c *Config) decryptTicket(encrypted []byte, ticketKeys []ticketKey) []byte {
   365  	if len(encrypted) < aes.BlockSize+sha256.Size {
   366  		return nil
   367  	}
   368  
   369  	iv := encrypted[:aes.BlockSize]
   370  	ciphertext := encrypted[aes.BlockSize : len(encrypted)-sha256.Size]
   371  	authenticated := encrypted[:len(encrypted)-sha256.Size]
   372  	macBytes := encrypted[len(encrypted)-sha256.Size:]
   373  
   374  	for _, key := range ticketKeys {
   375  		mac := hmac.New(sha256.New, key.hmacKey[:])
   376  		mac.Write(authenticated)
   377  		expected := mac.Sum(nil)
   378  
   379  		if subtle.ConstantTimeCompare(macBytes, expected) != 1 {
   380  			continue
   381  		}
   382  
   383  		block, err := aes.NewCipher(key.aesKey[:])
   384  		if err != nil {
   385  			return nil
   386  		}
   387  		plaintext := make([]byte, len(ciphertext))
   388  		cipher.NewCTR(block, iv).XORKeyStream(plaintext, ciphertext)
   389  
   390  		return plaintext
   391  	}
   392  
   393  	return nil
   394  }
   395  
   396  // ClientSessionState contains the state needed by a client to
   397  // resume a previous TLS session.
   398  type ClientSessionState struct {
   399  	ticket  []byte
   400  	session *SessionState
   401  }
   402  
   403  // ResumptionState returns the session ticket sent by the server (also known as
   404  // the session's identity) and the state necessary to resume this session.
   405  //
   406  // It can be called by [ClientSessionCache.Put] to serialize (with
   407  // [SessionState.Bytes]) and store the session.
   408  func (cs *ClientSessionState) ResumptionState() (ticket []byte, state *SessionState, err error) {
   409  	return cs.ticket, cs.session, nil
   410  }
   411  
   412  // NewResumptionState returns a state value that can be returned by
   413  // [ClientSessionCache.Get] to resume a previous session.
   414  //
   415  // state needs to be returned by [ParseSessionState], and the ticket and session
   416  // state must have been returned by [ClientSessionState.ResumptionState].
   417  func NewResumptionState(ticket []byte, state *SessionState) (*ClientSessionState, error) {
   418  	return &ClientSessionState{
   419  		ticket: ticket, session: state,
   420  	}, nil
   421  }
   422
View as plain text