Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

18.6. Password Vaults for Sensitive Strings

18.6.1. Password Vault System

Configuration of JBoss EAP and associated applications requires potentially sensitive information, such as usernames and passwords.
The Password Vault provides a feature to mask the password information and store it in an encrypted keystore. You can include references of the encrypted keystore in Management CLI commands or applications. The Password Vault uses the Java Keystore as its storage mechanism. The Password Vault consists of two parts: storage and key storage. Java Keystore is used to store the key, which is used to encrypt or decrypt sensitive strings in Vault storage.
Report a bug

18.6.2. Configure and Use Password Vault

The masked keystore password feature provided in Password Vault provides the option to obtain the masked keystore password from Password Vault, which is stored on the JBoss EAP server. The Password Vault uses the Java Keystore as its storage mechanism.

Procedure 18.7. Basic steps to configure and use Password Vault

  1. Setup a Java Keystore to store key for password encryption.
    For information on creating a keystore, refer Section 18.6.4, “Create a Java Keystore to Store Sensitive Strings”.
  2. Initialize the Password Vault.
    For information on masking the password and initialize the password vault, refer Section 18.6.5, “Initialize the Password Vault”.
  3. Store a Sensitive String in the Password Vault.
    For information on storing sensitive string in Password Vault, refer Section 18.6.8, “Store a Sensitive String in the Password Vault”.
  4. Configure JBoss EAP 6 to use the Password Vault.
    For information on configuring JBoss EAP 6 to use the Password Vault, refer Section 18.6.6, “Configure JBoss EAP 6 to Use the Password Vault”. For custom implementation, refer Section 18.6.7, “Configure JBoss EAP 6 to Use a Custom Implementation of the Password Vault”.

    Note

    To use an encrypted sensitive string in configuration, refer Section 18.6.9, “Use an Encrypted Sensitive String in Configuration”.
    To use an encrypted sensitive string in an application, refer Section 18.6.10, “Use an Encrypted Sensitive String in an Application”.
    To verify a sensitive string in Password Vault, refer Section 18.6.11, “Check if a Sensitive String is in the Password Vault”.
    To remove a sensitive string from Password Vault, refer Section 18.6.12, “Remove a Sensitive String from the Password Vault”.
Report a bug

18.6.3. Obtain Keystore Password From External Source

You can also the use the EXT, EXTC, CMD, CMDC or CLASS methods in Vault configuration for obtaining the Java keystore password. 
<vault-option name="KEYSTORE_PASSWORD" value="[here]"
The description for the methods are listed as:
  • {EXT}...: Refers to the exact command, where ‘…’ is the exact command. For example: {EXT}/usr/bin/getmypassword --section 1 --query company, run the /usr/bin/getmypassword command, which displays the password on standard output and use it as password for Security Vault's keystore. In this example, the command is using two options: --section 1 and --query company.
  • {EXTC[:expiration_in_millis]}...: Refers to the exact command, where the '...' is the exact command line that is passed to the Runtime.exec(String) method to execute a platform command. The first line of the command output is used as the password. EXTC variant caches the passwords for expiration_in_millis milliseconds. Default cache expiration is 0 (zero), meaning items in the cache never expire. For example: {EXTC:120000}/usr/bin/getmypassword --section 1 --query company Verify if cache contains /usr/bin/getmypassword output, if it contains the output then use it. If it does not contain the output, run the command to output it to cache and use it. In this example, the cache expires in 2 minute (120000 milliseconds).
  • {CMD}... or {CMDC[:expiration_in_millis]}...: The general command is a string delimited by ',' where the first part is the actual command and further parts represents the parameters. The comma can be backslashed to keep it as a part of the parameter. For example, {CMD}/usr/bin/getmypassword,--section,1,--query,company
  • {CLASS[@jboss_module_spec]}classname[:ctorargs]: Where the '[:ctorargs]' is an optional string delimited by the ':' from the classname is passed to the classname ctor. The ctorargs is a comma delimited list of strings. For example, {CLASS@org.test.passwd}org.test.passwd.ExternamPassworProvider. In this example, we load org.test.passwd.ExternamPassworProvider class from org.test.passwd module and use the toCharArray() method to get the password. If toCharArray() is not available use toString() method. The org.test.passwd.ExternamPassworProvider class must have the default constructor.
Report a bug

18.6.4. Create a Java Keystore to Store Sensitive Strings

Prerequisites

  • The keytool utility, provided by the Java Runtime Environment (JRE). Locate the path for the file, which on Red Hat Enterprise Linux is /usr/bin/keytool.

Warning

JCEKS keystore implementations differ between Java vendors so you must generate the keystore using the keytool utility from the same vendor as the Java development kit you use.
Using a keystore generated by the keytool from one vendor's Java development kit in a JBoss EAP instance running on a Java development kit from a different vendor results in the following exception: 
java.io.IOException: com.sun.crypto.provider.SealedObjectForKeyProtector

Procedure 18.8. Set up a Java Keystore

  1. Create a directory to store your keystore and other encrypted information.

    Create a directory to store your keystore and other important information. The rest of this procedure assumes that the directory is EAP_HOME/vault/. Since this directory will contain sensitive information it should be accessible to only limited users. At a minimum the user account under which JBoss EAP is running requires read-write access.

  2. Determine the parameters to use with keytool utility.

    Decide on values for the following parameters:
    alias
    The alias is a unique identifier for the vault or other data stored in the keystore. Aliases are case-insensitive.
    storetype
    The storetype specifies the keystore type. The value jceks is recommended.
    keyalg
    The algorithm to use for encryption. Use the documentation for your JRE and operating system to see which other choices may be available to you.
    keysize
    The size of an encryption key impacts how difficult it is to decrypt through brute force. For information on appropriate values, see the documentation distributed with the keytool utility.
    storepass
    The value of storepass is the password is used to authenticate to the keystore so that the key can be read. The password must be at least 6 characters long and must be provided when the keystore is accessed. If you omit this parameter, you will be prompted to enter it when you execute the command.
    keypass
    The value of keypass is the password used to access the specific key and must match the value of the storepass parameter.
    validity
    The value of validity is the period (in days) for which the key will be valid.
    keystore
    The value of keystore is the filepath and filename in which the keystore's values are to be stored. The keystore file is created when data is first added to it.
    Ensure you use the correct file path separator: / (forward slash) for Red Hat Enterprise Linux and similar operating systems, \ (backslash) for Microsoft Windows Server.
    The keytool utility has many other options. See the documentation for your JRE or your operating system for more details.

  3. Run the keytool command

    Launch your operating system's command line interface and run the keytool utility, supplying the information that you gathered.

Example 18.40. Create a Java Keystore

$ keytool -genseckey -alias vault -storetype jceks -keyalg AES -keysize 128 -storepass vault22 -keypass vault22 -validity 730 -keystore EAP_HOME/vault/vault.keystore
Result

In this a keystore has been created in the file EAP_HOME/vault/vault.keystore. It stores a single key, with the alias vault, which will be used to store encrypted strings, such as passwords, for JBoss EAP.

Report a bug

18.6.5. Initialize the Password Vault

Prerequisites

Overview

The Password Vault can be initialized either interactively, where you are prompted for each parameter's value, or non-interactively, where you provide all parameters' values on the commmand line. Each method gives the same result, so choose whichever method you prefer.

Refer to the following list when using either method.

Parameter Values

Keystore URL (KEYSTORE_URL)
The file system path or URI of the keystore file. The examples use EAP_HOME/vault/vault.keystore.
Keystore password (KEYSTORE_PASSWORD)
The password used to access the keystore.
Salt (SALT)
The salt value is a random string of eight characters used, together with the iteration count, to encrypt the content of the keystore.
Keystore Alias (KEYSTORE_ALIAS)
The alias by which the keystore is known.
Iteration Count (ITERATION_COUNT)
The number of times the encryption algorithm is run.
Directory to store encrypted files (ENC_FILE_DIR)
The path in which the encrypted files are to be stored. This is typically the directory containing the password vault.
It is convenient but not mandatory to store all of your encrypted information in the same place as the key store. This directory should be only accessible to limited users. At a minimum the user account under which JBoss EAP is running requires read-write access. If you followed Section 18.6.4, “Create a Java Keystore to Store Sensitive Strings”, your keystore is in a directory called EAP_HOME/vault/.

Note

The trailing backslash or forward slash on the directory name is required. Ensure you use the correct file path separator: / (forward slash) for Red Hat Enterprise Linux and similar operating systems, \ (backslash) for Microsoft Windows Server.
Vault Block (VAULT_BLOCK)
The name to be given to this block in the password vault. Choose a value which is significant to you.
Attribute (ATTRIBUTE)
The name to be given to the attribute being stored. Choose a value which is significant to you. For example, you could choose a name which you associate with a datasource.
Security Attribute (SEC-ATTR)
The password which is being stored in the password vault.

Procedure 18.9. Run the Password Vault Command Interactively

Use this method if you would prefer to be prompted for the value of each parameter.

  1. Launch the Password Vault command interactively.

    Launch your operating system's command line interface and run EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems) or EAP_HOME\bin\vault.bat (on Microsoft Windows Server). Start a new interactive session by typing 0 (zero).

  2. Complete the prompted parameters.

    Follow the prompts to input the required parameters.

  3. Make a note of the masked password information.

    The masked password, salt, and iteration count are printed to standard output. Make a note of them in a secure location. They are required to add entries to the Password Vault. Access to the keystore file and these values could allow an attacker access to obtain access to sensitive information in the Password Vault.

  4. Exit the interactive console.

    Type 3 (three) to exit the interactive console.

Example 18.41.  Run the Password Vault command interactively 

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:EAP_HOME/vault/                        
Enter Keystore URL:EAP_HOME/vault/vault.keystore
Enter Keystore password: vault22
Enter Keystore password again: vault22
Values match
Enter 8 character salt:1234abcd
Enter iteration count as a number (Eg: 44):120
Enter Keystore Alias:vault
Initializing Vault
Oct 17, 2014 12:58:11 PM org.picketbox.plugins.vault.PicketBoxSecurityVault init
INFO: PBOX000361: Default Security Vault Implementation Initialized and Ready
Vault Configuration in AS7 config file:
********************************************
...
</extensions>
<vault>
  <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/>
  <vault-option name="KEYSTORE_PASSWORD" value="MASK-5dOaAVafCSd"/>
  <vault-option name="KEYSTORE_ALIAS" value="vault"/>
  <vault-option name="SALT" value="1234abcd"/>
  <vault-option name="ITERATION_COUNT" value="120"/>
  <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/>
</vault><management> ...
********************************************
Vault is initialized and ready for use
Handshake with Vault complete

Procedure 18.10. Run the Password Vault Command Non-interactively

Use this method if you would prefer to provide all parameters' values at once.
  • Launch your operating system's command line interface and run the Password Vault command. Refer to the Parameter Values list, substituting the placeholder values with your preferred values.
    Use EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems) or EAP_HOME\bin\vault.bat (on Microsoft Windows Server). 
    vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --vault-block VAULT_BLOCK --attribute ATTRIBUTE --sec-attr SEC-ATTR --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT

    Example 18.42. Run the Password Vault command non-interactively

    vault.sh --keystore EAP_HOME/vault/vault.keystore --keystore-password vault22 --alias vault --vault-block vb --attribute password --sec-attr 0penS3sam3 --enc-dir EAP_HOME/vault/ --iteration 120 --salt 1234abcd
    Command output 
    =========================================================================

  JBoss Vault

  JBOSS_HOME: EAP_HOME

  JAVA: java

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

Oct 17, 2014 2:23:43 PM org.picketbox.plugins.vault.PicketBoxSecurityVault init
INFO: PBOX000361: Default Security Vault Implementation Initialized and Ready
Secured attribute value has been stored in vault. 
Please make note of the following:
********************************************
Vault Block:vb
Attribute Name:password
Configuration should be done as follows:
VAULT::vb::password::1
********************************************
Vault Configuration in AS7 config file:
********************************************
...
</extensions>
<vault>
  <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/>
  <vault-option name="KEYSTORE_PASSWORD" value="MASK-5dOaAVafCSd"/>
  <vault-option name="KEYSTORE_ALIAS" value="vault"/>
  <vault-option name="SALT" value="1234abcd"/>
  <vault-option name="ITERATION_COUNT" value="120"/>
  <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/>
</vault><management> ...
********************************************
Result

Your keystore password has been masked for use in configuration files and deployments. In addition, your vault is initialized and ready to use.

Report a bug

18.6.6. Configure JBoss EAP 6 to Use the Password Vault

Overview

Before you can mask passwords and other sensitive attributes in configuration files, you need to make JBoss EAP 6 aware of the password vault which stores and decrypts them.

Prerequisites

Procedure 18.11. Enable the Password Vault

  • Run the following Management CLI command, substituting the placeholder values with those from the output of the Password Vault command in Section 18.6.5, “Initialize the Password Vault”.

    Note

    If you use Microsoft Windows Server, use two backslashes (\\) in the file path where you would normally use one. For example, C:\\data\\vault\\vault.keystore. This is because a single backslash character (\) is used for character escaping. 
    /core-service=vault:add(vault-options=[("KEYSTORE_URL" => "PATH_TO_KEYSTORE"), ("KEYSTORE_PASSWORD" => "MASKED_PASSWORD"), ("KEYSTORE_ALIAS" => "ALIAS"), ("SALT" => "SALT"),("ITERATION_COUNT" => "ITERATION_COUNT"), ("ENC_FILE_DIR" => "ENC_FILE_DIR")])

Example 18.43. Enable the Password Vault

/core-service=vault:add(vault-options=[("KEYSTORE_URL" => "EAP_HOME/vault/vault.keystore"), ("KEYSTORE_PASSWORD" => "MASK-5dOaAVafCSd"), ("KEYSTORE_ALIAS" => "vault"), ("SALT" => "1234abcd"),("ITERATION_COUNT" => "120"), ("ENC_FILE_DIR" => "EAP_HOME/vault/")])
Result

JBoss EAP 6 is configured to decrypt masked strings stored in the Password Vault. To add strings to the Password Vault and use them in your configuration, see Section 18.6.8, “Store a Sensitive String in the Password Vault”.

Report a bug

18.6.7. Configure JBoss EAP 6 to Use a Custom Implementation of the Password Vault

Overview

You can use your own implementation of SecurityVault to mask passwords and other sensitive attributes in configuration files.

Prerequisites

Procedure 18.12. Use a Custom Implementation of the Password Vault

  1. Create a class that implements the interface SecurityVault.
  2. Create a module containing the class from the previous step, and specify a dependency on org.picketbox where the interface is SecurityVault.
  3. Enable the custom Password Vault in the JBoss EAP server configuration by adding the vault element with the following attributes:
    code
    The fully qualified name of class that implements SecurityVault.
    module
    The name of the module that contains the custom class.
    Optionally, you can use vault-options parameters to initialize the custom class for a Password Vault.

    Example 18.44.  Use vault-options Parameters to Initialize the Custom Class 

    /core-service=vault:add(code="custom.vault.implementation.CustomSecurityVault", module="custom.vault.module", vault-options=[("KEYSTORE_URL" => "PATH_TO_KEYSTORE"), ("KEYSTORE_PASSWORD" => "MASKED_PASSWORD"), ("KEYSTORE_ALIAS" => "ALIAS"), ("SALT" => "SALT"),("ITERATION_COUNT" => "ITERATION_COUNT"), ("ENC_FILE_DIR" => "ENC_FILE_DIR")])
Result

JBoss EAP 6 is configured to decrypt masked strings using a custom implementation of the password vault.

Report a bug

18.6.8. Store a Sensitive String in the Password Vault

Overview

Including passwords and other sensitive strings in plaintext configuration files is a security risk. Store these strings instead in the Password Vault for improved security, where they can then be referenced in configuration files, Management CLI commands and applications in their masked form.

Sensitive strings can be store in the Password Vault either interactively, where you are prompted for each parameter's value, or non-interactively, where you provide all parameters' values on the commmand line. Each method gives the same result, so choose whichever method you prefer. For a description of all parameters, see Section 18.6.5, “Initialize the Password Vault”.

Prerequisites

Procedure 18.13. Store a Sensitive String Interactively

Use this method if you would prefer to be prompted for the value of each parameter.

  1. Run the Password Vault command

    Launch your operating system's command line interface and run the Password Vault command. Use EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems) or EAP_HOME\bin\vault.bat (on Microsoft Windows Server). Start a new interactive session by typing 0 (zero).

  2. Complete the prompted parameters about the Password Vault

    Follow the prompts to input the required authentication parameters. These values must match those provided when the Password Vault was created.

    Note

    The keystore password must be given in plaintext form, not masked form.

  3. Complete the prompted parameters about the sensitive string

    Enter 0 (zero) to start storing the sensitive string. Follow the prompts to input the required parameters.

  4. Make note of the information about the masked string

    A message prints to standard output, showing the vault block, attribute name, masked string, and advice about using the string in your configuration. Make note of this information in a secure location. An extract of sample output is as follows: 
    Vault Block:ds_Example1
Attribute Name:password
Configuration should be done as follows:
VAULT::ds_Example1::password::1

  5. Exit the interactive console

    Enter 3 (three) to exit the interactive console.

Example 18.45.  Store a Sensitive String Interactively 

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

  JBoss Vault

  JBOSS_HOME: EAP_HOME/jboss-eap-6.4

  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:11:18:46,086 INFO  [org.jboss.security] (management-handler-thread - 4) PBOX0                                                                  
Enter directory to store encrypted files:EAP_HOME/vault/ 
Enter Keystore URL:EAP_HOME/vault/vault.keystore
Enter Keystore password: 
Enter Keystore password again: 
Values match
Enter 8 character salt:1234abcd
Enter iteration count as a number (Eg: 44):120
Enter Keystore Alias:vault
Initializing Vault
Oct 21, 2014 11:20:49 AM org.picketbox.plugins.vault.PicketBoxSecurityVault init
INFO: PBOX000361: Default Security Vault Implementation Initialized and Ready
Vault Configuration in AS7 config file:
********************************************
...
</extensions>
<vault>
  <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/>
  <vault-option name="KEYSTORE_PASSWORD" value="MASK-5dOaAVafCSd"/>
  <vault-option name="KEYSTORE_ALIAS" value="vault"/>
  <vault-option name="SALT" value="1234abcd"/>
  <vault-option name="ITERATION_COUNT" value="120"/>
  <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/>
</vault><management> ...
********************************************
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: Remove secured attribute  3: Exit
0
Task: Store a secured attribute
Please enter secured attribute value (such as password):
Please enter secured attribute value (such as password) again: 
Values match
Enter Vault Block:ds_Example1
Enter Attribute Name:password
Secured attribute value has been stored in vault. 
Please make note of the following:
********************************************
Vault Block:ds_Example1
Attribute Name:password
Configuration should be done as follows:
VAULT::ds_Example1::password::1
********************************************
Please enter a Digit::   0: Store a secured attribute  1: Check whether a secured attribute exists  2: Remove secured attribute  3: Exit

Procedure 18.14. Store a Sensitive String Non-interactively

Use this method if you would prefer to provide all parameters' values at once.
  1. Launch your operating system's command line interface and run the Password Vault command. Use EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems) or EAP_HOME\bin\vault.bat (on Microsoft Windows Server).
    Substitute the placeholder values with your own values. The values for parameters KEYSTORE_URL, KEYSTORE_PASSWORD and KEYSTORE_ALIAS must match those provided when the Password Vault was created.

    Note

    The keystore password must be given in plaintext form, not masked form. 
    EAP_HOME/bin/vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --vault-block VAULT_BLOCK --attribute ATTRIBUTE --sec-attr SEC-ATTR --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT

  2. Make note of the information about the masked string

    A message prints to standard output, showing the vault block, attribute name, masked string, and advice about using the string in your configuration. Make note of this information in a secure location. An extract of sample output is as follows: 
    Vault Block:vb
Attribute Name:password
Configuration should be done as follows:
VAULT::vb::password::1

Example 18.46. Run the Password Vault command non-interactively

EAP_HOME/bin/vault.sh --keystore EAP_HOME/vault/vault.keystore --keystore-password vault22 --alias vault --vault-block vb --attribute password --sec-attr 0penS3sam3 --enc-dir EAP_HOME/vault/ --iteration 120 --salt 1234abcd
Command output 
=========================================================================

  JBoss Vault

  JBOSS_HOME: EAP_HOME

  JAVA: java

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

Oct 22, 2014 9:24:43 AM org.picketbox.plugins.vault.PicketBoxSecurityVault init
INFO: PBOX000361: Default Security Vault Implementation Initialized and Ready
Secured attribute value has been stored in vault. 
Please make note of the following:
********************************************
Vault Block:vb
Attribute Name:password
Configuration should be done as follows:
VAULT::vb::password::1
********************************************
Vault Configuration in AS7 config file:
********************************************
...
</extensions>
<vault>
  <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/>
  <vault-option name="KEYSTORE_PASSWORD" value="vault22"/>
  <vault-option name="KEYSTORE_ALIAS" value="vault"/>
  <vault-option name="SALT" value="1234abcd"/>
  <vault-option name="ITERATION_COUNT" value="120"/>
  <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/vault/"/>
</vault><management> ...
********************************************
Result

The sensitive string has now been stored in the Password Vault and can be used in configuration files, Management CLI commands and applications in its masked form.

Report a bug

18.6.9. Use an Encrypted Sensitive String in Configuration

Prerequisites

Any sensitive string which has been encrypted can be used in a configuration file or Management CLI command in its masked form, providing expressions are allowed.
To confirm if expressions are allowed within a particular subsystem, run the following Management CLI command against that subsystem.

Note

Add the prefix /host=HOST_NAME to the command for a managed domain. 
/core-service=SUBSYSTEM:read-resource-description(recursive=true)

Example 18.47.  List the Description of all Resources in the Management Subsystem 

/core-service=management:read-resource-description(recursive=true)
From the output of running this command, look for the value of the expressions-allowed parameter. If this is true, then you can use expressions within the configuration of this subsystem.
Use the following syntax to replace any plaintext string with the masked form. 
${VAULT::VAULT_BLOCK::ATTRIBUTE_NAME::MASKED_STRING}

Example 18.48.  Datasource Definition Using a Password in Masked Form

In this example the vault block is ds_ExampleDS and the attribute is password. 
...
  <subsystem xmlns="urn:jboss:domain:datasources:1.0">
    <datasources>
      <datasource jndi-name="java:jboss/datasources/ExampleDS" enabled="true" use-java-context="true" pool-name="H2DS">
        <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
        <driver>h2</driver>
        <pool></pool>
        <security>
          <user-name>sa</user-name>
          <password>${VAULT::ds_ExampleDS::password::1}</password>
        </security>
      </datasource>
      <drivers>
         <driver name="h2" module="com.h2database.h2">
            <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
         </driver>
      </drivers>
    </datasources>
  </subsystem>
...
Report a bug

18.6.10. Use an Encrypted Sensitive String in an Application

Prerequisites

Encrypted strings stored in the Password Vault can be used in your application's source code.

Example 18.49. Servlet Using a Vaulted Password

This example is an extract of a servlet's source code, illustrating the use of a masked password in a datasource definition, instead of the plaintext password. The plaintext version is commented out so that you can see the difference. 
/*@DataSourceDefinition(
        name = "java:jboss/datasources/LoginDS",
        user = "sa",
        password = "sa",
        className = "org.h2.jdbcx.JdbcDataSource",
        url = "jdbc:h2:tcp://localhost/mem:test"
)*/
@DataSourceDefinition(
        name = "java:jboss/datasources/LoginDS",
        user = "sa",
        password = "VAULT::DS::thePass::1",
        className = "org.h2.jdbcx.JdbcDataSource",
        url = "jdbc:h2:tcp://localhost/mem:test"
)
Report a bug

18.6.11. Check if a Sensitive String is in the Password Vault

Overview

Before attempting to store or use a sensitive string in the Password Vault it can be useful to first confirm if it is already stored.

This check can be done either interactively, where you are prompted for each parameter's value, or non-interactively, where you provide all parameters' values on the commmand line. Each method gives the same result, so choose whichever method you prefer.

Procedure 18.15.  Check For a Sensitive String Interactively

Use this method if you would prefer to be prompted for the value of each parameter.

  1. Run the Password Vault command

    Launch your operating system's command line interface and run the Password Vault command. Use EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems) or EAP_HOME\bin\vault.bat (on Microsoft Windows Server). Start a new interactive session by typing 0 (zero).

  2. Complete the prompted parameters about the Password Vault

    Follow the prompts to input the required authentication parameters. These values must match those provided when the Password Vault was created.

    Note

    The keystore password must be given in plaintext form, not masked form.
  3. Enter 1 (one) to select “Check whether a secured attribute exists”.
  4. Enter the name of the vault block in which the sensitive string is stored.
  5. Enter the name of the sensitive string to be checked.
Result

If the sensitive string is stored in the vault block specified, a confirmation message like the following will be output. 

A value exists for (VAULT_BLOCK, ATTRIBUTE)
If the sensitive string is not stored in the specified block, a message like the following will be output. 
No value has been store for (VAULT_BLOCK, ATTRIBUTE)

Example 18.50. Check For a Sensitive String Interactively

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

  JBoss Vault

  JBOSS_HOME: EAP_HOME

  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:EAP_HOME/vault
Enter Keystore URL:EAP_HOME/vault/vault.keystore
Enter Keystore password:
Enter Keystore password again:
Values match
Enter 8 character salt:1234abcd
Enter iteration count as a number (Eg: 44):120
Enter Keystore Alias:vault
Initializing Vault
Oct 22, 2014 12:53:56 PM org.picketbox.plugins.vault.PicketBoxSecurityVault init
INFO: PBOX000361: Default Security Vault Implementation Initialized and Ready
Vault Configuration in AS7 config file:
********************************************
...
</extensions>
<vault>
  <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/>
  <vault-option name="KEYSTORE_PASSWORD" value="MASK-5dOaAVafCSd"/>
  <vault-option name="KEYSTORE_ALIAS" value="vault"/>
  <vault-option name="SALT" value="1234abcd"/>
  <vault-option name="ITERATION_COUNT" value="120"/>
  <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/>
</vault><management> ...
********************************************
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: Remove secured attribute  3: Exit
1
Task: Verify whether a secured attribute exists
Enter Vault Block:vb
Enter Attribute Name:password
A value exists for (vb, password)
Please enter a Digit::   0: Store a secured attribute  1: Check whether a secured attribute exists  2: Remove secured attribute  3: Exit

Procedure 18.16.  Check For a Sensitive String Non-Interactively

Use this method if you would prefer to provide all parameters' values at once. For a description of all parameters, see Section 18.6.5, “Initialize the Password Vault”.
  • Launch your operating system's command line interface and run the Password Vault command. Use EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems) or EAP_HOME\bin\vault.bat (on Microsoft Windows Server).
    Substitute the placeholder values with your own values. The values for parameters KEYSTORE_URL, KEYSTORE_PASSWORD-password and KEYSTORE_ALIAS must match those provided when the Password Vault was created.

    Note

    The keystore password must be given in plaintext form, not masked form. 
    EAP_HOME/bin/vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --check-sec-attr --vault-block VAULT_BLOCK --attribute ATTRIBUTE --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT
Result

If the sensitive string is stored in the vault block specified, the following message will be output. 

Password already exists.
If the value is not stored in the specified block, the following message will be output. 
Password doesn't exist.
Report a bug

18.6.12. Remove a Sensitive String from the Password Vault

Overview

For security reasons it is best to remove sensitive strings from the Password Vault when they are no longer required. For example, if you are decommissioning an application, any sensitive strings used in datasource definitions should be removed at the same time.

Prerequisite

Before removing a sensitive string from the Password Vault, confirm if it is used in the configuration of JBoss EAP. One method of doing this is to use the ‘grep’ utility to search configuration files for instances of the masked string. On Red Hat Enterprise Linux (and similar operating systems), grep is installed by default but for Microsoft Windows Server it must be installed manually.

The Password Vault utility provides two modes: interactive and non-interactive. Interactive mode prompts you for each parameter’s value, where non-interactive mode requires you to provide all parameters’ values in a single command.

Procedure 18.17. Remove a Sensitive String Interactively

Use this method if you would prefer to be prompted for the value of each parameter.

  1. Run the Password Vault command

    Launch your operating system's command line interface and run EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems) or EAP_HOME\bin\vault.bat (on Microsoft Windows Server). Start a new interactive session by typing 0 (zero).

  2. Provide Authentication Details

    Follow the prompts to input the required authentication parameters. These values must match those provided when the Password Vault was created.

    Note

    The keystore password must be given in plaintext form, not masked form.
  3. Enter 2 (two) to choose option Remove secured attribute.
  4. Enter the name of the vault block in which the sensitive string is stored.
  5. Enter the name of the sensitive string to be removed.
Result

If the sensitive string is successfully removed, a confirmation message like the following will be output. 

Secured attribute [VAULT_BLOCK::ATTRIBUTE] has been successfully removed from vault
If the sensitive string is not removed, a message like the following will be output. 
Secured attribute [VAULT_BLOCK::ATTRIBUTE] was not removed from vault, check whether it exist

Example 18.51.  Remove a Sensitive String Interactively 

**********************************
****  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:EAP_HOME/vault/
Enter Keystore URL:EAP_HOME/vault/vault.keystore
Enter Keystore password: 
Enter Keystore password again: 
Values match
Enter 8 character salt:1234abcd
Enter iteration count as a number (Eg: 44):120
Enter Keystore Alias:vault
Initializing Vault
Dec 23, 2014 1:40:56 PM org.picketbox.plugins.vault.PicketBoxSecurityVault init
INFO: PBOX000361: Default Security Vault Implementation Initialized and Ready
Vault Configuration in configuration file:
********************************************
...
</extensions>
<vault>
  <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/>
  <vault-option name="KEYSTORE_PASSWORD" value="MASK-5dOaAVafCSd"/>
  <vault-option name="KEYSTORE_ALIAS" value="vault"/>
  <vault-option name="SALT" value="1234abcd"/>
  <vault-option name="ITERATION_COUNT" value="120"/>
  <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/>
</vault><management> ...
********************************************
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: Remove secured attribute  3: Exit
2
Task: Remove secured attribute
Enter Vault Block:craft
Enter Attribute Name:password
Secured attribute [craft::password] has been successfully removed from vault

Procedure 18.18.  Remove a Sensitive String Non-interactively

Use this method if you would prefer to provide all parameters' values at once. For a description of all parameters, see Section 18.6.5, “Initialize the Password Vault”.
  • Launch your operating system's command line interface and run the Password Vault command. Use EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems) or EAP_HOME\bin\vault.bat (on Microsoft Windows Server).
    Substitute the placeholder values with your own values. The values for parameters KEYSTORE_URL, KEYSTORE_PASSWORD and KEYSTORE_ALIAS must match those provided when the Password Vault was created.

    Note

    The keystore password must be given in plaintext form, not masked form. 
    EAP_HOME/bin/vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --remove-sec-attr --vault-block VAULT_BLOCK --attribute ATTRIBUTE --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT
Result

If the sensitive string is successfully removed, a confirmation message like the following will be output. 

Secured attribute [VAULT_BLOCK::ATTRIBUTE] has been successfully removed from vault
If the sensitive string is not removed, a message like the following will be output. 
Secured attribute [VAULT_BLOCK::ATTRIBUTE] was not removed from vault, check whether it exist

Example 18.52.  Remove a Sensitive String Non-interactively 

./vault.sh --keystore EAP_HOME/vault/vault.keystore --keystore-password vault22 --alias vault --remove-sec-attr --vault-block craft --attribute password --enc-dir ../vault/ --iteration 120 --salt 1234abcd
=========================================================================

  JBoss Vault

  JBOSS_HOME: EAP_HOME

  JAVA: java

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

Dec 23, 2014 1:54:24 PM org.picketbox.plugins.vault.PicketBoxSecurityVault init
INFO: PBOX000361: Default Security Vault Implementation Initialized and Ready
Secured attribute [craft::password] has been successfully removed from vault
Report a bug