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.
First, create the server certificate which will be validated by the client upon SSL/TLS handshake.
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.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 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_key.pem in the current directory.
Note that, as from the Server Configuration guide,
server_key.pem file with the private key should be only readable and writable and only by the user PGX runs as;
openssl command usually sets these permissions at file creation, otherwise it suffices to run
chmod 600 server_key.pem
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
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.
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 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
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.
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.
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
--truststore command-line option. Similarly, you should specify the path to the keystore (
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.