feat: implement ALPS Extension draft

- Made necessary modifications to existing types to support ALPS.
- Ported `ApplicationSettingsExtension` implementation from `ulixee/utls` by @blakebyrnes with some adaptation.

Co-Authored-By: Blake Byrnes <115056+blakebyrnes@users.noreply.github.com>

common.go

@@ -238,6 +238,10 @@ type ConnectionState struct {
 	// Deprecated: this value is always true.
 	NegotiatedProtocolIsMutual bool
 
+	// PeerApplicationSettings is the Application-Layer Protocol Settings (ALPS)
+	// provided by peer.
+	PeerApplicationSettings []byte // [uTLS]
+
 	// ServerName is the value of the Server Name Indication extension sent by
 	// the client. It's available both on the server and on the client side.
 	ServerName string
@@ -625,6 +629,10 @@ type Config struct {
 	// ConnectionState.NegotiatedProtocol will be empty.
 	NextProtos []string
 
+	// ApplicationSettings is a set of application settings (ALPS) to use
+	// with each application protocol (ALPN).
+	ApplicationSettings map[string][]byte // [uTLS]
+
 	// ServerName is used to verify the hostname on the returned
 	// certificates unless InsecureSkipVerify is given. It is also included
 	// in the client's handshake to support virtual hosting unless it is
@@ -800,6 +808,7 @@ func (c *Config) Clone() *Config {
 		VerifyConnection:            c.VerifyConnection,
 		RootCAs:                     c.RootCAs,
 		NextProtos:                  c.NextProtos,
+		ApplicationSettings:         c.ApplicationSettings,
 		ServerName:                  c.ServerName,
 		ClientAuth:                  c.ClientAuth,
 		ClientCAs:                   c.ClientCAs,

conn.go

@@ -92,6 +92,10 @@ type Conn struct {
 	// clientProtocol is the negotiated ALPN protocol.
 	clientProtocol string
 
+	// [UTLS SECTION START]
+	utls utlsConnExtraFields // used for extensive things such as ALPS
+	// [UTLS SECTION END]
+
 	// input/output
 	in, out   halfConn
 	rawInput  bytes.Buffer // raw input, starting with a record header
@@ -1075,8 +1079,10 @@ func (c *Conn) readHandshake() (any, error) {
 		}
 	case typeFinished:
 		m = new(finishedMsg)
-	case typeEncryptedExtensions:
-		m = new(encryptedExtensionsMsg)
+	// [uTLS] Commented typeEncryptedExtensions to force
+	// utlsHandshakeMessageType to handle it
+	// case typeEncryptedExtensions:
+	// 	m = new(encryptedExtensionsMsg)
 	case typeEndOfEarlyData:
 		m = new(endOfEarlyDataMsg)
 	case typeKeyUpdate:
@@ -1517,6 +1523,7 @@ func (c *Conn) connectionStateLocked() ConnectionState {
 	} else {
 		state.ekm = c.ekm
 	}
+
 	return state
 }
 

handshake_client_tls13.go

@@ -98,6 +98,11 @@ func (hs *clientHandshakeStateTLS13) handshake() error {
 	if err := hs.readServerFinished(); err != nil {
 		return err
 	}
+	// [UTLS SECTION START]
+	if err := hs.serverFinishedReceived(); err != nil {
+		return err
+	}
+	// [UTLS SECTION END]
 	if err := hs.sendClientCertificate(); err != nil {
 		return err
 	}
@@ -472,6 +477,15 @@ func (hs *clientHandshakeStateTLS13) readServerParameters() error {
 	}
 	c.clientProtocol = encryptedExtensions.alpnProtocol
 
+	// [UTLS SECTION STARTS]
+	if hs.uconn != nil {
+		err = hs.utlsReadServerParameters(encryptedExtensions)
+		if err != nil {
+			c.sendAlert(alertUnsupportedExtension)
+			return err
+		}
+	}
+	// [UTLS SECTION ENDS]
 	return nil
 }
 
@@ -561,7 +575,7 @@ func (hs *clientHandshakeStateTLS13) readServerCertificate() error {
 	// See RFC 8446, Section 4.4.3.
 	if !isSupportedSignatureAlgorithm(certVerify.signatureAlgorithm, supportedSignatureAlgorithms()) {
 		c.sendAlert(alertIllegalParameter)
-		return errors.New("tls: certificate used with invalid signature algorithm")
+		return errors.New("tls: certificate used with invalid signature algorithm -- not implemented")
 	}
 	sigType, sigHash, err := typeAndHashFromSignatureScheme(certVerify.signatureAlgorithm)
 	if err != nil {
@@ -569,7 +583,7 @@ func (hs *clientHandshakeStateTLS13) readServerCertificate() error {
 	}
 	if sigType == signaturePKCS1v15 || sigHash == crypto.SHA1 {
 		c.sendAlert(alertIllegalParameter)
-		return errors.New("tls: certificate used with invalid signature algorithm")
+		return errors.New("tls: certificate used with invalid signature algorithm -- obsolete")
 	}
 	signed := signedMessage(sigHash, serverSignatureContext, hs.transcript)
 	if err := verifyHandshakeSignature(sigType, c.peerCertificates[0].PublicKey,

handshake_messages.go

@@ -868,6 +868,8 @@ func (m *serverHelloMsg) unmarshal(data []byte) bool {
 type encryptedExtensionsMsg struct {
 	raw          []byte
 	alpnProtocol string
+
+	utls utlsEncryptedExtensionsMsgExtraFields // [uTLS]
 }
 
 func (m *encryptedExtensionsMsg) marshal() []byte {
@@ -927,6 +929,11 @@ func (m *encryptedExtensionsMsg) unmarshal(data []byte) bool {
 			}
 			m.alpnProtocol = string(proto)
 		default:
+			// [UTLS SECTION START]
+			if !m.utlsUnmarshal(extension, extData) {
+				return false // return false when ERROR
+			}
+			// [UTLS SECTION END]
 			// Ignore unknown extensions.
 			continue
 		}

handshake_messages_test.go

@@ -36,7 +36,7 @@ var tests = []any{
 	&newSessionTicketMsgTLS13{},
 	&certificateRequestMsgTLS13{},
 	&certificateMsgTLS13{},
-	&compressedCertificateMsg{}, // [UTLS]
+	&utlsCompressedCertificateMsg{}, // [UTLS]
 }
 
 func TestMarshalUnmarshal(t *testing.T) {
@@ -406,8 +406,8 @@ func (*certificateMsgTLS13) Generate(rand *rand.Rand, size int) reflect.Value {
 }
 
 // [UTLS]
-func (*compressedCertificateMsg) Generate(rand *rand.Rand, size int) reflect.Value {
-	m := &compressedCertificateMsg{}
+func (*utlsCompressedCertificateMsg) Generate(rand *rand.Rand, size int) reflect.Value {
+	m := &utlsCompressedCertificateMsg{}
 	m.algorithm = uint16(rand.Intn(2 << 15))
 	m.uncompressedLength = uint32(rand.Intn(2 << 23))
 	m.compressedCertificateMessage = randomBytes(rand.Intn(500)+1, rand)

key_agreement.go

@@ -319,7 +319,7 @@ func (ka *ecdheKeyAgreement) processServerKeyExchange(config *Config, clientHell
 		}
 
 		if !isSupportedSignatureAlgorithm(signatureAlgorithm, clientHello.supportedSignatureAlgorithms) {
-			return errors.New("tls: certificate used with invalid signature algorithm")
+			return fmt.Errorf("tls: certificate used with invalid signature algorithm -- ClientHello not advertising %04x", uint16(signatureAlgorithm))
 		}
 		sigType, sigHash, err = typeAndHashFromSignatureScheme(signatureAlgorithm)
 		if err != nil {

tls_test.go

@@ -12,7 +12,6 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"github.com/refraction-networking/utls/testenv"
 	"io"
 	"math"
 	"net"
@@ -22,6 +21,8 @@ import (
 	"strings"
 	"testing"
 	"time"
+
+	"github.com/refraction-networking/utls/testenv"
 )
 
 var rsaCertPEM = `-----BEGIN CERTIFICATE-----
@@ -827,6 +828,8 @@ func TestCloneNonFuncFields(t *testing.T) {
 			f.Set(reflect.ValueOf(RenegotiateOnceAsClient))
 		case "mutex", "autoSessionTicketKeys", "sessionTicketKeys":
 			continue // these are unexported fields that are handled separately
+		case "ApplicationSettings":
+			f.Set(reflect.ValueOf(map[string][]byte{"a": {1}}))
 		default:
 			t.Errorf("all fields must be accounted for, but saw unknown field %q", fn)
 		}

u_common.go

@@ -19,23 +19,22 @@ import (
 
 // TLS handshake message types.
 const (
+	utlsTypeEncryptedExtensions uint8 = 8 // implemention incomplete by crypto/tls
 	// https://datatracker.ietf.org/doc/html/rfc8879#section-7.2
-	typeCompressedCertificate uint8 = 25
+	utlsTypeCompressedCertificate uint8 = 25
 )
 
 // TLS
 const (
 	utlsExtensionPadding              uint16 = 21
-	utlsExtensionExtendedMasterSecret uint16 = 23 // https://tools.ietf.org/html/rfc7627
-
-	// https://datatracker.ietf.org/doc/html/rfc8879#section-7.1
-	utlsExtensionCompressCertificate uint16 = 27
+	utlsExtensionExtendedMasterSecret uint16 = 23    // https://tools.ietf.org/html/rfc7627
+	utlsExtensionCompressCertificate  uint16 = 27    // https://datatracker.ietf.org/doc/html/rfc8879#section-7.1
+	utlsExtensionApplicationSettings  uint16 = 17513 // not IANA assigned
 
 	// extensions with 'fake' prefix break connection, if server echoes them back
 	fakeExtensionTokenBinding         uint16 = 24
 	fakeOldExtensionChannelID         uint16 = 30031 // not IANA assigned
 	fakeExtensionChannelID            uint16 = 30032 // not IANA assigned
-	fakeExtensionALPS                 uint16 = 17513 // not IANA assigned
 	fakeExtensionDelegatedCredentials uint16 = 34
 )
 

u_conn.go

@@ -714,9 +714,26 @@ func makeSupportedVersions(minVers, maxVers uint16) []uint16 {
 // Extending (*Conn).readHandshake() to support more customized handshake messages.
 func (c *Conn) utlsHandshakeMessageType(msgType byte) (handshakeMessage, error) {
 	switch msgType {
-	case typeCompressedCertificate:
-		return new(compressedCertificateMsg), nil
+	case utlsTypeCompressedCertificate:
+		return new(utlsCompressedCertificateMsg), nil
+	case utlsTypeEncryptedExtensions:
+		if c.isClient {
+			return new(encryptedExtensionsMsg), nil
+		} else {
+			return new(utlsClientEncryptedExtensionsMsg), nil
+		}
 	default:
 		return nil, c.in.setErrorLocked(c.sendAlert(alertUnexpectedMessage))
 	}
 }
+
+// Extending (*Conn).connectionStateLocked()
+func (c *Conn) utlsConnectionStateLocked(state *ConnectionState) {
+	state.PeerApplicationSettings = c.utls.peerApplicationSettings
+}
+
+type utlsConnExtraFields struct {
+	hasApplicationSettings   bool
+	peerApplicationSettings  []byte
+	localApplicationSettings []byte
+}

u_fingerprinter.go

@@ -335,7 +335,7 @@ func (f *Fingerprinter) FingerprintClientHello(data []byte) (*ClientHelloSpec, e
 			tokenBindingExt.KeyParameters = keyParameters
 			clientHelloSpec.Extensions = append(clientHelloSpec.Extensions, &tokenBindingExt)
 
-		case fakeExtensionALPS:
+		case utlsExtensionApplicationSettings:
 			// Similar to ALPN (RFC 7301, Section 3.1):
 			// https://datatracker.ietf.org/doc/html/draft-vvv-tls-alps#section-3
 			var protoList cryptobyte.String

u_handshake_client.go

@@ -7,6 +7,7 @@ package tls
 import (
 	"bytes"
 	"compress/zlib"
+	"errors"
 	"fmt"
 	"io"
 
@@ -14,15 +15,15 @@ import (
 	"github.com/klauspost/compress/zstd"
 )
 
-// This function is called by (*clientHandshakeStateTLS13.)readServerCertificate()
-// to retrieve the certificate out of a message read by (*Conn.)readHandshake()
+// This function is called by (*clientHandshakeStateTLS13).readServerCertificate()
+// to retrieve the certificate out of a message read by (*Conn).readHandshake()
 func (hs *clientHandshakeStateTLS13) utlsReadServerCertificate(msg any) (processedMsg any, err error) {
 	for _, ext := range hs.uconn.Extensions {
 		switch ext.(type) {
 		case *UtlsCompressCertExtension:
 			// Included Compressed Certificate extension
 			if len(hs.uconn.certCompressionAlgs) > 0 {
-				compressedCertMsg, ok := msg.(*compressedCertificateMsg)
+				compressedCertMsg, ok := msg.(*utlsCompressedCertificateMsg)
 				if ok {
 					hs.transcript.Write(compressedCertMsg.marshal())
 					msg, err = hs.decompressCert(*compressedCertMsg)
@@ -40,8 +41,8 @@ func (hs *clientHandshakeStateTLS13) utlsReadServerCertificate(msg any) (process
 	return nil, nil
 }
 
-// called by (*clientHandshakeStateTLS13.)utlsReadServerCertificate() when UtlsCompressCertExtension is used
-func (hs *clientHandshakeStateTLS13) decompressCert(m compressedCertificateMsg) (*certificateMsgTLS13, error) {
+// called by (*clientHandshakeStateTLS13).utlsReadServerCertificate() when UtlsCompressCertExtension is used
+func (hs *clientHandshakeStateTLS13) decompressCert(m utlsCompressedCertificateMsg) (*certificateMsgTLS13, error) {
 	var (
 		decompressed io.Reader
 		compressed   = bytes.NewReader(m.compressedCertificateMessage)
@@ -111,3 +112,52 @@ func (hs *clientHandshakeStateTLS13) decompressCert(m compressedCertificateMsg)
 	}
 	return certMsg, nil
 }
+
+// to be called in (*clientHandshakeStateTLS13).handshake(),
+// after hs.readServerFinished() and before hs.sendClientCertificate()
+func (hs *clientHandshakeStateTLS13) serverFinishedReceived() error {
+	if err := hs.sendClientEncryptedExtensions(); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (hs *clientHandshakeStateTLS13) sendClientEncryptedExtensions() error {
+	c := hs.c
+	clientEncryptedExtensions := new(utlsClientEncryptedExtensionsMsg)
+	if c.utls.hasApplicationSettings {
+		clientEncryptedExtensions.hasApplicationSettings = true
+		clientEncryptedExtensions.applicationSettings = c.utls.localApplicationSettings
+		hs.transcript.Write(clientEncryptedExtensions.marshal())
+		if _, err := c.writeRecord(recordTypeHandshake, clientEncryptedExtensions.marshal()); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (hs *clientHandshakeStateTLS13) utlsReadServerParameters(encryptedExtensions *encryptedExtensionsMsg) error {
+	hs.c.utls.hasApplicationSettings = encryptedExtensions.utls.hasApplicationSettings
+	hs.c.utls.peerApplicationSettings = encryptedExtensions.utls.applicationSettings
+
+	if hs.c.utls.hasApplicationSettings {
+		if hs.uconn.vers < VersionTLS13 {
+			return errors.New("tls: server sent application settings at invalid version")
+		}
+		if len(hs.uconn.clientProtocol) == 0 {
+			return errors.New("tls: server sent application settings without ALPN")
+		}
+
+		// Check if the ALPN selected by the server exists in the client's list.
+		if alps, ok := hs.uconn.config.ApplicationSettings[hs.serverHello.alpnProtocol]; ok {
+			hs.c.utls.localApplicationSettings = alps
+		} else {
+			// return errors.New("tls: server selected ALPN doesn't match a client ALPS")
+			return nil // ignore if client doesn't have ALPS in use.
+			// TODO: is this a issue or not?
+		}
+	}
+
+	return nil
+}

u_handshake_messages.go

@@ -12,7 +12,7 @@ import (
 // Alternate certificate message formats (https://datatracker.ietf.org/doc/html/rfc7250) are not
 // supported.
 // https://datatracker.ietf.org/doc/html/rfc8879
-type compressedCertificateMsg struct {
+type utlsCompressedCertificateMsg struct {
 	raw []byte
 
 	algorithm                    uint16
@@ -20,13 +20,13 @@ type compressedCertificateMsg struct {
 	compressedCertificateMessage []byte
 }
 
-func (m *compressedCertificateMsg) marshal() []byte {
+func (m *utlsCompressedCertificateMsg) marshal() []byte {
 	if m.raw != nil {
 		return m.raw
 	}
 
 	var b cryptobyte.Builder
-	b.AddUint8(typeCompressedCertificate)
+	b.AddUint8(utlsTypeCompressedCertificate)
 	b.AddUint24LengthPrefixed(func(b *cryptobyte.Builder) {
 		b.AddUint16(m.algorithm)
 		b.AddUint24(m.uncompressedLength)
@@ -39,8 +39,8 @@ func (m *compressedCertificateMsg) marshal() []byte {
 	return m.raw
 }
 
-func (m *compressedCertificateMsg) unmarshal(data []byte) bool {
-	*m = compressedCertificateMsg{raw: data}
+func (m *utlsCompressedCertificateMsg) unmarshal(data []byte) bool {
+	*m = utlsCompressedCertificateMsg{raw: data}
 	s := cryptobyte.String(data)
 
 	if !s.Skip(4) || // message type and uint24 length field
@@ -51,3 +51,76 @@ func (m *compressedCertificateMsg) unmarshal(data []byte) bool {
 	}
 	return true
 }
+
+type utlsEncryptedExtensionsMsgExtraFields struct {
+	hasApplicationSettings bool
+	applicationSettings    []byte
+	customExtension        []byte
+}
+
+func (m *encryptedExtensionsMsg) utlsUnmarshal(extension uint16, extData cryptobyte.String) bool {
+	switch extension {
+	case utlsExtensionApplicationSettings:
+		m.utls.hasApplicationSettings = true
+		m.utls.applicationSettings = []byte(extData)
+	}
+	return true // success/unknown extension
+}
+
+type utlsClientEncryptedExtensionsMsg struct {
+	raw                    []byte
+	applicationSettings    []byte
+	hasApplicationSettings bool
+}
+
+func (m *utlsClientEncryptedExtensionsMsg) marshal() (x []byte) {
+	if m.raw != nil {
+		return m.raw
+	}
+
+	var builder cryptobyte.Builder
+	builder.AddUint8(typeEncryptedExtensions)
+	builder.AddUint24LengthPrefixed(func(body *cryptobyte.Builder) {
+		body.AddUint16LengthPrefixed(func(extensions *cryptobyte.Builder) {
+			if m.hasApplicationSettings {
+				extensions.AddUint16(utlsExtensionApplicationSettings)
+				extensions.AddUint16LengthPrefixed(func(msg *cryptobyte.Builder) {
+					msg.AddBytes(m.applicationSettings)
+				})
+			}
+		})
+	})
+
+	m.raw = builder.BytesOrPanic()
+	return m.raw
+}
+
+func (m *utlsClientEncryptedExtensionsMsg) unmarshal(data []byte) bool {
+	*m = utlsClientEncryptedExtensionsMsg{raw: data}
+	s := cryptobyte.String(data)
+
+	var extensions cryptobyte.String
+	if !s.Skip(4) || // message type and uint24 length field
+		!s.ReadUint16LengthPrefixed(&extensions) || !s.Empty() {
+		return false
+	}
+
+	for !extensions.Empty() {
+		var extension uint16
+		var extData cryptobyte.String
+		if !extensions.ReadUint16(&extension) ||
+			!extensions.ReadUint16LengthPrefixed(&extData) {
+			return false
+		}
+
+		switch extension {
+		case utlsExtensionApplicationSettings:
+			m.hasApplicationSettings = true
+			m.applicationSettings = []byte(extData)
+		default:
+			// Unknown extensions are illegal in EncryptedExtensions.
+			return false
+		}
+	}
+	return true
+}

u_tls_extensions.go

@@ -356,17 +356,9 @@ func (e *ALPNExtension) Read(b []byte) (int, error) {
 	return e.Len(), io.EOF
 }
 
-// ApplicationSettingsExtension represents the TLS ALPS extension. At the time
-// of this writing, this extension is currently a draft:
+// ApplicationSettingsExtension represents the TLS ALPS extension.
+// At the time of this writing, this extension is currently a draft:
 // https://datatracker.ietf.org/doc/html/draft-vvv-tls-alps-01
-//
-// This library does not offer actual support for ALPS. This extension is
-// "faked" - it is advertised by the client, but not respected if the server
-// responds with support.
-//
-// In the normal convention of this library, this type name would be prefixed
-// with 'Fake'. The existing name is retained for backwards compatibility
-// reasons.
 type ApplicationSettingsExtension struct {
 	SupportedProtocols []string
 }
@@ -389,8 +381,8 @@ func (e *ApplicationSettingsExtension) Read(b []byte) (int, error) {
 	}
 
 	// Read Type.
-	b[0] = byte(fakeExtensionALPS >> 8)   // hex: 44 dec: 68
-	b[1] = byte(fakeExtensionALPS & 0xff) // hex: 69 dec: 105
+	b[0] = byte(utlsExtensionApplicationSettings >> 8)   // hex: 44 dec: 68
+	b[1] = byte(utlsExtensionApplicationSettings & 0xff) // hex: 69 dec: 105
 
 	lengths := b[2:] // get the remaining buffer without Type
 	b = b[6:]        // set the buffer to the buffer without Type, Length and ALPS Extension Length (so only the Supported ALPN list remains)