new: Support TLS-PSK (TLS 1.3) (#231)

* uTLS: X25519Kyber768Draft00 hybrid post-quantum key agreement by cloudflare/go (#222) * crypto/tls: Add hybrid post-quantum key agreement (#13) * import: client-side KEM from cloudflare/go * import: server-side KEM from cloudflare/go * fix: modify test to get rid of CFEvents. Note: uTLS does not promise any server-side functionality, and this change is made to be able to conduct unit tests which requires both side to be able to handle KEM Curves. Co-authored-by: Christopher Wood <caw@heapingbits.net> Co-Authored-By: Bas Westerbaan <bas@westerbaan.name> ---- Based on: * crypto/tls: Add hybrid post-quantum key agreement Adds X25519Kyber512Draft00, X25519Kyber768Draft00, and P256Kyber768Draft00 hybrid post-quantum key agreements with temporary group identifiers. The hybrid post-quantum key exchanges uses plain X{25519,448} instead of HPKE, which we assume will be more likely to be adopted. The order is chosen to match CECPQ2. Not enabled by default. Adds CFEvents to detect `HelloRetryRequest`s and to signal which key agreement was used. Co-authored-by: Christopher Wood <caw@heapingbits.net> [bas, 1.20.1: also adds P256Kyber768Draft00] [pwu, 1.20.4: updated circl to v1.3.3, moved code to cfevent.go] * crypto: add support for CIRCL signature schemes * only partially port the commit from cloudflare/go. We would stick to the official x509 at the cost of incompatibility. Co-Authored-By: Bas Westerbaan <bas@westerbaan.name> Co-Authored-By: Christopher Patton <3453007+cjpatton@users.noreply.github.com> Co-Authored-By: Peter Wu <peter@lekensteyn.nl> * crypto/tls: add new X25519Kyber768Draft00 code point Ported from cloudflare/go to support the upcoming new post-quantum keyshare. ---- * Point tls.X25519Kyber768Draft00 to the new 0x6399 identifier while the old 0xfe31 identifier is available as tls.X25519Kyber768Draft00Old. * Make sure that the kem.PrivateKey can always be mapped to the CurveID that was linked to it. This is needed since we now have two ID aliasing to the same scheme, and clients need to be able to detect whether the key share presented by the server actually matches the key share that the client originally sent. * Update tests, add the new identifier and remove unnecessary code. Link: https://mailarchive.ietf.org/arch/msg/tls/HAWpNpgptl--UZNSYuvsjB-Pc2k/ Link: https://datatracker.ietf.org/doc/draft-tls-westerbaan-xyber768d00/02/ Co-Authored-By: Peter Wu <peter@lekensteyn.nl> Co-Authored-By: Bas Westerbaan <bas@westerbaan.name> --------- Co-authored-by: Bas Westerbaan <bas@westerbaan.name> Co-authored-by: Christopher Patton <3453007+cjpatton@users.noreply.github.com> Co-authored-by: Peter Wu <peter@lekensteyn.nl> * new: enable PQ parrots (#225) * Redesign KeySharesEcdheParameters into KeySharesParameters which supports multiple types of keys. * Optimize program logic to prevent using unwanted keys * new: more parrots and safety update (#227) * new: PQ and other parrots Add new preset parrots: - HelloChrome_114_Padding_PSK_Shuf - HelloChrome_115_PQ - HelloChrome_115_PQ_PSK * new: ShuffleChromeTLSExtensions Implement a new function `ShuffleChromeTLSExtensions(exts []TLSExtension) []TLSExtension`. * update: include psk parameter for parrot-related functions Update following functions' prototype to accept an optional pskExtension (of type *FakePreSharedKeyExtension): - `UClient(conn net.Conn, config *Config, clientHelloID ClientHelloID)` => `UClient(conn net.Conn, config *Config, clientHelloID ClientHelloID, pskExtension ...*FakePreSharedKeyExtension)` - `UTLSIdToSpec(id ClientHelloID)` => `UTLSIdToSpec(id ClientHelloID, pskExtension ...*FakePreSharedKeyExtension)` * new: pre-defined error from UTLSIdToSpec Update UTLSIdToSpec to return more comprehensive errors by pre-defining them, allowing easier error comparing/unwrapping. * new: UtlsPreSharedKeyExtension In `u_pre_shared_key.go`, create `PreSharedKeyExtension` as an interface, with 3 implementations: - `UtlsPreSharedKeyExtension` implements full support for `pre_shared_key` less resuming after seeing HRR. - `FakePreSharedKeyExtension` uses CipherSuiteID, SessionSecret and Identities to calculate the corresponding binders and send them, without setting the internal states. Therefore if the server accepts the PSK and tries to resume, the connection fails. - `HardcodedPreSharedKeyExtension` allows user to hardcode Identities and Binders to be sent in the extension without setting the internal states. Therefore if the server accepts the PSK and tries to resume, the connection fails. TODO: Only one of FakePreSharedKeyExtension and HardcodedPreSharedKeyExtension should be kept, the other one should be just removed. We still need to learn more of the safety of hardcoding both Identities and Binders without recalculating the latter. * update: PSK minor changes and example * Updates PSK implementations for more comprehensible interfaces when applying preset/json/raw fingerprints. * Revert FakePreSharedKeyExtension to the old implementation. Add binder size checking. * Implement TLS-PSK example New bug: setting `tls.Config.ClientSessionCache` will cause PSK to fail. Currently users must set only `tls.UtlsPreSharedKeyExtension.ClientSessionCacheOverride`. * fix: PSK failing if config session cache set * Fix a bug causing PSK to fail if Config.ClientSessionCache is set. * Removed `ClientSessionCacheOverride` from `UtlsPreSharedKeyExtension`. Set the `ClientSessionCache` in `Config`! Co-Authored-By: zeeker999 <13848632+zeeker999@users.noreply.github.com> * Optimize tls resumption (#235) * feat: bug fix and refactor * feat: improve example docs: add detailed explanation about the design feat: add assertion on uApplyPatch * fix: address comments feat: add option `OmitEmptyPsk` and throw error on empty psk by default feat: revert changes to public interfaces * fix: weird residue caused by merging conflict * fix: remove merge conflict residue code --------- Co-authored-by: Bas Westerbaan <bas@westerbaan.name> Co-authored-by: Christopher Patton <3453007+cjpatton@users.noreply.github.com> Co-authored-by: Peter Wu <peter@lekensteyn.nl> Co-authored-by: zeeker999 <13848632+zeeker999@users.noreply.github.com> Co-authored-by: 3andne <52860475+3andne@users.noreply.github.com>
2025-04-03 03:57:36 +03:00 · 2023-08-27 12:48:31 -06:00 · 2023-08-27 12:48:31 -06:00 · 8094658e76
commit 8094658e76
parent 45e7f1de14
18 changed files with 1377 additions and 371 deletions
--- a/u_conn.go
+++ b/u_conn.go
@ -14,23 +14,26 @@ import (
 	"errors"
 	"fmt"
 	"hash"
-	"io"
 	"net"
 	"strconv"
 )

+type ClientHelloBuildStatus int
+
+const NotBuilt ClientHelloBuildStatus = 0
+const BuildByUtls ClientHelloBuildStatus = 1
+const BuildByGoTLS ClientHelloBuildStatus = 2
+
 type UConn struct {
 	*Conn

-	Extensions    []TLSExtension
-	ClientHelloID ClientHelloID
-	pskExtension  []*FakePreSharedKeyExtension
+	Extensions        []TLSExtension
+	ClientHelloID     ClientHelloID
+	sessionController *sessionController

-	ClientHelloBuilt bool
-	HandshakeState   PubClientHandshakeState
+	clientHelloBuildStatus ClientHelloBuildStatus

-	// sessionID may or may not depend on ticket; nil => random
-	GetSessionID func(ticket []byte) [32]byte
+	HandshakeState PubClientHandshakeState

 	greaseSeed [ssl_grease_last_index]uint16

@ -44,15 +47,17 @@ type UConn struct {

 // UClient returns a new uTLS client, with behavior depending on clientHelloID.
 // Config CAN be nil, but make sure to eventually specify ServerName.
-func UClient(conn net.Conn, config *Config, clientHelloID ClientHelloID, pskExtension ...*FakePreSharedKeyExtension) *UConn {
+func UClient(conn net.Conn, config *Config, clientHelloID ClientHelloID) *UConn {
 	if config == nil {
 		config = &Config{}
 	}
 	tlsConn := Conn{conn: conn, config: config, isClient: true}
 	handshakeState := PubClientHandshakeState{C: &tlsConn, Hello: &PubClientHelloMsg{}}
-	uconn := UConn{Conn: &tlsConn, ClientHelloID: clientHelloID, pskExtension: pskExtension, HandshakeState: handshakeState}
+	uconn := UConn{Conn: &tlsConn, ClientHelloID: clientHelloID, HandshakeState: handshakeState}
 	uconn.HandshakeState.uconn = &uconn
 	uconn.handshakeFn = uconn.clientHandshake
+	uconn.sessionController = newSessionController(&uconn)
+	uconn.utls.sessionController = uconn.sessionController
 	return &uconn
 }

@ -73,9 +78,10 @@ func UClient(conn net.Conn, config *Config, clientHelloID ClientHelloID, pskExte
 // default/mimicked ClientHello.
 func (uconn *UConn) BuildHandshakeState() error {
 	if uconn.ClientHelloID == HelloGolang {
-		if uconn.ClientHelloBuilt {
+		if uconn.clientHelloBuildStatus == BuildByGoTLS {
 			return nil
 		}
+		uAssert(uconn.clientHelloBuildStatus == NotBuilt, "BuildHandshakeState failed: invalid call, client hello has already been built by utls")

 		// use default Golang ClientHello.
 		hello, keySharePrivate, err := uconn.makeClientHello()
@ -92,8 +98,10 @@ func (uconn *UConn) BuildHandshakeState() error {
 			return fmt.Errorf("uTLS: unknown keySharePrivate type: %T", keySharePrivate)
 		}
 		uconn.HandshakeState.C = uconn.Conn
+		uconn.clientHelloBuildStatus = BuildByGoTLS
 	} else {
-		if !uconn.ClientHelloBuilt {
+		uAssert(uconn.clientHelloBuildStatus == BuildByUtls || uconn.clientHelloBuildStatus == NotBuilt, "BuildHandshakeState failed: invalid call, client hello has already been built by go-tls")
+		if uconn.clientHelloBuildStatus == NotBuilt {
 			err := uconn.applyPresetByID(uconn.ClientHelloID)
 			if err != nil {
 				return err
@ -107,52 +115,106 @@ func (uconn *UConn) BuildHandshakeState() error {
 		if err != nil {
 			return err
 		}
+
+		err = uconn.uLoadSession()
+		if err != nil {
+			return err
+		}
+
 		err = uconn.MarshalClientHello()
 		if err != nil {
 			return err
 		}
+
+		uconn.uApplyPatch()
+
+		uconn.sessionController.finalCheck()
+		uconn.clientHelloBuildStatus = BuildByUtls
 	}
-	uconn.ClientHelloBuilt = true
 	return nil
 }

+func (uconn *UConn) uLoadSession() error {
+	if cfg := uconn.config; cfg.SessionTicketsDisabled || cfg.ClientSessionCache == nil {
+		return nil
+	}
+	switch uconn.sessionController.shouldLoadSession() {
+	case shouldReturn:
+	case shouldSetTicket:
+		uconn.sessionController.setSessionTicketToUConn()
+	case shouldSetPsk:
+		uconn.sessionController.setPskToUConn()
+	case shouldLoad:
+		hello := uconn.HandshakeState.Hello.getPrivatePtr()
+		uconn.sessionController.utlsAboutToLoadSession()
+		session, earlySecret, binderKey, err := uconn.loadSession(hello)
+		if session == nil || err != nil {
+			return err
+		}
+		if session.version == VersionTLS12 {
+			// We use the session ticket extension for tls 1.2 session resumption
+			uconn.sessionController.initSessionTicketExt(session, hello.sessionTicket)
+			uconn.sessionController.setSessionTicketToUConn()
+		} else {
+			uconn.sessionController.initPskExt(session, earlySecret, binderKey, hello.pskIdentities)
+		}
+	}
+
+	return nil
+}
+
+func (uconn *UConn) uApplyPatch() {
+	helloLen := len(uconn.HandshakeState.Hello.Raw)
+	if uconn.sessionController.shouldUpdateBinders() {
+		uconn.sessionController.updateBinders()
+		uconn.sessionController.setPskToUConn()
+	}
+	uAssert(helloLen == len(uconn.HandshakeState.Hello.Raw), "tls: uApplyPatch Failed: the patch should never change the length of the marshaled clientHello")
+}
+
+func (uconn *UConn) DidTls12Resume() bool {
+	return uconn.didResume
+}
+
 // SetSessionState sets the session ticket, which may be preshared or fake.
 // If session is nil, the body of session ticket extension will be unset,
 // but the extension itself still MAY be present for mimicking purposes.
 // Session tickets to be reused - use same cache on following connections.
+//
+// Deprecated: This method is deprecated in favor of SetSessionTicketExtension,
+// as it only handles session override of TLS 1.2
 func (uconn *UConn) SetSessionState(session *ClientSessionState) error {
-	var sessionTicket []uint8
+	sessionTicketExt := &SessionTicketExtension{Initialized: true}
 	if session != nil {
-		sessionTicket = session.ticket
-		uconn.HandshakeState.Session = session.session
+		sessionTicketExt.Ticket = session.ticket
+		sessionTicketExt.Session = session.session
 	}
-	uconn.HandshakeState.Hello.TicketSupported = true
-	uconn.HandshakeState.Hello.SessionTicket = sessionTicket
+	return uconn.SetSessionTicketExtension(sessionTicketExt)
+}

-	for _, ext := range uconn.Extensions {
-		st, ok := ext.(*SessionTicketExtension)
-		if !ok {
-			continue
-		}
-		st.Session = session
-		if session != nil {
-			if len(session.SessionTicket()) > 0 {
-				if uconn.GetSessionID != nil {
-					sid := uconn.GetSessionID(session.SessionTicket())
-					uconn.HandshakeState.Hello.SessionId = sid[:]
-					return nil
-				}
-			}
-			var sessionID [32]byte
-			_, err := io.ReadFull(uconn.config.rand(), sessionID[:])
-			if err != nil {
-				return err
-			}
-			uconn.HandshakeState.Hello.SessionId = sessionID[:]
-		}
+// SetSessionTicket sets the session ticket extension.
+// If extension is nil, this will be a no-op.
+func (uconn *UConn) SetSessionTicketExtension(sessionTicketExt ISessionTicketExtension) error {
+	if uconn.config.SessionTicketsDisabled || uconn.config.ClientSessionCache == nil {
+		return fmt.Errorf("tls: SetSessionTicketExtension failed: session is disabled")
+	}
+	if sessionTicketExt == nil {
 		return nil
 	}
-	return nil
+	return uconn.sessionController.overrideSessionTicketExt(sessionTicketExt)
+}
+
+// SetPskExtension sets the psk extension for tls 1.3 resumption. This is a no-op if the psk is nil.
+func (uconn *UConn) SetPskExtension(pskExt PreSharedKeyExtension) error {
+	if uconn.config.SessionTicketsDisabled || uconn.config.ClientSessionCache == nil {
+		return fmt.Errorf("tls: SetPskExtension failed: session is disabled")
+	}
+	if pskExt == nil {
+		return nil
+	}
+
+	uconn.HandshakeState.Hello.TicketSupported = true
+	return uconn.sessionController.overridePskExt(pskExt)
 }

 // If you want session tickets to be reused - use same cache on following connections
@ -397,7 +459,7 @@ func (c *UConn) clientHandshake(ctx context.Context) (err error) {
 	hello := c.HandshakeState.Hello.getPrivatePtr()
 	defer func() { c.HandshakeState.Hello = hello.getPublicPtr() }()

-	sessionIsAlreadySet := c.HandshakeState.Session != nil
+	sessionIsLocked := c.utls.sessionController.isSessionLocked()

 	// after this point exactly 1 out of 2 HandshakeState pointers is non-nil,
 	// useTLS13 variable tells which pointer
@ -434,9 +496,24 @@ func (c *UConn) clientHandshake(ctx context.Context) (err error) {
 	if c.handshakes > 0 {
 		hello.secureRenegotiation = c.clientFinished[:]
 	}
-	// [uTLS section ends]

-	session, earlySecret, binderKey, err := c.loadSession(hello)
+	var (
+		session     *SessionState
+		earlySecret []byte
+		binderKey   []byte
+	)
+	if !sessionIsLocked {
+		// [uTLS section ends]
+
+		session, earlySecret, binderKey, err = c.loadSession(hello)
+
+		// [uTLS section start]
+	} else {
+		session = c.HandshakeState.Session
+		earlySecret = c.HandshakeState.State13.EarlySecret
+		binderKey = c.HandshakeState.State13.BinderKey
+	}
+	// [uTLS section ends]
 	if err != nil {
 		return err
 	}
@ -456,21 +533,20 @@ func (c *UConn) clientHandshake(ctx context.Context) (err error) {
 		}()
 	}

-	cacheKey := c.clientSessionCacheKey()
-	if c.config.ClientSessionCache != nil {
-		cs, ok := c.config.ClientSessionCache.Get(cacheKey)
-		if !sessionIsAlreadySet && ok { // uTLS: do not overwrite already set session
-			err = c.SetSessionState(cs)
-			if err != nil {
-				return
-			}
-		}
-	}
-
 	if _, err := c.writeHandshakeRecord(hello, nil); err != nil {
 		return err
 	}

+	if hello.earlyData {
+		suite := cipherSuiteTLS13ByID(session.cipherSuite)
+		transcript := suite.hash.New()
+		if err := transcriptMsg(hello, transcript); err != nil {
+			return err
+		}
+		earlyTrafficSecret := suite.deriveSecret(earlySecret, clientEarlyTrafficLabel, transcript)
+		c.quicSetWriteSecret(QUICEncryptionLevelEarly, suite.id, earlyTrafficSecret)
+	}
+
 	msg, err := c.readHandshake(nil)
 	if err != nil {
 		return err
@ -491,9 +567,11 @@ func (c *UConn) clientHandshake(ctx context.Context) (err error) {
 		hs13 := c.HandshakeState.toPrivate13()
 		hs13.serverHello = serverHello
 		hs13.hello = hello
-		if !sessionIsAlreadySet {
+		hs13.keySharesParams = NewKeySharesParameters()
+		if !sessionIsLocked {
 			hs13.earlySecret = earlySecret
 			hs13.binderKey = binderKey
+			hs13.session = session
 		}
 		hs13.ctx = ctx
 		// In TLS 1.3, session tickets are delivered after the handshake.
@ -508,6 +586,7 @@ func (c *UConn) clientHandshake(ctx context.Context) (err error) {
 	hs12.serverHello = serverHello
 	hs12.hello = hello
 	hs12.ctx = ctx
+	hs12.session = session
 	err = hs12.handshake()
 	if handshakeState := hs12.toPublic12(); handshakeState != nil {
 		c.HandshakeState = *handshakeState
@ -515,17 +594,6 @@ func (c *UConn) clientHandshake(ctx context.Context) (err error) {
 	if err != nil {
 		return err
 	}
-
-	// If we had a successful handshake and hs.session is different from
-	// the one already cached - cache a new one.
-	if cacheKey != "" && hs12.session != nil && session != hs12.session {
-		hs12cs := &ClientSessionState{
-			ticket:  hs12.ticket,
-			session: hs12.session,
-		}
-
-		c.config.ClientSessionCache.Put(cacheKey, hs12cs)
-	}
 	return nil
 }

@ -556,7 +624,7 @@ func (uconn *UConn) MarshalClientHello() error {
 			if paddingExt == nil {
 				paddingExt = pe
 			} else {
-				return errors.New("multiple padding extensions!")
+				return errors.New("multiple padding extensions")
 			}
 		}
 	}
@ -598,7 +666,9 @@ func (uconn *UConn) MarshalClientHello() error {
 	if len(uconn.Extensions) > 0 {
 		binary.Write(bufferedWriter, binary.BigEndian, uint16(extensionsLen))
 		for _, ext := range uconn.Extensions {
-			bufferedWriter.ReadFrom(ext)
+			if _, err := bufferedWriter.ReadFrom(ext); err != nil {
+				return err
+			}
 		}
 	}

@ -784,7 +854,10 @@ func (c *Conn) utlsConnectionStateLocked(state *ConnectionState) {
 }

 type utlsConnExtraFields struct {
+	// Application Settings (ALPS)
 	hasApplicationSettings   bool
 	peerApplicationSettings  []byte
 	localApplicationSettings []byte
+
+	sessionController *sessionController
 }