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 6.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-6.0.0-application-server.zip file. The password vault is located in the JWS_HOME /tomcat/lib/tomcat-vault.jar file. 6.2. Installing the password vault on RHEL by using the DNF package manager 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: 6.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 You have installed the password vault from an archive file or by using the DNF package manager . Procedure Stop Tomcat if it is already running. Open the JWS_HOME /tomcat/conf/catalina.properties file. 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. 6.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: 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 . 6.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: Interactive setup Noninteractive setup 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. 6.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 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. Run the tomcat-vault.sh script: Follow the on-screen prompts. For example: In the preceding example, replace the specified settings with values that are appropriate for your environment. Note the output for the Tomcat properties file. You need this information when configuring Tomcat to use the password vault. 6.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 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. Run the tomcat-vault.sh script and provide the required arguments: For example: 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 You can configure Apache Tomcat to use the password vault by updating configuration settings in the vault.properties file. Prerequisites You have initialized the password vault for Tomcat . Procedure Go to the JWS_HOME /tomcat/conf/ directory. Create a file named vault.properties . In the vault.properties file, enter the vault configuration properties that you specified when you initialized the password vault for Tomcat. For example: 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 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 10.1 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 Apache Tomcat 10: Introduction - Directories and Files Running The Apache Tomcat 10.1 Servlet/JSP Container : "Advanced Configuration - Multiple Tomcat Instances" 6.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 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. To use the tomcat-vault.sh script in noninteractive mode, enter the following command: 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 . 6.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 Open the Tomcat configuration file that contains the sensitive string. Replace the sensitive string with the attribute name for the string, and ensure that you enter the attribute name in the following format: USD{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=*"USD{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 .

Commands:
dnf install jws6-tomcat-vault
org.apache.tomcat.util.digester.PROPERTY_SOURCE=org.apache.tomcat.vault.util.PropertySourceVault
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
./tomcat-vault.sh
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
./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
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/
./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
<user username="manager" password=*"P@SSW0#D"* roles="manager-gui"/>
<user username="manager" password=*"USD{VAULT::my_block::manager_password::}"* roles="manager-gui"/>