Setting up HTTPS in Elvis 5 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.
Note: This step needs to be done on every node you want to access using HTTPS.
Step 1. Access the HTTPS Setup Helper page in the Elvis Server Admin pages.
Step 1a. Access the admin pages by doing one of the following:
- Enter the following URL:
- On the Elvis Server console, click Server admin page
Step 1b. Click Https setup in the menu bar.
Step 2. Follow the instructions on screen.
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:
Info: This feature requires Elvis Server 5.25 or higher.
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:
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 5 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).
- OS X: Add the following line just above the -jar argument in /Library/LaunchDaemons/com.dutchsoftware.elvis.server.launchd.plist.
- 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
- 23 May 2017: Added section 'Redirecting HTTP to HTTPS'.