Connecting to SSL services

In certain situations it might be necessary to connect to an external service via SSL, e.g.

  • connecting to an LDAP server over SSL
  • connecting to an SMTP server over SSL

For external services, not hosted in the own company, this normally shouldn't pose a problem, however most of the time those services are hosted in-house an therefore use an own certificate issued by a certificate authority (CA) which is also hosted locally within the company and therefore is not trusted on the world wide web, because they are only used by local clients.

Java (which PowerFolder is written in) uses an own key-store / trust store, which contains a list of all known CA certificates which are used to issue public certificates, like commonly used for public websites and other services secured by SSL.

If we take a look at the certificate used for our public websites, we will notice that the certificate *.powerfolder.com has been signed by the certificate intermediate certificate Go Daddy Secure Certification Authority. This intermediate certificate has been signed by the root certificate Go Daddy Class 2 Certification Authority. Those two certificates are referred to as certificate chain and are included in the Java key-store, since they are widely used in the world wide web and should therefore be trusted. Another possibility would be to add the certificate itself in to the key-store, which would have the connecting application trust the certificate.

Now when using either a self-signed certificate which haven't been signed by a CA at all or when using a certificate chain which is not included in the trust store, Java (an PowerFolder) will not trust those certificates. When using a normal web browser to access a SSL secured site, this will not pose a problem, because usually web browsers will let you access sites using those certificates on a more or less difficult way (maybe with a warning). However when it comes to Java there is no way for the program connecting to services using those certificates to ignore the non-trusted status without changing the code to ignore and raising a possible security issue (e.g. for man in the middle attacks).

Therefore we will show you how to add your own self-signed certificates or certificates issued and signed by your own CA to the Java key-store.

Overview:

 

Obtaining a server's public certificate

To obtain the certificate used by a SSL protected service:

  1. Download and start the Portacle application to manage Java key-stores and certificates. (warning) Since this is a third-party tool, we can't provide any support for it. Furthermore you need to have a Java 7 Runtime Environment installed to run the portacle.jar file.
  2. Click on Examine and then on Examine SSL/TLS Connection.
  3. Enter the hostname and port of the SSL protected service you want to connect to.
  4. The application will now show further information about the certificate used by the service. Click on PEM Encoding to show the certificate itself.
  5. Click on Save to save the certificate to a temporary location. Make sure you replace .pem with .cer as the extension to save.

Now you have a copy of the server's public certificate. Next we need to import that certificate to the cacerts key-store file.

Importing a server's public certificate to the Java keystore

Since we always include the latest Java Runtime Environment (JRE) in our server and client releases, you need to open the cacerts file coming with the JRE and import the certificate obtained before to that keystore file.

The steps below have to be repeated after every update of PowerFolder Server, because a PowerFolder Server update will also update/replace the Java Runtime Environment with the latest version available at the time of the release!

Location of the cacerts file

  • On Windows operating systems: %PROGRAMFILES%\PowerFolder.com\PowerFolder-Server\jre\lib\security
  • On Linux operating systems: $SERVER_INSTALL/jre32/lib/security or $POWERFOLDER_INSTALL/jre64/lib/security (replace $SERVER_INSTALL with the path to the PowerFolder Server installation directory)

Password of the cacerts file

By default the cacerts file is protected with the password "changeit" (without the quotation marks).

Importing a certificate to the cacerts files

To import the certificate to the cacerts key-store file:

  1. Download and start the Portacle application to manage Java key-stores and certificates. (warning) Since this is a third-party tool, we can't provide any support for it. Furthermore you need to have a Java 7 Runtime Environment installed to run the portacle.jar file.
  2. Click on File and then Open Keystore File.
  3. Click on Tools and then Import Trusted Certificate.
  4. Select the certificate exported above and confirm that you trust it. Enter an alias for it which fits the purpose (e.g. powerfoldermail or powerfolderldap).
    (info) There may be an error message telling you that the trust path could not be established. Ignore it and click on OK.
  5. Click on File and then Save to save the changes to your cacerts file.
  6. Replace the cacerts file delivered with the Java Runtime Environment with the one just modified.
  7. Restart PowerFolder Server.
  8. Test the connection to the SSL service.