From d39a49c1e459804831302807c724fa6512e90cf0 Mon Sep 17 00:00:00 2001 From: Heikki Linnakangas Date: Mon, 8 Apr 2024 04:24:49 +0300 Subject: Support TLS handshake directly without SSLRequest negotiation By skipping SSLRequest, you can eliminate one round-trip when establishing a TLS connection. It is also more friendly to generic TLS proxies that don't understand the PostgreSQL protocol. This is disabled by default in libpq, because the direct TLS handshake will fail with old server versions. It can be enabled with the sslnegotation=direct option. It will still fall back to the negotiated TLS handshake if the server rejects the direct attempt, either because it is an older version or the server doesn't support TLS at all, but the fallback can be disabled with the sslnegotiation=requiredirect option. Author: Greg Stark, Heikki Linnakangas Reviewed-by: Matthias van de Meent, Jacob Champion --- doc/src/sgml/libpq.sgml | 87 ++++++++++++++++++++++++++++++++++++++++++---- doc/src/sgml/protocol.sgml | 36 +++++++++++++++++++ 2 files changed, 116 insertions(+), 7 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index aadd5d2581c..0fb728e2b28 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1740,8 +1740,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname encryption, regardless of the value of sslmode. To force use of SSL encryption in an environment that has working GSSAPI - infrastructure (such as a Kerberos server), also - set gssencmode to disable. + infrastructure (such as a Kerberos server), also set + gssencmode to disable. @@ -1768,6 +1768,67 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname + + sslnegotiation + + + This option controls whether PostgreSQL + will perform its protocol negotiation to request encryption from the + server or will just directly make a standard SSL + connection. Traditional PostgreSQL + protocol negotiation is the default and the most flexible with + different server configurations. If the server is known to support + direct SSL connections then the latter requires one + fewer round trip reducing connection latency and also allows the use + of protocol agnostic SSL network tools. + + + + + postgres + + + perform PostgreSQL protocol + negotiation. This is the default if the option is not provided. + + + + + + direct + + + 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. + + + + + + requiredirect + + + attempt to establish a standard SSL connection and if that fails + return a connection failure immediately. + + + + + + + Note that if gssencmode is set + to prefer, a GSS connection is + attempted first. If the server ejectes GSS encryption, SSL is + negotiated over the same TCP connection using the traditional postgres + protocol, regardless of sslnegotiation. In other + words, the direct SSL handshake is not used, if a TCP connection has + already been established and can be used for the SSL handshake. + + + + sslcompression @@ -2001,11 +2062,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname The Server Name Indication can be used by SSL-aware proxies to route - connections without having to decrypt the SSL stream. (Note that this - requires a proxy that is aware of the PostgreSQL protocol handshake, - not just any SSL proxy.) However, SNI makes the - destination host name appear in cleartext in the network traffic, so - it might be undesirable in some cases. + connections without having to decrypt the SSL stream. (Note that + unless the proxy is aware of the PostgreSQL protocol handshake this + would require setting sslnegotiation + to direct or requiredirect.) + However, SNI makes the destination host name appear + in cleartext in the network traffic, so it might be undesirable in + some cases. @@ -8676,6 +8739,16 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) + + + + PGSSLNEGOTIATION + + PGSSLNEGOTIATION behaves the same as the connection parameter. + + + diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 11f75cd3d65..a8ec72c27f4 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1529,11 +1529,47 @@ SELCT 1/0; bytes. + + Likewise the server expects the client to not begin + the SSL negotiation until it receives the server's + single byte response to the SSL request. If the + client begins the SSL negotiation immediately without + waiting for the server response to be received it can reduce connection + latency by one round-trip. However this comes at the cost of not being + able to handle the case where the server sends a negative response to the + SSL request. In that case instead of continuing with either GSSAPI or an + unencrypted connection or a protocol error the server will simply + disconnect. + + An initial SSLRequest can also be used in a connection that is being opened to send a CancelRequest message. + + A second alternate way to initiate SSL encryption is + available. The server will recognize connections which immediately + begin SSL negotiation without any previous SSLRequest + packets. Once the SSL connection is established the + server will expect a normal startup-request packet and continue + negotiation over the encrypted channel. In this case any other requests + for encryption will be refused. This method is not preferred for general + purpose tools as it cannot negotiate the best connection encryption + available or handle unencrypted connections. However it is useful for + environments where both the server and client are controlled together. + In that case it avoids one round trip of latency and allows the use of + network tools that depend on standard SSL connections. + When using SSL connections in this style the client is + required to use the ALPN extension defined + by RFC 7301 to + protect against protocol confusion attacks. + The PostgreSQL protocol is "TBD-pgsql" as + registered + at IANA + TLS ALPN Protocol IDs registry. + + While the protocol itself does not provide a way for the server to force SSL encryption, the administrator can -- cgit v1.2.3