Changing security certificates on Synthetic TEA Agents

By default, TEA Agents use pregenerated, self-signed certificates for authentication with App Visibility Manager. You can use your own custom certificates.

You can update certificates before installing your TEA Agents, or you can update certificates on TEA Agents that are already installed.

• To update certificates before installing TEA Agents, follow the instructions in To create the custom certificate folder in the TEA Agent installer.
• To update certificates for previously installed TEA Agents, follow the instructions in To replace security files on previously installed TEA Agents.

This topic contains the following sections:

• • Before you begin
  • To create the custom certificate folder in the TEA Agent installer
  • To test the connection to your App Visibility portal
  • To replace security files on previously installed TEA Agents
  • To encrypt a keystore passphrase
  • Related topics

Before you begin

• Install and configure App Visibility components.

• Install the TEA Agent.

• Prepare the following files and place them in a folder that is accessible to your TEA Agent computer:
  
  • keystoreFileName.jks, where keystoreFileName is your custom keystore file name
  • truststoreFileName.jks, where truststoreFileName is your custom truststore file name

To create the custom certificate folder in the TEA Agent installer

This procedure creates the ..\Disk1\files\security\custom folder. The custom certificate is then included in your TEA Agent installation. The files are also used by the installer and the other utilities on the TEA Agent for communicating with App Visibility components.

1. From the ..\Disk1\utility\ReplaceCertificateTool folder of your TEA Agent installer files, right-click the ReplaceCertificateTool batch file and select Run as administrator.
2. Enter 1 to select Create Certificate folder with the encrypted passphrase.

3. Enter the required parameters:

   The [liveData] macro is a standalone macro and it cannot be used inline. Click on this message for details.
   This macro generates standalone content. As a consequence you need to make sure to use a syntax that separates your macro from the content before and after it so that it's on a line by itself. For example in XWiki Syntax 2.0+ this means having 2 newline characters (a.k.a line breaks) separating your macro from the content before and after it.

   
   

   Note

   If your truststore and your keystore use different passwords, the certificate replacement tool displays a message saying JKS convert procedure failed. Exit the utility, check log for more information. If you see this message, change the truststore password to match the keystore password as follows:

   1. Run the keytool from the ..\Disk1\files\jre\bin\keytool.exe folder as follows.

      Example

      keytool -storepasswd -new <NewPwd> -keystore <truststore file name>

      NewPwd indicates the new password for your truststore, which must match the keystore password.

   2. Enter your original truststore password when prompted by the keytool to Enter keystore password.
   3. Restart the certificate replacement procedure.

   The certificate replacement utility:

   • Creates the ..\Disk1\files\security\custom folder
   • Creates .pem files for the TEA Agent
   • Encrypts the keystore passphrase
   • Creates the cert.properties file with the new .jks files, .pem files, and encrypted keystore passphrase
   • Puts the .pem files, .jks files, and cert.properties file in the custom folder
4. (Recommended) Perform the procedure in To test the connection to your App Visibility portal. 

To test the connection to your App Visibility portal

Perform the following test to check the connection to your App Visibility portal using the certificates in the ..\Disk1\files\security\custom folder.

1. From the ..\Disk1\utility\ReplaceCertificateTool folder of your TEA Agent installer files, right-click the ReplaceCertificateTool batch file and select Run as administrator.
2. Enter 2 to select Test connection to App Visibility.

3. Enter the required parameters or press Enter to accept the default values:

   The [liveData] macro is a standalone macro and it cannot be used inline. Click on this message for details.
   This macro generates standalone content. As a consequence you need to make sure to use a syntax that separates your macro from the content before and after it so that it's on a line by itself. For example in XWiki Syntax 2.0+ this means having 2 newline characters (a.k.a line breaks) separating your macro from the content before and after it.

   The certificate replacement tests the connection with the App Visibility portal.

To replace security files on previously installed TEA Agents

1. If you are running the TEA Agent as a process, stop the TEA Agent process. See Starting-and-stopping-a-synthetic-TEA-Agent-as-a-process for more details.
2. If you have not created the custom certificate folder, perform the steps in To create the custom certificate folder in the TEA Agent installer.
3. From the ..\Disk1\utility\ReplaceCertificateTool folder of your TEA Agent installer files, right-click the ReplaceCertificateTool batch file and select Run as administrator.
4. Enter 3 to select Apply custom certificate to TEA Agent.

5. Enter the required parameter or press Enter to accept the default values:

   The [liveData] macro is a standalone macro and it cannot be used inline. Click on this message for details.
   This macro generates standalone content. As a consequence you need to make sure to use a syntax that separates your macro from the content before and after it so that it's on a line by itself. For example in XWiki Syntax 2.0+ this means having 2 newline characters (a.k.a line breaks) separating your macro from the content before and after it.

   The certificate replacement utility:

   • Stops the TEA Agent service
   • Copies the .pem files and .jks files from the ..\Disk1\files\security\custom folder to your TEA Agent working folder
   • Updates the cert.properties file with your new certificates
   • Restarts the TEA Agent service
6. If you run the TEA Agent as a process, stop the TEA Agent service (which was started automatically by the certificate replacement utility), and restart the TEA Agent process. See Starting-and-stopping-a-synthetic-TEA-Agent-as-a-process for more details.

To encrypt a keystore passphrase

Use this procedure to encrypt your TEA Agent passphrase if you want to build a cert.properties file manually.

1. From the ..\Disk1\utility\ReplaceCertificateTool folder of your TEA Agent installer files, right-click the ReplaceCertificateTool batch file and select Run as administrator.
2. Enter 4 to select Keystore passphrase encryption only.

3. Enter the required parameter:

   The [liveData] macro is a standalone macro and it cannot be used inline. Click on this message for details.
   This macro generates standalone content. As a consequence you need to make sure to use a syntax that separates your macro from the content before and after it so that it's on a line by itself. For example in XWiki Syntax 2.0+ this means having 2 newline characters (a.k.a line breaks) separating your macro from the content before and after it.

   The certificate replacement tool displays the encrypted passphrase. Copy the passphrase and paste it where you need it.

Related topics

Security planning for Presentation Server

Starting-and-stopping-services

Changing-security-certificates-in-App-Visibility-componentsReplacing security certificates in BMC PATROL for Application Management 10.5