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 15).
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 19.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
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
To start in SSL mode, the files server.crt
and server.key must exist in the server's data directory.
These files should contain the server certificate and private key,
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.
If the private key is protected with a passphrase, the
server will prompt for the passphrase and will not start until it has
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 "root"
authority that is trusted by the clients. The root certificate should
be included in every case where server.crt contains more than
To require the client to supply a trusted certificate, place
certificates of the certificate authorities (CAs)
you trust in the file root.crt in the data
directory, and set the clientcert parameter
to 1 on the appropriate hostssl line(s) in
A certificate will then be requested from the client during
SSL connection startup. (See Section 31.17 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. Certificate Revocation List (CRL) entries
are also checked if the file root.crl exists.
for diagrams showing SSL certificate usage.)
The clientcert option in pg_hba.conf is
available for all authentication methods, but only for rows specified as
hostssl. When clientcert is not specified
or is set to 0, the server will still verify presented client
certificates against root.crt if that file exists
— but it will not insist that a client certificate be presented.
Note that 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 19.3.9 for details.
The files server.key, server.crt,
root.crt, and root.crl
are only examined during server start; so you must restart
the server for changes in them to take effect.
Table 17-3. SSL Server File Usage
|server.crt||server certificate||sent to client to indicate server's identity|
|server.key||server private key||proves server certificate was sent by the owner; does not indicate
certificate owner is trustworthy|
|root.crt||trusted certificate authorities||checks that client certificate is
signed by a trusted certificate authority|
|root.crl||certificates revoked by certificate authorities||client certificate must not be on this list|
To create a quick self-signed certificate for the server, use the
following OpenSSL command:
openssl req -new -text -out server.req
Fill out the information that openssl asks for. Make sure
you enter the local host name as "Common Name"; the challenge
password can be left blank. The program will generate a key that is
passphrase protected; it will not accept a passphrase that is less
than four characters long. To remove the passphrase (as you must if
you want automatic start-up of the server), run the commands:
openssl rsa -in privkey.pem -out server.key
Enter the old passphrase to unlock the existing key. Now do:
openssl req -x509 -in server.req -text -key server.key -out server.crt
to turn the certificate into a self-signed certificate and to copy
the key and certificate to where the server will look for them.
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