Add support for protocol 3.2

This adds support for the 3.2 protocol version, introduced with
PostgreSQL 18.

It follows postgres in the sense that the default is still 3.0, but this
allows for allocations to allow the 3.2 version of the protocol with
longer secret key data.

This is to both improve security and to provide room for additional
metadata for middleware.

Signed-off-by: Dirkjan Bussink <d.bussink@gmail.com>

Author: dbussink

conn.go

@@ -174,11 +174,12 @@ type conn struct {
 	// (ErrBadConn) or getForNext().
 	err syncErr
 
-	processID, secretKey int                 // Cancellation key data for use with CancelRequest messages.
-	inCopy               bool                // If true this connection is in the middle of a COPY
-	noticeHandler        func(*Error)        // If not nil, notices will be synchronously sent here
-	notificationHandler  func(*Notification) // If not nil, notifications will be synchronously sent here
-	gss                  GSS                 // GSSAPI context
+	processID           int                 // Cancellation key data for use with CancelRequest messages.
+	secretKey           []byte              //
+	inCopy              bool                // If true this connection is in the middle of a COPY
+	noticeHandler       func(*Error)        // If not nil, notices will be synchronously sent here
+	notificationHandler func(*Notification) // If not nil, notifications will be synchronously sent here
+	gss                 GSS                 // GSSAPI context
 }
 
 type syncErr struct {
@@ -1186,7 +1187,11 @@ func (cn *conn) ssl(cfg Config) error {
 
 func (cn *conn) startup(cfg Config) error {
 	w := cn.writeBuf(0)
-	w.int32(proto.ProtocolVersion30)
+	maxProto, err := parseProtocolVersion(cfg.MaxProtocolVersion)
+	if err != nil {
+		return err
+	}
+	w.int32(maxProto)
 
 	w.string("user")
 	w.string(cfg.User)
@@ -1227,6 +1232,16 @@ func (cn *conn) startup(cfg Config) error {
 			if err != nil {
 				return err
 			}
+		case proto.NegotiateProtocolVersion:
+			newestMinor := r.int32()
+			serverVersion := proto.ProtocolVersion30&0xFFFF0000 | newestMinor
+			minProto, err := parseProtocolVersion(cfg.MinProtocolVersion)
+			if err != nil {
+				return err
+			}
+			if serverVersion < minProto {
+				return fmt.Errorf("pq: server does not support minimum protocol version (server newest minor: %d)", newestMinor)
+			}
 		case proto.ReadyForQuery:
 			cn.processReadyForQuery(r)
 			return nil
@@ -1561,7 +1576,8 @@ func (cn *conn) readReadyForQuery() error {
 
 func (cn *conn) processBackendKeyData(r *readBuf) {
 	cn.processID = r.int32()
-	cn.secretKey = r.int32()
+	cn.secretKey = make([]byte, len(*r))
+	copy(cn.secretKey, *r)
 }
 
 func (cn *conn) readParseResponse() error {

conn_go18.go

@@ -152,7 +152,7 @@ func (cn *conn) cancel(ctx context.Context) error {
 	w := cn2.writeBuf(0)
 	w.int32(proto.CancelRequestCode)
 	w.int32(cn.processID)
-	w.int32(cn.secretKey)
+	w.bytes(cn.secretKey)
 	if err := cn2.sendStartupPacket(w); err != nil {
 		return err
 	}

connector.go

@@ -19,6 +19,7 @@ import (
 	"unicode"
 
 	"github.com/lib/pq/internal/pqutil"
+	"github.com/lib/pq/internal/proto"
 )
 
 type (
@@ -110,6 +111,11 @@ const (
 
 var loadBalanceHosts = []LoadBalanceHosts{LoadBalanceHostsDisable, LoadBalanceHostsRandom}
 
+const (
+	defaultMinProtocolVersion = "3.0"
+	defaultMaxProtocolVersion = "3.0"
+)
+
 // Connector represents a fixed configuration for the pq driver with a given
 // dsn. Connector satisfies the [database/sql/driver.Connector] interface and
 // can be used to create any number of DB Conn's via [sql.OpenDB].
@@ -303,6 +309,15 @@ type Config struct {
 	// to the same server.
 	LoadBalanceHosts LoadBalanceHosts `postgres:"load_balance_hosts" env:"PGLOADBALANCEHOSTS"`
 
+	// Minimum acceptable PostgreSQL protocol version. If the server does not
+	// support at least this version, the connection will fail. Valid values:
+	// "3.0", "3.2", "latest". Defaults to "3.0".
+	MinProtocolVersion string `postgres:"min_protocol_version" env:"PGMINPROTOCOLVERSION"`
+
+	// Maximum PostgreSQL protocol version to request from the server. Valid
+	// values: "3.0", "3.2", "latest". Defaults to "3.0".
+	MaxProtocolVersion string `postgres:"max_protocol_version" env:"PGMAXPROTOCOLVERSION"`
+
 	// Runtime parameters: any unrecognized parameter in the DSN will be added
 	// to this and sent to PostgreSQL during startup.
 	Runtime map[string]string `postgres:"-" env:"-"`
@@ -487,9 +502,40 @@ func newConfig(dsn string, env []string) (Config, error) {
 		cfg.SSLMode = SSLModeDisable
 	}
 
+	// Default protocol versions.
+	if cfg.MinProtocolVersion == "" {
+		cfg.MinProtocolVersion = defaultMinProtocolVersion
+	}
+	if cfg.MaxProtocolVersion == "" {
+		cfg.MaxProtocolVersion = defaultMaxProtocolVersion
+	}
+	minProto, err := parseProtocolVersion(cfg.MinProtocolVersion)
+	if err != nil {
+		return Config{}, err
+	}
+	maxProto, err := parseProtocolVersion(cfg.MaxProtocolVersion)
+	if err != nil {
+		return Config{}, err
+	}
+	if minProto > maxProto {
+		return Config{}, fmt.Errorf("pq: min_protocol_version %q cannot be greater than max_protocol_version %q",
+			cfg.MinProtocolVersion, cfg.MaxProtocolVersion)
+	}
+
 	return cfg, nil
 }
 
+func parseProtocolVersion(s string) (int, error) {
+	switch s {
+	case "", "3.0":
+		return proto.ProtocolVersion30, nil
+	case "3.2", "latest":
+		return proto.ProtocolVersion32, nil
+	default:
+		return 0, fmt.Errorf("pq: invalid protocol version: %q", s)
+	}
+}
+
 func (cfg Config) network() (string, string) {
 	if cfg.Hostaddr != (netip.Addr{}) {
 		return "tcp", net.JoinHostPort(cfg.Hostaddr.String(), strconv.Itoa(int(cfg.Port)))
@@ -514,7 +560,7 @@ func (cfg *Config) fromEnv(env []string) error {
 		case "PGREQUIREAUTH", "PGCHANNELBINDING", "PGSERVICE", "PGSERVICEFILE", "PGREALM",
 			"PGSSLCERTMODE", "PGSSLCOMPRESSION", "PGREQUIRESSL", "PGSSLCRL", "PGREQUIREPEER",
 			"PGSYSCONFDIR", "PGLOCALEDIR", "PGSSLCRLDIR", "PGSSLMINPROTOCOLVERSION", "PGSSLMAXPROTOCOLVERSION",
-			"PGGSSENCMODE", "PGGSSDELEGATION", "PGMINPROTOCOLVERSION", "PGMAXPROTOCOLVERSION", "PGGSSLIB":
+			"PGGSSENCMODE", "PGGSSDELEGATION", "PGGSSLIB":
 			return fmt.Errorf("pq: environment variable $%s is not supported", k)
 		case "PGKRBSRVNAME":
 			if newGss == nil {
@@ -654,6 +700,8 @@ func (cfg *Config) setFromTag(o map[string]string, tag string) error {
 			sslnegotiation     = (tag == "postgres" && k == "sslnegotiation") || (tag == "env" && k == "PGSSLNEGOTIATION")
 			targetsessionattrs = (tag == "postgres" && k == "target_session_attrs") || (tag == "env" && k == "PGTARGETSESSIONATTRS")
 			loadbalancehosts   = (tag == "postgres" && k == "load_balance_hosts") || (tag == "env" && k == "PGLOADBALANCEHOSTS")
+			minprotocolversion = (tag == "postgres" && k == "min_protocol_version") || (tag == "env" && k == "PGMINPROTOCOLVERSION")
+			maxprotocolversion = (tag == "postgres" && k == "max_protocol_version") || (tag == "env" && k == "PGMAXPROTOCOLVERSION")
 		)
 		if k == "" || k == "-" {
 			continue
@@ -706,6 +754,9 @@ func (cfg *Config) setFromTag(o map[string]string, tag string) error {
 				if loadbalancehosts && !slices.Contains(loadBalanceHosts, LoadBalanceHosts(v)) {
 					return fmt.Errorf(f+`%q is not supported; supported values are %s`, k, v, pqutil.Join(loadBalanceHosts))
 				}
+				if (minprotocolversion || maxprotocolversion) && v != "3.0" && v != "3.2" && v != "latest" {
+					return fmt.Errorf(f+`%q is not supported; supported values are "3.0", "3.2", "latest"`, k, v)
+				}
 				if host {
 					vv := strings.Split(v, ",")
 					v = vv[0]
@@ -835,7 +886,7 @@ func (cfg Config) string() string {
 		switch k {
 		case "datestyle", "client_encoding":
 			continue
-		case "host", "port", "user", "sslsni":
+		case "host", "port", "user", "sslsni", "min_protocol_version", "max_protocol_version":
 			if !cfg.isset(k) {
 				continue
 			}

connector_test.go

@@ -415,6 +415,19 @@ func TestNewConfig(t *testing.T) {
 		{"host=a,b,c hostaddr=1.1.1.1,2.2.2.2", nil, "", "could not match 3 host names to 2 hostaddr values"},
 		{"host=a hostaddr=1.1.1.1,2.2.2.2", nil, "", "could not match 1 host names to 2 hostaddr values"},
 		{"", []string{"PGHOST=a,,b", "PGHOSTADDR=1.1.1.1,,2.2.2.2", "PGPORT=3,,4"}, "host=a,localhost,b hostaddr=1.1.1.1,,2.2.2.2 port=3,5432,4", ""},
+
+		// Protocol version
+		{"min_protocol_version=3.0", nil, "min_protocol_version=3.0", ""},
+		{"max_protocol_version=3.2", nil, "max_protocol_version=3.2", ""},
+		{"min_protocol_version=3.2 max_protocol_version=3.2", nil, "max_protocol_version=3.2 min_protocol_version=3.2", ""},
+		{"min_protocol_version=latest max_protocol_version=latest", nil, "max_protocol_version=latest min_protocol_version=latest", ""},
+		{"min_protocol_version=3.0 max_protocol_version=latest", nil, "max_protocol_version=latest min_protocol_version=3.0", ""},
+		{"", []string{"PGMINPROTOCOLVERSION=3.0", "PGMAXPROTOCOLVERSION=3.2"}, "max_protocol_version=3.2 min_protocol_version=3.0", ""},
+		{"min_protocol_version=bogus", nil, "", `pq: wrong value for "min_protocol_version": "bogus" is not supported`},
+		{"max_protocol_version=bogus", nil, "", `pq: wrong value for "max_protocol_version": "bogus" is not supported`},
+		{"", []string{"PGMINPROTOCOLVERSION=bogus"}, "", `pq: wrong value for $PGMINPROTOCOLVERSION: "bogus" is not supported`},
+		{"", []string{"PGMAXPROTOCOLVERSION=bogus"}, "", `pq: wrong value for $PGMAXPROTOCOLVERSION: "bogus" is not supported`},
+		{"min_protocol_version=3.2 max_protocol_version=3.0", nil, "", `min_protocol_version "3.2" cannot be greater than max_protocol_version "3.0"`},
 	}
 
 	t.Parallel()
@@ -723,3 +736,95 @@ func TestConnectionTargetSessionAttrs(t *testing.T) {
 		})
 	}
 }
+
+func TestProtocolVersion32(t *testing.T) {
+	t.Run("BackendKeyData", func(t *testing.T) {
+		t.Parallel()
+
+		f := pqtest.NewFake(t, func(f pqtest.Fake, cn net.Conn) {
+			if _, ok := f.ReadStartup(cn); !ok {
+				return
+			}
+			f.WriteMsg(cn, proto.AuthenticationRequest, "\x00\x00\x00\x00")
+			f.WriteBackendKeyData(cn, 12345, make([]byte, 32))
+			f.WriteMsg(cn, proto.ReadyForQuery, "I")
+			for {
+				code, _, ok := f.ReadMsg(cn)
+				if !ok {
+					return
+				}
+				switch code {
+				case proto.Query:
+					f.WriteMsg(cn, proto.EmptyQueryResponse, "")
+					f.WriteMsg(cn, proto.ReadyForQuery, "I")
+				case proto.Terminate:
+					cn.Close()
+					return
+				}
+			}
+		})
+		defer f.Close()
+
+		db := pqtest.MustDB(t, f.DSN()+" max_protocol_version=3.2")
+		if err := db.Ping(); err != nil {
+			t.Fatal(err)
+		}
+	})
+
+	t.Run("NegotiateProtocolVersion accepted", func(t *testing.T) {
+		t.Parallel()
+
+		f := pqtest.NewFake(t, func(f pqtest.Fake, cn net.Conn) {
+			if _, ok := f.ReadStartup(cn); !ok {
+				return
+			}
+			f.WriteMsg(cn, proto.AuthenticationRequest, "\x00\x00\x00\x00")
+			// Server says it only supports minor version 0 (i.e. 3.0).
+			f.WriteNegotiateProtocolVersion(cn, 0, nil)
+			f.WriteMsg(cn, proto.ReadyForQuery, "I")
+			for {
+				code, _, ok := f.ReadMsg(cn)
+				if !ok {
+					return
+				}
+				switch code {
+				case proto.Query:
+					f.WriteMsg(cn, proto.EmptyQueryResponse, "")
+					f.WriteMsg(cn, proto.ReadyForQuery, "I")
+				case proto.Terminate:
+					cn.Close()
+					return
+				}
+			}
+		})
+		defer f.Close()
+
+		// min=3.0, max=3.2: server negotiates down to 3.0, which is >= min, so OK.
+		db := pqtest.MustDB(t, f.DSN()+" min_protocol_version=3.0 max_protocol_version=3.2")
+		if err := db.Ping(); err != nil {
+			t.Fatal(err)
+		}
+	})
+
+	t.Run("NegotiateProtocolVersion rejected", func(t *testing.T) {
+		t.Parallel()
+
+		f := pqtest.NewFake(t, func(f pqtest.Fake, cn net.Conn) {
+			if _, ok := f.ReadStartup(cn); !ok {
+				return
+			}
+			f.WriteMsg(cn, proto.AuthenticationRequest, "\x00\x00\x00\x00")
+			// Server says it only supports minor version 0 (i.e. 3.0).
+			f.WriteNegotiateProtocolVersion(cn, 0, nil)
+			// Client will disconnect; don't try to read further.
+		})
+		defer f.Close()
+
+		// min=3.2, max=3.2: server negotiates down to 3.0, which is < min, so error.
+		db := pqtest.MustDB(t, f.DSN()+" min_protocol_version=3.2 max_protocol_version=3.2")
+		err := db.Ping()
+		if !pqtest.ErrorContains(err, "server does not support minimum protocol version") {
+			t.Fatalf("wrong error\nhave: %v\nwant: server does not support minimum protocol version", err)
+		}
+	})
+}

internal/pqtest/fake.go

@@ -246,3 +246,24 @@ func (f Fake) SimpleQuery(cn net.Conn, tag string, values ...any) {
 
 	f.WriteMsg(cn, proto.CommandComplete, tag+"\x00")
 }
+
+// WriteBackendKeyData sends a BackendKeyData message with the given process ID
+// and secret key (variable length).
+func (f Fake) WriteBackendKeyData(cn net.Conn, pid int, secretKey []byte) {
+	b := make([]byte, 4+len(secretKey))
+	binary.BigEndian.PutUint32(b[0:4], uint32(pid))
+	copy(b[4:], secretKey)
+	f.WriteMsg(cn, proto.BackendKeyData, string(b))
+}
+
+// WriteNegotiateProtocolVersion sends a NegotiateProtocolVersion message.
+func (f Fake) WriteNegotiateProtocolVersion(cn net.Conn, newestMinor int, options []string) {
+	b := make([]byte, 8)
+	binary.BigEndian.PutUint32(b[0:4], uint32(newestMinor))
+	binary.BigEndian.PutUint32(b[4:8], uint32(len(options)))
+	for _, o := range options {
+		b = append(b, o...)
+		b = append(b, 0)
+	}
+	f.WriteMsg(cn, proto.NegotiateProtocolVersion, string(b))
+}

internal/proto/proto.go

@@ -10,7 +10,7 @@ import (
 // Constants from pqcomm.h
 const (
 	ProtocolVersion30 = (3 << 16) | 0 //lint:ignore SA4016 x
-	ProtocolVersion32 = (3 << 16) | 2 // PostgreSQL ≥18; not yet supported.
+	ProtocolVersion32 = (3 << 16) | 2 // PostgreSQL ≥18.
 	CancelRequestCode = (1234 << 16) | 5678
 	NegotiateSSLCode  = (1234 << 16) | 5679
 	NegotiateGSSCode  = (1234 << 16) | 5680