Chapter 7. Using a password vault with Red Hat JBoss Web Server

The JBoss Web Server password vault, which is named tomcat-vault, is a PicketLink vault extension for Apache Tomcat. You can use the password vault to mask passwords and other sensitive strings, and to store sensitive information in an encrypted Java keystore. When you use the password vault, you can stop storing clear-text passwords in your Tomcat configuration files. Tomcat can use the password vault to search for passwords and other sensitive strings from a keystore.

Important

For more information about using the CRYPT feature with the password vault, see Using CRYPT.

Note

The Federal Information Processing Standard (FIPS) 140-2 does not support the password-based encryption that is provided by tomcat-vault. If you want to use password-based encryption on the JBoss Web Server host, you must ensure that FIPS is disabled. If you attempt to use tomcat-vault when FIPS mode is enabled, the following error message is displayed: Security Vault can’t be used in FIPS mode

7.1. Password vault installation from an archive file

When you install JBoss Web Server from an archive file, the password vault is installed automatically when you install the jws-5.7.0-application-server.zip file. The password vault is located in the JWS_HOME/tomcat/lib/tomcat-vault.jar file.

7.2. Installing the password vault on RHEL by using the YUM package manager

When you install JBoss Web Server on Red Hat Enterprise Linux from RPM packages, you can use the YUM package manager to install the password vault.

Procedure

  • Enter the following command as the root user: 

    yum install jws5-tomcat-vault

7.3. Enabling the password vault in JBoss Web Server

You can enable the password vault by adding a configuration property in the catalina.properties file.

Prequisites

Procedure

  1. Stop Tomcat if it is already running.
  2. Open the JWS_HOME/tomcat/conf/catalina.properties file.

  3. In the catalina.properties file, enter the following line: 

    org.apache.tomcat.util.digester.PROPERTY_SOURCE=org.apache.tomcat.vault.util.PropertySourceVault
    Note

    In the preceding example, replace JWS_HOME with the path to your JBoss Web Server installation. The paths shown in this example use a forward slash (/) for directory separators.

7.4. Creating a Java keystore in JBoss Web Server

Before you use the password vault, you must first create a Java keystore by using the keytool -genseckey command.

Procedure

  • Enter the following command: 

    $ keytool -genseckey \
 -keystore JWS_HOME/tomcat/vault.keystore \
 -alias my_vault \
 -storetype jceks \
 -keyalg AES \
 -keysize 128 \
 -storepass <vault_password> \
 -keypass <vault_password> \
 -validity 730
    Note

    In the preceding example, replace the parameter settings with values that are appropriate for your environment.

    For more information about each parameter, use the keytool -genseckey -help command.

Important

The password vault does not currently support the PKCS12 keystore type. The password vault supports the JCEKS keystore type only.

Depending on the keystore algorithm that you are using, you must specify one of the following keysize values:

  • If you are using AES, specify -keysize 128.
  • If you are using DES, specify -keysize 56.
  • If you are using DESede, specify -keysize 168.

7.5. Password vault initialization for Apache Tomcat

You can use the tomcat-vault.sh script to initialize the password vault for Apache Tomcat. The tomcat-vault.sh script supports either of the following mechanisms to initialize the password vault:

Note

Depending on how you installed the password vault, the location of the tomcat-vault script varies:

  • If you installed the password vault from an archive file, the tomcat-vault.sh script is located in the JWS_HOME/tomcat/bin directory.
  • If you installed the password vault by using the YUM package manager, the tomcat-vault.sh script is located in the /opt/rh/jws5/root/usr/bin directory.

7.5.1. Initializing password vault for Apache Tomcat interactively

You can initialize the password vault for Tomcat interactively. In this situation, the tomcat-vault.sh script prompts you to enter values while the script is running.

Procedure

  1. Go to the directory that contains the tomcat-vault.sh script:

    • If you installed the password vault from an archive file, go to the JWS_HOME/tomcat/bin directory.
    • If you installed the password vault from an RPM package, go to the /opt/rh/jws5/root/usr/bin directory.

  2. Run the tomcat-vault.sh script: 

    $ ./tomcat-vault.sh

  3. Follow the on-screen prompts.

    For example: 

    WARNING JBOSS_HOME may be pointing to a different installation - unpredictable results may occur.

=========================================================================

  JBoss Vault

  JBOSS_HOME: JWS_HOME/tomcat

  JAVA: java

=========================================================================

**********************************
****  JBoss Vault  ***************
**********************************
Please enter a Digit::
0: Start Interactive Session
1: Remove Interactive Session
2: Exit

0

Starting an interactive session
Enter directory to store encrypted files: JWS_HOME/tomcat/
Enter Keystore URL: JWS_HOME/tomcat/vault.keystore
Enter Keystore password: <vault_password>
Enter Keystore password again: <vault_password>
Values match
Enter 8 character salt: 1234abcd
Enter iteration count as a number (Eg: 44): 120
Enter Keystore Alias: my_vault
Initializing Vault
Jun 16, 2018 10:24:27 AM org.apache.tomcat.vault.security.vault.PicketBoxSecurityVault init
INFO: PBOX000361: Default Security Vault Implementation Initialized and Ready
Vault Configuration in tomcat properties file:
********************************************
...
KEYSTORE_URL=JWS_HOME/tomcat/vault.keystore
KEYSTORE_PASSWORD=MASK-3CuP21KMHn7G6iH/A3YpM/
KEYSTORE_ALIAS=my_vault
SALT=1234abcd
ITERATION_COUNT=120
ENC_FILE_DIR=JWS_HOME/tomcat/
...
********************************************
Vault is initialized and ready for use
Handshake with Vault complete
Please enter a Digit::
0: Store a secured attribute
1: Check whether a secured attribute exists
2: Exit

2

    In the preceding example, replace the specified settings with values that are appropriate for your environment.

  4. Note the output for the Tomcat properties file. You need this information when configuring Tomcat to use the password vault.

7.5.2. Initializing password vault for Apache Tomcat by using a noninteractive setup

You can initialize the password vault for Tomcat by using a noninteractive setup. In this situation, you must provide the required input as arguments to the tomcat-vault.sh script when you run the script.

Procedure

  1. Go to the directory that contains the tomcat-vault.sh script:

    • If you installed the password vault from an archive file, go to the JWS_HOME/tomcat/bin directory.
    • If you installed the password vault from an RPM package, go to the /opt/rh/jws5/root/usr/bin directory.

  2. Run the tomcat-vault.sh script and provide the required arguments:

    For example: 

    $ ./tomcat-vault.sh \
 --keystore JWS_HOME/tomcat/vault.keystore \
 --keystore-password <vault_password> \
 --alias my_vault \
 --enc-dir JWS_HOME/tomcat/ \
 --iteration 120 \
 --salt 1234abcd \
 --generate-config JWS_HOME/tomcat/conf/vault.properties

    In the preceding example, replace the specified settings with values that are appropriate for your environment.

Note

When you specify the -g, --generate-config option, the tomcat-vault.sh script also creates a vault.properties file that contains the specified properties.

7.6. Configuring Tomcat to use the password vault

You can configure Apache Tomcat to use the password vault by updating configuration settings in the vault.properties file.

Prerequisites

Procedure

  1. Go to the JWS_HOME/tomcat/conf/ directory.
  2. Create a file named vault.properties.

  3. In the vault.properties file, enter the vault configuration properties that you specified when you initialized the password vault for Tomcat.

    For example: 

    KEYSTORE_URL=JWS_HOME/tomcat/vault.keystore
KEYSTORE_PASSWORD=MASK-3CuP21KMHn7G6iH/A3YpM/
KEYSTORE_ALIAS=my_vault
SALT=1234abcd
ITERATION_COUNT=120
ENC_FILE_DIR=JWS_HOME/tomcat/
Note

The preceding example is based on the example vault settings in Initializing password vault for Apache Tomcat interactively.

For the KEYSTORE_PASSWORD setting, ensure that you use the masked value that was generated when you initialized the password vault.

7.7. External password vault configuration

You can store the vault.properties file for the password vault outside of the JWS_HOME/tomcat/conf/ directory. If you have already set a CATALINA_BASE/conf/ directory, you can store the vault.properties file in the CATALINA_BASE/conf/ directory.

For more information about setting the CATALINA_BASE directory, see the "Advanced Configuration - Multiple Tomcat Instances" section in Running The Apache Tomcat 9.0 Servlet/JSP Container on the Apache Tomcat website.

Note

The default location for CATALINA_BASE is JWS_HOME/tomcat/. This is also known as the CATALINA_HOME directory.

Additional Resources

7.8. Storing a sensitive string in the password vault

You can use the tomcat-vault.sh script to store sensitive strings in the password vault. You can run the tomcat-vault.sh script interactively or in a noninteractive mode.

When you add a sensitive string to the password vault, you must specify a name for the string. In this situation, the name of the string is called an attribute name, and the string itself is called a secured attribute.

Procedure

  1. Go to the directory that contains the tomcat-vault.sh script:

    • If you installed the password vault from an archive file, go to the JWS_HOME/tomcat/bin directory.
    • If you installed the password vault from an RPM package, go to the /opt/rh/jws5/root/usr/bin directory.

  2. To use the tomcat-vault.sh script in noninteractive mode, enter the following command: 

    $ ./tomcat-vault.sh \
 --keystore JWS_HOME/tomcat/vault.keystore \
 --keystore-password <vault_password> \
 --alias my_vault \
 --enc-dir JWS_HOME/tomcat \
 --iteration 120 \
 --salt 1234abcd \
 --vault-block my_block \
 --attribute manager_password \
 --sec-attr P@SSW0#D
Note

The preceding example is based on the example vault settings in Initializing password vault for Apache Tomcat interactively. The preceding example stores the sensitive string, P@SSW0#D, with the attribute name, manager_password.

When you run the tomcat-vault.sh script, you can optionally specify a vault block to store the password in. If you do not specify a block, the tomcat-vault.sh script creates a block automatically. The preceding example specifies a vault block named my_block.

7.9. Using a stored sensitive string in your Tomcat configuration

When you store a sensitive string in the password vault, you can refer to the attribute name rather than specify the actual string in your configuration files. By replacing a secured string with the attribute name for the string, you can ensure that the Tomcat configuration file contains only a reference to the password. In this situation, the actual password is stored in the password vault only.

Procedure

  1. Open the Tomcat configuration file that contains the sensitive string.

  2. Replace the sensitive string with the attribute name for the string, and ensure that you enter the attribute name in the following format: ${VAULT::block_name::attribute_name::}

    For example:

    Consider the following example file entry for the secured string, P@SSW0#D: 

    <user username="manager" password=*"P@SSW0#D"* roles="manager-gui"/>

    If the secured string, P@SSW0#D, has the attribute name, manager_password, replace the secured string with the following value: 

    <user username="manager" password=*"${VAULT::my_block::manager_password::}"* roles="manager-gui"/>
Note

The preceding example is based on the example settings in Storing a sensitive string in the password vault. The preceding example replaces a sensitive string, P@SSW0#D, with an attribute name, manager_password, that is in a block called, my_block.