Merge branch 'master'

.github/workflows/go.yml

@@ -15,7 +15,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ "ubuntu-latest", "windows-latest", "macos-latest" ]
-        go: [ "1.20.x", "1.21.0" ]
+        go: [ "1.20.x", "1.21.x" ]
     runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v3

cipher_suites.go

@@ -19,6 +19,7 @@ import (
 	"hash"
 	"runtime"
 
+	"github.com/refraction-networking/utls/internal/boring"
 	"golang.org/x/sys/cpu"
 
 	"golang.org/x/crypto/chacha20poly1305"

common.go

@@ -700,6 +700,19 @@ type Config struct {
 	// This field is ignored when InsecureSkipVerify is true.
 	InsecureServerNameToVerify string // [uTLS]
 
+	// PreferSkipResumptionOnNilExtension controls the behavior when session resumption is enabled but the corresponding session extensions are nil.
+	//
+	// To successfully use session resumption, ensure that the following requirements are met:
+	//  - SessionTicketsDisabled is set to false
+	//  - ClientSessionCache is non-nil
+	//  - For TLS 1.2, SessionTicketExtension is non-nil
+	//  - For TLS 1.3, PreSharedKeyExtension is non-nil
+	//
+	// There may be cases where users enable session resumption (SessionTicketsDisabled: false && ClientSessionCache: non-nil), but they do not provide SessionTicketExtension or PreSharedKeyExtension in the ClientHelloSpec. This could be intentional or accidental.
+	//
+	// By default, utls throws an exception in such scenarios. Set this to true to skip the resumption and suppress the exception.
+	PreferSkipResumptionOnNilExtension bool // [uTLS]
+
 	// CipherSuites is a list of enabled TLS 1.0–1.2 cipher suites. The order of
 	// the list is ignored. Note that TLS 1.3 ciphersuites are not configurable.
 	//
@@ -906,6 +919,8 @@ func (c *Config) Clone() *Config {
 		KeyLogWriter:                c.KeyLogWriter,
 		sessionTicketKeys:           c.sessionTicketKeys,
 		autoSessionTicketKeys:       c.autoSessionTicketKeys,
+
+		PreferSkipResumptionOnNilExtension: c.PreferSkipResumptionOnNilExtension, // [UTLS]
 	}
 }
 

examples/tls-resumption/main.go

@@ -38,7 +38,16 @@ func (csc *ClientSessionCache) Put(sessionKey string, cs *tls.ClientSessionState
 	}
 }
 
-func runResumptionCheck(helloID tls.ClientHelloID, serverAddr string, retry int, verbose bool) {
+type ResumptionType int
+
+const (
+	noResumption     ResumptionType = 0
+	pskResumption    ResumptionType = 1
+	ticketResumption ResumptionType = 2
+)
+
+func runResumptionCheck(helloID tls.ClientHelloID, getCustomSpec func() *tls.ClientHelloSpec, expectResumption ResumptionType, serverAddr string, retry int, verbose bool) {
+	fmt.Printf("checking: hello [%s], expectResumption [%v], serverAddr [%s]\n", helloID.Client, expectResumption, serverAddr)
 	csc := NewClientSessionCache()
 	tcpConn, err := net.Dial("tcp", serverAddr)
 	if err != nil {
@@ -55,6 +64,10 @@ func runResumptionCheck(helloID tls.ClientHelloID, serverAddr string, retry int,
 		OmitEmptyPsk:       true,
 	}, helloID)
 
+	if getCustomSpec != nil {
+		tlsConn.ApplyPreset(getCustomSpec())
+	}
+
 	// HS
 	err = tlsConn.Handshake()
 	if err != nil {
@@ -108,6 +121,10 @@ func runResumptionCheck(helloID tls.ClientHelloID, serverAddr string, retry int,
 			OmitEmptyPsk:       true,
 		}, helloID)
 
+		if getCustomSpec != nil {
+			tlsConnPSK.ApplyPreset(getCustomSpec())
+		}
+
 		// HS
 		err = tlsConnPSK.Handshake()
 		if verbose {
@@ -133,27 +150,16 @@ func runResumptionCheck(helloID tls.ClientHelloID, serverAddr string, retry int,
 
 			if tlsVer == tls.VersionTLS13 && tlsConnPSK.HandshakeState.State13.UsingPSK {
 				fmt.Println("[PSK used]")
-				return
+				resumption = pskResumption
+				break
 			} else if tlsVer == tls.VersionTLS12 && tlsConnPSK.DidTls12Resume() {
 				fmt.Println("[session ticket used]")
-				return
+				resumption = ticketResumption
+				break
 			}
 		}
 		time.Sleep(700 * time.Millisecond)
 	}
 	panic(fmt.Sprintf("PSK or session ticket not used for a resumption session, server %s, helloID: %s", serverAddr, helloID.Client))
-}
-
-func main() {
-	tls13Url := "www.microsoft.com:443"
-	tls12Url1 := "spocs.getpocket.com:443"
-	tls12Url2 := "marketplace.visualstudio.com:443"
-	runResumptionCheck(tls.HelloChrome_100_PSK, tls13Url, 1, false) // psk + utls
-	runResumptionCheck(tls.HelloGolang, tls13Url, 1, false)         // psk + crypto/tls
-
-	runResumptionCheck(tls.HelloChrome_100_PSK, tls12Url1, 10, false) // session ticket + utls
-	runResumptionCheck(tls.HelloGolang, tls12Url1, 10, false)         // session ticket + crypto/tls
-	runResumptionCheck(tls.HelloChrome_100_PSK, tls12Url2, 10, false) // session ticket + utls
-	runResumptionCheck(tls.HelloGolang, tls12Url2, 10, false)         // session ticket + crypto/tls
 
 }

go.mod

@@ -13,9 +13,9 @@ require (
 	github.com/gaukas/godicttls v0.0.4
 	github.com/klauspost/compress v1.16.7
 	github.com/quic-go/quic-go v0.37.4
-	golang.org/x/crypto v0.12.0
-	golang.org/x/net v0.14.0
-	golang.org/x/sys v0.11.0
+	golang.org/x/crypto v0.14.0
+	golang.org/x/net v0.17.0
+	golang.org/x/sys v0.13.0
 )
 
-require golang.org/x/text v0.12.0 // indirect
+require golang.org/x/text v0.13.0 // indirect

go.sum

@@ -1,9 +1,25 @@
 github.com/andybalholm/brotli v1.0.5/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig=
+github.com/cloudflare/circl v1.3.3 h1:fE/Qz0QdIGqeWfnwq0RE0R7MI51s0M2E4Ga9kq5AEMs=
 github.com/cloudflare/circl v1.3.3/go.mod h1:5XYMA4rFBvNIrhs50XuiBJ15vF2pZn4nnUKZrLbUZFA=
+github.com/gaukas/godicttls v0.0.4 h1:NlRaXb3J6hAnTmWdsEKb9bcSBD6BvcIjdGdeb0zfXbk=
 github.com/gaukas/godicttls v0.0.4/go.mod h1:l6EenT4TLWgTdwslVb4sEMOCf7Bv0JAK67deKr9/NCI=
+github.com/go-logr/logr v1.2.4 h1:g01GSCwiDw2xSZfjJ2/T9M+S6pFdcNtFYsp+Y43HYDQ=
+github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572 h1:tfuBGBXKqDEevZMzYi5KSi8KkcZtzBcTgAUUtapy0OI=
+github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
+github.com/google/pprof v0.0.0-20210407192527-94a9f03dee38 h1:yAJXTCF9TqKcTiHJAE8dj7HMvPfh66eeA2JYW7eFpSE=
+github.com/klauspost/compress v1.16.7 h1:2mk3MPGNzKyxErAw8YaohYh69+pa4sIQSC0fPGCFR9I=
 github.com/klauspost/compress v1.16.7/go.mod h1:ntbaceVETuRiXiv4DpjP66DpAtAGkEQskQzEyD//IeE=
+github.com/onsi/ginkgo/v2 v2.9.5 h1:+6Hr4uxzP4XIUyAkg61dWBw8lb/gc4/X5luuxN/EC+Q=
+github.com/onsi/gomega v1.27.6 h1:ENqfyGeS5AX/rlXDd/ETokDz93u0YufY1Pgxuy/PvWE=
+github.com/quic-go/quic-go v0.37.4 h1:ke8B73yMCWGq9MfrCCAw0Uzdm7GaViC3i39dsIdDlH4=
 github.com/quic-go/quic-go v0.37.4/go.mod h1:YsbH1r4mSHPJcLF4k4zruUkLBqctEMBDR6VPvcYjIsU=
-golang.org/x/crypto v0.12.0/go.mod h1:NF0Gs7EO5K4qLn+Ylc+fih8BSTeIjAP05siRnAh98yw=
-golang.org/x/net v0.14.0/go.mod h1:PpSgVXXLK0OxS0F31C1/tv6XNguvCrnXIDrFMspZIUI=
-golang.org/x/sys v0.11.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/text v0.12.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
+golang.org/x/crypto v0.14.0 h1:wBqGXzWJW6m1XrIKlAH0Hs1JJ7+9KBwnIO8v66Q9cHc=
+golang.org/x/crypto v0.14.0/go.mod h1:MVFd36DqK4CsrnJYDkBA3VC4m2GkXAM0PvzMCn4JQf4=
+golang.org/x/net v0.17.0 h1:pVaXccu2ozPjCXewfr1S7xza/zcXTity9cCdXQYSjIM=
+golang.org/x/net v0.17.0/go.mod h1:NxSsAGuq816PNPmqtQdLE42eU2Fs7NoRIZrHJAlaCOE=
+golang.org/x/sys v0.13.0 h1:Af8nKPmuFypiUBjVoU9V20FiaFXOcuZI21p0ycVYYGE=
+golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/text v0.13.0 h1:ablQoSUd0tRdKxZewP80B+BaqeKJuVhuRxj/dkrun3k=
+golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
+golang.org/x/tools v0.9.1 h1:8WMNJAz3zrtPmnYC7ISf5dEn3MT0gY7jBJfw27yrrLo=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

internal/boring/notboring.go

@@ -0,0 +1,16 @@
+package boring
+
+import (
+	"crypto/cipher"
+	"errors"
+)
+
+const Enabled bool = false
+
+func NewGCMTLS(_ cipher.Block) (cipher.AEAD, error) {
+	return nil, errors.New("boring not implemented")
+}
+
+func Unreachable() {
+	// do nothing
+}

notboring.go

@@ -3,11 +3,6 @@
 // license that can be found in the LICENSE file.
 package tls
 
-import (
-	"crypto/cipher"
-	"errors"
-)
-
 func needFIPS() bool { return false }
 
 func supportedSignatureAlgorithms() []SignatureScheme {
@@ -20,20 +15,3 @@ func fipsCurvePreferences(c *Config) []CurveID { panic("fipsCurvePreferences") }
 func fipsCipherSuites(c *Config) []uint16      { panic("fipsCipherSuites") }
 
 var fipsSupportedSignatureAlgorithms []SignatureScheme
-
-// [uTLS]
-// Boring struct is only to be used to record static env variables
-// in boring package. We do not implement BoringSSL compatibliity here.
-type Boring struct {
-	Enabled bool
-}
-
-func (*Boring) NewGCMTLS(_ cipher.Block) (cipher.AEAD, error) {
-	return nil, errors.New("boring not implemented")
-}
-
-func (*Boring) Unreachable() {
-	// do nothing
-}
-
-var boring Boring

tls_test.go

@@ -854,7 +854,7 @@ func TestCloneNonFuncFields(t *testing.T) {
 			f.Set(reflect.ValueOf("b"))
 		case "ClientAuth":
 			f.Set(reflect.ValueOf(VerifyClientCertIfGiven))
-		case "InsecureSkipVerify", "InsecureSkipTimeVerify", "SessionTicketsDisabled", "DynamicRecordSizingDisabled", "PreferServerCipherSuites", "OmitEmptyPsk":
+		case "InsecureSkipVerify", "InsecureSkipTimeVerify", "SessionTicketsDisabled", "DynamicRecordSizingDisabled", "PreferServerCipherSuites", "OmitEmptyPsk", "PreferSkipResumptionOnNilExtension":
 			f.Set(reflect.ValueOf(true))
 		case "InsecureServerNameToVerify":
 			f.Set(reflect.ValueOf("c"))

u_alias.go

@@ -0,0 +1,12 @@
+package tls
+
+// This file contains all the alias functions, symbols, names, etc. that
+// was once used in the old version of the library.  This is to ensure
+// backwards compatibility with the old version of the library.
+
+// TLS Extensions
+
+// UtlsExtendedMasterSecretExtension is an alias for ExtendedMasterSecretExtension.
+//
+// Deprecated: Use ExtendedMasterSecretExtension instead.
+type UtlsExtendedMasterSecretExtension = ExtendedMasterSecretExtension

u_common.go

@@ -208,8 +208,6 @@ func (chs *ClientHelloSpec) ReadCompressionMethods(compressionMethods []byte) er
 
 // ReadTLSExtensions is a helper function to construct a list of TLS extensions from
 // a byte slice into []TLSExtension.
-//
-// If keepPSK is not set, the PSK extension will cause an error.
 func (chs *ClientHelloSpec) ReadTLSExtensions(b []byte, allowBluntMimicry bool, realPSK bool) error {
 	extensions := cryptobyte.String(b)
 	for !extensions.Empty() {
@@ -233,12 +231,11 @@ func (chs *ClientHelloSpec) ReadTLSExtensions(b []byte, allowBluntMimicry bool,
 				} else {
 					extWriter = &FakePreSharedKeyExtension{}
 				}
-			}
-
-			if extension == extensionSupportedVersions {
+			case extensionSupportedVersions:
 				chs.TLSVersMin = 0
 				chs.TLSVersMax = 0
 			}
+
 			if _, err := extWriter.Write(extData); err != nil {
 				return err
 			}

u_conn.go

@@ -39,6 +39,11 @@ type UConn struct {
 
 	omitSNIExtension bool
 
+	// skipResumptionOnNilExtension is copied from `Config.PreferSkipResumptionOnNilExtension`.
+	//
+	// By default, if ClientHelloSpec is predefined or utls-generated (as opposed to HelloCustom), this flag will be updated to true.
+	skipResumptionOnNilExtension bool
+
 	// certCompressionAlgs represents the set of advertised certificate compression
 	// algorithms, as specified in the ClientHello. This is only relevant client-side, for the
 	// server certificate. All other forms of certificate compression are unsupported.
@@ -58,6 +63,7 @@ func UClient(conn net.Conn, config *Config, clientHelloID ClientHelloID) *UConn
 	uconn.handshakeFn = uconn.clientHandshake
 	uconn.sessionController = newSessionController(&uconn)
 	uconn.utls.sessionController = uconn.sessionController
+	uconn.skipResumptionOnNilExtension = config.PreferSkipResumptionOnNilExtension || clientHelloID.Client != helloCustom
 	return &uconn
 }
 

u_fingerprinter.go

@@ -8,7 +8,6 @@ package tls
 type Fingerprinter struct {
 	// AllowBluntMimicry will ensure that unknown extensions are
 	// passed along into the resulting ClientHelloSpec as-is
-	// It will not ensure that the PSK is passed along, if you require that, use KeepPSK
 	// WARNING: there could be numerous subtle issues with ClientHelloSpecs
 	// that are generated with this flag which could compromise security and/or mimicry
 	AllowBluntMimicry bool

u_pre_shared_key.go

@@ -134,6 +134,7 @@ type UtlsPreSharedKeyExtension struct {
 	PreSharedKeyCommon
 	cipherSuite  *cipherSuiteTLS13
 	cachedLength *int
+	// Deprecated: Set OmitEmptyPsk in Config instead.
 	OmitEmptyPsk bool
 }
 
@@ -308,8 +309,9 @@ func (e *UtlsPreSharedKeyExtension) UnmarshalJSON(_ []byte) error {
 type FakePreSharedKeyExtension struct {
 	UnimplementedPreSharedKeyExtension
 
-	Identities   []PskIdentity `json:"identities"`
-	Binders      [][]byte      `json:"binders"`
+	Identities []PskIdentity `json:"identities"`
+	Binders    [][]byte      `json:"binders"`
+	// Deprecated: Set OmitEmptyPsk in Config instead.
 	OmitEmptyPsk bool
 }