API Client Certificates

When API clients connect to RoboServer over SSL, RoboServer will verify the certificates presented to it (provided that the "Verify API Client Certificates" checkbox is checked). Verification means that RoboServer will reject connections from clients that fail verification, and is done based on two sets of trusted certificates: The set of root certificates and an additional set of API client certificates.

The root certificates are installed with Kapow Katalyst just as root certificates are installed with your browser. They are found in the Certificates/Root folder in the application data folder. These are the same root certificates which are used for checking HTTPS certificates; however, root certificates probably will play a much smaller role when verifying API clients.

This is because in most cases, you will create your own self-signed API client certificates rather than use (expensive) certificates issued by official signing authorities. You should install your API client certificates in the Certificates/API/TrustedClients folder in the application data folder so that RoboServer will recognize them.

Technically speaking, it does not matter - for the purpose of verifying connecting API clients - whether you add API client certificates to the set of root certificates or to the set of API client certificates. However the guidelines given above will help you avoid problems caused by the fact that the root certificates are also (even mainly) used when checking HTTPS certificates.

You can generate a self-signed certificate for your API client with the Java keytool command as follows:

keytool -genkey -keystore client.p12 -alias client -keyalg RSA -storetype "PKCS12"

You will be prompted for the following information: Name (domain), name of Organizational Unit, Organization, City, State, Country and password. Do not forget the password, there is no way to retrieve it if lost. This call of keytool will put the certificate into the keystore client.p12. You then must extract it into a separate file:

keytool -export -keystore client.p12 -alias client -storetype "PKCS12" -file client.pub.cer 

You will be prompted for the password used when the certificate was generated. The output file client.pub.cer is what should be copied into the Certificates/API/TrustedClients folder in the application data folder.