PGX 20.1.1
Documentation

TLS/SSL Configuration

The PGX web server enables two-way SSL/TLS by default. The PGX server enforces TLS 1.2 and disables certain cipher suites known to be vulnerable to attacks. Upon TLS handshake, both server and client present certificates to each other which are used to validate the authenticity of the other party. Client certificates are additionally used to authorize client applications.

Prepare the Certificates

Disabling SSL/TLS

You can skip this part if you turn off SSL/TLS in single-node or multi-node PGX server configuration. However, we strongly recommend to leave SSL/TLS turned on for any production deployment.

First, create the server certificate which will be validated by the client upon SSL/TLS handshake.

Create a Self-Signed Server Certificate

Do not use self-signed certificates in production deployments

For production, you should obtain a certificate from a certificate authority which is trusted by your organization (see next section).

An easy way to create a self-signed certificate is to the keytool command-line utility, which is part of the Java Development Kit (JDK) you already installed (see installation). To create a new keystore containing a self-signed certificate, do

keytool -genkey -alias pgx -keyalg RSA -keystore server_keystore.jks

The command will prompt with a keystore password, general information of the certificate (which will be displayed to clients who attempt to connect to the PGX web server) and the key password. The keystore password is for the keystore file itself and the key password is for the certificate. This is because JKS keystore files can store more than one certificate (identified by the provided alias). When prompted for first and last name, enter the host name of the host you will deploy the PGX server on. If the host name in the certificate does not match the host name the server is listening on, client applications will reject the connection.

In distributed mode: use the host which starts the web server

For the multi-node setup, use the first host name in the list of pgx_hostnames as the host name for your certificates. Only the first host in this list will start a http server.

The PGX server requires both the server certificate and server private key in the PKCS12 (PEM) format. In order to extract the certifcate and private key from the JKS file, first convert the generated server_keystore.jks file into a server_keystore.p12 file by doing:

keytool -importkeystore -srckeystore server_keystore.jks -destkeystore server_keystore.p12 -srcalias pgx \ 
    -srcstoretype jks -deststoretype pkcs12

The command will prompt with both the source and destination keystore passwords and then generate a file server_keystore.p12 in the current directory. Next, extract certificate and private key from that server_keystore.p12 file running the following two openssl commands:

openssl pkcs12 -in server_keystore.p12 -nokeys -out server_cert.pem
openssl pkcs12 -in server_keystore.p12 -nodes -nocerts -out server_key.pem

The above commands will generate server_cert.pem and server_key.pem in the current directory.

Note that, as from the Server Configuration guide, the server_key.pem file with the private key should be only readable and writable and only by the user PGX runs as; the openssl command usually sets these permissions at file creation, otherwise it suffices to run

chmod 600 server_key.pem

Import an Existing Certificate or Install a Certificate from a Certificate Authority

If you have a certificate issued by a CA, add it to the ca_certs server configuration field. The server_cert.pem that you specify must only contain one certificate (no intermediate or root certificates) and must be trusted by the certificates in your ca_certs list.

For more information, please refer to the Tomcat TLS/SSL documentation on how to import existing certificates or on how to install a certificate from a certificate authority into keystore files.

Prepare the Client Keystore

Disabling two-way SSL/TLS

You can skip this part if you turn off client authentication in single-node or multi-node PGX server configuration. However, we strongly recommend to leave two-way SSL/TLS turned on for any production deployment.

For two-way SSL/TLS to work, you now have to create one certificate for each client application you allow access to your PGX server. First, create a keystore file for the client:

keytool -genkey -alias pgx -keyalg RSA -keystore client_keystore.jks

Just like the server keystore command, above command will prompt with a keystore password, general information of the certificate and the key password. Note down the general information in the certificate (distinguished name string) as you will need this information again in the next section for the PGX server authorization configuration.

Next, sign the certificate inside the client keystore with the server private key which will make the client certificate to be accepted by the server. For that, you first have to create a sign request file client.csr by doing:

keytool -certreq -keystore client_keystore.jks -alias pgx -keyalg RSA -file client.csr

which will prompt for the keystore password. Next, sign the the client.csr file by providing both the server's certificate and private key files to the following openssl command:

openssl x509 -req -CA server_cert.pem -CAkey server_key.pem -in client.csr -out client_certificate.pem -days 365 -CAcreateserial

The above command generates a signed client certificate file client_certificate.pem which will be accepted by the server for the next 365 days. You can adapt the -days parameter to your needs.

Next, import both the server certificate as well as the signed client certificate back into the client keystore file by doing:

keytool -import -noprompt -trustcacerts -keystore client_keystore.jks -file server_cert.pem -alias pgxserver
keytool -import -noprompt -trustcacerts -keystore client_keystore.jks -file client_certificate.pem -alias pgx

Prepare the Client Truststore

In this tutorial, we will use the same client_keystore.jks file for both the client keystore (which certificate to present to the server) and the client trust store (which server certificates to trust). Depending on whether or not you used a self-signed server certificate, you may also have to import the server certificate's trust authority (CA) into the client keystore, otherwise the client will reject the server certificate. Note that if you are using the PGX client shell, are range of well-known certificate authorities are trusted already by default by the client-side Java virtual machine.

Configure the PGX Web Server

Next, specify the paths to the server_cert.pem and the server_key.pem files in the single-node or multi-node PGX server configurations. You can also specify a list of certificate authorities which will be trusted by the server.

Test the Connection Using the PGX Client Shell

If you started the web server with a self-signed certificate, you first have to configure the client to accept the certificate. As the certificate is self-signed and therefore not issued from a trusted certificate authority, the PGX client would reject it otherwise. You can set the trust store of the PGX client shell via the --truststore command-line option. Similarly, you should specify the path to the keystore (--keystore) which contains the certificate the client will present to the server for authentication and authorization. In case the keystore is protected by a password, the Shell will automatically prompt with it.

Do not accept self-signed certificates from unknown sources

Never accept certificates from sources other than yourself.

Assuming the PGX web server listens on the default port 7007 on the same machine and you created the keystores as described above, you can test the connection by doing

cd $PGX_HOME
./bin/pgx-jshell --base_url https://localhost:7007 --truststore client_keystore.jks --keystore client_keystore.jks

If the shell starts up without any error, you successfully connected to the PGX web server securely over two-way TLS/SSL.