Keystore configuration notes

Overview

This KB article covers some common keystore-related questions regarding configuring SymmetricDS to use SSL on top of HTTP for secure communication. Section 5.9 of the User's Guide includes details of how to generate keys, but some additional notes are below.

Background

The keystore file is kept on the root, and the cacerts file is kept on the client, and both have a password associated with them. In addition, the key itself, in the keystore, also has a password, which can be different than the keystore's if desired. Both of these files reside in the "security" subdirectory under the symmetricds install.

Notes

1. The key's CN -must- match the hostname or a wildcard version of the hostname. Using an IP Address isn't sufficient, at least for Java 1.6.

2. The keystore and key's password can be different. SymmetricDS needs the key's password on the root side, but neither the root nor the client need the keystore's / cacerts password. So, only one password is exposed, that of the key itself, and only on the root side (specified by -Djavax.net.ssl.keyStorePassword).

3. DNS lookup of the hostname at the client level is needed if a sync URL contains the hostname $(hostName) for the ssl to work (and, of course, to even connect to the server by hostname). If not, the fallback is to use a sync url with an ip address $(ipAddress) and include the https.verified.server.names= property with the ipaddress in symmetric.properties. Note that the key on the server still needs a CN of the hostname (as discussed above).