SSL Endpoint verification

When you create a new Cluster you can select that you want the communication with the RoboServers to be SSL encrypted, this prevents anyone from "listening" to the network and extracting critical information exchanged between the two parties.

In addition to encryption, SSL also offer endpoint validation. This is to ensure that you don't exchange critical information with a third party, either due to misconfiguration, or because you DNS has been hacked. For this to work you need to configure RoboServer to trust your Management Console and configure Management Console to trust your RoboServers.

This requires you to edit files inside ManagementConsole.war, so make sure you Tomcat server is not running when you perform this modification.

Certificates

You will need to create two certificates, one for Management Console and one for RoboServer, each certificate contains a private and a public key. Creating a certificate and exporting the public key is described here, in general it is a good idea to read the entire section of the help the discusses certificates, especially the section on API Client/Server certificates.

Endpoint verification can be separated into two parts, making RoboServer trust Management Console and making Management Console trust RoboServer, each of these are configured individually, and you don't have to configure both.

Making RoboServer trust Management Console

You now have to tell Management Console to use the private key when creating the SSL connection to RoboServer. This is done by modifying /WEB-INF/certs.xml found inside the WAR file. Here you will need to provide the location, and the password for the certificate, which could look like this:

<bean id="sslCertificationConfiguration" class="com.kapowtech.mc.config.SSLVerificationConfiguration">
                  ...
    <property name="privateCertificateLocation" value="file:///home/roboserver/client.p12"/>
    <property name="privateCertPassword" value="changeit"/>

</bean>

              

Management Console is now using it private key when establishing SSL connections, once Management Console's public key is deployed in RoboServer's /TrustedClients folder it will allow the RoboServer to verify that it is connected to the right Management Console. You can read about the /TrustedClients here Remember to enable Verify API Client Certificates in RoboServer Setting, and deploy the public key on all RoboServers in the cluster.

Making Management Console trust RoboServer

RoboServer already comes with a API certificate installed, so you have to create a new certificate and replace the pre-configured. First create the certificate as described above, then start RoboServer Settings and go to the Certificates tab, and click the change button, select the certificate, and enter the password when prompted. RoboServer will now use the new certificate when creating SSL connection with Management Console (and other API clients).

Now you need to configure Management Console to only trust SSL connections from RoboServers with the correct certificate. Like Management Console's client certificate this is (partly) configured in /WEB-INF/certs.xml, using the following two options:

<bean id="sslCertificationConfiguration" class="com.kapowtech.mc.config.SSLVerificationConfiguration">
    <property name="verifyRoboServerCert" value="true"/>
    <property name="checkHostName" value="true"/>
    ...
</bean>

              

The option for verifying RoboServer certificates is a simple boolean flag (true/false), this is because you have to import the RoboServers public key into the JRE's default keystore. The JRE's default keystore is a file named cacerts located at /jre/lib/security/.

To import RoboServer's public key into cacerts, you use use the following command:

keytool -import -alias RoboServer -keystore cacerts -trustcacerts -file server.pub.cer

You will be prompted for a password, which is changeit unless you have changed it. The alias will have to be unique, so if you created a separate certificate for each RoboServer, you will have to add a suffix. Also note that the references to cacerts and server.pub.cer are relative in this example.

The checkHostName option ensures that Management Console will only talk to the RoboServer if it presents the correct certificate AND is contacted using the hostname written inside the RoboServer's certificate. Note that localhost and 127.0.0.1 is not considered the same host when it comes to hostname checks.

Trouble Shooting

Trouble shooting can be quite hard as there is virtually no information available if SSL connections can't be established., but it is important to know that:

If Management Console can't connect to a RoboServer the following may help you troubleshoot: