18.9. Secure TCP/IP Connections with SSL
PostgreSQL has native support for using SSL connections to encrypt client/server communications for increased security. This requires that OpenSSL is installed on both client and server systems and that support in PostgreSQL is enabled at build time (see Chapter 16 ).
With
SSL
support compiled in, the
PostgreSQL
server can be started with
SSL
enabled by setting the parameter
ssl
to
on
in
postgresql.conf
. The server will listen for both normal
and
SSL
connections on the same TCP port, and will negotiate
with any connecting client on whether to use
SSL
. By
default, this is at the client's option; see
Section 20.1
about how to set up the server to require
use of
SSL
for some or all connections.
PostgreSQL
reads the system-wide
OpenSSL
configuration file. By default, this
file is named
openssl.cnf
and is located in the
directory reported by
openssl version -d
.
This default can be overridden by setting environment variable
OPENSSL_CONF
to the name of the desired configuration file.
OpenSSL
supports a wide range of ciphers
and authentication algorithms, of varying strength. While a list of
ciphers can be specified in the
OpenSSL
configuration file, you can specify ciphers specifically for use by
the database server by modifying
ssl_ciphers
in
postgresql.conf
.
Note
It is possible to have authentication without encryption overhead by
using
NULL-SHA
or
NULL-MD5
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.
To start in
SSL
mode, files containing the server certificate
and private key must exist. By default, these files are expected to be
named
server.crt
and
server.key
, respectively, in
the server's data directory, but other names and locations can be specified
using the configuration parameters
ssl_cert_file
and
ssl_key_file
.
On Unix systems, the permissions on
server.key
must
disallow any access to world or group; achieve this by the command
chmod 0600 server.key
. Alternatively, the file can be
owned by root and have group read access (that is,
0640
permissions). That setup is intended for installations where certificate
and key files are managed by the operating system. The user under which
the
PostgreSQL
server runs should then be made a
member of the group that has access to those certificate and key files.
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.
In some cases, the server certificate might be signed by an
"
intermediate
"
certificate authority, rather than one that is
directly trusted by clients. To use such a certificate, append the
certificate of the signing authority to the
server.crt
file,
then its parent authority's certificate, and so on up to a certificate
authority,
"
root
"
or
"
intermediate
"
, that is trusted by
clients, i.e. signed by a certificate in the clients'
root.crt
files.
18.9.1. Using Client Certificates
To require the client to supply a trusted certificate, place
certificates of the certificate authorities (
CA
s)
you trust in the file
root.crt
in the data
directory, set the parameter
ssl_ca_file
in
postgresql.conf
to
root.crt
,
and add the authentication option
clientcert=1
to the
appropriate
hostssl
line(s) in
pg_hba.conf
.
A certificate will then be requested from the client during
SSL connection startup. (See
Section 33.18
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.
If intermediate
CA
s appear in
root.crt
, the file must also contain certificate
chains to their root
CA
s. Certificate Revocation List
(CRL) entries
are also checked if the parameter
ssl_crl_file
is set.
(See
http://h71000.www7.hp.com/doc/83final/ba554_90007/ch04s02.html
for diagrams showing SSL certificate usage.)
The
clientcert
authentication option is available for
all authentication methods, but only in
pg_hba.conf
lines
specified as
hostssl
. When
clientcert
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.
Note that the server's
root.crt
lists the top-level
CAs that are considered trusted for signing client certificates.
In principle it need
not list the CA that signed the server's certificate, though in most cases
that CA would also be trusted for client certificates.
If you are setting up client certificates, you may wish to use
the
cert
authentication method, so that the certificates
control user authentication as well as providing connection security.
See
Section 20.3.9
for details. (It is not necessary to
specify
clientcert=1
explicitly when using
the
cert
authentication method.)
18.9.2. SSL Server File Usage
Table 18.2 summarizes the files that are relevant to the SSL setup on the server. (The shown file names are default or typical names. The locally configured names could be different.)
Table 18.2. SSL Server File Usage
| File | Contents | Effect |
|---|---|---|
ssl_cert_file
(
$PGDATA/server.crt
)
|
server certificate | sent to client to indicate server's identity |
ssl_key_file
(
$PGDATA/server.key
)
|
server private key | proves server certificate was sent by the owner; does not indicate certificate owner is trustworthy |
ssl_ca_file
(
$PGDATA/root.crt
)
|
trusted certificate authorities | checks that client certificate is signed by a trusted certificate authority |
ssl_crl_file
(
$PGDATA/root.crl
)
|
certificates revoked by certificate authorities | client certificate must not be on this list |
The server reads these files at server start and whenever the server configuration is reloaded. On Windows systems, they are also re-read whenever a new backend process is spawned for a new client connection.
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 Windows 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.
18.9.3. Creating a Self-signed Certificate
To create a quick self-signed certificate for the server, valid for 365
days, use the following
OpenSSL
command,
replacing
yourdomain.com
with the server's host name:
openssl req -new -x509 -days 365 -nodes -text -out server.crt \
-keyout server.key -subj "/CN=yourdomain.com"
Then do:
chmod og-rwx server.key
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 OpenSSL documentation.
A self-signed certificate can be used for testing, but a certificate signed by a certificate authority ( CA ) (either one of the global CAs or a local one) should be used in production so that clients can verify the server's identity. If all the clients are local to the organization, using a local CA is recommended.