14th September 2023: PostgreSQL 16 Released!
Supported Versions: Current (16) / 15 / 14 / 13 / 12 / 11
Development Versions: devel
Unsupported versions: 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1
This documentation is for an unsupported version of PostgreSQL.
You may want to view the same page for the current version, or one of the other supported versions listed above instead.

17.8. 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 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 standard 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 21.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, 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, respectively. 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.

To require the client to supply a trusted certificate, place certificates of the certificate authorities (CA) you trust in the file root.crt in the data directory. A certificate will then be requested from the client during SSL connection startup. (See Section 30.16 for a description of how to set up client certificates.) 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. (See http://h71000.www7.hp.com/DOC/83final/BA554_90007/ch04s02.html for diagrams showing SSL certificate usage.)

If the root.crt file is not present, client certificates will not be requested or checked. In this mode, SSL provides encrypted communication but not authentication.

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

File Contents Effect
server.crt server certificate requested by client
server.key server private key proves server certificate sent by owner; does not indicate certificate owner is trustworthy
root.crt trusted certificate authorities requests client certificate; checks certificate is signed by a trusted certificate authority
root.crl certificates revoked by certificate authorities client certificate must not be on this list

17.8.1. Creating a Self-Signed Certificate

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
rm privkey.pem

Enter the old passphrase to unlock the existing key. Now do:

openssl req -x509 -in server.req -text -key server.key -out server.crt
chmod og-rwx server.key

to turn the certificate into a self-signed certificate and to copy the key and certificate to where the server will look for them. 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 the client can verify the server's identity.