Configuring Voyager to run in HTTPS/SSL mode

Running Voyager in HTTPS/SSL requires creating a Java keystore and server.dex files in the Voyager data/config folder. This is accomplished with the following high-level steps, which are described in more detail below.

1. Create a Java keystore in ${voyager.data.dir}/config/

2. Create a server.dex file in ${voyager.data.dir}/config/

3. Change Voyager's base URL to HTTPS

4. Change the URL of a reference base map to HTTPS

Create a Java keystore

You can create a Java keystore with your own self-signed certificate or import existing PKCS#12, PFX or PEM certificates into the keystore. Choose from the steps below (1.1, 1.2 or 1.3) based on the type of certificate you are going to import.

Once you have imported the certificate into the Java keystore, copy the keystore file into the  ${voyager.data.dir}/config/ directory.

Create a Java keystore with your own self-signed certificate

• To create your own keystore with a self-signed certificate, enter the following command:

  $ keytool -genkey -keyalg RSA -alias selfsigned -keystore keystore.jks -storepass password -validity 360 -keysize 2048

Import PKCS#12 and PFX certificates into a Java keystore

• To import a PKCS#12 certificate into a Java keystore, enter the following command:

  $ keytool -importkeystore -srckeystore <pkcsfile.p12> -srcstoretype pkcs12 -keystore <keystorefile.jks> -storepass <password>

• To import a PFX certificate into a Java keystore, enter the following command:
  $ keytool -importkeystore -srckeystore <pfxfile.pfx> -srcstoretype pkcs12 -keystore <keystorefile.jks> -storepass <password>

Import a PEM certificate into a Java keystore

• First, export the PEM certificate and key into the PKCS#12 file using openssl (http://www.openssl.org/related/binaries.html):
  $ openssl pkcs12 -inkey <file.key> -in <file.crt> -export -out <pkcsfile.p12>

• Then import the PKCS#12 into the keystore by running:
  $ keytool -importkeystore -srckeystore <pkcsfile.p12> -srcstoretype pkcs12 -keystore <keystorefile.jks> -storepass <password>

Create a server.dex file

Create a server.dex file in ${voyager.data.dir}/config/ folder containing the following parameters (see the sample server.dex bellow):

ssl_port
ssl_key_store_path
ssl_key_store_password
ssl_key_manager_password
ssl_trust_store_path
ssl_trust_store_password

You can use a sample server.dex file stored in ${voyager.install.dir}/app/util/ssl/server.dex

Passwords in server.dex must be encoded. To encode passwords, run the following command from  the ${voyager.install.dir} folder. (Replace jetty-util-xxx.jar with your current version, e.g. jetty-util-9.2.13.v20150730.jar):

“jre/bin/java.exe” -cp app/lib/jetty-util-xxx.jar org.eclipse.jetty.util.security.Password <my-password>

Sample server.dex

#if this exists, it will load SSL
ssl_port = 8443
# path is relative to ${config.dir}

ssl_key_store_path = keystore.jks
ssl_key_store_password = OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1v
ssl_key_manager_password = OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1v
ssl_trust_store_path = keystore.jks
ssl_trust_store_password = OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1v 

Change Voyager's base URL to HTTPS

In the Voyager Manage UI go to Manage > Settings > Appearance and click Edit to change the Voyager URL to HTTPS, e.g. https://my-voyager-server:8443/

Open

Change the URL of the Referenced Base Map to HTTPS

In the Voyager Manage UI, go to Manage > Settings > Mapping and change the map URL from HTTP to HTTPS.

Open