By default, the keystore password is stored as plain text in the Tomcat server configuration file used by DPA (DPA-install-dir/iwc/tomcat/conf/server.xml). This article describes how to store an encrypted keystore password that Tomcat can understand and decrypt when you start the DPA server in HTTPS mode.

See the following sections to download the password encryption utility, encrypt the password, and update the configuration file with the encrypted password.

Prerequisites

Before encrypting the password, you must:

• Download the encryption utility.

  Go to the Customer Portal and download the Tomcat server.xml Keystore Password Encryption DPA Utility.

• Have a valid certificate that is or can be used for SSL enablement in the Tomcat server configuration.

  You can either use the default .keystore file found in DPA-install-dir/iwc/tomcat/conf/, or you can use a server-specific CA certified custom certificate. For more information on using a custom certificate, see Configure DPA to use a custom certificate for SSL/TLS.

• Make sure that the $JAVA_HOME path is set to the JDK installation directory.

Encrypt the password and update the configuration file

Complete the following steps to encrypt the password and update the configuration file.

Note: Whenever you change the password for the keystore file or the certificate stored in the keystore file, repeat these steps to encrypt the new password and replace it in the server.xml file.

1. Stop DPA.

2. Make a backup copy of the following files:

   • DPA-install-dir/iwc/tomcat/conf/server.xml
   • DPA-install-dir/iwc/tomcat/conf/.keystore or the custom certificate used in your environment

   If a problem occurs during this procedure, you can use the backup files to restore your earlier configuration.

3. Copy the downloaded password encryption utility (swdpa-ksencrypt-util-1.0.0.zip or swdpa-ksencrypt-util-1.0.0.tar.gz) into the following folder, and extract the files:

   DPA-install-dir/iwc/tomcat/lib

4. Open a command prompt, and change the directory to DPA-install-dir/iwc/.

5. Run the following command to encrypt the keystore password. Replace keystore_password with your keystore password.

   • For Windows:

     java -jar tomcat\lib\swdpa-customutil-1.0.0.jar keystore_password

   • For Linux:

     java -jar tomcat/lib/swdpa-customutil-1.0.0.jar keystore_password

   When the password is encrypted, the console displays the following message:

   Success: Encrypted String for 'keystore_password' is 'encrypted_keystore_password'.

   Note: If you are using a different password for the certificate stored in the keystore file, you can encrypt that password as well using the same command.

6. Open the Tomcat server configuration file in a text editor:

   DPA-install-dir/iwc/tomcat/conf/server.xml

7. Comment out the HTTPS connector node.

   Note: XML comments begin with <!-- and end with -->.

   For example (configuration with the default .keystore file):

   <!--
       <Connector port="8124" maxHttpHeaderSize="20480" URIEncoding="UTF-8" 
           scheme="https" secure="true" SSLEnabled="true"
           clientAuth="false" useServerCipherSuitesOrder="true" 
           compression="on" compressionMinSize="2048" compressableMimeType="text/html,text/xml,text/csv,text/css,application/javascript"
           keystoreType="PKCS12"
           keystoreFile="conf/.keystore"
           sslEnabledProtocols="TLSv1.2+TLSv1.3"
           ciphers="HIGH:!SHA1:!SHA256:!SHA384:!RSA:!DHE"
       />
   -->

8. Add the following connector node just below the connector node you commented out.

   • Replace encrypted_keystore_password with the encrypted string returned in step 5.

   • If you are using a different password for the certificate stored in the keystore file, you can use the certificateKeyPassword attribute and replace the encrypted_cert_password_if_needed with the encrypted string returned in step 5 for the certificate password.

   • Replace the values for other attributes (such as port, ciphers, protocols, certificateKeystoreFile, certificateKeystoreType, and others as needed) with the appropriate values from your earlier configuration.

   <Connector port="8124" maxHttpHeaderSize="20480" URIEncoding="UTF-8" 
           scheme="https" secure="true" SSLEnabled="true" compression="on"
           compressionMinSize="2048" 
           protocol="com.solarwinds.dpa.util.CustomHttp11Nio2Protocol">
           <SSLHostConfig ciphers="HIGH:!SHA1:!SHA256:!SHA384:!RSA:!DHE"
               protocols="TLSv1.2+TLSv1.3">
               <Certificate certificateKeystoreFile="conf/.keystore" 
                   certificateKeystoreType="PKCS12" 
                   certificateKeystorePassword="encrypted_keystore_password"
                   certificateKeyPassword="encrypted_cert_password_if_needed"/>
           </SSLHostConfig>
       </Connector>

9. Save the file, and restart DPA.

10. Check the following file for any errors:

    DPA-install-dir/iwc/tomcat/logs/catalina*.log

    If the log does not contain severe errors, the Tomcat server successfully decrypted the keystore password.

    If the log contains keystore password decryption errors, see the Troubleshooting section below.

Troubleshooting

Issue: The following error message occurs when you attempt to encrypt the keystore password:

Unable to access jar

Resolution: Make sure the utility path is OS-specific, and execute following command in the DPA installation directory.

• For Windows:

  $ cd DPA-install-dir\iwc

  $ java -jar tomcat\lib\encryptdecryptutil.jar keystore_password

• For Linux:

  $ cd DPA-install-dir/iwc

  $ java -jar tomcat/lib/encryptdecryptutil.jar keystore_password

Issue: The following error message occurs during server startup:

java.lang.IllegalArgumentException: keystore password was incorrect

Resolution:

1. Verify that the existing connector node is replaced correctly. See steps 7 and 8 in the previous procedure.

2. Verify that the certificateKeyPassword attribute has the correct value. See step 8 in the previous procedure.