Remove option to fall back from direct to postgres SSL negotiation

There were three problems with the sslnegotiation options:

1. The sslmode=prefer and sslnegotiation=requiredirect combination was
somewhat dangerous, as you might unintentionally fall back to
plaintext authentication when connecting to a pre-v17 server.

2. There was an asymmetry between 'postgres' and 'direct'
options. 'postgres' meant "try only traditional negotiation", while
'direct' meant "try direct first, and fall back to traditional
negotiation if it fails". That was apparent only if you knew that the
'requiredirect' mode also exists.

3. The "require" word in 'requiredirect' suggests that it's somehow
more strict or more secure, similar to sslmode. However, I don't
consider direct SSL connections to be a security feature.

To address these problems:

- Only allow sslnegotiation='direct' if sslmode='require' or
stronger. And for the record, Jacob and Robert felt that we should do
that (or have sslnegotiation='direct' imply sslmode='require') anyway,
regardless of the first issue.

- Remove the 'direct' mode that falls back to traditional negotiation,
and rename what was called 'requiredirect' to 'direct' instead. In
other words, there is no "try both methods" option anymore, 'postgres'
now means the traditional negotiation and 'direct' means a direct SSL
connection.

Reviewed-by: Jelte Fennema-Nio, Robert Haas, Jacob Champion
Discussion: https://www.postgresql.org/message-id/d3b1608a-a1b6-4eda-9ec5-ddb3e4375808%40iki.fi

1 files changed, 17 insertions, 32 deletions

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 74b6ed0cf97..80179f99783 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1773,15 +1773,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>sslnegotiation</literal></term>
       <listitem>
        <para>
-        This option controls whether <productname>PostgreSQL</productname>
-        will perform its protocol negotiation to request encryption from the
-        server or will just directly make a standard <acronym>SSL</acronym>
-        connection.  Traditional <productname>PostgreSQL</productname>
-        protocol negotiation is the default and the most flexible with
-        different server configurations. If the server is known to support
-        direct <acronym>SSL</acronym> connections then the latter requires one
-        fewer round trip reducing connection latency and also allows the use
-        of protocol agnostic SSL network tools.
+        This option controls how SSL encryption is negotiated with the server,
+        if SSL is used. In the default <literal>postgres</literal> mode, the
+        client first asks the server if SSL is supported. In
+        <literal>direct</literal> mode, the client starts the standard SSL
+        handshake directly after establishing the TCP/IP connection. Traditional
+        <productname>PostgreSQL</productname> protocol negotiation is the most
+        flexible with different server configurations. If the server is known
+        to support direct <acronym>SSL</acronym> connections then the latter
+        requires one fewer round trip reducing connection latency and also
+        allows the use of protocol agnostic SSL network tools. The direct SSL
+        option was introduced in <productname>PostgreSQL</productname> version
+        17.
        </para>
 
         <variablelist>
@@ -1799,32 +1802,14 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
           <term><literal>direct</literal></term>
           <listitem>
            <para>
-             first attempt to establish a standard SSL connection and if that
-             fails reconnect and perform the negotiation. This fallback
-             process adds significant latency if the initial SSL connection
-             fails.
-           </para>
-           <para>
-             An exception is if <literal>gssencmode</literal> is set
-             to <literal>prefer</literal>, but the server rejects GSS encryption.
-             In that case, SSL is negotiated over the same TCP connection using
-             <productname>PostgreSQL</productname> protocol negotiation. In
-             other words, the direct SSL handshake is not used, if a TCP
-             connection has already been established and can be used for the
+             start SSL handshake directly after establishing the TCP/IP
+             connection.  This is only allowed with sslmode=require or higher,
+             because the weaker settings could lead to unintended fallback to
+             plaintext authentication when the server does not support direct
              SSL handshake.
            </para>
           </listitem>
          </varlistentry>
-
-         <varlistentry>
-          <term><literal>requiredirect</literal></term>
-          <listitem>
-           <para>
-             attempt to establish a standard SSL connection and if that fails
-             return a connection failure immediately.
-           </para>
-          </listitem>
-         </varlistentry>
         </variablelist>
       </listitem>
      </varlistentry>
@@ -2065,7 +2050,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
         connections without having to decrypt the SSL stream.  (Note that
         unless the proxy is aware of the PostgreSQL protocol handshake this
         would require setting <literal>sslnegotiation</literal>
-        to <literal>direct</literal> or <literal>requiredirect</literal>.)
+        to <literal>direct</literal>.)
         However, <acronym>SNI</acronym> makes the destination host name appear
         in cleartext in the network traffic, so it might be undesirable in
         some cases.