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">
 ...
  <GlobalNamingResources>
       <Resource name="jdbc/TestDB"
            auth="Container"
            type="javax.sql.DataSource"
            username="root"
            password="mypassword"
            driverClassName="com.mysql.jdbc.Driver"
            url="jdbc:mysql://localhost:3306/mysql?autoReconnect=true"
        ...
  </GlobalNamingResources>
  ...
  <Service name="Catalina">
  ...
  </Service>
</Server>

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.

Encoding a Password

As of tc Server 3.2.0, 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]

Where

  • <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.

Examples

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

pbkdf2://BYpfwwvtZ4H8YRjTDFYKXcH3liVP2do7tUuUd3SSQHTv/2Vc44P6G/xQqV9dXpY1TEJ8L/d8JXHGmryEEg4FyRNUrfCKzuyY0pDJ

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

Notes

  • 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 encrypted passwords on the local file system when using passphrase encryption 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 Encryption 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):

org.apache.tomcat.util.digester.PROPERTY_SOURCE=com.springsource.tcserver.security.PropertyDecoder
com.springsource.tcserver.security.PropertyDecoder.passphrase=console
db.password=pbkdf2://BYpfwwvtZ4H8YRjTDFYKXcH3liVP2do7tUuUd3SSQHTv/2Vc44P6G/xQqV9dXpY1TEJ8L/d8JXHGmryEEg4FyRNUrfCKzuyY0pDJ

Storing Passphrases and Encrypted Properties in Separate Files

Although storing the passphrase (when using passphrase encryption) and encrypted 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:

org.apache.tomcat.util.digester.PROPERTY_SOURCE=com.springsource.tcserver.security.PropertyDecoder
com.springsource.tcserver.security.PropertyDecoder.passphrase=${catalina.base}/conf/secure.file
db.password=pbkdf2://BYpfwwvtZ4H8YRjTDFYKXcH3liVP2do7tUuUd3SSQHTv/2Vc44P6G/xQqV9dXpY1TEJ8L/d8JXHGmryEEg4FyRNUrfCKzuyY0pDJ

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

mypassphrase

Similarly, to store the actual encrypted 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 encrypted password is stored in a file called application.properties in the CATALINA_BASE/conf directory of the tc Runtime instance:

org.apache.tomcat.util.digester.PROPERTY_SOURCE=com.springsource.tcserver.security.PropertyDecoder
com.springsource.tcserver.security.PropertyDecoder.passphrase=${catalina.base}/conf/secure.file
com.springsource.tcserver.security.PropertyDecoder.properties=${catalina.base}/conf/application.properties

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

db.password=pbkdf2://BYpfwwvtZ4H8YRjTDFYKXcH3liVP2do7tUuUd3SSQHTv/2Vc44P6G/xQqV9dXpY1TEJ8L/d8JXHGmryEEg4FyRNUrfCKzuyY0pDJ