Encoding Properties

Obfuscating Passwords in tc Runtime Configuration Files

The use of tcEnc:// and s2enc:// have been removed from tc Server 4.1.0. This document covers 4.1.0 and newer.

VMware tc Runtime stores its configuration files in the CATALINA_BASE/conf directory. The directory includes the following files:

  • context.xml
  • jmxremote.password
  • server.xml
  • web.xml

By default, passwords in these files are in cleartext. This is typically not a problem during development; however, when you move to production, you will probably want to protect these passwords for security reasons so that the actual password string does not show up in the configuration files.

Passwords appear in these configuration files in a variety of places. For example, as described in Configuring the High Concurrency JDBC Connection Pool, you use the <Resource> element of the server.xml file to configure a JDBC connection pool, and the element’s password attribute specifies the password of the user who connects to the database server, as shown in the following sample snippet of the server.xml file (only relevant parts shown):

<?xml version='1.0' encoding='utf-8'?>
<Server port="-1" shutdown="SHUTDOWN">
       <Resource name="jdbc/TestDB"
  <Service name="Catalina">

Another example is the jmxremote.password file that contains the password for the JMX username/role that a monitoring client uses to connect to the JMX server associated with the tc Runtime instance. By default, the password is in cleartext. The following example shows the out-of-the-box file in which the admin role has the password pivotal:

# The "admin" role has password "pivotal".
admin pivotal

The remainder of this section describes how to protect the password text in any of the tc Runtime configuration files located in the CATALINA_BASE/conf directory.

Important note on security

The choice of using term encoding to describe the process of obfuscating passwords with tc Server is important to understand. Unless the passphrase is being stored externally and entered upon instance startup the passphrase is stored somewhere readable by the tc Runtime instance. Because of this the terms encoding and obfuscation were choisen to describe this feature. No matter which algorithm/encoding technology is used the encoded values are only as secure as it is stored. The passphrase which must be accessible by the tc Runtime instance in order for tc Runtime to decode the value. This encoding feature is intended to mask plaintext values in properties files and doesn’t provide full encryption.

Encoding a Password

The tcserver script has an encode option that simplifies the basic usage of our PropertyDecoder as described below.

Usage of the command is as follows:

tcserver encode <instance name> [options]


  • <instance name> is the name of the instance to use. The catalina.properties file of the instance will be used for retrieving passphrase information and setting values. The command will output an encoded value which can be used in one of the supported configuration files described in this section.


tcserver encode instance -p mysql.db.password

The above example will look for an existing passphrase, if not found a random phrase will be generated, and then encode the value found for mysql.db.password and save it to instance’s catalina.properties

The “encode” command also supports decoding an encoded value with a known passphrase.

tcserver encode instance --value foo

The above example will look for an existing passphrase, if not found a random phrase will be generated, and then encode foo and display the value on the last line of output. Such as


This can then be saved in the inserted into the appropriate file such as jmxremote.password


  • By default /dev/random is used on Linux for randomness. In some cases this may cause the command to take a long time to complete. It is possible to override the java default by specifying the java.security.egd property. See the example below
JAVA_OPTS=-Djava.security.egd=file:/dev/./urandom tcserver encode foo bar

Being Prompted for the Passphrase When you Start the Instance

Storing the passphrase and encoded passwords on the local file system when using passphrase encoding is reasonably secure. However, some users may want to be prompted for the passphrase so that it does not appear in cleartext in any file at all.

Warning: This feature requires that you start the tc Runtime instance as a foreground process using the run option of the tcserver script on both Unix and Windows. On Unix, you can then put the process in the background. On Windows, however, this means that you cannot control the instance using the Windows Services console. For this reason, this feature is not practical for production use on Windows.

The following assumes that you have already generated an encoded value as described in Basic Encoding Usage and that you added it to your configuration file.

To be prompted for the passphrase when you start the tc Runtime instance, update the catalina.properties file and set the com.springsource.tcserver.security.PropertyDecoder.passphrase property to the value console.

For example (catalina.properties):


Storing Passphrases and Encoded Properties in Separate Files

Although storing the passphrase (when using passphrase encoding) and encoded passwords in the catalina.properties is reasonably secure, some users might prefer to store these values in separate files.

To store the passphrase in a separate file, replace the value of the com.springsource.tcserver.security.PropertyDecoder.passphrase property with the name of a file. You can use the ${catalina.base} variable to specify a directory relative to the CATALINA_BASE of the tc Runtime instance.

In the following sample snippet of catalina.properties, the passphrase is stored in a file called secure.file in the CATALINA_BASE/conf directory of the tc Runtime instance:


Create the secure.file file: it should contain a single line with the passphrase. For example:


Similarly, to store the actual encoded password in a separate file, replace the password variable (db.password in our example) in the catalina.properties file with a property called com.springsource.tcserver.security.PropertyDecoder.properties. Set this property to the name of a file that contains the password variable.

In the following sample snippet of catalina.properties, the encoded password is stored in a file called application.properties in the CATALINA_BASE/conf directory of the tc Runtime instance:


Create the application.properties file and add the original password variable. Following with our example, the file would include the following:


PBKDF2 Property Reference Table

This table lists system properties and their defaults. These properties may be set to override the default.

The property keys should be prefixed with com.springsource.tcserver.security.pbkdf2decoder. For example: Key securerandomalgorithm should be com.springsource.tcserver.security.pbkdf2decoder.securerandomalgorithm

Key Default Value
securerandomalgorithm SHA1PRNG
encryptionkeyspecalgorithm AES
ciphertransformation AES/CTR/NoPadding
iterations 65535
macalgorithm HmacSHA256
keyspecification PBKDF2WithHmacSHA1