Custom trust stores

A trust store defines the roots of the certificate trust chain. Typically, these are the certificate authority root certificates that sign other certificates. It can also be end entity certificates that are directly trusted. Java includes a default trust store that contains certificate authority root certificates for many well-known authorities. This trust store is a file called cacerts and is contained in the Java installation. The file has the same format as a keystore, but it never contains a private key. It is possible to modify or replace this file to alter the trust roots with the keytool program. If this is undesirable, a custom trust store must be used instead. It is even possible to copy cacerts and modify the copy to expand the set of trust roots.

Custom server trust stores

The server is similar to the agent, but has potentially two custom trust stores depending on the role of the server in the connection. The trust stores are independent, and can be selectively enabled, or both can be configured to share the same trust store file. The server trust stores are configured in the serverInstallDir/conf/server/installed.properties file.

When the server is in the server role, it authenticate clients, which are both agents and other servers in the same cluster. The property verify.client.identity must be set to true. By default, the default cacerts trust store is used. The is no hostname verification step because client certificates do not contain a hostname. Set agentcomm.serverTruststore to the path of the trust store file. Set agentcomm.serverTruststore.password to the trust store file password (changeit by default). Unlike the agent, the password property is stored in secured-installed.properties with other passwords. Note that we configure the trust store for the server role, but that server verifies the identity of clients. This explains the asymmetry in the names of this group of properties. When the server is in the client role, the naming is reversed.

When the server is in the client role, it only verifies the identity of the other server members of its cluster. The property verify.server.identity must be set to true. Again, cacerts is used by default. As it is in the client role, a hostname verification step is also performed. Set the properties agentcomm.clientTruststore and agentcomm.clientTruststore.password as with the server trust store.

Custom agent trust stores

For web agent communication, the agent permits a custom trust store for validating connections to the server. The agent trust stores are configured in the agentInstallDir/conf/agent/installed.properties file. For the custom trust store to take effect, the property verify.server.identity must be set to true. This property is generally configured by the installer. However, it can be set without configuring a custom trust store. By default, setting this property uses the default cacerts trust store. It also performs an extra hostname verification on the server certificate, which is the same as in a Web browser. A custom trust store is configured by setting agentcomm.truststore property to the path of trust store file, and setting agentcomm.truststore.password property to the keystore file password. If the pasword is not set, it defaults to changeit.

Custom relay trust stores

Agent relays have no custom trust store support for web agent communication as it does not participate in authenticating communications.