Merge pull request #201 from SenseUnit/persistent_tls_ticket_cache

Persistent TLS ticket cache

Author: Snawoot

README.md

@@ -648,6 +648,8 @@ Usage of /home/user/go/bin/dumbproxy:
     	mark TLS sessions with cookie-like unique session IDs (default true)
   -tls-session-key value
     	override TLS server session keys. Key must be provided as hex-encoded 32-byte string. This option can be repeated multiple times, first key will be used to create session tickets. Empty value resets the list.
+  -tls-session-cache-db string
+    	location of TLS client session cache DB
   -trusttunnel
     	enable TrustTunnel protocol extensions (default true)
   -unix-sock-mode value

go.mod

@@ -15,6 +15,7 @@ require (
 	github.com/refraction-networking/utls v1.8.2
 	github.com/tg123/go-htpasswd v1.2.4
 	github.com/things-go/go-socks5 v0.1.0
+	go.etcd.io/bbolt v1.4.3
 	golang.org/x/crypto v0.48.0
 	golang.org/x/crypto/x509roots/fallback v0.0.0-20260213171211-a408498e5541
 	golang.org/x/net v0.51.0

go.sum

@@ -59,6 +59,8 @@ github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZ
 github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
 github.com/zeebo/xxh3 v1.0.2 h1:xZmwmqxHZA8AI603jOQ0tMqmBr9lPeFwGg6d+xy9DC0=
 github.com/zeebo/xxh3 v1.0.2/go.mod h1:5NWz9Sef7zIDm2JHfFlcQvNekmcEl9ekUZQQKCYaDcA=
+go.etcd.io/bbolt v1.4.3 h1:dEadXpI6G79deX5prL3QRNP6JB8UxVkqo4UPnHaNXJo=
+go.etcd.io/bbolt v1.4.3/go.mod h1:tKQlpPaYCVFctUIgFKFnAlvbmB3tpy1vkTnDWohtc0E=
 go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
 go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
 golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=

main.go

@@ -315,6 +315,7 @@ type CLIArgs struct {
 	tlsALPNEnabled           bool
 	tlsSessionKeys           [][32]byte
 	tlsCookies               bool
+	tlsSessionCacheDB        string
 	bwLimit                  forward.LimitSpec
 	bwBurst                  int64
 	bwSeparate               bool
@@ -507,6 +508,7 @@ func parse_args() *CLIArgs {
 		return nil
 	})
 	flag.BoolVar(&args.tlsCookies, "tls-cookies", true, "mark TLS sessions with cookie-like unique session IDs")
+	flag.StringVar(&args.tlsSessionCacheDB, "tls-session-cache-db", "", "location of TLS client session cache DB")
 	flag.Func("config", "read configuration from file with space-separated keys and values", readConfig)
 	flag.Parse()
 	// pull up remaining parameters from other BW-related arguments
@@ -617,6 +619,19 @@ func run() int {
 	tlsSessionLogger := clog.NewCondLogger(log.New(logWriter, "TLSSESS :",
 		log.LstdFlags|log.Lshortfile),
 		args.verbosity)
+	tlsCacheLogger := clog.NewCondLogger(log.New(logWriter, "TLSCACHE:",
+		log.LstdFlags|log.Lshortfile),
+		args.verbosity)
+
+	// setup TLS session cache
+	if args.tlsSessionCacheDB != "" {
+		cache, err := tlsutil.NewPersistentClientSessionCache(args.tlsSessionCacheDB, tlsCacheLogger)
+		if err != nil {
+			mainLogger.Critical("Failed to instantiate TLS session cache: %v", err)
+			return 3
+		}
+		tlsutil.SessionCache = cache
+	}
 
 	// setup auth provider
 	authProvider, err := auth.NewAuth(args.auth, authLogger)

tlsutil/ccache.go

@@ -0,0 +1,281 @@
+package tlsutil
+
+import (
+	"bytes"
+	"crypto/tls"
+	"encoding/binary"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"runtime/debug"
+	"time"
+
+	"go.etcd.io/bbolt"
+
+	clog "github.com/SenseUnit/dumbproxy/log"
+)
+
+var (
+	bucketName               = []byte("tickets")
+	currentFormatVersion     = getSessionFormatVer()
+	ErrFormatVersionMismatch = errors.New("format version mismatch")
+)
+
+func getSessionFormatVer() string {
+	bi, ok := debug.ReadBuildInfo()
+	if !ok {
+		return "unknown"
+	}
+	return bi.GoVersion
+}
+
+type sessionCacheEntry struct {
+	formatVersion string
+	ticket        []byte
+	state         []byte
+}
+
+func uintToVarintBytes(x uint) []byte {
+	buf := make([]byte, binary.MaxVarintLen64)
+	n := binary.PutUvarint(buf, uint64(x))
+	return buf[:n]
+}
+
+func (e *sessionCacheEntry) MarshalBinary() (data []byte, err error) {
+	buf := new(bytes.Buffer)
+	_, _ = buf.Write(uintToVarintBytes(uint(len(e.formatVersion))))
+	_, _ = buf.WriteString(e.formatVersion)
+	_, _ = buf.Write(uintToVarintBytes(uint(len(e.ticket))))
+	_, _ = buf.Write(e.ticket)
+	_, _ = buf.Write(uintToVarintBytes(uint(len(e.state))))
+	_, _ = buf.Write(e.state)
+	return append([]byte(nil), buf.Bytes()...), nil
+}
+
+func (e *sessionCacheEntry) UnmarshalBinary(data []byte) error {
+	r := bytes.NewReader(data)
+
+	formatVerLen, err := binary.ReadUvarint(r)
+	if err != nil {
+		return fmt.Errorf("unable to read length of format version field: %w", err)
+	}
+	formatVerBytes := make([]byte, formatVerLen)
+	_, err = io.ReadFull(r, formatVerBytes)
+	if err != nil {
+		return fmt.Errorf("unable to read format version field: %w", err)
+	}
+
+	ticketLen, err := binary.ReadUvarint(r)
+	if err != nil {
+		return fmt.Errorf("unable to read length of ticket field: %w", err)
+	}
+	ticketBytes := make([]byte, ticketLen)
+	_, err = io.ReadFull(r, ticketBytes)
+	if err != nil {
+		return fmt.Errorf("unable to read ticket field: %w", err)
+	}
+
+	stateLen, err := binary.ReadUvarint(r)
+	if err != nil {
+		return fmt.Errorf("unable to read length of state field: %w", err)
+	}
+	stateBytes := make([]byte, stateLen)
+	_, err = io.ReadFull(r, stateBytes)
+	if err != nil {
+		return fmt.Errorf("unable to read state field: %w", err)
+	}
+
+	e.formatVersion = string(formatVerBytes)
+	e.ticket = ticketBytes
+	e.state = stateBytes
+
+	return nil
+}
+
+func clientSessionStateToBytes(cs *tls.ClientSessionState) ([]byte, error) {
+	ticket, state, err := cs.ResumptionState()
+	if err != nil {
+		return nil, err
+	}
+	stateBytes, err := state.Bytes()
+	if err != nil {
+		return nil, err
+	}
+	return (&sessionCacheEntry{
+		formatVersion: currentFormatVersion,
+		ticket:        ticket,
+		state:         stateBytes,
+	}).MarshalBinary()
+}
+
+func clientSessionStateFromBytes(data []byte) (*tls.ClientSessionState, error) {
+	sce := new(sessionCacheEntry)
+	err := sce.UnmarshalBinary(data)
+	if err != nil {
+		return nil, fmt.Errorf("TLS session state unmarshaling failed: %w", err)
+	}
+	if sce.formatVersion != currentFormatVersion {
+		return nil, ErrFormatVersionMismatch
+	}
+	ss, err := tls.ParseSessionState(sce.state)
+	if err != nil {
+		return nil, fmt.Errorf("unable to parse TLS client session state: %w", err)
+	}
+	cs, err := tls.NewResumptionState(sce.ticket, ss)
+	if err != nil {
+		return nil, fmt.Errorf("unable to construct new resumption state: %w", err)
+	}
+	return cs, nil
+}
+
+var SessionCache tls.ClientSessionCache = tls.NewLRUClientSessionCache(0)
+
+type PersistentClientSessionCache struct {
+	db     *bbolt.DB
+	logger *clog.CondLogger
+}
+
+func NewPersistentClientSessionCache(path string, logger *clog.CondLogger) (*PersistentClientSessionCache, error) {
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0700); err != nil {
+		return nil, err
+	}
+	db, err := bbolt.Open(path, 0600, &bbolt.Options{
+		Timeout: 5 * time.Second,
+		Logger:  bboltLogger{logger},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &PersistentClientSessionCache{
+		db:     db,
+		logger: logger,
+	}, nil
+}
+
+func (cache *PersistentClientSessionCache) Get(sessionKey string) (*tls.ClientSessionState, bool) {
+	var data []byte
+	err := cache.db.View(func(tx *bbolt.Tx) error {
+		bucket := tx.Bucket(bucketName)
+		if bucket == nil {
+			return nil
+		}
+		data = bucket.Get([]byte(sessionKey))
+		return nil
+	})
+	if err != nil {
+		cache.logger.Error("cache db: key %q read failed: %v", err)
+		return nil, false
+	}
+	if data == nil {
+		return nil, false
+	}
+	cs, err := clientSessionStateFromBytes(data)
+	if err != nil {
+		if err == ErrFormatVersionMismatch {
+			cache.logger.Debug("rejected cached ticket for key %q due to version mismatch", sessionKey)
+		} else {
+			cache.logger.Error("cached session recovery failed: %v", err)
+		}
+	}
+	return cs, true
+}
+
+func (cache *PersistentClientSessionCache) delete(sessionKey string) {
+	err := cache.db.Update(func(tx *bbolt.Tx) error {
+		if bucket := tx.Bucket(bucketName); bucket != nil {
+			return bucket.Delete([]byte(sessionKey))
+		}
+		return nil
+	})
+	if err != nil {
+		cache.logger.Error("cache db: key %q delete failed: %v", sessionKey, err)
+	}
+}
+
+func (cache *PersistentClientSessionCache) put(sessionKey string, cs *tls.ClientSessionState) {
+	csBytes, err := clientSessionStateToBytes(cs)
+	if err != nil {
+		cache.logger.Error("dropping client session state with key %q: unable to marshal client session state: %v", sessionKey, err)
+		return
+	}
+	err = cache.db.Update(func(tx *bbolt.Tx) error {
+		if bucket, err := tx.CreateBucketIfNotExists(bucketName); err == nil {
+			return bucket.Put([]byte(sessionKey), csBytes)
+		} else {
+			return err
+		}
+	})
+	if err != nil {
+		cache.logger.Error("cache db: key %q write failed: %v", sessionKey, err)
+	}
+}
+
+func (cache *PersistentClientSessionCache) Put(sessionKey string, cs *tls.ClientSessionState) {
+	if cs == nil {
+		cache.delete(sessionKey)
+		return
+	} else {
+		cache.put(sessionKey, cs)
+	}
+}
+
+type bboltLogger struct {
+	l *clog.CondLogger
+}
+
+func (l bboltLogger) Debug(v ...interface{}) {
+	l.l.Debug("%s", fmt.Sprint(v...))
+}
+
+func (l bboltLogger) Debugf(format string, v ...interface{}) {
+	l.l.Debug(format, v...)
+}
+
+func (l bboltLogger) Error(v ...interface{}) {
+	l.l.Error("%s", fmt.Sprint(v...))
+}
+
+func (l bboltLogger) Errorf(format string, v ...interface{}) {
+	l.l.Error(format, v...)
+}
+
+func (l bboltLogger) Info(v ...interface{}) {
+	l.l.Info("%s", fmt.Sprint(v...))
+}
+
+func (l bboltLogger) Infof(format string, v ...interface{}) {
+	l.l.Info(format, v...)
+}
+
+func (l bboltLogger) Warning(v ...interface{}) {
+	l.l.Warning("%s", fmt.Sprint(v...))
+}
+
+func (l bboltLogger) Warningf(format string, v ...interface{}) {
+	l.l.Warning(format, v...)
+}
+
+func (l bboltLogger) Fatal(v ...interface{}) {
+	l.l.Critical("%s", fmt.Sprint(v...))
+	os.Exit(1)
+}
+
+func (l bboltLogger) Fatalf(format string, v ...interface{}) {
+	l.l.Critical(format, v...)
+	os.Exit(1)
+}
+
+func (l bboltLogger) Panic(v ...interface{}) {
+	s := fmt.Sprint(v...)
+	l.l.Critical("%s", s)
+	panic(s)
+}
+
+func (l bboltLogger) Panicf(format string, v ...interface{}) {
+	s := fmt.Sprintf(format, v...)
+	l.l.Critical("%s", s)
+	panic(s)
+}

tlsutil/util.go

@@ -12,8 +12,6 @@ import (
 	utls "github.com/refraction-networking/utls"
 )
 
-var sessionCache = tls.NewLRUClientSessionCache(0)
-
 func ExpectPeerName(name string, roots *x509.CertPool) func(cs tls.ConnectionState) error {
 	return func(cs tls.ConnectionState) error {
 		opts := x509.VerifyOptions{
@@ -173,7 +171,7 @@ func TLSConfigFromURL(u *url.URL) (*tls.Config, error) {
 	}
 	tlsConfig := &tls.Config{
 		ServerName:         host,
-		ClientSessionCache: sessionCache,
+		ClientSessionCache: SessionCache,
 	}
 	if params.Has("cafile") {
 		roots, err := LoadCAfile(params.Get("cafile"))