encryption, regardless of the value of <literal>sslmode</literal>.

To force use of <acronym>SSL</acronym> encryption in an

environment that has working <acronym>GSSAPI</acronym>

infrastructure (such as a Kerberos server), also

set<literal>gssencmode</literal> to <literal>disable</literal>.

infrastructure (such as a Kerberos server), also set

<literal>gssencmode</literal> to <literal>disable</literal>.

</para>

</listitem>

</varlistentry>

</listitem>

</varlistentry>

<varlistentry id="libpq-connect-sslnegotiation" xreflabel="sslnegotiation">

<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.

</para>

<variablelist>

<varlistentry>

<term><literal>postgres</literal></term>

<listitem>

<para>

perform <productname>PostgreSQL</productname> protocol

negotiation. This is the default if the option is not provided.

</para>

</listitem>

</varlistentry>

<varlistentry>

<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>

</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>

<para>

Note that if <literal>gssencmode</literal> is set

to <literal>prefer</literal>, a <acronym>GSS</acronym> 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 <literal>sslnegotiation</literal>. 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.

</para>

</listitem>

</varlistentry>

<varlistentry id="libpq-connect-sslcompression" xreflabel="sslcompression">

<term><literal>sslcompression</literal></term>

<listitem>

<para>

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, <acronym>SNI</acronym> 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 <literal>sslnegotiation</literal>

to <literal>direct</literal> or <literal>requiredirect</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.

</para>

</listitem>

</varlistentry>

</para>

</listitem>

<listitem>

<para>

<indexterm>

<primary><envar>PGSSLNEGOTIATION</envar></primary>

</indexterm>

<envar>PGSSLNEGOTIATION</envar> behaves the same as the <xref

linkend="libpq-connect-sslnegotiation"/> connection parameter.

</para>

</listitem>

<listitem>

<para>

<indexterm>

bytes.

</para>

<para>

Likewise the server expects the client to not begin

the <acronym>SSL</acronym> negotiation until it receives the server's

single byte response to the <acronym>SSL</acronym> request. If the

client begins the <acronym>SSL</acronym> 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

<acronym>SSL</acronym> request. In that case instead of continuing with either GSSAPI or an

unencrypted connection or a protocol error the server will simply

disconnect.

</para>

<para>

An initial SSLRequest can also be used in a connection that is being

opened to send a CancelRequest message.

</para>

<para>

A second alternate way to initiate <acronym>SSL</acronym> encryption is

available. The server will recognize connections which immediately

begin <acronym>SSL</acronym> negotiation without any previous SSLRequest

packets. Once the <acronym>SSL</acronym> 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 <acronym>SSL</acronym> connections.

When using <acronym>SSL</acronym> connections in this style the client is

required to use the ALPN extension defined

by <ulink url="https://tools.ietf.org/html/rfc7301">RFC 7301</ulink> to

protect against protocol confusion attacks.

The <productname>PostgreSQL</productname> protocol is "TBD-pgsql" as

registered

at <ulink url="https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids">IANA

TLS ALPN Protocol IDs</ulink> registry.

</para>

<para>

While the protocol itself does not provide a way for the server to

force <acronym>SSL</acronym> encryption, the administrator can

secure_open_server(Port*port)

{

intr=0;

ssize_tlen;

len=pq_buffer_remaining_data();

if (len>0)

{

char*buf=palloc(len);

pq_startmsgread();

if (pq_getbytes(buf,len)==EOF)

returnSTATUS_ERROR;/* shouldn't be possible */

pq_endmsgread();

port->raw_buf=buf;

port->raw_buf_remaining=len;

port->raw_buf_consumed=0;

}

Assert(pq_buffer_remaining_data()==0);

r=be_tls_open_server(port);

if (port->raw_buf_remaining>0)

{

elog(LOG,"buffered unencrypted data remains after negotiating SSL connection");

returnSTATUS_ERROR;

}

if (port->raw_buf!=NULL)

{

pfree(port->raw_buf);

port->raw_buf=NULL;

}

ereport(DEBUG2,

(errmsg_internal("SSL connection from DN:\"%s\" CN:\"%s\"",

port->peer_dn ?port->peer_dn :"(anonymous)",

port->peer_cn ?port->peer_cn :"(anonymous)")));

returnr;

return0;

}

{

ssize_tn;

if (port->raw_buf_remaining>0)

{

if (len>port->raw_buf_remaining)

len=port->raw_buf_remaining;

Assert(port->raw_buf);

memcpy(ptr,port->raw_buf+port->raw_buf_consumed,len);

port->raw_buf_consumed+=len;

port->raw_buf_remaining-=len;

returnlen;

}

}

pq_buffer_has_data(void)

pq_buffer_remaining_data(void)

{

return (PqRecvPointer<PqRecvLength);

Assert(PqRecvLength >=PqRecvPointer);

return (PqRecvLength-PqRecvPointer);

}