How can we help?

My Cases

Add a Third-Party SSL Certificate to the ESS Trust Store
Last Updated: Nov 09, 2017 04:51PM EST

This article applies to:  Echo360 Admins


This article explains how to configure the ESS to make secure connections with systems using third-party SSL certificates.


Secure websites all use something called SSL (secure sockets layer) to establish the encryption that secures the traffic. In order for this to be possible, the web server needs to offer an SSL certificate, a small document that performs two functions: it provides the encryption keys for the transport layer security and a trust chain so that a client can easily verify the site's identity.

In most implementations of servers with public-facing sites, the trust chain ends with a root CA (certification authority), which people commonly know as the company you must pay to have a certificate "signed." All Web browsers and some Web-enabled applications are distributed with their own libraries of trusted root CA certificates so that they can validate the trust chain; It's like saying, "I know Alice (because everyone knows Alice), and Alice vouches for Bob, and Bob's signature matches what Alice says it ought to be, so this must be Bob I'm dealing with."

This trust chain, however, is not always implemented completely or correctly. In these cases, the root CA is left out, or another unknown CA is there instead. Instead of Alice vouching for Bob, Bob is vouching for himself; maybe Zeke (someone you know even less about) is vouching for him. In these cases, the certificate is still good for encryption, but there is no way of knowing that the website belongs to the people to whom it claims to belong. This is a problem, since the ESS doesn't establish encrypted connections with untrusted peers.


In the common case where an institution is issuing SSL certificates from their own CA it is necessary to instruct the ESS to trust that CA in order for it to make secure connections to systems using certificates issued by it:

  1. Open a command line on the ESS server.
    • On Windows enter:
      cd C:\Program Files\Echo360\Server
      jre\bin\java.exe -jar lib\ess-command.jar InstallCert --host hostname [--port port]
    • On Linux enter:
      cd /usr/local/echo360/server
      jre/bin/java -jar lib/ess-command.jar InstallCert --host hostname [--port port]
    Replace hostname with the address of the server with the certificate to import and port with the number the remote server is listening on (this is only required if it happens to be something other than 443).
  2. The program may present more than one certificate to you, each representing one of the certs in the target host's trust chain. The program assigns each certificate a number, and prompts to select which one to import. Start at the top of the chain -- with the Root CA -- and repeat the process stepwise working down the chain if the CA alone isn't enough to enable communication.
  3. Restart the ESS service.


When executing the InstallCert class, be aware of what user account is being used. The truststore that this class edits (a file located, by default, at ${ESS_HOME}/echo360/server/jre/lib/security/cacerts, although you may have defined an alternate location in your configuration files) will become owned by that user. To avoid permissions issues later on, either switch to the user account that runs the ESS or be careful to set ownership back to the original user so that the ESS can read it. If the ESS cannot open this file, a Java exception will be thrown on every access attempt and will be seen in the server's application logs: the trustAnchors parameter must be non-empty.
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found