<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>18.9. Secure TCP/IP Connections with SSL</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="encryption-options.html" title="18.8. Encryption Options" /><link rel="next" href="ssh-tunnels.html" title="18.10. Secure TCP/IP Connections with SSH Tunnels" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">18.9. Secure TCP/IP Connections with SSL</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="encryption-options.html" title="18.8. Encryption Options">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 18. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 18. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 11.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ssh-tunnels.html" title="18.10. Secure TCP/IP Connections with SSH Tunnels">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="SSL-TCP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">18.9. Secure TCP/IP Connections with SSL</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ssl-tcp.html#SSL-SETUP">18.9.1. Basic Setup</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-OPENSSL-CONFIG">18.9.2. OpenSSL Configuration</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-CLIENT-CERTIFICATES">18.9.3. Using Client Certificates</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-SERVER-FILES">18.9.4. SSL Server File Usage</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-CERTIFICATE-CREATION">18.9.5. Creating Certificates</a></span></dt></dl></div><a id="id-1.6.5.11.2" class="indexterm"></a><p>
<span class="productname">PostgreSQL</span> has native support for using
<acronym class="acronym">SSL</acronym> connections to encrypt client/server communications
for increased security. This requires that
<span class="productname">OpenSSL</span> is installed on both client and
server systems and that support in <span class="productname">PostgreSQL</span> is
enabled at build time (see <a class="xref" href="installation.html" title="Chapter 16. Installation from Source Code">Chapter 16</a>).
</p><div class="sect2" id="SSL-SETUP"><div class="titlepage"><div><div><h3 class="title">18.9.1. Basic Setup</h3></div></div></div><p>
With <acronym class="acronym">SSL</acronym> support compiled in, the
<span class="productname">PostgreSQL</span> server can be started with
<acronym class="acronym">SSL</acronym> enabled by setting the parameter
<a class="xref" href="runtime-config-connection.html#GUC-SSL">ssl</a> to <code class="literal">on</code> in
<code class="filename">postgresql.conf</code>. The server will listen for both normal
and <acronym class="acronym">SSL</acronym> connections on the same TCP port, and will negotiate
with any connecting client on whether to use <acronym class="acronym">SSL</acronym>. By
default, this is at the client's option; see <a class="xref" href="auth-pg-hba-conf.html" title="20.1. The pg_hba.conf File">Section 20.1</a> about how to set up the server to require
use of <acronym class="acronym">SSL</acronym> for some or all connections.
</p><p>
To start in <acronym class="acronym">SSL</acronym> mode, files containing the server certificate
and private key must exist. By default, these files are expected to be
named <code class="filename">server.crt</code> and <code class="filename">server.key</code>, respectively, in
the server's data directory, but other names and locations can be specified
using the configuration parameters <a class="xref" href="runtime-config-connection.html#GUC-SSL-CERT-FILE">ssl_cert_file</a>
and <a class="xref" href="runtime-config-connection.html#GUC-SSL-KEY-FILE">ssl_key_file</a>.
</p><p>
On Unix systems, the permissions on <code class="filename">server.key</code> must
disallow any access to world or group; achieve this by the command
<code class="command">chmod 0600 server.key</code>. Alternatively, the file can be
owned by root and have group read access (that is, <code class="literal">0640</code>
permissions). That setup is intended for installations where certificate
and key files are managed by the operating system. The user under which
the <span class="productname">PostgreSQL</span> server runs should then be made a
member of the group that has access to those certificate and key files.
</p><p>
If the data directory allows group read access then certificate files may
need to be located outside of the data directory in order to conform to the
security requirements outlined above. Generally, group access is enabled
to allow an unprivileged user to backup the database, and in that case the
backup software will not be able to read the certificate files and will
likely error.
</p><p>
If the private key is protected with a passphrase, the
server will prompt for the passphrase and will not start until it has
been entered.
Using a passphrase also disables the ability to change the server's SSL
configuration without a server restart.
Furthermore, passphrase-protected private keys cannot be used at all
on Windows.
</p><p>
The first certificate in <code class="filename">server.crt</code> must be the
server's certificate because it must match the server's private key.
The certificates of <span class="quote">“<span class="quote">intermediate</span>”</span> certificate authorities
can also be appended to the file. Doing this avoids the necessity of
storing intermediate certificates on clients, assuming the root and
intermediate certificates were created with <code class="literal">v3_ca</code>
extensions. This allows easier expiration of intermediate certificates.
</p><p>
It is not necessary to add the root certificate to
<code class="filename">server.crt</code>. Instead, clients must have the root
certificate of the server's certificate chain.
</p></div><div class="sect2" id="SSL-OPENSSL-CONFIG"><div class="titlepage"><div><div><h3 class="title">18.9.2. OpenSSL Configuration</h3></div></div></div><p>
<span class="productname">PostgreSQL</span> reads the system-wide
<span class="productname">OpenSSL</span> configuration file. By default, this
file is named <code class="filename">openssl.cnf</code> and is located in the
directory reported by <code class="literal">openssl version -d</code>.
This default can be overridden by setting environment variable
<code class="envar">OPENSSL_CONF</code> to the name of the desired configuration file.
</p><p>
<span class="productname">OpenSSL</span> supports a wide range of ciphers
and authentication algorithms, of varying strength. While a list of
ciphers can be specified in the <span class="productname">OpenSSL</span>
configuration file, you can specify ciphers specifically for use by
the database server by modifying <a class="xref" href="runtime-config-connection.html#GUC-SSL-CIPHERS">ssl_ciphers</a> in
<code class="filename">postgresql.conf</code>.
</p><div class="note"><h3 class="title">Note</h3><p>
It is possible to have authentication without encryption overhead by
using <code class="literal">NULL-SHA</code> or <code class="literal">NULL-MD5</code> ciphers. However,
a man-in-the-middle could read and pass communications between client
and server. Also, encryption overhead is minimal compared to the
overhead of authentication. For these reasons NULL ciphers are not
recommended.
</p></div></div><div class="sect2" id="SSL-CLIENT-CERTIFICATES"><div class="titlepage"><div><div><h3 class="title">18.9.3. Using Client Certificates</h3></div></div></div><p>
To require the client to supply a trusted certificate,
place certificates of the root certificate authorities
(<acronym class="acronym">CA</acronym>s) you trust in a file in the data
directory, set the parameter <a class="xref" href="runtime-config-connection.html#GUC-SSL-CA-FILE">ssl_ca_file</a> in
<code class="filename">postgresql.conf</code> to the new file name, and add the
authentication option <code class="literal">clientcert=1</code> to the appropriate
<code class="literal">hostssl</code> line(s) in <code class="filename">pg_hba.conf</code>.
A certificate will then be requested from the client during SSL
connection startup. (See <a class="xref" href="libpq-ssl.html" title="34.18. SSL Support">Section 34.18</a> for a description
of how to set up certificates on the client.) The server will
verify that the client's certificate is signed by one of the trusted
certificate authorities.
</p><p>
Intermediate certificates that chain up to existing root certificates
can also appear in the <a class="xref" href="runtime-config-connection.html#GUC-SSL-CA-FILE">ssl_ca_file</a> file if
you wish to avoid storing them on clients (assuming the root and
intermediate certificates were created with <code class="literal">v3_ca</code>
extensions). Certificate Revocation List (CRL) entries are also
checked if the parameter <a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-FILE">ssl_crl_file</a> is set.
(See <a class="ulink" href="http://h41379.www4.hpe.com/doc/83final/ba554_90007/ch04s02.html" target="_top">http://h41379.www4.hpe.com/doc/83final/ba554_90007/ch04s02.html</a>
for diagrams showing SSL certificate usage.)
</p><p>
The <code class="literal">clientcert</code> authentication option is available for
all authentication methods, but only in <code class="filename">pg_hba.conf</code> lines
specified as <code class="literal">hostssl</code>. When <code class="literal">clientcert</code> is
not specified or is set to 0, the server will still verify any presented
client certificates against its CA file, if one is configured — but
it will not insist that a client certificate be presented.
</p><p>
If you are setting up client certificates, you may wish to use
the <code class="literal">cert</code> authentication method, so that the certificates
control user authentication as well as providing connection security.
See <a class="xref" href="auth-cert.html" title="20.12. Certificate Authentication">Section 20.12</a> for details. (It is not necessary to
specify <code class="literal">clientcert=1</code> explicitly when using
the <code class="literal">cert</code> authentication method.)
</p></div><div class="sect2" id="SSL-SERVER-FILES"><div class="titlepage"><div><div><h3 class="title">18.9.4. SSL Server File Usage</h3></div></div></div><p>
<a class="xref" href="ssl-tcp.html#SSL-FILE-USAGE" title="Table 18.2. SSL Server File Usage">Table 18.2</a> summarizes the files that are
relevant to the SSL setup on the server. (The shown file names are default
names. The locally configured names could be different.)
</p><div class="table" id="SSL-FILE-USAGE"><p class="title"><strong>Table 18.2. SSL Server File Usage</strong></p><div class="table-contents"><table class="table" summary="SSL Server File Usage" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>File</th><th>Contents</th><th>Effect</th></tr></thead><tbody><tr><td><a class="xref" href="runtime-config-connection.html#GUC-SSL-CERT-FILE">ssl_cert_file</a> (<code class="filename">$PGDATA/server.crt</code>)</td><td>server certificate</td><td>sent to client to indicate server's identity</td></tr><tr><td><a class="xref" href="runtime-config-connection.html#GUC-SSL-KEY-FILE">ssl_key_file</a> (<code class="filename">$PGDATA/server.key</code>)</td><td>server private key</td><td>proves server certificate was sent by the owner; does not indicate
certificate owner is trustworthy</td></tr><tr><td><a class="xref" href="runtime-config-connection.html#GUC-SSL-CA-FILE">ssl_ca_file</a></td><td>trusted certificate authorities</td><td>checks that client certificate is
signed by a trusted certificate authority</td></tr><tr><td><a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-FILE">ssl_crl_file</a></td><td>certificates revoked by certificate authorities</td><td>client certificate must not be on this list</td></tr></tbody></table></div></div><br class="table-break" /><p>
The server reads these files at server start and whenever the server
configuration is reloaded. On <span class="systemitem">Windows</span>
systems, they are also re-read whenever a new backend process is spawned
for a new client connection.
</p><p>
If an error in these files is detected at server start, the server will
refuse to start. But if an error is detected during a configuration
reload, the files are ignored and the old SSL configuration continues to
be used. On <span class="systemitem">Windows</span> systems, if an error in
these files is detected at backend start, that backend will be unable to
establish an SSL connection. In all these cases, the error condition is
reported in the server log.
</p></div><div class="sect2" id="SSL-CERTIFICATE-CREATION"><div class="titlepage"><div><div><h3 class="title">18.9.5. Creating Certificates</h3></div></div></div><p>
To create a simple self-signed certificate for the server, valid for 365
days, use the following <span class="productname">OpenSSL</span> command,
replacing <em class="replaceable"><code>dbhost.yourdomain.com</code></em> with the
server's host name:
</p><pre class="programlisting">
openssl req -new -x509 -days 365 -nodes -text -out server.crt \
-keyout server.key -subj "/CN=<em class="replaceable"><code>dbhost.yourdomain.com</code></em>"
</pre><p>
Then do:
</p><pre class="programlisting">
chmod og-rwx server.key
</pre><p>
because the server will reject the file if its permissions are more
liberal than this.
For more details on how to create your server private key and
certificate, refer to the <span class="productname">OpenSSL</span> documentation.
</p><p>
While a self-signed certificate can be used for testing, a certificate
signed by a certificate authority (<acronym class="acronym">CA</acronym>) (usually an
enterprise-wide root <acronym class="acronym">CA</acronym>) should be used in production.
</p><p>
To create a server certificate whose identity can be validated
by clients, first create a certificate signing request
(<acronym class="acronym">CSR</acronym>) and a public/private key file:
</p><pre class="programlisting">
openssl req -new -nodes -text -out root.csr \
-keyout root.key -subj "/CN=<em class="replaceable"><code>root.yourdomain.com</code></em>"
chmod og-rwx root.key
</pre><p>
Then, sign the request with the key to create a root certificate
authority (using the default <span class="productname">OpenSSL</span>
configuration file location on <span class="productname">Linux</span>):
</p><pre class="programlisting">
openssl x509 -req -in root.csr -text -days 3650 \
-extfile /etc/ssl/openssl.cnf -extensions v3_ca \
-signkey root.key -out root.crt
</pre><p>
Finally, create a server certificate signed by the new root certificate
authority:
</p><pre class="programlisting">
openssl req -new -nodes -text -out server.csr \
-keyout server.key -subj "/CN=<em class="replaceable"><code>dbhost.yourdomain.com</code></em>"
chmod og-rwx server.key
openssl x509 -req -in server.csr -text -days 365 \
-CA root.crt -CAkey root.key -CAcreateserial \
-out server.crt
</pre><p>
<code class="filename">server.crt</code> and <code class="filename">server.key</code>
should be stored on the server, and <code class="filename">root.crt</code> should
be stored on the client so the client can verify that the server's leaf
certificate was signed by its trusted root certificate.
<code class="filename">root.key</code> should be stored offline for use in
creating future certificates.
</p><p>
It is also possible to create a chain of trust that includes
intermediate certificates:
</p><pre class="programlisting">
# root
openssl req -new -nodes -text -out root.csr \
-keyout root.key -subj "/CN=<em class="replaceable"><code>root.yourdomain.com</code></em>"
chmod og-rwx root.key
openssl x509 -req -in root.csr -text -days 3650 \
-extfile /etc/ssl/openssl.cnf -extensions v3_ca \
-signkey root.key -out root.crt
# intermediate
openssl req -new -nodes -text -out intermediate.csr \
-keyout intermediate.key -subj "/CN=<em class="replaceable"><code>intermediate.yourdomain.com</code></em>"
chmod og-rwx intermediate.key
openssl x509 -req -in intermediate.csr -text -days 1825 \
-extfile /etc/ssl/openssl.cnf -extensions v3_ca \
-CA root.crt -CAkey root.key -CAcreateserial \
-out intermediate.crt
# leaf
openssl req -new -nodes -text -out server.csr \
-keyout server.key -subj "/CN=<em class="replaceable"><code>dbhost.yourdomain.com</code></em>"
chmod og-rwx server.key
openssl x509 -req -in server.csr -text -days 365 \
-CA intermediate.crt -CAkey intermediate.key -CAcreateserial \
-out server.crt
</pre><p>
<code class="filename">server.crt</code> and
<code class="filename">intermediate.crt</code> should be concatenated
into a certificate file bundle and stored on the server.
<code class="filename">server.key</code> should also be stored on the server.
<code class="filename">root.crt</code> should be stored on the client so
the client can verify that the server's leaf certificate was signed
by a chain of certificates linked to its trusted root certificate.
<code class="filename">root.key</code> and <code class="filename">intermediate.key</code>
should be stored offline for use in creating future certificates.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="encryption-options.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ssh-tunnels.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">18.8. Encryption Options </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 18.10. Secure TCP/IP Connections with <span class="application">SSH</span> Tunnels</td></tr></table></div></body></html>
