This page describes how to secure communication between the Java Agent and these components using SSL:

• Controller: Before you configure the agent to communicate with the Controller through SSL, you must either use a SaaS Controller or configure the on-premises Controller to use SSL. See Gather SSL Configuration Details.
• Analytics Agent: Before you configure the agent to communicate with the Analytics Agent through SSL, you must Enable SSL for the Analytics Agent.

The Java Agent supports extending and enforcing the SSL trust chain when in SSL mode.

Gather SSL Configuration Details

In preparation to secure Java Agent communications through SSL, you need information about the SSL configuration of the Controller or the Analytics Agent:

• The SSL port:
  • For SaaS Controllers, the SSL port is 443.
  • For on-premises Controllers, the default SSL port is 8181, but you may configure the Controller to listen for SSL on another port.
  • You configure the port for the Analytics Agent using the ad.dw.http.port property. See Enable SSL for the Analytics Agent.
• The signature method for the certificates:
  
  • A publicly known certificate authority (CA) signed the certificate. This applies for DigiCert, Verisign, Thawte, and other commercial CAs.
  • A CA internal to your organization signed the certificate. Some companies maintain internal certificate authorities to manage trust and encryption within their domain.
  • The Controller or Analytics agent uses a self-signed certificate.

Establish Trust for the Controller SSL Certificate

To establish trust between the Java Agent and the Controller, you must import the root certificate for the authority that signed the Controller's certificate into the agent truststore.

1. Obtain the root certificate for the authority that signed the certificate for the Controller.
   

   1. For SaaS Controller deployments only: You can download the DigiCert root certificates from https://www.digicert.com/digicert-root-certificates.htm and the IdenTrust root certificate from https://www.identrust.com/identrust-commercial-root-ca-1. Ensure to include at least the following certificates:

      • • • • DigiCert Global Root CA
            • DigiCert Global Root G2
            • DigiCert Global Root G3
            • IdenTrust Commercial Root CA 1

   2. You must import only the Root CA Certificate into the Java SSL Trust Store because Host Certificates have a very short lifespan and change often. Trusting the Root CA Certificate ensures uninterrupted connectivity to the controller when the Host Certificate changes before expiry.

2. Run the Java keytool command to import the root certificate. The command creates the keystore in the versioned agent configuration directory if it does not exist:

   keytool -import -alias rootCA -file <root_certificate_file_name> -keystore <agent_home>/<version_number>/conf/cacerts.jks -storepass <truststore_password>

   For example:

   keytool -import -alias ControllerRootCA -file /usr/home/appdynamics/DigicertGlobalRootCA.pem -keystore /usr/local/appagent/4.3.0.0/conf/cacerts.jks -storepass MySecurePassword

   Make note of the truststore password, you need it to configure the Java Agent.

Enable SSL between the Java Agent and the Controller

Configure these system properties in the versioned controller-info.xml: <agent_home>/<version_number>/conf/controller-info.xml. See SSL Configuration Properties for full details on each property.

• Controller Port: The SSL port for the controller. 443 for SaaS.

  <controller-port>443</controller-port>

• Controller SSL Enabled: true. 

  <controller-ssl-enabled>true</controller-ssl-enabled>

• Controller Keystore Password: The plaintext password for the agent truststore.

  <controller-keystore-password>MySecurePassword</controller-keystore-password>

  If you enabled the Secure Credential Store, encrypt the password and enter it here. See Encrypt Agent Credentials.

• Controller Keystore Filename: Path of the agent truststore relative to <agent home>/<version>/conf. Required if you use a truststore other than the default <agent_home>/<version_number>/conf/cacerts.jks.

  <controller-keystore-filename>../../conf/cacerts.jks</controller-keystore-filename>

  You can also configure these system properties in the JVM startup script. See Java Agent Configuration Properties.

Restart the JVM after you complete the configuration changes.

Sample Controller-info.xml with SSL and Secure Credential Store Encryption Enabled

<?xml version="1.0" encoding="UTF-8"?>
<controller-info>
    <controller-host>mycompany.saas.appdynamics.com</controller-host>
    <controller-port>443</controller-port>
    <controller-ssl-enabled>true</controller-ssl-enabled>
    <!-- Encrypted Controller keystore / agent trust store password -->
    <controller-keystore-password>Tw49bd0hdCMBoQ5pfMMuYA/cA5B4pouVPkv48ovRm6c=</controller-keystore-password>
    <controller-keystore-filename>../../conf/cacerts.jks</controller-keystore-filename>
    ...
    <!-- Secure Credential Store configuration -->
    <!-- Enable the Secure Credential Store -->
    <use-encrypted-credentials>true</use-encrypted-credentials>
    <!-- Path to they secure credential keystore -->
    <credential-store-filename>/opt/appdynamics/secretKeyStore</credential-store-filename>
    <!-- Obfuscated secure credential keystore password -->
    <credential-store-password>n/8GvAZsKk4gM3Z6g+XQ1w==</credential-store-password>
</controller-info>

Establish Trust for the Analytics Agent SSL Certificate

To establish trust between the Java Agent and the Analytics Agent, you must import the root certificate for the authority that signed the Analytics Agent's certificate into the agent truststore.

1. Obtain the root certificate for the authority that signed the certificate for the Analytics Agent.

2. Run the Java keytool command to import the root certificate into the JRE truststore.

   keytool -import -trustcacerts -alias analytics-agent -file <root_certificate_file_name> -keystore $JAVA_HOME/jre/lib/security/cacerts

   For example:

   keytool -import -trustcacerts -alias analytics-agent -file /usr/home/appdynamics/MyAnalyticsCert.crt -keystore $JAVA_HOME/jre/lib/security/cacerts

Establish Trust for Analytics without an Analytics Agent

You can retrieve Transaction Analytics data through Java Agent >= 4.5.16 without the need for a dedicated Analytics Agent. In this deployment model, the Java Agent communicates with the Events Service directly. 

If you use a custom trust store for the Java Agent, you need to establish trust with the Events Service to enable Transaction Analytics without an Analytics Agent. These commands demonstrate how to import the Events Service certificate to the Java Agent trust store:

• Using a signed certificate:

  keytool -import -trustcacerts -v -alias events_service -file /path/to/CA-cert.txt -keystore cacerts.jks

• Using a self-signed certificate:

  keytool -import -v -alias events_service -file events_service.crt -keystore cacerts.jks

If you do not establish trust for the private certificate, you cannot retrieve Transaction Analytics data through your Java Agent. Any applications and business transactions you have configured for Transaction Analytics cannot be enabled if the Java Agent cannot communicate with the Events Service. 

You can override this behavior using the -Dappdynamics.force.default.ssl.certificate.validation property. See Java Agent Configuration Properties for details. 

Enable SSL Between the Java Agent and the Analytics Agent

To enable the Java Agent to access the Analytics Agent over SSL, configure the appdynamics.analytics.agent.url system property for the JVM.

• Use the HTTPS protocol.

• Use the Analytics Agent SSL port. The port should be the same value as the Analytics Agent ad.dw.http.port property. See Enable SSL for the Analytics Agent. 
  

  -Dappdynamics.analytics.agent.url=https://<analytics_agent_host>:<analytics_agent_port>/v2/sinks/bt

  For example:

  java -javaagent:/home/appdynamics/agent/javaagent.jar -Dappdynamics.controller.hostName=mycontroller.example.com -Dappdynamics.controller.port=8090 -Dappdynamics.analytics.agent.url=https://my.analytics.host.example.com:9090/v2/sinks/bt -Dappdynamics.agent.applicationName=ACMEOnline -Dappdynamics.agent.tierName=Inventory -Dappdynamics.agent.nodeName=Inventory1 ACMEOnline.jar

  Restart the JVM after you complete the configuration changes.

Secure the Java Agent Truststore

To prevent tampering with the Java Agent truststore, you should:

• Secure the truststore file through filesystem permissions:

  • Make the agent truststore readable by any user.

  • Make the truststore owned by a privileged user.

  • Make the truststore writable only by the specified privileged user.

• Secure the agent configuration files so that they are only readable by the agent runtime user and only writable by a privileged user:

  • Versioned configuration file: <agent_home>/<version_number>/conf/controller-info.xml.

  • Global configuration file: <agent_home>/conf/controller-info.xml.

Keystore Certificate Extractor Utility

The Keystore Certificate Extractor Utility exports certificates from the Controller's Java keystore and writes them to an agent truststore. It installs to this location:

<agent_home>/<version_number>/utils/keystorereader/kr.jar

To avoid copying the Controller keystore to an agent machine, you can run this utility from the Controller server. Access the agent distribution on the Controller at this location:

<controller_home>/appserver/glassfish/domains/domain1/appagent

1. Execute kr.jar and pass these parameters:
   

   • The full path to the Controller's keystore:

     <controller_home>/appserver/glassfish/domains/domain1/config/keystore.jks

   • The truststore output file name. By default, the agent looks for a Java truststore file named cacerts.jks in the <agent_home>/<version>/conf directory in the agent home. 

   • The password for the Controller's certificate, which defaults to "changeit". If you don't include a password, the extractor applies the password "changeit" to the output truststore.

     /<full path to application JRE>/bin/java -jar kr.jar <controller_home>/appserver/glassfish/domains/domain1/config/keystore.jks cacerts.jks <controller_certificate_password>

2. Install the agent trust store to the versioned agent configuration directory:

   <agent_home>/<version_number>/conf/

Configure the Java Agent for FIPS Compliance

1. Rename the existing secure credential keystore file.

2. Initialize a new secure credential keystore using the Secure Credential Store (SCS) utility.
   The SCS utility is available at:  <javaagent_home>/verX.X.X.X/utils/scs/scs-tool.jar.

3. Run the Secure Credential Store utility generate_ks command with the following parameters:

   • filename: Absolute path where the utility will create the secure credential keystore. Use this path for <credential-store-filename> in agent configuration.
   • storepass: The secure credential keystore password. Use the obfuscated version of this password as the value for <credential-store-password> in agent configuration.
     

   • format (For FIPS-compliant users only): The format of the secure credential keystore. 

   java -jar scs-tool.jar generate_ks -filename '<>/secretKeyStoreFIPS' -storepass 'MyCredentialStorePassword' -format FIPS

   The Secure Credential Store utility confirms the creation and initialization of the keystore.
   

   Successfully created and initialized new KeyStore file: /opt/appdynamics/secretKeyStore Verification - New KeyStore file: /opt/appdynamics/secretKeyStoreFIPS is properly initialized.

   
   

4. Run the following command to obfuscate the plain text password.
   

   java -jar scs-tool.jar obfuscate -plaintext 'MyCredentialStorePassword'

   The output is an encrypted string that looks like s_-001-12-5pA2yIp3rZY=zIgMiWjtFhMRAtpN4FI6U12PRVghqTpnFHmTN7Rh6HY=.

5. Run the following command using the obfuscated password from Step 4 to encrypt the actual Controller account access key. 

   java -jar scs-tool.jar encrypt -filename '<>/secretKeyStoreFIPS’ -storepass ’<output_from_step_above>‘ -plaintext '<controller_account_access_key>' -format FIPS

   The output is an encrypted string that looks like -001-24-mEE2dy63UbE/u93idMxfew==JZgvmqT/+OddN+sLH43mx145FNoducIM44qeYczBnc5tbUoay3x8qc/Z3pDlGC4C.

   
   

6. Modify the controller.xml file using the outputs of Step 4 and Step 5. The following is an example of the controller.xml file.
   

   <controller-info> <controller-host><controller_url></controller-host> <controller-port><port></controller-port> <controller-ssl-enabled><true/false></controller-ssl-enabled> <enable-orchestration>false</enable-orchestration> <use-simple-hostname>false</use-simple-hostname> <use-encrypted-credentials>true</use-encrypted-credentials> <!-- Full qualified path name for the SCS-KeyStore file name. --> <credential-store-filename><path</secretKeyStoreFIPS</credential-store-filename> <!-- Password for the 'Secure Credential Store' (SCS). This password must be obfuscated. --> <credential-store-password><obfuscated_password></credential-store-password> <credential-store-format>FIPS</credential-store-format> . . . This account-access-key must be encrypted if 'use-encrypted-credentials' is set to true --> <account-access-key><encrypted_account_access_key></account-access-key>

Resolve SSL Issues

If you run into problems with the version of TLS/SSL, see SSL Compatibility between Java Agent and Controller and Cisco AppDynamics Agent SSL Protocol.