Appendix - Generate New Credentials for the Java Agent

Under some circumstances, you may find it necessary to generate new credentials for the Java AgentClosed The Java Agent, one of Keyfactor's suite of orchestrators, is used to perform discovery of Java keystores and PEM certificate stores, to inventory discovered stores, and to push certificates out to stores as needed.. This can happen, for example, if you make a change to the hostnameClosed The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername). of the machine on which the Java Agent is running. The credentials file stores the username and password for the service account user that allows the Java Agent to communicate with Keyfactor Command—the identity for the agent (see Create Service Accounts for the Java Agent)—encrypted with the hostname to prevent the file from being used on machines other than the machine on which the agent has been installed.

Log messages that indicate a new credentials file is needed look similar to the following:

2020-10-02 15:21:43.307 [Scheduler_Worker-1] ERROR com.css_security.cms.apache.http.HttpClientFactory - Given final block not properly padded. Such issues can arise if a bad key is used during decryption.
2020-10-02 15:21:43.307 [Scheduler_Worker-1] ERROR com.css_security.cms.apache.http.HttpClientFactory - Could not decrypt credentials file at config\install.creds
2020-10-02 15:21:43.526 [Scheduler_Worker-1] INFO  com.css_security.cms.apache.http.HttpClientFactory - Your machine key may have changed. Reencrypt credentials using local machine key.
2020-10-02 15:21:43.541 [Scheduler_Worker-1] INFO  com.css_security.cms.apache.http.HttpClientFactory - Generate new credentials by running included cms-credential-encryptor utility

To generate a new credentials file on Windows:

  1. Open a command prompt using the “Run as administrator” option.
  2. Change directories to the directory in which the Java Agent is installed. By default, this is:

    C:\Program Files\Keyfactor\Keyfactor Java Agent

  3. Type the following command to generate a new credentials file in the current directory:

    java -jar CSS.CMS.CredentialEncryptor.jar encode-basic install.creds

  4. Locate the existing credentials file in the config directory under the installed directory. By default, this is:

    C:\Program Files\Keyfactor\Keyfactor Java Agent\config

  5. Delete or name off the existing install.creds file in the config directory and copy the new install.creds file from the base install directory to the config directory.
  6. Restart the Java Agent service (see Start the Keyfactor Java Agent Service).
  7. Review the log messages to confirm that credential errors are no longer occurring (see Configure Logging for the Java Agent).

To generate a new credentials file on Linux:

  1. Open a command shell.
  2. Change directories to the directory in which the Java Agent is installed. By default, this is:

    /opt/keyfactor-java-agent

  3. As a user with rights to write to the current directory (or use sudo), type the following command to generate a new credentials file in the current directory:

    java -jar CSS.CMS.CredentialEncryptor.jar encode-basic install.creds

  4. Locate the existing credentials file in the config directory under the installed directory. By default, this is:

    /opt/keyfactor-java-agent/config

  5. Delete or name off the existing install.creds file in the config directory and copy the new install.creds file from the base install directory to the config directory.
  6. Restart the Java Agent service (see Start the Keyfactor Java Agent Service).
  7. Review the log messages to confirm that credential errors are no longer occurring (see Configure Logging for the Java Agent).