Add Network.framework TLS engine

cmd/internal/update_certificates/main.go

@@ -5,6 +5,7 @@ import (
 	"io"
 	"net/http"
 	"os"
+	"path/filepath"
 	"strings"
 
 	"github.com/sagernet/sing-box/log"
@@ -35,21 +36,9 @@ func updateMozillaIncludedRootCAs() error {
 		return err
 	}
 	geoIndex := slices.Index(header, "Geographic Focus")
-	nameIndex := slices.Index(header, "Common Name or Certificate Name")
 	certIndex := slices.Index(header, "PEM Info")
 
-	generated := strings.Builder{}
-	generated.WriteString(`// Code generated by 'make update_certificates'. DO NOT EDIT.
-
-package certificate
-
-import "crypto/x509"
-
-var mozillaIncluded *x509.CertPool
-
-func init() {
-	mozillaIncluded = x509.NewCertPool()
-`)
+	pemBundle := strings.Builder{}
 	for {
 		record, err := reader.Read()
 		if err == io.EOF {
@@ -60,18 +49,12 @@ func init() {
 		if record[geoIndex] == "China" {
 			continue
 		}
-		generated.WriteString("\n	// ")
-		generated.WriteString(record[nameIndex])
-		generated.WriteString("\n")
-		generated.WriteString("	mozillaIncluded.AppendCertsFromPEM([]byte(`")
 		cert := record[certIndex]
-		// Remove single quotes
 		cert = cert[1 : len(cert)-1]
-		generated.WriteString(cert)
-		generated.WriteString("`))\n")
+		pemBundle.WriteString(cert)
+		pemBundle.WriteString("\n")
 	}
-	generated.WriteString("}\n")
-	return os.WriteFile("common/certificate/mozilla.go", []byte(generated.String()), 0o644)
+	return writeGeneratedCertificateBundle("mozilla", "mozillaIncluded", pemBundle.String())
 }
 
 func fetchChinaFingerprints() (map[string]bool, error) {
@@ -119,23 +102,11 @@ func updateChromeIncludedRootCAs() error {
 	if err != nil {
 		return err
 	}
-	subjectIndex := slices.Index(header, "Subject")
 	statusIndex := slices.Index(header, "Google Chrome Status")
 	certIndex := slices.Index(header, "X.509 Certificate (PEM)")
 	fingerprintIndex := slices.Index(header, "SHA-256 Fingerprint")
 
-	generated := strings.Builder{}
-	generated.WriteString(`// Code generated by 'make update_certificates'. DO NOT EDIT.
-
-package certificate
-
-import "crypto/x509"
-
-var chromeIncluded *x509.CertPool
-
-func init() {
-	chromeIncluded = x509.NewCertPool()
-`)
+	pemBundle := strings.Builder{}
 	for {
 		record, err := reader.Read()
 		if err == io.EOF {
@@ -149,18 +120,39 @@ func init() {
 		if chinaFingerprints[record[fingerprintIndex]] {
 			continue
 		}
-		generated.WriteString("\n	// ")
-		generated.WriteString(record[subjectIndex])
-		generated.WriteString("\n")
-		generated.WriteString("	chromeIncluded.AppendCertsFromPEM([]byte(`")
 		cert := record[certIndex]
-		// Remove single quotes if present
 		if len(cert) > 0 && cert[0] == '\'' {
 			cert = cert[1 : len(cert)-1]
 		}
-		generated.WriteString(cert)
-		generated.WriteString("`))\n")
+		pemBundle.WriteString(cert)
+		pemBundle.WriteString("\n")
 	}
-	generated.WriteString("}\n")
-	return os.WriteFile("common/certificate/chrome.go", []byte(generated.String()), 0o644)
+	return writeGeneratedCertificateBundle("chrome", "chromeIncluded", pemBundle.String())
+}
+
+func writeGeneratedCertificateBundle(name string, variableName string, pemBundle string) error {
+	goSource := `// Code generated by 'make update_certificates'. DO NOT EDIT.
+
+package certificate
+
+import (
+	"crypto/x509"
+	_ "embed"
+)
+
+//go:embed ` + name + `.pem
+var ` + variableName + `PEM string
+
+var ` + variableName + ` *x509.CertPool
+
+func init() {
+	` + variableName + ` = x509.NewCertPool()
+	` + variableName + `.AppendCertsFromPEM([]byte(` + variableName + `PEM))
+}
+`
+	err := os.WriteFile(filepath.Join("common/certificate", name+".pem"), []byte(pemBundle), 0o644)
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(filepath.Join("common/certificate", name+".go"), []byte(goSource), 0o644)
 }

common/certificate/store.go

@@ -22,8 +22,10 @@ var _ adapter.CertificateStore = (*Store)(nil)
 
 type Store struct {
 	access                    sync.RWMutex
+	store                     string
 	systemPool                *x509.CertPool
 	currentPool               *x509.CertPool
+	currentPEM                []string
 	certificate               string
 	certificatePaths          []string
 	certificateDirectoryPaths []string
@@ -61,6 +63,7 @@ func NewStore(ctx context.Context, logger logger.Logger, options option.Certific
 		return nil, E.New("unknown certificate store: ", options.Store)
 	}
 	store := &Store{
+		store:                     options.Store,
 		systemPool:                systemPool,
 		certificate:               strings.Join(options.Certificate, "\n"),
 		certificatePaths:          options.CertificatePath,
@@ -123,19 +126,37 @@ func (s *Store) Pool() *x509.CertPool {
 	return s.currentPool
 }
 
+func (s *Store) StoreKind() string {
+	return s.store
+}
+
+func (s *Store) CurrentPEM() []string {
+	s.access.RLock()
+	defer s.access.RUnlock()
+	return append([]string(nil), s.currentPEM...)
+}
+
 func (s *Store) update() error {
 	s.access.Lock()
 	defer s.access.Unlock()
 	var currentPool *x509.CertPool
+	var currentPEM []string
 	if s.systemPool == nil {
 		currentPool = x509.NewCertPool()
 	} else {
 		currentPool = s.systemPool.Clone()
 	}
+	switch s.store {
+	case C.CertificateStoreMozilla:
+		currentPEM = append(currentPEM, mozillaIncludedPEM)
+	case C.CertificateStoreChrome:
+		currentPEM = append(currentPEM, chromeIncludedPEM)
+	}
 	if s.certificate != "" {
 		if !currentPool.AppendCertsFromPEM([]byte(s.certificate)) {
 			return E.New("invalid certificate PEM strings")
 		}
+		currentPEM = append(currentPEM, s.certificate)
 	}
 	for _, path := range s.certificatePaths {
 		pemContent, err := os.ReadFile(path)
@@ -145,6 +166,7 @@ func (s *Store) update() error {
 		if !currentPool.AppendCertsFromPEM(pemContent) {
 			return E.New("invalid certificate PEM file: ", path)
 		}
+		currentPEM = append(currentPEM, string(pemContent))
 	}
 	var firstErr error
 	for _, directoryPath := range s.certificateDirectoryPaths {
@@ -157,8 +179,8 @@ func (s *Store) update() error {
 		}
 		for _, directoryEntry := range directoryEntries {
 			pemContent, err := os.ReadFile(filepath.Join(directoryPath, directoryEntry.Name()))
-			if err == nil {
-				currentPool.AppendCertsFromPEM(pemContent)
+			if err == nil && currentPool.AppendCertsFromPEM(pemContent) {
+				currentPEM = append(currentPEM, string(pemContent))
 			}
 		}
 	}
@@ -166,6 +188,7 @@ func (s *Store) update() error {
 		return firstErr
 	}
 	s.currentPool = currentPool
+	s.currentPEM = currentPEM
 	return nil
 }
 

common/tls/apple_client_platform_test.go

@@ -0,0 +1,205 @@
+//go:build darwin && cgo
+
+package tls
+
+import (
+	"context"
+	stdtls "crypto/tls"
+	"net"
+	"testing"
+	"time"
+
+	"github.com/sagernet/sing-box/option"
+	"github.com/sagernet/sing/common/json/badoption"
+	"github.com/sagernet/sing/common/logger"
+)
+
+const appleTLSTestTimeout = 5 * time.Second
+
+type appleTLSServerResult struct {
+	state stdtls.ConnectionState
+	err   error
+}
+
+func TestAppleClientHandshakeAppliesALPNAndVersion(t *testing.T) {
+	serverCertificate, serverCertificatePEM := newAppleTestCertificate(t, "localhost")
+	serverResult, serverAddress := startAppleTLSTestServer(t, &stdtls.Config{
+		Certificates: []stdtls.Certificate{serverCertificate},
+		MinVersion:   stdtls.VersionTLS12,
+		MaxVersion:   stdtls.VersionTLS12,
+		NextProtos:   []string{"h2"},
+	})
+
+	clientConn, err := newAppleTestClientConn(t, serverAddress, option.OutboundTLSOptions{
+		Enabled:     true,
+		Engine:      "apple",
+		ServerName:  "localhost",
+		MinVersion:  "1.2",
+		MaxVersion:  "1.2",
+		ALPN:        badoption.Listable[string]{"h2"},
+		Certificate: badoption.Listable[string]{serverCertificatePEM},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer clientConn.Close()
+
+	clientState := clientConn.ConnectionState()
+	if clientState.Version != stdtls.VersionTLS12 {
+		t.Fatalf("unexpected negotiated version: %x", clientState.Version)
+	}
+	if clientState.NegotiatedProtocol != "h2" {
+		t.Fatalf("unexpected negotiated protocol: %q", clientState.NegotiatedProtocol)
+	}
+
+	result := <-serverResult
+	if result.err != nil {
+		t.Fatal(result.err)
+	}
+	if result.state.Version != stdtls.VersionTLS12 {
+		t.Fatalf("server negotiated unexpected version: %x", result.state.Version)
+	}
+	if result.state.NegotiatedProtocol != "h2" {
+		t.Fatalf("server negotiated unexpected protocol: %q", result.state.NegotiatedProtocol)
+	}
+}
+
+func TestAppleClientHandshakeRejectsVersionMismatch(t *testing.T) {
+	serverCertificate, serverCertificatePEM := newAppleTestCertificate(t, "localhost")
+	serverResult, serverAddress := startAppleTLSTestServer(t, &stdtls.Config{
+		Certificates: []stdtls.Certificate{serverCertificate},
+		MinVersion:   stdtls.VersionTLS13,
+		MaxVersion:   stdtls.VersionTLS13,
+	})
+
+	clientConn, err := newAppleTestClientConn(t, serverAddress, option.OutboundTLSOptions{
+		Enabled:     true,
+		Engine:      "apple",
+		ServerName:  "localhost",
+		MaxVersion:  "1.2",
+		Certificate: badoption.Listable[string]{serverCertificatePEM},
+	})
+	if err == nil {
+		clientConn.Close()
+		t.Fatal("expected version mismatch handshake to fail")
+	}
+
+	if result := <-serverResult; result.err == nil {
+		t.Fatal("expected server handshake to fail on version mismatch")
+	}
+}
+
+func TestAppleClientHandshakeRejectsServerNameMismatch(t *testing.T) {
+	serverCertificate, serverCertificatePEM := newAppleTestCertificate(t, "localhost")
+	serverResult, serverAddress := startAppleTLSTestServer(t, &stdtls.Config{
+		Certificates: []stdtls.Certificate{serverCertificate},
+	})
+
+	clientConn, err := newAppleTestClientConn(t, serverAddress, option.OutboundTLSOptions{
+		Enabled:     true,
+		Engine:      "apple",
+		ServerName:  "example.com",
+		Certificate: badoption.Listable[string]{serverCertificatePEM},
+	})
+	if err == nil {
+		clientConn.Close()
+		t.Fatal("expected server name mismatch handshake to fail")
+	}
+
+	if result := <-serverResult; result.err == nil {
+		t.Fatal("expected server handshake to fail on server name mismatch")
+	}
+}
+
+func newAppleTestCertificate(t *testing.T, serverName string) (stdtls.Certificate, string) {
+	t.Helper()
+
+	privateKeyPEM, certificatePEM, err := GenerateCertificate(nil, nil, time.Now, serverName, time.Now().Add(time.Hour))
+	if err != nil {
+		t.Fatal(err)
+	}
+	certificate, err := stdtls.X509KeyPair(certificatePEM, privateKeyPEM)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return certificate, string(certificatePEM)
+}
+
+func startAppleTLSTestServer(t *testing.T, tlsConfig *stdtls.Config) (<-chan appleTLSServerResult, string) {
+	t.Helper()
+
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		listener.Close()
+	})
+
+	if tcpListener, isTCP := listener.(*net.TCPListener); isTCP {
+		err = tcpListener.SetDeadline(time.Now().Add(appleTLSTestTimeout))
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	result := make(chan appleTLSServerResult, 1)
+	go func() {
+		defer close(result)
+
+		conn, err := listener.Accept()
+		if err != nil {
+			result <- appleTLSServerResult{err: err}
+			return
+		}
+		defer conn.Close()
+
+		err = conn.SetDeadline(time.Now().Add(appleTLSTestTimeout))
+		if err != nil {
+			result <- appleTLSServerResult{err: err}
+			return
+		}
+
+		tlsConn := stdtls.Server(conn, tlsConfig)
+		defer tlsConn.Close()
+
+		err = tlsConn.Handshake()
+		if err != nil {
+			result <- appleTLSServerResult{err: err}
+			return
+		}
+
+		result <- appleTLSServerResult{state: tlsConn.ConnectionState()}
+	}()
+
+	return result, listener.Addr().String()
+}
+
+func newAppleTestClientConn(t *testing.T, serverAddress string, options option.OutboundTLSOptions) (Conn, error) {
+	t.Helper()
+
+	ctx, cancel := context.WithTimeout(context.Background(), appleTLSTestTimeout)
+	t.Cleanup(cancel)
+
+	clientConfig, err := NewClientWithOptions(ClientOptions{
+		Context:       ctx,
+		Logger:        logger.NOP(),
+		ServerAddress: "",
+		Options:       options,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	conn, err := net.DialTimeout("tcp", serverAddress, appleTLSTestTimeout)
+	if err != nil {
+		return nil, err
+	}
+
+	tlsConn, err := ClientHandshake(ctx, conn, clientConfig)
+	if err != nil {
+		conn.Close()
+		return nil, err
+	}
+	return tlsConn, nil
+}

common/tls/apple_client_stub.go

@@ -0,0 +1,15 @@
+//go:build !darwin || !cgo
+
+package tls
+
+import (
+	"context"
+
+	"github.com/sagernet/sing-box/option"
+	E "github.com/sagernet/sing/common/exceptions"
+	"github.com/sagernet/sing/common/logger"
+)
+
+func newAppleClient(ctx context.Context, logger logger.ContextLogger, serverAddress string, options option.OutboundTLSOptions, allowEmptyServerName bool) (Config, error) {
+	return nil, E.New("Apple TLS engine is not available on non-Apple platforms")
+}

common/tls/client.go

@@ -64,6 +64,13 @@ func NewClientWithOptions(options ClientOptions) (Config, error) {
 	if options.Options.KernelRx {
 		options.Logger.Warn("enabling kTLS RX will definitely reduce performance, please checkout https://sing-box.sagernet.org/configuration/shared/tls/#kernel_rx")
 	}
+	switch options.Options.Engine {
+	case "", "go":
+	case "apple":
+		return newAppleClient(options.Context, options.Logger, options.ServerAddress, options.Options, options.AllowEmptyServerName)
+	default:
+		return nil, E.New("unknown tls engine: ", options.Options.Engine)
+	}
 	if options.Options.Reality != nil && options.Options.Reality.Enabled {
 		return newRealityClient(options.Context, options.Logger, options.ServerAddress, options.Options, options.AllowEmptyServerName)
 	} else if options.Options.UTLS != nil && options.Options.UTLS.Enabled {

docs/configuration/shared/tls.md

@@ -108,6 +108,7 @@ icon: material/new-box
 ```json
 {
   "enabled": true,
+  "engine": "",
   "disable_sni": false,
   "server_name": "",
   "insecure": false,
@@ -188,6 +189,49 @@ Cipher suite values:
 
 Enable TLS.
 
+#### engine
+
+==Client only==
+
+TLS engine to use.
+
+Values:
+
+* `go`
+* `apple`
+
+`apple` uses Network.framework, only available on Apple platforms and only supports **direct** TCP TLS client connections.
+
+!!! warning ""
+
+    Experimental only: due to the high memory overhead of both CGO and Network.framework,
+    do not use in proxy paths on iOS and tvOS.
+    If you want to circumvent TLS fingerprint-based proxy censorship,
+    use [NaiveProxy](/configuration/outbound/naive/) instead.
+
+Supported fields:
+
+* `server_name`
+* `insecure`
+* `alpn`
+* `min_version`
+* `max_version`
+* `certificate` / `certificate_path`
+* `certificate_public_key_sha256`
+* `handshake_timeout`
+
+Unsupported fields:
+
+* `disable_sni`
+* `cipher_suites`
+* `curve_preferences`
+* `client_certificate` / `client_certificate_path` / `client_key` / `client_key_path`
+* `fragment` / `record_fragment`
+* `kernel_tx` / `kernel_rx`
+* `ech`
+* `utls`
+* `reality`
+
 #### disable_sni
 
 ==Client only==

docs/configuration/shared/tls.zh.md

@@ -108,6 +108,7 @@ icon: material/new-box
 ```json
 {
   "enabled": true,
+  "engine": "",
   "disable_sni": false,
   "server_name": "",
   "insecure": false,
@@ -188,6 +189,48 @@ TLS 版本值：
 
 启用 TLS
 
+#### engine
+
+==仅客户端==
+
+要使用的 TLS 引擎。
+
+可用值：
+
+* `go`
+* `apple`
+
+`apple` 使用 Network.framework，仅在 Apple 平台可用，且仅支持 **直接** TCP TLS 客户端连接。
+
+!!! warning ""
+
+    仅供实验用途：由于 CGO 和 Network.framework 占用的内存都很多，
+    不应在 iOS 和 tvOS 的代理路径中使用。
+    如果您想规避基于 TLS 指纹的代理审查，应使用 [NaiveProxy](/zh/configuration/outbound/naive/)。
+
+支持的字段：
+
+* `server_name`
+* `insecure`
+* `alpn`
+* `min_version`
+* `max_version`
+* `certificate` / `certificate_path`
+* `certificate_public_key_sha256`
+* `handshake_timeout`
+
+不支持的字段：
+
+* `disable_sni`
+* `cipher_suites`
+* `curve_preferences`
+* `client_certificate` / `client_certificate_path` / `client_key` / `client_key_path`
+* `fragment` / `record_fragment`
+* `kernel_tx` / `kernel_rx`
+* `ech`
+* `utls`
+* `reality`
+
 #### disable_sni
 
 ==仅客户端==

option/tls.go

@@ -101,6 +101,7 @@ func (o *InboundTLSOptionsContainer) ReplaceInboundTLSOptions(options *InboundTL
 
 type OutboundTLSOptions struct {
 	Enabled                    bool                                `json:"enabled,omitempty"`
+	Engine                     string                              `json:"engine,omitempty"`
 	DisableSNI                 bool                                `json:"disable_sni,omitempty"`
 	ServerName                 string                              `json:"server_name,omitempty"`
 	Insecure                   bool                                `json:"insecure,omitempty"`