From 4dd508fad6f9088894054d37ab3d49dc5fdcd701 Mon Sep 17 00:00:00 2001 From: Greg Stark Date: Thu, 16 Mar 2023 15:10:15 -0400 Subject: [PATCH v4 3/4] Direct SSL connections documentation --- doc/src/sgml/libpq.sgml | 102 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 93 insertions(+), 9 deletions(-) diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 9ee5532c07..0b89b224ba 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1691,10 +1691,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname Note that if GSSAPI encryption is possible, that will be used in preference to SSL 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. + To negotiate SSL encryption in an environment that + has working GSSAPI infrastructure (such as a + Kerberos server), also set gssencmode + to disable. + Use of non-default values of sslnegotiation can + also cause SSL to be used instead of + negotiating GSSAPI encryption. @@ -1721,6 +1724,75 @@ 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. + + + + + + + If sslmode set to disable + or allow then sslnegotiation is + ignored. If gssencmode is set + to require then sslnegotiation + must be the default postgres value. + + + + Moreover, note if gssencmode is set + to prefer and sslnegotiation + to direct then the effective preference will be + direct SSL connections, followed by + negotiated GSS connections, followed by + negotiated SSL connections, possibly followed + lastly by unencrypted connections. + + + + sslcompression @@ -1874,11 +1946,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. @@ -7956,6 +8030,16 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) + + + + PGSSLNEGOTIATION + + PGSSLNEGOTIATION behaves the same as the connection parameter. + + + -- 2.39.2