Configuring SSL

Using SSL (Secure Sockets Layer) encrypts transmissions between web browsers and PageSeeder to provide extra security. To do this, you need to create a private key, create a certificate by having your public key signed by yourself or a certificate authority, and then install both on your proxy server or in Tomcat.

Create private key

If not done already, install OpenSSL by entering:

$ yum install openssl

Create a private key by entering the following command. Make sure you can remember the passphrase you are asked for as you need it at another time.

$ openssl genrsa -des3 -out mydomain.key 2048

Create SSL certificate

Create a certificate signing request as follows:

$ openssl req -new -key mydomain.key -out mydomain.csr

This command prompts for fields that need to be filled in.

The most important field is “Common Name” which is the domain name of your server. If you want the certificate to cover multiple sub-domains, you can use *.mycompany.com.

You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:AU
State or Province Name (full name) [Some-State]:NSW
Locality Name (eg, city) []:Sydney
Organization Name (eg, company) [Internet Widgits Pty Ltd]:ACME Inc
Organizational Unit Name (eg, section) []:My Department
Common Name (e.g. server FQDN or YOUR name) []:myserver.mycompany.com                  
Email Address []:webmaster@mycompany.com

Certificate authority signs your certificate

To ensure web browsers accept your certificate without warning messages, you need to send your CSR file to a Certificate Authority to have it signed. They typically return to you an individual CRT file for your domain and a bundle CRT file containing their own certificates. These need to be concatenated in the correct order, for example:

$ cat mydomain_individual.crt ca_bundle.crt > mydomain.crt

Self-sign your SSL certificate

Alternatively, for testing, you could sign the certificate yourself but it is only accepted by web browsers after warning the user. You can specify how long the certificate remains valid by changing the 365 to the number of days you prefer.

To create a self-signed certificate, you could enter:

$ openssl x509 -req -days 365 -in mydomain.csr -signkey mydomain.key -out mydomain.crt

Install certificate

NGINX

If you are using NGINX as a reverse proxy for PageSeeder, you need to install your certificate there and configure NGINX accordingly.

Remove the key passphrase

To install an SSL certificate on NGINX, it is easier to first remove the passphrase. Though the passphrase does provide extra protection, removing it saves you from having to re-enter the passphrase every time NGINX is restarted. To do this, use the following commands:

$ mv mydomain.key mydomain.key.orig
$ openssl rsa -in mydomain.key.orig -out mydomain.key

Configure NGINX

Copy the key and certificate to NGINX as follows:

$ mkdir -p /etc/nginx/ssl/pageseeder
$ cp mydomain.key /etc/nginx/ssl/pageseeder/
$ cp mydomain.crt /etc/nginx/ssl/pageseeder/

Modify the nginx.conf file as described in Configuring a proxy and restart the “nginx” service.

Tomcat

If you aren’t using a proxy like NGINX and your website port is larger than 1024 (e.g. 8443), you can configure Tomcat to use SSL as follows:

Create a KEYSTORE or JKS file using the Java keytool utility.
PageSeeder includes a self-signed certificate for localhost under pageseeder/webapp/WEB-INF/config/pslocalhost.keystore (password pslocalxyz) which can be used for testing.

Obtain an SSL certificate for your server's domain name from a certificate provider,or self-sign it, and add it to your KEYSTORE file. Then, copy it to your server and make sure you know your keystore password.

Stop your PageSeeder service if it is running and:
start the pageseeder-[version].exe for Windows,
or enter pageseeder service config for Linux.

Follow the installer prompts and select “Enable SSL”.

When prompted, enter the path to your SSL certificate keystore file and its password.

For “List of ports to redirect from” (Windows only), you can add other ports that your PageSeeder was previously using, so that users are automatically redirected to use SSL (e.g. 80,8080).

Finish the installation.

Converting existing .keystore or .jks to .key

If you have existing KEYSTORE or JKS files that you need to use with NGINX, they can be converted using the Java keytool and openssl as follows:

$ keytool -importkeystore -srckeystore mydomain.jks -destkeystore mydomain.p12 - srcstoretype jks -deststoretype pkcs12
$ openssl pkcs12 -in mydomain.p12 -nocerts -out mydomain.pem
$ openssl rsa -in mydomain.pem -out mydomain.key

Adding .key and .crt to .p12 file

If you need to bundle the .key and .crt files into a .p12 file you can use the following openssl command:

$ openssl pkcs12 -export -out mydomain.p12 -inkey mydomain.key -in mydomain.crt