17.9. Secure TCP/IP Connections with SSL
Postgres Pro has native support for usingSSL connections to encrypt client/server communications for increased security.
WithSSL support compiled in, thePostgres Pro server can be started withSSL enabled by setting the parameterssl toon inpostgresql.conf. The server will listen for both normal andSSL connections on the same TCP port, and will negotiate with any connecting client on whether to useSSL. By default, this is at the client's option; seeSection 19.1 about how to set up the server to require use ofSSL for some or all connections.
OpenSSL supports a wide range of ciphers and authentication algorithms, of varying strength. While a list of ciphers can be specified in theOpenSSL configuration file, you can specify ciphers specifically for use by the database server by modifyingssl_ciphers inpostgresql.conf.
Note
It is possible to have authentication without encryption overhead by usingNULL-SHA orNULL-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 inSSL mode, files containing the server certificate and private key must exist. By default, these files are expected to be namedserver.crt andserver.key, respectively, in the server's data directory, but other names and locations can be specified using the configuration parametersssl_cert_file andssl_key_file.
On Unix systems, the permissions onserver.key must disallow any access to world or group; achieve this by the commandchmod 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 thePostgres Pro 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.
The first certificate inserver.crt must be the server's certificate because it must match the server's private key. The certificates of“intermediate” 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 withv3_ca extensions. (This sets the certificate's basic constraint ofCA totrue.) This allows easier expiration of intermediate certificates.
It is not necessary to add the root certificate toserver.crt. Instead, clients must have the root certificate of the server's certificate chain.
17.9.1. Using Client Certificates
To require the client to supply a trusted certificate, place certificates of the root certificate authorities (CAs) you trust in a file in the data directory, set the parameterssl_ca_file inpostgresql.conf to the new file name, and add the authentication optionclientcert=1 to the appropriatehostssl line(s) inpg_hba.conf. A certificate will then be requested from the client during SSL connection startup. (SeeSection 30.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.
Intermediate certificates that chain up to existing root certificates can also appear in the fileroot.crt if you wish to avoid storing them on clients (assuming the root and intermediate certificates were created withv3_ca extensions). Certificate Revocation List (CRL) entries are also checked if the parameterssl_crl_file is set.
Theclientcert authentication option is available for all authentication methods, but only inpg_hba.conf lines specified ashostssl. Whenclientcert 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.
If you are setting up client certificates, you may wish to use thecert authentication method, so that the certificates control user authentication as well as providing connection security. SeeSection 19.3.9 for details. (It is not necessary to specifyclientcert=1 explicitly when using thecert authentication method.)
17.9.2. SSL Server File Usage
Table 17.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 17.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 filesserver.key,server.crt,root.crt, androot.crl (or their configured alternative names) are only examined during server start; so you must restart the server for changes in them to take effect.
17.9.3. Creating Certificates
To create a simple self-signed certificate for the server, valid for 365 days, use the followingOpenSSL command, replacingdbhost.yourdomain.com with the server's host name:
openssl req -new -x509 -days 365 -nodes -text -out server.crt \ -keyout server.key -subj "/CN=dbhost.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 theOpenSSL documentation.
While a self-signed certificate can be used for testing, a certificate signed by a certificate authority (CA) (usually an enterprise-wide rootCA) should be used in production.
To create a server certificate whose identity can be validated by clients, first create a certificate signing request (CSR) and a public/private key file:
openssl req -new -nodes -text -out root.csr \ -keyout root.key -subj "/CN=root.yourdomain.com"chmod og-rwx root.keyopenssl x509 -req -in root.csr -text -days 3650 \ -extfile /etc/ssl/openssl.cnf -extensions v3_ca \ -signkey root.key -out root.crt
Finally, create a server certificate signed by the new root certificate authority:
openssl req -new -nodes -text -out server.csr \ -keyout server.key -subj "/CN=dbhost.yourdomain.com"chmod og-rwx server.keyopenssl x509 -req -in server.csr -text -days 365 \ -CA root.crt -CAkey root.key -CAcreateserial \ -out server.crtIt is also possible to create a chain of trust that includes intermediate certificates:
# rootopenssl req -new -nodes -text -out root.csr \ -keyout root.key -subj "/CN=root.yourdomain.com"chmod og-rwx root.keyopenssl x509 -req -in root.csr -text -days 3650 \ -extfile /etc/ssl/openssl.cnf -extensions v3_ca \ -signkey root.key -out root.crt# intermediateopenssl req -new -nodes -text -out intermediate.csr \ -keyout intermediate.key -subj "/CN=intermediate.yourdomain.com"chmod og-rwx intermediate.keyopenssl 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# leafopenssl req -new -nodes -text -out server.csr \ -keyout server.key -subj "/CN=dbhost.yourdomain.com"chmod og-rwx server.keyopenssl x509 -req -in server.csr -text -days 365 \ -CA intermediate.crt -CAkey intermediate.key -CAcreateserial \ -out server.crt