Keystores configuration#

Server, agents, and agent relays keystores are used for a secured web communication between servers and agents.

Web agents come with and use public-key pinning for strong security. Agents and servers identify each other with SSL certificates. The public keys in the certificates are pinned on the initial connection. When a public key is pinned, any certificate that asserts the same identity must be generated with the same public and private key pair that was used to create the original certificate. Connections from clients or servers that do not correctly identify themselves are closed.

Server keystores#

Server keystore locations are defined in the installed.properties file.

Server keystore Description
agentcomm.keystore The keystore contains the certificate and public and private key pair that the server uses to identify itself as the client. Keys are stored in the serverInstallDir/conf/server/s2s-client-identity.keystore file. These keys are not shared in high-availability environments. The server uses its web certificate to identify itself as the server in a connection. The subject DN must be in this format: CN=ucd-server-EndpointID.
encryption.keystore Server property encryption secret keys are stored in the serverInstallDir/appdata/conf/encryption.keystore file. These keys are shared in high-availability environments.
tomcat.keystore The keystore points to server UI/API HTTP server certificate and key. Keys are stored in the serverInstallDir/opt/tomcat/conf/tomcat.keystore file. These keys are not shared in high-availability environments.

Important: Do not lose the server public/private key. Recovery requires manually clearing the server certificate pins for every web agent. To help prevent loss, make a secure backup of all server keystores.

To override any of the server keystore passwords, see Changing passwords for the server KeyStore.

Agent keystores#

Agents store pinned server public keys in the agentInstalldir/conf/agent/pinned-server-public-keys folder. Keys are stored as certificates in Privacy Enhanced Mail (PEM) formatted files. The filename corresponds to the hostname in the certificate DN, but hostnames that contain characters that are not universally safe have more complex encoding. Certificates written here typically originate from the server's appdata/conf/server.keystore file

Agent keystore Description
encryption.keystore Agent property encryption secret keys are stored in agentInstallDir/conf/encryption.keystore file. These keys are shared in high-availability environments.

Web agent relay keystores#

Each agent relay contains two keystores. The agentrelay keystore controls the web connection between the agent relay and the server and agents. The codestation keystore controls HTTPS connections to the agent relay and is used with server identity verification. See Enabling server identity verification.

The agentrelay keystore stores web agent communication client certificate and keys (alias ucd-agentrelay-id). The subject DN must be in this format: CN=ucd-agentRelay-EndpointID.

Note: For more information about changing relay keystore password, see Changing passwords for the agent relay keystores

Parent topic: Web agent configuration