infrastructure (such as a Kerberos server), also set

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

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

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.

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

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

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>

#ifdef USE_SSL

ssize_t len;

/* push unencrypted buffered data back through SSL setup */

len = pq_buffer_remaining_data();

if (len > 0)

{

char *buf = palloc(len);

pq_startmsgread();

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

return STATUS_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);

if (port->raw_buf_remaining > 0)

{

/*

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

return STATUS_ERROR;

}

if (port->raw_buf != NULL)

{

pfree(port->raw_buf);

port->raw_buf = NULL;

}

return 0;

/* Read from the "unread" buffered data first. c.f. libpq-be.h */

if (port->raw_buf_remaining > 0)

{

/* consume up to len bytes from the raw_buf */

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;

return len;

}

pq_buffer_remaining_data(void)

Assert(PqRecvLength >= PqRecvPointer);

return (PqRecvLength - PqRecvPointer);