SSL Client Connections

To establish SSL connections from Horizon to monitored nodes, you need to set up a Java Truststore. The truststore should contain all certificates that Horizon needs to verify trust when making connections when polling or collecting.

Horizon will use the system truststore for your Java installation. Since any changes to that truststore may be overwritten if Java is upgraded or reinstalled, you can specify a custom truststore to use.

Set up Java Truststore

Use the following command to set up the Java Truststore.

Import a certificate to the Java Truststore

keytool \
  -import \ (1)
  -v \ (2)
  -trustcacerts \ (3)
  -alias localhost \ (4)
  -file localhost.cert \ (5)
  -keystore ${OPENNMS_HOME}/etc/trust-store.jks  (6)

1	Define certificate or a certificate chain import.
2	Use verbose output.
3	Trust certificates from `cacerts`.
4	The alias for the certificate to import; for example, the common name.
5	The certificate to import.
6	The location of the Java Truststore. If this file doesn’t exist, it will be created.

If you create a new Java Truststore, you must provide a password to protect it. If you updated an existing Java Truststore, type the password you chose when you first created the Java Truststore.

Download existing public certificate (optional)

Use the following command to download an existing public certificate, if needed.

Download an existing public certificate

openssl \
  s_client \ (1)
  -showcerts \ (2)
  -connect localhost:443 \ (3)
  -servername localhost \ (4)
  < /dev/null \ (5)
  > localhost.cert (6)

1	Use SSL/TLS client functionality of `openssl`.
2	Show all certificates in the chain.
3	PORT:HOST to connect to; for example, localhost:443.
4	Optional. If you are serving multiple certificates under one IP address, you may define a server name; otherwise, the `ip of localhost`:PORT certificate is returned, which may not match the requested server name (`mail.domain.com`, `opennms.domain.com`, `dns.domain.com`).
5	No input
6	Where to store the certificate.

Configure Horizon to use the defined Java Truststore

To set up Horizon to use the defined Java Truststore, you must set the applicable javax.net.ssl.trustStore* properties. Edit or create ${OPENNMS_HOME}/etc/opennms.properties.d/ssl.properties and add the properties as shown below.

${OPENNMS_HOME}/etc/opennms.properties snippet to define a Java Truststore

javax.net.ssl.trustStore=${OPENNMS_HOME}/etc/trust-store.jks
javax.net.ssl.trustStorePassword=change-me

For more details on the Java built-in SSL system properties, see Debugging/Properties.

Each time you modify the Java Truststore, you must restart Horizon services for the changes to take effect.

Differences between Java Truststore and Java Keystore

The Java Truststore determines whether a remote connection should be trusted; in other words, whether a remote party is who it claims to be (client use case).

The Java Keystore decides which authentication credentials should be sent to the remote host for authentication during SSL handshake (server use case).

For more details, see the link: JSSE Reference Guide.

Debugging/Properties

If you encounter issues while using SSL, it might be useful to enable debug logging or use one of the built-in Java System Properties to configure the proper use of SSL.

Table 1. Java built-in System Properties
System Property Name	Description
javax.net.ssl.keyStore	Location of the Java keystore file that contains an application process’s own certificate and private key.
javax.net.ssl.keyStorePassword	Password to access the private key from the keystore file `javax.net.ssl.keyStore` specifies. This password is used twice: to unlock the keystore file (store password) and to decrypt the private key stored in the keystore (key password). The JSSE framework requires these passwords to be identical.
javax.net.ssl.keyStoreType	(Optional) Keystore type. Defaults to `jks`.
javax.net.ssl.trustStore	Location of the Java Truststore file that contains the collection of CA certificates this application process (truststore) trusts. If this property does not specify a truststore location, the Java implementation searches for and uses a keystore file in the following locations (in order): `${JAVA_HOME}/lib/security/jssecacerts` and `${JAVA_HOME}/lib/security/cacerts`.
javax.net.ssl.trustStorePassword	Password to unlock the truststore file.
javax.net.ssl.trustStoreType	(Optional) Truststore type. Defaults to `jks`.
javax.net.debug	(Optional) To switch on logging for the SSL/TLS layer, set this property to ssl. For more details about possible values, see debugging utilities.