pgconn: document secure connection configuration

Add a "Connecting Securely" section to the package doc showing a
hardened connection string (sslmode=verify-full, channel_binding=require,
require_auth=scram-sha-256) and explaining what each parameter protects
against.

Also expand the ParseConfig "Important Security Notes" to call out that
servicefile, passfile, sslkey, sslcert, and sslrootcert read files from
the local filesystem, and to point at ParseConfigWithOptions with
ConnStringAllowedKeys for connection strings built from untrusted input.

Documentation only; no functional change.

Co-Authored-By: Jack Christensen <jack@jackchristensen.com>

Author: sean-

pgconn/config.go

@@ -293,6 +293,15 @@ func NetworkAddress(host string, port uint16) (network, address string) {
 // changed later but the unencrypted fallback is present. Ensure there are no stale fallbacks when manually setting
 // TLSConfig.
 //
+// Several connection parameters cause ParseConfig to read files from the local filesystem: servicefile, passfile,
+// sslkey, sslcert, and sslrootcert. Applications that build connection strings from untrusted input must not allow
+// these keys to be set by that input. In particular, servicefile (which pgconn accepts in the connection string;
+// libpq does not) is read as an INI file whose entries override other connection settings including host, port, and
+// sslmode, so an attacker who controls servicefile and service can redirect the connection. If any portion of the
+// connection string is externally supplied, use ParseConfigWithOptions and set ParseConfigOptions.ConnStringAllowedKeys
+// to an allow-list of the keys that input is expected to supply; any other key in the connection string is then
+// rejected before any filesystem access occurs.
+//
 // Other known differences with libpq:
 //
 // When multiple hosts are specified, libpq allows them to have different passwords set via the .pgpass file. pgconn

pgconn/doc.go

@@ -8,6 +8,32 @@ Establishing a Connection
 Use Connect to establish a connection. It accepts a connection string in URL or keyword/value format and will read the
 environment for libpq style environment variables.
 
+Connecting Securely
+
+By default ParseConfig matches libpq and uses sslmode=prefer, which silently falls back to an unencrypted connection
+if the server does not offer TLS. For connections that traverse an untrusted network, set the following parameters
+explicitly:
+
+	# URL form
+	postgres://user@db.example.com/mydb?sslmode=verify-full&sslrootcert=/path/to/root.crt&channel_binding=require&require_auth=scram-sha-256
+
+	# keyword/value form
+	host=db.example.com user=user dbname=mydb sslmode=verify-full sslrootcert=/path/to/root.crt channel_binding=require require_auth=scram-sha-256
+
+	sslmode=verify-full       Require TLS, verify the server certificate against sslrootcert, and verify that the
+	                          certificate's host name matches the host being connected to. Weaker modes (disable,
+	                          allow, prefer, require) either permit plaintext fallback or skip certificate
+	                          verification, allowing a network attacker to impersonate the server.
+	channel_binding=require   Require SCRAM-SHA-256-PLUS, which binds the authentication exchange to the TLS channel
+	                          so that a TLS-terminating intermediary cannot relay credentials to the real server.
+	require_auth=scram-sha-256
+	                          Refuse to respond to AuthenticationCleartextPassword or AuthenticationMD5Password
+	                          requests from the server. Without this, a server (or interceptor) can request the
+	                          password in cleartext and the client will send it.
+
+These parameters may also be set via the PGSSLMODE, PGSSLROOTCERT, PGCHANNELBINDING, and PGREQUIREAUTH environment
+variables.
+
 Executing a Query
 
 ExecParams and ExecPrepared execute a single query. They return readers that iterate over each row. The Read method