Pivotal Knowledge Base


Encrypting system properties used by Pivotal tc Server 2.x or 3.x

This article provides information on how an administrator can extend the existing functionality to obfuscate passwords in tc Server so that system properties can be obfuscated as well.

Many organizations have a security policy that states that passwords and sensitive information must not be stored in plain text. This presents a problem for tc Server administrators who frequently need to specify passwords or other sensitive information in text-based configuration files.  Fortunately, tc Server provides an enhanced security mechanism that enables an administrator to obfuscate this sensitive information. However, this functionality extends only to a specific subset of the files located in the tc Server's configuration directory.
For more information on this functionality, see 2.9.x or 3.0.x.

One specific case not covered by the out-of-the-box obfuscation mechanism is specifying system properties.  In general, system properties do not contain sensitive information; however, there are some corner cases where a password will need to be specified as a system property.  A good example of this is when specifying a keystore or truststore to the JVM.  When doing this an administrator will need to specify system properties that indicate both the keystore and the password for the keystore. With tc Server, system properties like the keystore password are set in the bin/setenv.sh file or, for Windows users, the conf/wrapper.conf file, and since these particular files does not, by default, allow obfuscated information, the keystore password would need to be specified in plain text.


These instructions allow you to enable tc Server to obfuscate system properties, such as those specified in the bin/setenv.sh file or, for Windows users, the wrapper.conf file. Additional details about the process can be found in the Additional Information section of this article.


  1. Create a tc Server instance, if you do not already have one: 
    ./tcruntime-instance.sh|bat create -t bio myTestInstance
  2. Download the attached JAR file, systemPropertyDecoder.jar, and place it into the lib directory of your tc Server instance. The JAR file contains both the class and source code for the SystemPropertyDecoderListener. For more information on manually compiling the class, see the Additional Information section of this document.
  3. Open the conf/server.xml file.  Locate the group of Listener tags toward the top of the file and add the following Listener tag to the beginning of that group.
    <Listener className="com.springsource.support.catalina.listener.SystemPropertyDecoderListener" />
  4. Open the bin/setenv.sh file or, for Windows users, open the conf/wrapper.conf file. Locate the system property you want to obfuscate.  Change the value of that property from the plain text value to tcEnc:// followed by the obfuscated value for that property.

    The obfuscated value can be found by using the PropertyDecoder packaged with tc Server. Instructions on its usage can be found at one of the following links. 

      Base64 Encoding  and Encrypt with Passcode  2.9.x or 3.0.x

  5. Restart the tc Server instance. It should now accept the obfuscated system properties.

If you experience any issues where it appears that a value is not being properly decoded, confirm that a value is being decoded by enabling logging for the SystemPropertyDecoderListener. This additional logging indicates which system properties are being examined by the Listener and which properties are being decoded and the decoded value.

To enable additional logging, simply modify the conf/logging.properties file, add the following at the bottom of the file, and restart your tc Server instance.

   com.springsource.support.catalina.listener.SystemPropertyDecoderListener.level = FINE

This is debug level logging and results in the decoded values of your system properties being printed to the log file. Enabling this additional logging in a production environment is not recommended, as it may result in a leak of sensitive information.


As indicated, the example code included with this article will decode or decrypt any obfuscated system properties and store the plain text value back into the system property.  This means that while the values of system properties stored in the bin/setenv.sh or conf/wrapper.conf files are obfuscated, once tc Server has been initialized and our example code has run, the plain text value for the system properties is available by calling System.getProperty().  As an administrator, you need to be aware that any web application deployed to the tc Server instance can retrieve the system property by simply calling System.getProperty().

For additional information about securing a tc Server instance, see the General Security Best Practices section at the following link.

   2.9.x or 3.0.x

Additional Information

Explanation of the Solution

The resolution documented in this article works by creating a custom Tomcat Lifecycle Listener.  This is a custom Java class that can be registered with tc Server in the conf/server.xml file.  Once registered, the class will receive a notification for each of the Lifecycle events in tc Server.  The attached class is setup as a listener, but actually decodes properties in a static block on the class.  This ensures that the decoding is done as early as possible, prior to other code trying to access the system properties.

The decoding process itself is simple.  The code iterates through all of the system properties and decodes any properties that contain the key tcEnc://.  Once the property is decoded, the Listener sets the system property to the decoded value, making it available for use by tc Server and applications deployed to tc Server.

The listener does not actually perform the decoding; rather it calls out to the same class that is used by tc Server to decode configuration properties, com.springsource.tcserver.security.KeyDecoder.  Because the listener is utilizing the KeyDecoder class, it does not require any additional configuration settings, but uses the same configuration settings used by tc Server's out-of-the-box obfuscation.

Instructions for Manual Compilation

This section contains instructions for manually compiling the SystemPropertyDecoderListener.
  1. Download the systemPropertyDecoder JAR file attached to this article, and place it into the lib directory of your tc Server instance.
  2. Open a terminal and change directories to the lib directory of your tc Server instance.
  3. Extract the source code from the JAR file with this command.
    jar xvf systemPropertyDecoder.jar com/springsource/support/catalina/listener/SystemPropertyDecoderListener.java
  4. Delete the systemPropertyDecoder JAR file.
  5. Run this command to compile the code.

    Linux / Unix
    javac -classpath ../../tomcat-7.0.50.C.RELEASE/bin/tomcat-juli.jar:../../tomcat-7.0.50.C.RELEASE/lib/catalina.jar:../../tomcat-7.0.50.C.RELEASE/lib/tcServer.jar com/springsource/support/catalina/listener/SystemPropertyDecoderListener.java
    javac -classpath ../../tomcat-7.0.50.C.RELEASE/bin/tomcat-juli.jar;../../tomcat-7.0.50.C.RELEASE/lib/catalina.jar;../../tomcat-7.0.50.C.RELEASE/lib/tcServer.jar com/springsource/support/catalina/listener/SystemPropertyDecoderListener.java
    This command will work for tc Server 2.9.5.SR1.  If you are using a different version, then you'll need to adjust the version numbers in the command (i.e. tomcat-7.0.50.C.RELEASE) to coincide with the version number of the Tomcat runtime that is installed on your system.

    This command also assumes that you have installed your tc Server instance within the tc Server installation directory.  If you created your tc Server instance using the -i option, to specify an alternate installation location, you'll need to replace the relative path markers in the above command with the full path to the required resources.
After you execute the last command you should see a file SystemPropertyDecoderListener.class located in the lib/com/springsource/support/catalina/listener directory.  If this file is present, then the class has been compiled successfully.

If you run the command above and receive compilation errors, you likely do not have the correct paths specified for the -classpath argument.  This argument needs to reference tomcat-juli.jar, catalina.jar and tcServer.jar.  All three of these JAR files can be found under the Tomcat Runtime directory located within the tc Server installation directory.

©VMware 2013


Powered by Zendesk