Setting up HTTPS in Elvis 4 Server
Client/server communication is all HTTP based and not encrypted by itself. For internal Elvis setups this provides the best performance. Most data is transmitted 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 setup HTTPS.
Note: On Elvis 5.x, this step needs to be done on every node you want to access using HTTPS.
Use the HTTPS Setup Helper page in the server admin pages to set up your secure connection. All the steps are explained in the interface.
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.
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 with a chain of your certificate with all intermediaries, down to the root certificate. 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 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
keytool -v -importkeystore -srckeystore jetty.pkcs12 -srcstoretype PKCS12 -destkeystore keystore.jks
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.
Place the produced 'keystore.jks' in the Config folder.
Step 4. 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
Now open the config.properties.txt, and adjust the settings.
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
For the full set of https settings and their default values see the .
Finally, restart the server to apply the changes.
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:
- 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, you have to 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