Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 6. 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

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

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

Procedure

  • Enter the following command as the root user: 

    dnf install jws6-tomcat-vault
    Copy to Clipboard Toggle word wrap

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

Prerequisites

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
    Copy to Clipboard Toggle word wrap
    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.

6.4. Creating a Java keystore in JBoss Web Server
Copy link

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

Important

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

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
    Copy to Clipboard Toggle word wrap

    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.

    Note

    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.

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 DNF package manager, the tomcat-vault.sh script is located in the /opt/rh/jws6/root/usr/bin directory.

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/jws6/root/usr/bin directory.

  2. Run the tomcat-vault.sh script: 

    $ ./tomcat-vault.sh
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

    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.

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/jws6/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
    Copy to Clipboard Toggle word wrap

    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.

6.6. Configuring Tomcat to use the password vault
Copy link

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/
    Copy to Clipboard Toggle word wrap
    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.

6.7. External password vault configuration
Copy link

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.

Note

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

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/jws6/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
    Copy to Clipboard Toggle word wrap
    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.

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"/>
    Copy to Clipboard Toggle word wrap

    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"/>
    Copy to Clipboard Toggle word wrap
    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.

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top