Setting up HTTPS in Assets Server

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

For internal Assets Server 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 Assets Server.

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

Step 1. Access the Management Console and in the menu on the left, choose Tools > HTTPS tools.

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 Assets Server nodes redirect HTTP to HTTPS, perform the following steps:

Step 1. Ensure that the Assets Server 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 Assets Server service.

Note: More and more customers are running Assets Server 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 Assets Server 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 Assets Server.

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 and that it is configured to use TLS1.2 (see the Java documentation Diagnosing TLS, SSL, and HTTPS). Older versions of the TLS protocol are known to have security vulnerabilities associated with them; their use it not recommended.

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 Assets Server configuration for a running cluster.

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

#
# Use the HTTPS setup tool on the Assets 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 Assets 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 Assets 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

• macOS: 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 the configuration file that is applicable to your version of Assets Server:

Note: Make sure to use a free number.

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

For Assets Server 6.60 and higher:

/srv/elvis-server/app/wrapper/conf/wrapper_custom.conf

For Assets Server 6.59 and lower:

/srv/elvis-server/app/wrapper/conf/wrapper.conf