1 // Copyright 2010 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 // TLS low level connection and record layer
6 7 package tls
8 9 import (
10 "bytes"
11 "context"
12 "crypto/cipher"
13 "crypto/subtle"
14 "crypto/x509"
15 "errors"
16 "fmt"
17 "hash"
18 "internal/godebug"
19 "io"
20 "net"
21 "sync"
22 "sync/atomic"
23 "time"
24 )
25 26 // A Conn represents a secured connection.
27 // It implements the net.Conn interface.
28 type Conn struct {
29 // constant
30 conn net.Conn
31 isClient bool
32 handshakeFn func(context.Context) error // (*Conn).clientHandshake or serverHandshake
33 quic *quicState // nil for non-QUIC connections
34 35 // isHandshakeComplete is true if the connection is currently transferring
36 // application data (i.e. is not currently processing a handshake).
37 // isHandshakeComplete is true implies handshakeErr == nil.
38 isHandshakeComplete atomic.Bool
39 // constant after handshake; protected by handshakeMutex
40 handshakeMutex sync.Mutex
41 handshakeErr error // error resulting from handshake
42 vers uint16 // TLS version
43 haveVers bool // version has been negotiated
44 config *Config // configuration passed to constructor
45 // handshakes counts the number of handshakes performed on the
46 // connection so far. If renegotiation is disabled then this is either
47 // zero or one.
48 handshakes int
49 extMasterSecret bool
50 didResume bool // whether this connection was a session resumption
51 didHRR bool // whether a HelloRetryRequest was sent/received
52 cipherSuite uint16
53 curveID CurveID
54 peerSigAlg SignatureScheme
55 ocspResponse []byte // stapled OCSP response
56 scts [][]byte // signed certificate timestamps from server
57 peerCertificates []*x509.Certificate
58 // verifiedChains contains the certificate chains that we built, as
59 // opposed to the ones presented by the server.
60 verifiedChains [][]*x509.Certificate
61 // serverName contains the server name indicated by the client, if any.
62 serverName []byte
63 // secureRenegotiation is true if the server echoed the secure
64 // renegotiation extension. (This is meaningless as a server because
65 // renegotiation is not supported in that case.)
66 secureRenegotiation bool
67 // ekm is a closure for exporting keying material.
68 ekm func(label []byte, context []byte, length int) ([]byte, error)
69 // resumptionSecret is the resumption_master_secret for handling
70 // or sending NewSessionTicket messages.
71 resumptionSecret []byte
72 echAccepted bool
73 74 // ticketKeys is the set of active session ticket keys for this
75 // connection. The first one is used to encrypt new tickets and
76 // all are tried to decrypt tickets.
77 ticketKeys []ticketKey
78 79 // clientFinishedIsFirst is true if the client sent the first Finished
80 // message during the most recent handshake. This is recorded because
81 // the first transmitted Finished message is the tls-unique
82 // channel-binding value.
83 clientFinishedIsFirst bool
84 85 // closeNotifyErr is any error from sending the alertCloseNotify record.
86 closeNotifyErr error
87 // closeNotifySent is true if the Conn attempted to send an
88 // alertCloseNotify record.
89 closeNotifySent bool
90 91 // clientFinished and serverFinished contain the Finished message sent
92 // by the client or server in the most recent handshake. This is
93 // retained to support the renegotiation extension and tls-unique
94 // channel-binding.
95 clientFinished [12]byte
96 serverFinished [12]byte
97 98 // clientProtocol is the negotiated ALPN protocol.
99 clientProtocol []byte
100 101 // input/output
102 in, out halfConn
103 rawInput bytes.Buffer // raw input, starting with a record header
104 input bytes.Reader // application data waiting to be read, from rawInput.Next
105 hand bytes.Buffer // handshake data waiting to be read
106 buffering bool // whether records are buffered in sendBuf
107 sendBuf []byte // a buffer of records waiting to be sent
108 109 // bytesSent counts the bytes of application data sent.
110 // packetsSent counts packets.
111 bytesSent int64
112 packetsSent int64
113 114 // retryCount counts the number of consecutive non-advancing records
115 // received by Conn.readRecord. That is, records that neither advance the
116 // handshake, nor deliver application data. Protected by in.Mutex.
117 retryCount int
118 119 // activeCall indicates whether Close has been call in the low bit.
120 // the rest of the bits are the number of goroutines in Conn.Write.
121 activeCall atomic.Int32
122 123 tmp [16]byte
124 }
125 126 // Access to net.Conn methods.
127 // Cannot just embed net.Conn because that would
128 // export the struct field too.
129 130 // LocalAddr returns the local network address.
131 func (c *Conn) LocalAddr() net.Addr {
132 return c.conn.LocalAddr()
133 }
134 135 // RemoteAddr returns the remote network address.
136 func (c *Conn) RemoteAddr() net.Addr {
137 return c.conn.RemoteAddr()
138 }
139 140 // SetDeadline sets the read and write deadlines associated with the connection.
141 // A zero value for t means [Conn.Read] and [Conn.Write] will not time out.
142 // After a Write has timed out, the TLS state is corrupt and all future writes will return the same error.
143 func (c *Conn) SetDeadline(t time.Time) error {
144 return c.conn.SetDeadline(t)
145 }
146 147 // SetReadDeadline sets the read deadline on the underlying connection.
148 // A zero value for t means [Conn.Read] will not time out.
149 func (c *Conn) SetReadDeadline(t time.Time) error {
150 return c.conn.SetReadDeadline(t)
151 }
152 153 // SetWriteDeadline sets the write deadline on the underlying connection.
154 // A zero value for t means [Conn.Write] will not time out.
155 // After a [Conn.Write] has timed out, the TLS state is corrupt and all future writes will return the same error.
156 func (c *Conn) SetWriteDeadline(t time.Time) error {
157 return c.conn.SetWriteDeadline(t)
158 }
159 160 // NetConn returns the underlying connection that is wrapped by c.
161 // Note that writing to or reading from this connection directly will corrupt the
162 // TLS session.
163 func (c *Conn) NetConn() net.Conn {
164 return c.conn
165 }
166 167 // A halfConn represents one direction of the record layer
168 // connection, either sending or receiving.
169 type halfConn struct {
170 sync.Mutex
171 172 err error // first permanent error
173 version uint16 // protocol version
174 cipher any // cipher algorithm
175 mac hash.Hash
176 seq [8]byte // 64-bit sequence number
177 178 scratchBuf [13]byte // to avoid allocs; interface method args escape
179 180 nextCipher any // next encryption state
181 nextMac hash.Hash // next MAC algorithm
182 183 level QUICEncryptionLevel // current QUIC encryption level
184 trafficSecret []byte // current TLS 1.3 traffic secret
185 }
186 187 type permanentError struct {
188 err net.Error
189 }
190 191 func (e *permanentError) Error() string { return e.err.Error() }
192 func (e *permanentError) Unwrap() error { return e.err }
193 func (e *permanentError) Timeout() bool { return e.err.Timeout() }
194 func (e *permanentError) Temporary() bool { return false }
195 196 func (hc *halfConn) setErrorLocked(err error) error {
197 if e, ok := err.(net.Error); ok {
198 hc.err = &permanentError{err: e}
199 } else {
200 hc.err = err
201 }
202 return hc.err
203 }
204 205 // prepareCipherSpec sets the encryption and MAC states
206 // that a subsequent changeCipherSpec will use.
207 func (hc *halfConn) prepareCipherSpec(version uint16, cipher any, mac hash.Hash) {
208 hc.version = version
209 hc.nextCipher = cipher
210 hc.nextMac = mac
211 }
212 213 // changeCipherSpec changes the encryption and MAC states
214 // to the ones previously passed to prepareCipherSpec.
215 func (hc *halfConn) changeCipherSpec() error {
216 if hc.nextCipher == nil || hc.version == VersionTLS13 {
217 return alertInternalError
218 }
219 hc.cipher = hc.nextCipher
220 hc.mac = hc.nextMac
221 hc.nextCipher = nil
222 hc.nextMac = nil
223 clear(hc.seq[:])
224 return nil
225 }
226 227 // setTrafficSecret sets the traffic secret for the given encryption level. setTrafficSecret
228 // should not be called directly, but rather through the Conn setWriteTrafficSecret and
229 // setReadTrafficSecret wrapper methods.
230 func (hc *halfConn) setTrafficSecret(suite *cipherSuiteTLS13, level QUICEncryptionLevel, secret []byte) {
231 hc.trafficSecret = secret
232 hc.level = level
233 key, iv := suite.trafficKey(secret)
234 hc.cipher = suite.aead(key, iv)
235 clear(hc.seq[:])
236 }
237 238 // incSeq increments the sequence number.
239 func (hc *halfConn) incSeq() {
240 for i := 7; i >= 0; i-- {
241 hc.seq[i]++
242 if hc.seq[i] != 0 {
243 return
244 }
245 }
246 247 // Not allowed to let sequence number wrap.
248 // Instead, must renegotiate before it does.
249 // Not likely enough to bother.
250 panic("TLS: sequence number wraparound")
251 }
252 253 // explicitNonceLen returns the number of bytes of explicit nonce or IV included
254 // in each record. Explicit nonces are present only in CBC modes after TLS 1.0
255 // and in certain AEAD modes in TLS 1.2.
256 func (hc *halfConn) explicitNonceLen() int {
257 if hc.cipher == nil {
258 return 0
259 }
260 261 switch c := hc.cipher.(type) {
262 case cipher.Stream:
263 return 0
264 case aead:
265 return c.explicitNonceLen()
266 case cbcMode:
267 // TLS 1.1 introduced a per-record explicit IV to fix the BEAST attack.
268 if hc.version >= VersionTLS11 {
269 return c.BlockSize()
270 }
271 return 0
272 default:
273 panic("unknown cipher type")
274 }
275 }
276 277 // extractPadding returns, in constant time, the length of the padding to remove
278 // from the end of payload. It also returns a byte which is equal to 255 if the
279 // padding was valid and 0 otherwise. See RFC 2246, Section 6.2.3.2.
280 func extractPadding(payload []byte) (toRemove int, good byte) {
281 if len(payload) < 1 {
282 return 0, 0
283 }
284 285 paddingLen := payload[len(payload)-1]
286 t := uint(len(payload)-1) - uint(paddingLen)
287 // if len(payload) >= (paddingLen - 1) then the MSB of t is zero
288 good = byte(int32(^t) >> 31)
289 290 // The maximum possible padding length plus the actual length field
291 toCheck := 256
292 // The length of the padded data is public, so we can use an if here
293 if toCheck > len(payload) {
294 toCheck = len(payload)
295 }
296 297 for i := 0; i < toCheck; i++ {
298 t := uint(paddingLen) - uint(i)
299 // if i <= paddingLen then the MSB of t is zero
300 mask := byte(int32(^t) >> 31)
301 b := payload[len(payload)-1-i]
302 good &^= mask&paddingLen ^ mask&b
303 }
304 305 // We AND together the bits of good and replicate the result across
306 // all the bits.
307 good &= good << 4
308 good &= good << 2
309 good &= good << 1
310 good = uint8(int8(good) >> 7)
311 312 // Zero the padding length on error. This ensures any unchecked bytes
313 // are included in the MAC. Otherwise, an attacker that could
314 // distinguish MAC failures from padding failures could mount an attack
315 // similar to POODLE in SSL 3.0: given a good ciphertext that uses a
316 // full block's worth of padding, replace the final block with another
317 // block. If the MAC check passed but the padding check failed, the
318 // last byte of that block decrypted to the block size.
319 //
320 // See also macAndPaddingGood logic below.
321 paddingLen &= good
322 323 toRemove = int(paddingLen) + 1
324 return
325 }
326 327 func roundUp(a, b int) int {
328 return a + (b-a%b)%b
329 }
330 331 // cbcMode is an interface for block ciphers using cipher block chaining.
332 type cbcMode interface {
333 cipher.BlockMode
334 SetIV([]byte)
335 }
336 337 // decrypt authenticates and decrypts the record if protection is active at
338 // this stage. The returned plaintext might overlap with the input.
339 func (hc *halfConn) decrypt(record []byte) ([]byte, recordType, error) {
340 var plaintext []byte
341 typ := recordType(record[0])
342 payload := record[recordHeaderLen:]
343 344 // In TLS 1.3, change_cipher_spec messages are to be ignored without being
345 // decrypted. See RFC 8446, Appendix D.4.
346 if hc.version == VersionTLS13 && typ == recordTypeChangeCipherSpec {
347 return payload, typ, nil
348 }
349 350 paddingGood := byte(255)
351 paddingLen := 0
352 353 explicitNonceLen := hc.explicitNonceLen()
354 355 if hc.cipher != nil {
356 switch c := hc.cipher.(type) {
357 case cipher.Stream:
358 c.XORKeyStream(payload, payload)
359 case aead:
360 if len(payload) < explicitNonceLen {
361 return nil, 0, alertBadRecordMAC
362 }
363 nonce := payload[:explicitNonceLen]
364 if len(nonce) == 0 {
365 nonce = hc.seq[:]
366 }
367 payload = payload[explicitNonceLen:]
368 369 var additionalData []byte
370 if hc.version == VersionTLS13 {
371 additionalData = record[:recordHeaderLen]
372 } else {
373 additionalData = append(hc.scratchBuf[:0], hc.seq[:]...)
374 additionalData = append(additionalData, record[:3]...)
375 n := len(payload) - c.Overhead()
376 additionalData = append(additionalData, byte(n>>8), byte(n))
377 }
378 379 var err error
380 plaintext, err = c.Open(payload[:0], nonce, payload, additionalData)
381 if err != nil {
382 return nil, 0, alertBadRecordMAC
383 }
384 case cbcMode:
385 blockSize := c.BlockSize()
386 minPayload := explicitNonceLen + roundUp(hc.mac.Size()+1, blockSize)
387 if len(payload)%blockSize != 0 || len(payload) < minPayload {
388 return nil, 0, alertBadRecordMAC
389 }
390 391 if explicitNonceLen > 0 {
392 c.SetIV(payload[:explicitNonceLen])
393 payload = payload[explicitNonceLen:]
394 }
395 c.CryptBlocks(payload, payload)
396 397 // In a limited attempt to protect against CBC padding oracles like
398 // Lucky13, the data past paddingLen (which is secret) is passed to
399 // the MAC function as extra data, to be fed into the HMAC after
400 // computing the digest. This makes the MAC roughly constant time as
401 // long as the digest computation is constant time and does not
402 // affect the subsequent write, modulo cache effects.
403 paddingLen, paddingGood = extractPadding(payload)
404 default:
405 panic("unknown cipher type")
406 }
407 408 if hc.version == VersionTLS13 {
409 if typ != recordTypeApplicationData {
410 return nil, 0, alertUnexpectedMessage
411 }
412 if len(plaintext) > maxPlaintext+1 {
413 return nil, 0, alertRecordOverflow
414 }
415 // Remove padding and find the ContentType scanning from the end.
416 for i := len(plaintext) - 1; i >= 0; i-- {
417 if plaintext[i] != 0 {
418 typ = recordType(plaintext[i])
419 plaintext = plaintext[:i]
420 break
421 }
422 if i == 0 {
423 return nil, 0, alertUnexpectedMessage
424 }
425 }
426 }
427 } else {
428 plaintext = payload
429 }
430 431 if hc.mac != nil {
432 macSize := hc.mac.Size()
433 if len(payload) < macSize {
434 return nil, 0, alertBadRecordMAC
435 }
436 437 n := len(payload) - macSize - paddingLen
438 n = subtle.ConstantTimeSelect(int(uint32(n)>>31), 0, n) // if n < 0 { n = 0 }
439 record[3] = byte(n >> 8)
440 record[4] = byte(n)
441 remoteMAC := payload[n : n+macSize]
442 localMAC := tls10MAC(hc.mac, hc.scratchBuf[:0], hc.seq[:], record[:recordHeaderLen], payload[:n], payload[n+macSize:])
443 444 // This is equivalent to checking the MACs and paddingGood
445 // separately, but in constant-time to prevent distinguishing
446 // padding failures from MAC failures. Depending on what value
447 // of paddingLen was returned on bad padding, distinguishing
448 // bad MAC from bad padding can lead to an attack.
449 //
450 // See also the logic at the end of extractPadding.
451 macAndPaddingGood := subtle.ConstantTimeCompare(localMAC, remoteMAC) & int(paddingGood)
452 if macAndPaddingGood != 1 {
453 return nil, 0, alertBadRecordMAC
454 }
455 456 plaintext = payload[:n]
457 }
458 459 hc.incSeq()
460 return plaintext, typ, nil
461 }
462 463 // sliceForAppend extends the input slice by n bytes. head is the full extended
464 // slice, while tail is the appended part. If the original slice has sufficient
465 // capacity no allocation is performed.
466 func sliceForAppend(in []byte, n int) (head, tail []byte) {
467 if total := len(in) + n; cap(in) >= total {
468 head = in[:total]
469 } else {
470 head = []byte{:total}
471 copy(head, in)
472 }
473 tail = head[len(in):]
474 return
475 }
476 477 // encrypt encrypts payload, adding the appropriate nonce and/or MAC, and
478 // appends it to record, which must already contain the record header.
479 func (hc *halfConn) encrypt(record, payload []byte, rand io.Reader) ([]byte, error) {
480 if hc.cipher == nil {
481 return append(record, payload...), nil
482 }
483 484 var explicitNonce []byte
485 if explicitNonceLen := hc.explicitNonceLen(); explicitNonceLen > 0 {
486 record, explicitNonce = sliceForAppend(record, explicitNonceLen)
487 if _, isCBC := hc.cipher.(cbcMode); !isCBC && explicitNonceLen < 16 {
488 // The AES-GCM construction in TLS has an explicit nonce so that the
489 // nonce can be random. However, the nonce is only 8 bytes which is
490 // too small for a secure, random nonce. Therefore we use the
491 // sequence number as the nonce. The 3DES-CBC construction also has
492 // an 8 bytes nonce but its nonces must be unpredictable (see RFC
493 // 5246, Appendix F.3), forcing us to use randomness. That's not
494 // 3DES' biggest problem anyway because the birthday bound on block
495 // collision is reached first due to its similarly small block size
496 // (see the Sweet32 attack).
497 copy(explicitNonce, hc.seq[:])
498 } else {
499 if _, err := io.ReadFull(rand, explicitNonce); err != nil {
500 return nil, err
501 }
502 }
503 }
504 505 var dst []byte
506 switch c := hc.cipher.(type) {
507 case cipher.Stream:
508 mac := tls10MAC(hc.mac, hc.scratchBuf[:0], hc.seq[:], record[:recordHeaderLen], payload, nil)
509 record, dst = sliceForAppend(record, len(payload)+len(mac))
510 c.XORKeyStream(dst[:len(payload)], payload)
511 c.XORKeyStream(dst[len(payload):], mac)
512 case aead:
513 nonce := explicitNonce
514 if len(nonce) == 0 {
515 nonce = hc.seq[:]
516 }
517 518 if hc.version == VersionTLS13 {
519 record = append(record, payload...)
520 521 // Encrypt the actual ContentType and replace the plaintext one.
522 record = append(record, record[0])
523 record[0] = byte(recordTypeApplicationData)
524 525 n := len(payload) + 1 + c.Overhead()
526 record[3] = byte(n >> 8)
527 record[4] = byte(n)
528 529 record = c.Seal(record[:recordHeaderLen],
530 nonce, record[recordHeaderLen:], record[:recordHeaderLen])
531 } else {
532 additionalData := append(hc.scratchBuf[:0], hc.seq[:]...)
533 additionalData = append(additionalData, record[:recordHeaderLen]...)
534 record = c.Seal(record, nonce, payload, additionalData)
535 }
536 case cbcMode:
537 mac := tls10MAC(hc.mac, hc.scratchBuf[:0], hc.seq[:], record[:recordHeaderLen], payload, nil)
538 blockSize := c.BlockSize()
539 plaintextLen := len(payload) + len(mac)
540 paddingLen := blockSize - plaintextLen%blockSize
541 record, dst = sliceForAppend(record, plaintextLen+paddingLen)
542 copy(dst, payload)
543 copy(dst[len(payload):], mac)
544 for i := plaintextLen; i < len(dst); i++ {
545 dst[i] = byte(paddingLen - 1)
546 }
547 if len(explicitNonce) > 0 {
548 c.SetIV(explicitNonce)
549 }
550 c.CryptBlocks(dst, dst)
551 default:
552 panic("unknown cipher type")
553 }
554 555 // Update length to include nonce, MAC and any block padding needed.
556 n := len(record) - recordHeaderLen
557 record[3] = byte(n >> 8)
558 record[4] = byte(n)
559 hc.incSeq()
560 561 return record, nil
562 }
563 564 // RecordHeaderError is returned when a TLS record header is invalid.
565 type RecordHeaderError struct {
566 // Msg contains a human readable string that describes the error.
567 Msg []byte
568 // RecordHeader contains the five bytes of TLS record header that
569 // triggered the error.
570 RecordHeader [5]byte
571 // Conn provides the underlying net.Conn in the case that a client
572 // sent an initial handshake that didn't look like TLS.
573 // It is nil if there's already been a handshake or a TLS alert has
574 // been written to the connection.
575 Conn net.Conn
576 }
577 578 func (e RecordHeaderError) Error() string { return "tls: " + e.Msg }
579 580 func (c *Conn) newRecordHeaderError(conn net.Conn, msg []byte) (err RecordHeaderError) {
581 err.Msg = msg
582 err.Conn = conn
583 copy(err.RecordHeader[:], c.rawInput.Bytes())
584 return err
585 }
586 587 func (c *Conn) readRecord() error {
588 return c.readRecordOrCCS(false)
589 }
590 591 func (c *Conn) readChangeCipherSpec() error {
592 return c.readRecordOrCCS(true)
593 }
594 595 // readRecordOrCCS reads one or more TLS records from the connection and
596 // updates the record layer state. Some invariants:
597 // - c.in must be locked
598 // - c.input must be empty
599 //
600 // During the handshake one and only one of the following will happen:
601 // - c.hand grows
602 // - c.in.changeCipherSpec is called
603 // - an error is returned
604 //
605 // After the handshake one and only one of the following will happen:
606 // - c.hand grows
607 // - c.input is set
608 // - an error is returned
609 func (c *Conn) readRecordOrCCS(expectChangeCipherSpec bool) error {
610 if c.in.err != nil {
611 return c.in.err
612 }
613 handshakeComplete := c.isHandshakeComplete.Load()
614 615 // This function modifies c.rawInput, which owns the c.input memory.
616 if c.input.Len() != 0 {
617 return c.in.setErrorLocked(errors.New("tls: internal error: attempted to read record with pending application data"))
618 }
619 c.input.Reset(nil)
620 621 if c.quic != nil {
622 return c.in.setErrorLocked(errors.New("tls: internal error: attempted to read record with QUIC transport"))
623 }
624 625 // Read header, payload.
626 if err := c.readFromUntil(c.conn, recordHeaderLen); err != nil {
627 // RFC 8446, Section 6.1 suggests that EOF without an alertCloseNotify
628 // is an error, but popular web sites seem to do this, so we accept it
629 // if and only if at the record boundary.
630 if err == io.ErrUnexpectedEOF && c.rawInput.Len() == 0 {
631 err = io.EOF
632 }
633 if e, ok := err.(net.Error); !ok || !e.Temporary() {
634 c.in.setErrorLocked(err)
635 }
636 return err
637 }
638 hdr := c.rawInput.Bytes()[:recordHeaderLen]
639 typ := recordType(hdr[0])
640 641 // No valid TLS record has a type of 0x80, however SSLv2 handshakes
642 // start with a uint16 length where the MSB is set and the first record
643 // is always < 256 bytes long. Therefore typ == 0x80 strongly suggests
644 // an SSLv2 client.
645 if !handshakeComplete && typ == 0x80 {
646 c.sendAlert(alertProtocolVersion)
647 return c.in.setErrorLocked(c.newRecordHeaderError(nil, "unsupported SSLv2 handshake received"))
648 }
649 650 vers := uint16(hdr[1])<<8 | uint16(hdr[2])
651 expectedVers := c.vers
652 if expectedVers == VersionTLS13 {
653 // All TLS 1.3 records are expected to have 0x0303 (1.2) after
654 // the initial hello (RFC 8446 Section 5.1).
655 expectedVers = VersionTLS12
656 }
657 n := int(hdr[3])<<8 | int(hdr[4])
658 if c.haveVers && vers != expectedVers {
659 c.sendAlert(alertProtocolVersion)
660 msg := fmt.Sprintf("received record with version %x when expecting version %x", vers, expectedVers)
661 return c.in.setErrorLocked(c.newRecordHeaderError(nil, msg))
662 }
663 if !c.haveVers {
664 // First message, be extra suspicious: this might not be a TLS
665 // client. Bail out before reading a full 'body', if possible.
666 // The current max version is 3.3 so if the version is >= 16.0,
667 // it's probably not real.
668 if (typ != recordTypeAlert && typ != recordTypeHandshake) || vers >= 0x1000 {
669 return c.in.setErrorLocked(c.newRecordHeaderError(c.conn, "first record does not look like a TLS handshake"))
670 }
671 }
672 if c.vers == VersionTLS13 && n > maxCiphertextTLS13 || n > maxCiphertext {
673 c.sendAlert(alertRecordOverflow)
674 msg := fmt.Sprintf("oversized record received with length %d", n)
675 return c.in.setErrorLocked(c.newRecordHeaderError(nil, msg))
676 }
677 if err := c.readFromUntil(c.conn, recordHeaderLen+n); err != nil {
678 if e, ok := err.(net.Error); !ok || !e.Temporary() {
679 c.in.setErrorLocked(err)
680 }
681 return err
682 }
683 684 // Process message.
685 record := c.rawInput.Next(recordHeaderLen + n)
686 data, typ, err := c.in.decrypt(record)
687 if err != nil {
688 return c.in.setErrorLocked(c.sendAlert(err.(alert)))
689 }
690 if len(data) > maxPlaintext {
691 return c.in.setErrorLocked(c.sendAlert(alertRecordOverflow))
692 }
693 694 // Application Data messages are always protected.
695 if c.in.cipher == nil && typ == recordTypeApplicationData {
696 return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
697 }
698 699 if typ != recordTypeAlert && typ != recordTypeChangeCipherSpec && len(data) > 0 {
700 // This is a state-advancing message: reset the retry count.
701 c.retryCount = 0
702 }
703 704 // Handshake messages MUST NOT be interleaved with other record types in TLS 1.3.
705 if c.vers == VersionTLS13 && typ != recordTypeHandshake && c.hand.Len() > 0 {
706 return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
707 }
708 709 switch typ {
710 default:
711 return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
712 713 case recordTypeAlert:
714 if c.quic != nil {
715 return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
716 }
717 if len(data) != 2 {
718 return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
719 }
720 if alert(data[1]) == alertCloseNotify {
721 return c.in.setErrorLocked(io.EOF)
722 }
723 if c.vers == VersionTLS13 {
724 // TLS 1.3 removed warning-level alerts except for alertUserCanceled
725 // (RFC 8446, ยง 6.1). Since at least one major implementation
726 // (https://bugs.openjdk.org/browse/JDK-8323517) misuses this alert,
727 // many TLS stacks now ignore it outright when seen in a TLS 1.3
728 // handshake (e.g. BoringSSL, NSS, Rustls).
729 if alert(data[1]) == alertUserCanceled {
730 // Like TLS 1.2 alertLevelWarning alerts, we drop the record and retry.
731 return c.retryReadRecord(expectChangeCipherSpec)
732 }
733 return c.in.setErrorLocked(&net.OpError{Op: "remote error", Err: alert(data[1])})
734 }
735 switch data[0] {
736 case alertLevelWarning:
737 // Drop the record on the floor and retry.
738 return c.retryReadRecord(expectChangeCipherSpec)
739 case alertLevelError:
740 return c.in.setErrorLocked(&net.OpError{Op: "remote error", Err: alert(data[1])})
741 default:
742 return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
743 }
744 745 case recordTypeChangeCipherSpec:
746 if len(data) != 1 || data[0] != 1 {
747 return c.in.setErrorLocked(c.sendAlert(alertDecodeError))
748 }
749 // Handshake messages are not allowed to fragment across the CCS.
750 if c.hand.Len() > 0 {
751 return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
752 }
753 // In TLS 1.3, change_cipher_spec records are ignored until the
754 // Finished. See RFC 8446, Appendix D.4. Note that according to Section
755 // 5, a server can send a ChangeCipherSpec before its ServerHello, when
756 // c.vers is still unset. That's not useful though and suspicious if the
757 // server then selects a lower protocol version, so don't allow that.
758 if c.vers == VersionTLS13 {
759 return c.retryReadRecord(expectChangeCipherSpec)
760 }
761 if !expectChangeCipherSpec {
762 return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
763 }
764 if err := c.in.changeCipherSpec(); err != nil {
765 return c.in.setErrorLocked(c.sendAlert(err.(alert)))
766 }
767 768 case recordTypeApplicationData:
769 if !handshakeComplete || expectChangeCipherSpec {
770 return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
771 }
772 // Some OpenSSL servers send empty records in order to randomize the
773 // CBC IV. Ignore a limited number of empty records.
774 if len(data) == 0 {
775 return c.retryReadRecord(expectChangeCipherSpec)
776 }
777 // Note that data is owned by c.rawInput, following the Next call above,
778 // to avoid copying the plaintext. This is safe because c.rawInput is
779 // not read from or written to until c.input is drained.
780 c.input.Reset(data)
781 782 case recordTypeHandshake:
783 if len(data) == 0 || expectChangeCipherSpec {
784 return c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
785 }
786 c.hand.Write(data)
787 }
788 789 return nil
790 }
791 792 // retryReadRecord recurs into readRecordOrCCS to drop a non-advancing record, like
793 // a warning alert, empty application_data, or a change_cipher_spec in TLS 1.3.
794 func (c *Conn) retryReadRecord(expectChangeCipherSpec bool) error {
795 c.retryCount++
796 if c.retryCount > maxUselessRecords {
797 c.sendAlert(alertUnexpectedMessage)
798 return c.in.setErrorLocked(errors.New("tls: too many ignored records"))
799 }
800 return c.readRecordOrCCS(expectChangeCipherSpec)
801 }
802 803 // atLeastReader reads from R, stopping with EOF once at least N bytes have been
804 // read. It is different from an io.LimitedReader in that it doesn't cut short
805 // the last Read call, and in that it considers an early EOF an error.
806 type atLeastReader struct {
807 R io.Reader
808 N int64
809 }
810 811 func (r *atLeastReader) Read(p []byte) (int, error) {
812 if r.N <= 0 {
813 return 0, io.EOF
814 }
815 n, err := r.R.Read(p)
816 r.N -= int64(n) // won't underflow unless len(p) >= n > 9223372036854775809
817 if r.N > 0 && err == io.EOF {
818 return n, io.ErrUnexpectedEOF
819 }
820 if r.N <= 0 && err == nil {
821 return n, io.EOF
822 }
823 return n, err
824 }
825 826 // readFromUntil reads from r into c.rawInput until c.rawInput contains
827 // at least n bytes or else returns an error.
828 func (c *Conn) readFromUntil(r io.Reader, n int) error {
829 if c.rawInput.Len() >= n {
830 return nil
831 }
832 needs := n - c.rawInput.Len()
833 // There might be extra input waiting on the wire. Make a best effort
834 // attempt to fetch it so that it can be used in (*Conn).Read to
835 // "predict" closeNotify alerts.
836 c.rawInput.Grow(needs + bytes.MinRead)
837 _, err := c.rawInput.ReadFrom(&atLeastReader{r, int64(needs)})
838 return err
839 }
840 841 // sendAlertLocked sends a TLS alert message.
842 func (c *Conn) sendAlertLocked(err alert) error {
843 if c.quic != nil {
844 return c.out.setErrorLocked(&net.OpError{Op: "local error", Err: err})
845 }
846 847 switch err {
848 case alertNoRenegotiation, alertCloseNotify:
849 c.tmp[0] = alertLevelWarning
850 default:
851 c.tmp[0] = alertLevelError
852 }
853 c.tmp[1] = byte(err)
854 855 _, writeErr := c.writeRecordLocked(recordTypeAlert, c.tmp[0:2])
856 if err == alertCloseNotify {
857 // closeNotify is a special case in that it isn't an error.
858 return writeErr
859 }
860 861 return c.out.setErrorLocked(&net.OpError{Op: "local error", Err: err})
862 }
863 864 // sendAlert sends a TLS alert message.
865 func (c *Conn) sendAlert(err alert) error {
866 c.out.Lock()
867 defer c.out.Unlock()
868 return c.sendAlertLocked(err)
869 }
870 871 const (
872 // tcpMSSEstimate is a conservative estimate of the TCP maximum segment
873 // size (MSS). A constant is used, rather than querying the kernel for
874 // the actual MSS, to avoid complexity. The value here is the IPv6
875 // minimum MTU (1280 bytes) minus the overhead of an IPv6 header (40
876 // bytes) and a TCP header with timestamps (32 bytes).
877 tcpMSSEstimate = 1208
878 879 // recordSizeBoostThreshold is the number of bytes of application data
880 // sent after which the TLS record size will be increased to the
881 // maximum.
882 recordSizeBoostThreshold = 128 * 1024
883 )
884 885 // maxPayloadSizeForWrite returns the maximum TLS payload size to use for the
886 // next application data record. There is the following trade-off:
887 //
888 // - For latency-sensitive applications, such as web browsing, each TLS
889 // record should fit in one TCP segment.
890 // - For throughput-sensitive applications, such as large file transfers,
891 // larger TLS records better amortize framing and encryption overheads.
892 //
893 // A simple heuristic that works well in practice is to use small records for
894 // the first 1MB of data, then use larger records for subsequent data, and
895 // reset back to smaller records after the connection becomes idle. See "High
896 // Performance Web Networking", Chapter 4, or:
897 // https://www.igvita.com/2013/10/24/optimizing-tls-record-size-and-buffering-latency/
898 //
899 // In the interests of simplicity and determinism, this code does not attempt
900 // to reset the record size once the connection is idle, however.
901 func (c *Conn) maxPayloadSizeForWrite(typ recordType) int {
902 if c.config.DynamicRecordSizingDisabled || typ != recordTypeApplicationData {
903 return maxPlaintext
904 }
905 906 if c.bytesSent >= recordSizeBoostThreshold {
907 return maxPlaintext
908 }
909 910 // Subtract TLS overheads to get the maximum payload size.
911 payloadBytes := tcpMSSEstimate - recordHeaderLen - c.out.explicitNonceLen()
912 if c.out.cipher != nil {
913 switch ciph := c.out.cipher.(type) {
914 case cipher.Stream:
915 payloadBytes -= c.out.mac.Size()
916 case cipher.AEAD:
917 payloadBytes -= ciph.Overhead()
918 case cbcMode:
919 blockSize := ciph.BlockSize()
920 // The payload must fit in a multiple of blockSize, with
921 // room for at least one padding byte.
922 payloadBytes = (payloadBytes & ^(blockSize - 1)) - 1
923 // The MAC is appended before padding so affects the
924 // payload size directly.
925 payloadBytes -= c.out.mac.Size()
926 default:
927 panic("unknown cipher type")
928 }
929 }
930 if c.vers == VersionTLS13 {
931 payloadBytes-- // encrypted ContentType
932 }
933 934 // Allow packet growth in arithmetic progression up to max.
935 pkt := c.packetsSent
936 c.packetsSent++
937 if pkt > 1000 {
938 return maxPlaintext // avoid overflow in multiply below
939 }
940 941 n := payloadBytes * int(pkt+1)
942 if n > maxPlaintext {
943 n = maxPlaintext
944 }
945 return n
946 }
947 948 func (c *Conn) write(data []byte) (int, error) {
949 if c.buffering {
950 c.sendBuf = append(c.sendBuf, data...)
951 return len(data), nil
952 }
953 954 n, err := c.conn.Write(data)
955 c.bytesSent += int64(n)
956 return n, err
957 }
958 959 func (c *Conn) flush() (int, error) {
960 if len(c.sendBuf) == 0 {
961 return 0, nil
962 }
963 964 n, err := c.conn.Write(c.sendBuf)
965 c.bytesSent += int64(n)
966 c.sendBuf = nil
967 c.buffering = false
968 return n, err
969 }
970 971 // outBufPool pools the record-sized scratch buffers used by writeRecordLocked.
972 var outBufPool = sync.Pool{
973 New: func() any {
974 b := []byte{:0}
975 return &b
976 },
977 }
978 979 // writeRecordLocked writes a TLS record with the given type and payload to the
980 // connection and updates the record layer state.
981 func (c *Conn) writeRecordLocked(typ recordType, data []byte) (int, error) {
982 if c.quic != nil {
983 if typ != recordTypeHandshake {
984 return 0, errors.New("tls: internal error: sending non-handshake message to QUIC transport")
985 }
986 c.quicWriteCryptoData(c.out.level, data)
987 if !c.buffering {
988 if _, err := c.flush(); err != nil {
989 return 0, err
990 }
991 }
992 return len(data), nil
993 }
994 995 outBufPtr := outBufPool.Get().(*[]byte)
996 outBuf := *outBufPtr
997 defer func() {
998 // You might be tempted to simplify this by just passing &outBuf to Put,
999 // but that would make the local copy of the outBuf slice header escape
1000 // to the heap, causing an allocation. Instead, we keep around the
1001 // pointer to the slice header returned by Get, which is already on the
1002 // heap, and overwrite and return that.
1003 *outBufPtr = outBuf
1004 outBufPool.Put(outBufPtr)
1005 }()
1006 1007 var n int
1008 for len(data) > 0 {
1009 m := len(data)
1010 if maxPayload := c.maxPayloadSizeForWrite(typ); m > maxPayload {
1011 m = maxPayload
1012 }
1013 1014 _, outBuf = sliceForAppend(outBuf[:0], recordHeaderLen)
1015 outBuf[0] = byte(typ)
1016 vers := c.vers
1017 if vers == 0 {
1018 // Some TLS servers fail if the record version is
1019 // greater than TLS 1.0 for the initial ClientHello.
1020 vers = VersionTLS10
1021 } else if vers == VersionTLS13 {
1022 // TLS 1.3 froze the record layer version to 1.2.
1023 // See RFC 8446, Section 5.1.
1024 vers = VersionTLS12
1025 }
1026 outBuf[1] = byte(vers >> 8)
1027 outBuf[2] = byte(vers)
1028 outBuf[3] = byte(m >> 8)
1029 outBuf[4] = byte(m)
1030 1031 var err error
1032 outBuf, err = c.out.encrypt(outBuf, data[:m], c.config.rand())
1033 if err != nil {
1034 return n, err
1035 }
1036 if _, err := c.write(outBuf); err != nil {
1037 return n, err
1038 }
1039 n += m
1040 data = data[m:]
1041 }
1042 1043 if typ == recordTypeChangeCipherSpec && c.vers != VersionTLS13 {
1044 if err := c.out.changeCipherSpec(); err != nil {
1045 return n, c.sendAlertLocked(err.(alert))
1046 }
1047 }
1048 1049 return n, nil
1050 }
1051 1052 // writeHandshakeRecord writes a handshake message to the connection and updates
1053 // the record layer state. If transcript is non-nil the marshaled message is
1054 // written to it.
1055 func (c *Conn) writeHandshakeRecord(msg handshakeMessage, transcript transcriptHash) (int, error) {
1056 c.out.Lock()
1057 defer c.out.Unlock()
1058 1059 data, err := msg.marshal()
1060 if err != nil {
1061 return 0, err
1062 }
1063 if transcript != nil {
1064 transcript.Write(data)
1065 }
1066 1067 return c.writeRecordLocked(recordTypeHandshake, data)
1068 }
1069 1070 // writeChangeCipherRecord writes a ChangeCipherSpec message to the connection and
1071 // updates the record layer state.
1072 func (c *Conn) writeChangeCipherRecord() error {
1073 c.out.Lock()
1074 defer c.out.Unlock()
1075 _, err := c.writeRecordLocked(recordTypeChangeCipherSpec, []byte{1})
1076 return err
1077 }
1078 1079 // readHandshakeBytes reads handshake data until c.hand contains at least n bytes.
1080 func (c *Conn) readHandshakeBytes(n int) error {
1081 if c.quic != nil {
1082 return c.quicReadHandshakeBytes(n)
1083 }
1084 for c.hand.Len() < n {
1085 if err := c.readRecord(); err != nil {
1086 return err
1087 }
1088 }
1089 return nil
1090 }
1091 1092 // readHandshake reads the next handshake message from
1093 // the record layer. If transcript is non-nil, the message
1094 // is written to the passed transcriptHash.
1095 func (c *Conn) readHandshake(transcript transcriptHash) (any, error) {
1096 if err := c.readHandshakeBytes(4); err != nil {
1097 return nil, err
1098 }
1099 data := c.hand.Bytes()
1100 1101 maxHandshakeSize := maxHandshake
1102 // hasVers indicates we're past the first message, forcing someone trying to
1103 // make us just allocate a large buffer to at least do the initial part of
1104 // the handshake first.
1105 if c.haveVers && data[0] == typeCertificate {
1106 // Since certificate messages are likely to be the only messages that
1107 // can be larger than maxHandshake, we use a special limit for just
1108 // those messages.
1109 maxHandshakeSize = maxHandshakeCertificateMsg
1110 }
1111 1112 n := int(data[1])<<16 | int(data[2])<<8 | int(data[3])
1113 if n > maxHandshakeSize {
1114 c.sendAlertLocked(alertInternalError)
1115 return nil, c.in.setErrorLocked(fmt.Errorf("tls: handshake message of length %d bytes exceeds maximum of %d bytes", n, maxHandshakeSize))
1116 }
1117 if err := c.readHandshakeBytes(4 + n); err != nil {
1118 return nil, err
1119 }
1120 data = c.hand.Next(4 + n)
1121 return c.unmarshalHandshakeMessage(data, transcript)
1122 }
1123 1124 func (c *Conn) unmarshalHandshakeMessage(data []byte, transcript transcriptHash) (handshakeMessage, error) {
1125 var m handshakeMessage
1126 switch data[0] {
1127 case typeHelloRequest:
1128 m = &helloRequestMsg{}
1129 case typeClientHello:
1130 m = &clientHelloMsg{}
1131 case typeServerHello:
1132 m = &serverHelloMsg{}
1133 case typeNewSessionTicket:
1134 if c.vers == VersionTLS13 {
1135 m = &newSessionTicketMsgTLS13{}
1136 } else {
1137 m = &newSessionTicketMsg{}
1138 }
1139 case typeCertificate:
1140 if c.vers == VersionTLS13 {
1141 m = &certificateMsgTLS13{}
1142 } else {
1143 m = &certificateMsg{}
1144 }
1145 case typeCertificateRequest:
1146 if c.vers == VersionTLS13 {
1147 m = &certificateRequestMsgTLS13{}
1148 } else {
1149 m = &certificateRequestMsg{
1150 hasSignatureAlgorithm: c.vers >= VersionTLS12,
1151 }
1152 }
1153 case typeCertificateStatus:
1154 m = &certificateStatusMsg{}
1155 case typeServerKeyExchange:
1156 m = &serverKeyExchangeMsg{}
1157 case typeServerHelloDone:
1158 m = &serverHelloDoneMsg{}
1159 case typeClientKeyExchange:
1160 m = &clientKeyExchangeMsg{}
1161 case typeCertificateVerify:
1162 m = &certificateVerifyMsg{
1163 hasSignatureAlgorithm: c.vers >= VersionTLS12,
1164 }
1165 case typeFinished:
1166 m = &finishedMsg{}
1167 case typeEncryptedExtensions:
1168 m = &encryptedExtensionsMsg{}
1169 case typeEndOfEarlyData:
1170 m = &endOfEarlyDataMsg{}
1171 case typeKeyUpdate:
1172 m = &keyUpdateMsg{}
1173 default:
1174 return nil, c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
1175 }
1176 1177 // The handshake message unmarshalers
1178 // expect to be able to keep references to data,
1179 // so pass in a fresh copy that won't be overwritten.
1180 data = append([]byte(nil), data...)
1181 1182 if !m.unmarshal(data) {
1183 return nil, c.in.setErrorLocked(c.sendAlert(alertDecodeError))
1184 }
1185 1186 if transcript != nil {
1187 transcript.Write(data)
1188 }
1189 1190 return m, nil
1191 }
1192 1193 var (
1194 errShutdown = errors.New("tls: protocol is shutdown")
1195 )
1196 1197 // Write writes data to the connection.
1198 //
1199 // As Write calls [Conn.Handshake], in order to prevent indefinite blocking a deadline
1200 // must be set for both [Conn.Read] and Write before Write is called when the handshake
1201 // has not yet completed. See [Conn.SetDeadline], [Conn.SetReadDeadline], and
1202 // [Conn.SetWriteDeadline].
1203 func (c *Conn) Write(b []byte) (int, error) {
1204 // interlock with Close below
1205 for {
1206 x := c.activeCall.Load()
1207 if x&1 != 0 {
1208 return 0, net.ErrClosed
1209 }
1210 if c.activeCall.CompareAndSwap(x, x+2) {
1211 break
1212 }
1213 }
1214 defer c.activeCall.Add(-2)
1215 1216 if err := c.Handshake(); err != nil {
1217 return 0, err
1218 }
1219 1220 c.out.Lock()
1221 defer c.out.Unlock()
1222 1223 if err := c.out.err; err != nil {
1224 return 0, err
1225 }
1226 1227 if !c.isHandshakeComplete.Load() {
1228 return 0, alertInternalError
1229 }
1230 1231 if c.closeNotifySent {
1232 return 0, errShutdown
1233 }
1234 1235 // TLS 1.0 is susceptible to a chosen-plaintext
1236 // attack when using block mode ciphers due to predictable IVs.
1237 // This can be prevented by splitting each Application Data
1238 // record into two records, effectively randomizing the IV.
1239 //
1240 // https://www.openssl.org/~bodo/tls-cbc.txt
1241 // https://bugzilla.mozilla.org/show_bug.cgi?id=665814
1242 // https://www.imperialviolet.org/2012/01/15/beastfollowup.html
1243 1244 var m int
1245 if len(b) > 1 && c.vers == VersionTLS10 {
1246 if _, ok := c.out.cipher.(cipher.BlockMode); ok {
1247 n, err := c.writeRecordLocked(recordTypeApplicationData, b[:1])
1248 if err != nil {
1249 return n, c.out.setErrorLocked(err)
1250 }
1251 m, b = 1, b[1:]
1252 }
1253 }
1254 1255 n, err := c.writeRecordLocked(recordTypeApplicationData, b)
1256 return n + m, c.out.setErrorLocked(err)
1257 }
1258 1259 // handleRenegotiation processes a HelloRequest handshake message.
1260 func (c *Conn) handleRenegotiation() error {
1261 if c.vers == VersionTLS13 {
1262 return errors.New("tls: internal error: unexpected renegotiation")
1263 }
1264 1265 msg, err := c.readHandshake(nil)
1266 if err != nil {
1267 return err
1268 }
1269 1270 helloReq, ok := msg.(*helloRequestMsg)
1271 if !ok {
1272 c.sendAlert(alertUnexpectedMessage)
1273 return unexpectedMessageError(helloReq, msg)
1274 }
1275 1276 if !c.isClient {
1277 return c.sendAlert(alertNoRenegotiation)
1278 }
1279 1280 switch c.config.Renegotiation {
1281 case RenegotiateNever:
1282 return c.sendAlert(alertNoRenegotiation)
1283 case RenegotiateOnceAsClient:
1284 if c.handshakes > 1 {
1285 return c.sendAlert(alertNoRenegotiation)
1286 }
1287 case RenegotiateFreelyAsClient:
1288 // Ok.
1289 default:
1290 c.sendAlert(alertInternalError)
1291 return errors.New("tls: unknown Renegotiation value")
1292 }
1293 1294 c.handshakeMutex.Lock()
1295 defer c.handshakeMutex.Unlock()
1296 1297 c.isHandshakeComplete.Store(false)
1298 if c.handshakeErr = c.clientHandshake(context.Background()); c.handshakeErr == nil {
1299 c.handshakes++
1300 }
1301 return c.handshakeErr
1302 }
1303 1304 // handlePostHandshakeMessage processes a handshake message arrived after the
1305 // handshake is complete. Up to TLS 1.2, it indicates the start of a renegotiation.
1306 func (c *Conn) handlePostHandshakeMessage() error {
1307 if c.vers != VersionTLS13 {
1308 return c.handleRenegotiation()
1309 }
1310 1311 msg, err := c.readHandshake(nil)
1312 if err != nil {
1313 return err
1314 }
1315 c.retryCount++
1316 if c.retryCount > maxUselessRecords {
1317 c.sendAlert(alertUnexpectedMessage)
1318 return c.in.setErrorLocked(errors.New("tls: too many non-advancing records"))
1319 }
1320 1321 switch msg := msg.(type) {
1322 case *newSessionTicketMsgTLS13:
1323 return c.handleNewSessionTicket(msg)
1324 case *keyUpdateMsg:
1325 return c.handleKeyUpdate(msg)
1326 }
1327 // The QUIC layer is supposed to treat an unexpected post-handshake CertificateRequest
1328 // as a QUIC-level PROTOCOL_VIOLATION error (RFC 9001, Section 4.4). Returning an
1329 // unexpected_message alert here doesn't provide it with enough information to distinguish
1330 // this condition from other unexpected messages. This is probably fine.
1331 c.sendAlert(alertUnexpectedMessage)
1332 return fmt.Errorf("tls: received unexpected handshake message of type %T", msg)
1333 }
1334 1335 func (c *Conn) handleKeyUpdate(keyUpdate *keyUpdateMsg) error {
1336 if c.quic != nil {
1337 c.sendAlert(alertUnexpectedMessage)
1338 return c.in.setErrorLocked(errors.New("tls: received unexpected key update message"))
1339 }
1340 1341 cipherSuite := cipherSuiteTLS13ByID(c.cipherSuite)
1342 if cipherSuite == nil {
1343 return c.in.setErrorLocked(c.sendAlert(alertInternalError))
1344 }
1345 1346 if keyUpdate.updateRequested {
1347 c.out.Lock()
1348 defer c.out.Unlock()
1349 1350 msg := &keyUpdateMsg{}
1351 msgBytes, err := msg.marshal()
1352 if err != nil {
1353 return err
1354 }
1355 _, err = c.writeRecordLocked(recordTypeHandshake, msgBytes)
1356 if err != nil {
1357 // Surface the error at the next write.
1358 c.out.setErrorLocked(err)
1359 return nil
1360 }
1361 1362 newSecret := cipherSuite.nextTrafficSecret(c.out.trafficSecret)
1363 c.setWriteTrafficSecret(cipherSuite, QUICEncryptionLevelInitial, newSecret)
1364 }
1365 1366 newSecret := cipherSuite.nextTrafficSecret(c.in.trafficSecret)
1367 if err := c.setReadTrafficSecret(cipherSuite, QUICEncryptionLevelInitial, newSecret); err != nil {
1368 return err
1369 }
1370 1371 return nil
1372 }
1373 1374 // Read reads data from the connection.
1375 //
1376 // As Read calls [Conn.Handshake], in order to prevent indefinite blocking a deadline
1377 // must be set for both Read and [Conn.Write] before Read is called when the handshake
1378 // has not yet completed. See [Conn.SetDeadline], [Conn.SetReadDeadline], and
1379 // [Conn.SetWriteDeadline].
1380 func (c *Conn) Read(b []byte) (int, error) {
1381 if err := c.Handshake(); err != nil {
1382 return 0, err
1383 }
1384 if len(b) == 0 {
1385 // Put this after Handshake, in case people were calling
1386 // Read(nil) for the side effect of the Handshake.
1387 return 0, nil
1388 }
1389 1390 c.in.Lock()
1391 defer c.in.Unlock()
1392 1393 for c.input.Len() == 0 {
1394 if err := c.readRecord(); err != nil {
1395 return 0, err
1396 }
1397 for c.hand.Len() > 0 {
1398 if err := c.handlePostHandshakeMessage(); err != nil {
1399 return 0, err
1400 }
1401 }
1402 }
1403 1404 n, _ := c.input.Read(b)
1405 1406 // If a close-notify alert is waiting, read it so that we can return (n,
1407 // EOF) instead of (n, nil), to signal to the HTTP response reading
1408 // goroutine that the connection is now closed. This eliminates a race
1409 // where the HTTP response reading goroutine would otherwise not observe
1410 // the EOF until its next read, by which time a client goroutine might
1411 // have already tried to reuse the HTTP connection for a new request.
1412 // See https://golang.org/cl/76400046 and https://golang.org/issue/3514
1413 if n != 0 && c.input.Len() == 0 && c.rawInput.Len() > 0 &&
1414 recordType(c.rawInput.Bytes()[0]) == recordTypeAlert {
1415 if err := c.readRecord(); err != nil {
1416 return n, err // will be io.EOF on closeNotify
1417 }
1418 }
1419 1420 return n, nil
1421 }
1422 1423 // Close closes the connection.
1424 func (c *Conn) Close() error {
1425 // Interlock with Conn.Write above.
1426 var x int32
1427 for {
1428 x = c.activeCall.Load()
1429 if x&1 != 0 {
1430 return net.ErrClosed
1431 }
1432 if c.activeCall.CompareAndSwap(x, x|1) {
1433 break
1434 }
1435 }
1436 if x != 0 {
1437 // io.Writer and io.Closer should not be used concurrently.
1438 // If Close is called while a Write is currently in-flight,
1439 // interpret that as a sign that this Close is really just
1440 // being used to break the Write and/or clean up resources and
1441 // avoid sending the alertCloseNotify, which may block
1442 // waiting on handshakeMutex or the c.out mutex.
1443 return c.conn.Close()
1444 }
1445 1446 var alertErr error
1447 if c.isHandshakeComplete.Load() {
1448 if err := c.closeNotify(); err != nil {
1449 alertErr = fmt.Errorf("tls: failed to send closeNotify alert (but connection was closed anyway): %w", err)
1450 }
1451 }
1452 1453 if err := c.conn.Close(); err != nil {
1454 return err
1455 }
1456 return alertErr
1457 }
1458 1459 var errEarlyCloseWrite = errors.New("tls: CloseWrite called before handshake complete")
1460 1461 // CloseWrite shuts down the writing side of the connection. It should only be
1462 // called once the handshake has completed and does not call CloseWrite on the
1463 // underlying connection. Most callers should just use [Conn.Close].
1464 func (c *Conn) CloseWrite() error {
1465 if !c.isHandshakeComplete.Load() {
1466 return errEarlyCloseWrite
1467 }
1468 1469 return c.closeNotify()
1470 }
1471 1472 func (c *Conn) closeNotify() error {
1473 c.out.Lock()
1474 defer c.out.Unlock()
1475 1476 if !c.closeNotifySent {
1477 // Set a Write Deadline to prevent possibly blocking forever.
1478 c.SetWriteDeadline(time.Now().Add(time.Second * 5))
1479 c.closeNotifyErr = c.sendAlertLocked(alertCloseNotify)
1480 c.closeNotifySent = true
1481 // Any subsequent writes will fail.
1482 c.SetWriteDeadline(time.Now())
1483 }
1484 return c.closeNotifyErr
1485 }
1486 1487 // Handshake runs the client or server handshake
1488 // protocol if it has not yet been run.
1489 //
1490 // Most uses of this package need not call Handshake explicitly: the
1491 // first [Conn.Read] or [Conn.Write] will call it automatically.
1492 //
1493 // For control over canceling or setting a timeout on a handshake, use
1494 // [Conn.HandshakeContext] or the [Dialer]'s DialContext method instead.
1495 //
1496 // In order to avoid denial of service attacks, the maximum RSA key size allowed
1497 // in certificates sent by either the TLS server or client is limited to 8192
1498 // bits. This limit can be overridden by setting tlsmaxrsasize in the GODEBUG
1499 // environment variable (e.g. GODEBUG=tlsmaxrsasize=4096).
1500 func (c *Conn) Handshake() error {
1501 return c.HandshakeContext(context.Background())
1502 }
1503 1504 // HandshakeContext runs the client or server handshake
1505 // protocol if it has not yet been run.
1506 //
1507 // The provided Context must be non-nil. If the context is canceled before
1508 // the handshake is complete, the handshake is interrupted and an error is returned.
1509 // Once the handshake has completed, cancellation of the context will not affect the
1510 // connection.
1511 //
1512 // Most uses of this package need not call HandshakeContext explicitly: the
1513 // first [Conn.Read] or [Conn.Write] will call it automatically.
1514 func (c *Conn) HandshakeContext(ctx context.Context) error {
1515 // Delegate to unexported method for named return
1516 // without confusing documented signature.
1517 return c.handshakeContext(ctx)
1518 }
1519 1520 func (c *Conn) handshakeContext(ctx context.Context) (ret error) {
1521 // Fast sync/atomic-based exit if there is no handshake in flight and the
1522 // last one succeeded without an error. Avoids the expensive context setup
1523 // and mutex for most Read and Write calls.
1524 if c.isHandshakeComplete.Load() {
1525 return nil
1526 }
1527 1528 handshakeCtx, cancel := context.WithCancel(ctx)
1529 // Note: defer this before calling context.AfterFunc
1530 // so that we can tell the difference between the input being canceled and
1531 // this cancellation. In the former case, we need to close the connection.
1532 defer cancel()
1533 1534 if c.quic != nil {
1535 c.quic.ctx = handshakeCtx
1536 c.quic.cancel = cancel
1537 } else if ctx.Done() != nil {
1538 // Close the connection if ctx is canceled before the function returns.
1539 stop := context.AfterFunc(ctx, func() {
1540 _ = c.conn.Close()
1541 })
1542 defer func() {
1543 if !stop() {
1544 // Return context error to user.
1545 ret = ctx.Err()
1546 }
1547 }()
1548 }
1549 1550 c.handshakeMutex.Lock()
1551 defer c.handshakeMutex.Unlock()
1552 1553 if err := c.handshakeErr; err != nil {
1554 return err
1555 }
1556 if c.isHandshakeComplete.Load() {
1557 return nil
1558 }
1559 1560 c.in.Lock()
1561 defer c.in.Unlock()
1562 1563 c.handshakeErr = c.handshakeFn(handshakeCtx)
1564 if c.handshakeErr == nil {
1565 c.handshakes++
1566 } else {
1567 // If an error occurred during the handshake try to flush the
1568 // alert that might be left in the buffer.
1569 c.flush()
1570 }
1571 1572 if c.handshakeErr == nil && !c.isHandshakeComplete.Load() {
1573 c.handshakeErr = errors.New("tls: internal error: handshake should have had a result")
1574 }
1575 if c.handshakeErr != nil && c.isHandshakeComplete.Load() {
1576 panic("tls: internal error: handshake returned an error but is marked successful")
1577 }
1578 1579 if c.quic != nil {
1580 if c.handshakeErr == nil {
1581 c.quicHandshakeComplete()
1582 // Provide the 1-RTT read secret now that the handshake is complete.
1583 // The QUIC layer MUST NOT decrypt 1-RTT packets prior to completing
1584 // the handshake (RFC 9001, Section 5.7).
1585 if err := c.quicSetReadSecret(QUICEncryptionLevelApplication, c.cipherSuite, c.in.trafficSecret); err != nil {
1586 return err
1587 }
1588 } else {
1589 c.out.Lock()
1590 a, ok := c.out.err.(alert)
1591 if !ok {
1592 a = alertInternalError
1593 }
1594 c.out.Unlock()
1595 // Return an error which wraps both the handshake error and
1596 // any alert error we may have sent, or alertInternalError
1597 // if we didn't send an alert.
1598 // Truncate the text of the alert to 0 characters.
1599 c.handshakeErr = fmt.Errorf("%w%.0w", c.handshakeErr, AlertError(a))
1600 }
1601 close(c.quic.blockedc)
1602 close(c.quic.signalc)
1603 }
1604 1605 return c.handshakeErr
1606 }
1607 1608 // ConnectionState returns basic TLS details about the connection.
1609 func (c *Conn) ConnectionState() ConnectionState {
1610 c.handshakeMutex.Lock()
1611 defer c.handshakeMutex.Unlock()
1612 return c.connectionStateLocked()
1613 }
1614 1615 var tlsunsafeekm = godebug.New("tlsunsafeekm")
1616 1617 func (c *Conn) connectionStateLocked() ConnectionState {
1618 var state ConnectionState
1619 state.HandshakeComplete = c.isHandshakeComplete.Load()
1620 state.Version = c.vers
1621 state.NegotiatedProtocol = c.clientProtocol
1622 state.DidResume = c.didResume
1623 state.HelloRetryRequest = c.didHRR
1624 state.testingOnlyPeerSignatureAlgorithm = c.peerSigAlg
1625 state.CurveID = c.curveID
1626 state.NegotiatedProtocolIsMutual = true
1627 state.ServerName = c.serverName
1628 state.CipherSuite = c.cipherSuite
1629 state.PeerCertificates = c.peerCertificates
1630 state.VerifiedChains = c.verifiedChains
1631 state.SignedCertificateTimestamps = c.scts
1632 state.OCSPResponse = c.ocspResponse
1633 if (!c.didResume || c.extMasterSecret) && c.vers != VersionTLS13 {
1634 if c.clientFinishedIsFirst {
1635 state.TLSUnique = c.clientFinished[:]
1636 } else {
1637 state.TLSUnique = c.serverFinished[:]
1638 }
1639 }
1640 if c.config.Renegotiation != RenegotiateNever {
1641 state.ekm = noEKMBecauseRenegotiation
1642 } else if c.vers != VersionTLS13 && !c.extMasterSecret {
1643 state.ekm = func(label []byte, context []byte, length int) ([]byte, error) {
1644 if tlsunsafeekm.Value() == "1" {
1645 tlsunsafeekm.IncNonDefault()
1646 return c.ekm(label, context, length)
1647 }
1648 return noEKMBecauseNoEMS(label, context, length)
1649 }
1650 } else {
1651 state.ekm = c.ekm
1652 }
1653 state.ECHAccepted = c.echAccepted
1654 return state
1655 }
1656 1657 // OCSPResponse returns the stapled OCSP response from the TLS server, if
1658 // any. (Only valid for client connections.)
1659 func (c *Conn) OCSPResponse() []byte {
1660 c.handshakeMutex.Lock()
1661 defer c.handshakeMutex.Unlock()
1662 1663 return c.ocspResponse
1664 }
1665 1666 // VerifyHostname checks that the peer certificate chain is valid for
1667 // connecting to host. If so, it returns nil; if not, it returns an error
1668 // describing the problem.
1669 func (c *Conn) VerifyHostname(host []byte) error {
1670 c.handshakeMutex.Lock()
1671 defer c.handshakeMutex.Unlock()
1672 if !c.isClient {
1673 return errors.New("tls: VerifyHostname called on TLS server connection")
1674 }
1675 if !c.isHandshakeComplete.Load() {
1676 return errors.New("tls: handshake has not yet been performed")
1677 }
1678 if len(c.verifiedChains) == 0 {
1679 return errors.New("tls: handshake did not verify certificate chain")
1680 }
1681 return c.peerCertificates[0].VerifyHostname(host)
1682 }
1683 1684 // setReadTrafficSecret sets the read traffic secret for the given encryption level. If
1685 // being called at the same time as setWriteTrafficSecret, the caller must ensure the call
1686 // to setWriteTrafficSecret happens first so any alerts are sent at the write level.
1687 func (c *Conn) setReadTrafficSecret(suite *cipherSuiteTLS13, level QUICEncryptionLevel, secret []byte) error {
1688 // Ensure that there are no buffered handshake messages before changing the
1689 // read keys, since that can cause messages to be parsed that were encrypted
1690 // using old keys which are no longer appropriate.
1691 if c.hand.Len() != 0 {
1692 c.sendAlert(alertUnexpectedMessage)
1693 return errors.New("tls: handshake buffer not empty before setting read traffic secret")
1694 }
1695 c.in.setTrafficSecret(suite, level, secret)
1696 return nil
1697 }
1698 1699 // setWriteTrafficSecret sets the write traffic secret for the given encryption level. If
1700 // being called at the same time as setReadTrafficSecret, the caller must ensure the call
1701 // to setWriteTrafficSecret happens first so any alerts are sent at the write level.
1702 func (c *Conn) setWriteTrafficSecret(suite *cipherSuiteTLS13, level QUICEncryptionLevel, secret []byte) {
1703 c.out.setTrafficSecret(suite, level, secret)
1704 }
1705