Setting up HTTPS in Elvis 6 Server

Communication between the server and the clients in Elvis are all HTTP-based and is not encrypted by itself.

For internal Elvis setups this provides the best performance. Most data is transmitted by using the binary AMF protocol, which by nature makes it hard to read, although there are tools available to parse it.

To create a secure connection you need to set up HTTPS. This is done by using the HTTPS Setup page in Elvis.

Note: This step needs to be done on every node that you want to access using HTTPS.

Step 1. Access the Elvis HTTPS Setup page by doing one of the following:

• For Elvis 6.16 or higher: access the Management Console and in the menu on the left, choose Tools > HTTPS tools.

• For Elvis 6.15 or lower: access the Admin pages and choose 'Https setup' in the menu bar.

Step 2. Follow the instructions on the page.

Tip: If the password for the key differs from the Keystore Password you will need to manually change the httpsKeyManagerPassword property in the config.properties.txt file.

Redirecting HTTP to HTTPS

By default, when a domain name is typed into a Web browser, the browser will try to connect to that domain over HTTP. However, when HTTPS is configured, you typically want the server to redirect the Web browser to HTTPS so that the user always connects over a secure connection.

To make the Elvis nodes redirect HTTP to HTTPS, perform the following steps:

Step 1. Ensure that the Elvis node is set up for HTTPS as explained above.

Step 2. Add the following setting to the cluster-config.properties.txt file on all of the nodes:

redirectHttpToHttps=true

Step 3. Restart the Elvis service.

Note: More and more customers are running Elvis on Amazon AWS and on HTTPS. AWS CloudFront can redirect HTTP to HTTPS automatically, but an AWS load balancer does not have such a setting. When only using an AWS load balancer, the Elvis nodes will need to provide the redirect from HTTP to HTTPS.

HTTPS setup using an existing key pair

These steps can be used to convert an already signed Apache private and public key pair for use with Elvis.

Step 1. Create a .txt file file with a chain of your certificate with all intermediaries, down to the root certificate.

Note: Depending on which CA you used, you may need to merge not just your own crt and the root crt, but also one or more intermediate .crt files.

cat yourdomain.crt intermediate.crt [intermediate2.crt] rootCA.crt > cert-chain.txt

Step 2. Create a pkcs12 file from the key and certificate chain.

openssl pkcs12 -export -inkey yourdomain.key -in cert-chain.txt -out jetty.pkcs12

Step 3. Import the produced .pkcs into a new keystore.jks file.

keytool -v -importkeystore -srckeystore jetty.pkcs12 -srcstoretype PKCS12 -destkeystore keystore.jks

Note: The keytool command comes bundled with the Java JDK. Make sure to use the one from Java 1.6 or 1.7.

If you want to use a different alias or password in the src and dest keystores, make sure to specify additional arguments:

-srcstorepass -srckeypass -srcalias -destalias -destkeypass -deststorepass.

Step 4. Place the produced 'keystore.jks' in the Config folder.

Step 5. Find out the name of the alias. If you followed the previous steps, this alias will probably be '1'.

keytool -v -list -keystore keystore.jks

Step 6. Configure the following settings in the cluster-config.properties.txt file.

Note: For information about how to edit this file, see Changing the Elvis 6 Server configuration for a running cluster.

Important: To obscure the password, use the Jetty tools.

#
# Use the HTTPS setup tool on the Elvis server admin page.
#
httpsEnabled=true

#
# Password of the keystore
#
httpsKeyStorePassword=OBF:...

#
# Password of the key stored in the keystore
# Useful if the password is different from the keystore password
#
httpsKeyManagerPassword=OBF:...

#
# Alias/name of the certificate stored in the keystore
#
httpsCertAlias=1

Step 7. Restart Elvis Server.

Common issues when setting up HTTPS

If the keystore.jks is not properly set up, HTTPS connection will fail. Sadly, the errors logged do not always provide much clarification on what is going wrong. Common causes are:

• Incorrect certificate chain in the server keystore.jks
• Invalid key algorithm used for private key
• Expired certificate or expired CA certificate
• Incorrect password used to access the keystore.jks
• Multiple private keys to choose from
• Mismatching alias name in config.properties.txt and keystore.jks

See also Smartjava.org: How to analyze Java SSL errors

To get more logging about the SSL handshake in the Elvis Server log, add the following JVM parameter:

• Windows: Add the following extra line to C:\Program Files\Elvis Server\elvis-service\elvis-service.conf (make sure to use a free number).

wrapper.java.additional.8=-Djavax.net.debug=ssl:handshake

• OS X: Add the following line just above the -jar argument in /Library/LaunchDaemons/com.dutchsoftware.elvis.server.launchd.plist.

<string>-Djavax.net.debug=ssl:handshake</string>

• Linux: Add the following line to /srv/elvis-server/app/wrapper/conf/wrapper.conf (make sure to use a free number):

wrapper.java.additional.8 = -Djavax.net.debug=ssl:handshake