Encrypting passwords in JBoss EAP 6/7 configuration files using the Vault

Solution Verified - Updated 17 Jun 2024

Environment

Red Hat JBoss Enterprise Application Platform (JBoss EAP) 6/7
Clear text passwords in the configuration or on the command line

Issue

Configure vault to encrypt passwords in configuration files
Encrypt the database password
Update vault attribute value
Avoid plain text username and password in the standalone.xml / domain.xml file.
How to encrypt RHPAM controller password ?

Resolution

The preferred solution for datasource security is the use of either security domains or password vaults.

Secure a Datasource Using a Security Domain
For more information on using Security Domains, see the How to Configure Identity Management guide.
Secure a Datasource Using a Password Vault
For more information on using the Password Vault, see the How To Configure Server Security guide.

Here's a detailed demonstration of using the vault for encrypting passwords.
To set up and use a Password Vault requires the following steps:

Set Up a Java Keystore to Store Key for Password Encryption
Initialize the Password Vault
Configure JBoss EAP to use the Password Vault
Store a Sensitive String in the Password Vault
Use an Encrypted Sensitive String in Configuration

Set Up a Java Keystore to Store Key for Password Encryption

The keytool utility, provided by the Java Runtime Environment (JRE), is utilized for these steps.
To set up the keystore, perform the following steps:

Create a directory to store the keystore and other encrypted information.
Create a directory to store the 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.
```
 $ cd $EAP_HOME
 $ mkdir vault
```
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 the JRE and operating system to see which other choices are available.
- 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 that 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 this parameter is omitted, the keytool utility will prompt for it to be entered after the command has been executed
- 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 the correct file path separator is used: / (forward slash) for Red Hat Enterprise Linux and similar operating systems, \ (backslash) for Microsoft Windows Server.
Run the keytool command
```
 $ $JAVA_HOME/bin/keytool -genseckey -alias vault -storetype jceks -keyalg AES -keysize 128 -storepass vault22 -keypass vault22 -validity 730 -keystore $EAP_HOME/vault/vault.keystore
```
This results in a keystore that 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.

Initialize the Password Vault

The Password Vault can be initialized either interactively, where you are prompted for each parameter’s value, or non-interactively, where all parameters' values are provided on the command line. Each method gives the same result, so either may be used.

The following parameters will be needed:

Keystore URL (--keystore) : 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 (--alias) : The alias by which the keystore is known.

Iteration Count (--iteration) : The number of times the encryption algorithm is run.

Directory to store encrypted files (--enc-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 7 is running requires read-write access. The keystore should be located in the directory used for Step 1. Note that the trailing backslash or forward slash on the directory name is required. Ensure the correct file path separator is used: / (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.

Attribute (--attribute) : The name to be given to the attribute being stored.

Security Attribute (--sec-attr) : The actual value that is being secured in the vault, in this case, the password.

To run the password vault command non-interactively, the vault script (located in EAP_HOME/bin/) can be invoked with parameters for the relevant information:

$ $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
=========================================================================
JBoss Vault
JBOSS_HOME: $EAP_HOME
JAVA: $JAVA_HOME/bin/java
=========================================================================
Dec 02, 2016 10:21:31 AM org.picketbox.plugins.vault.PicketBoxSecurityVault init
INFO: PBOX00361: Default Security Vault Implementation Initialized and Ready
WFLYSEC0047: 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
********************************************
WFLYSEC0048: Vault Configuration in WildFly 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> ...
********************************************

Updating Attribute Value

To update the attribute value, run the keytool command as mentioned in 3. Run the keytool command changing --sec-attr value and maintaining all other values. It will replace the current content with the new one.

Configure JBoss EAP to use the Password Vault

Before passwords and other sensitive attributes can be masked and used in configuration files, JBoss EAP 7 must be made aware of the password vault which stores and decrypts them.

The following command can be used to configure JBoss EAP 7 to use the password vault:

(CLI Command)

Standalone:

      /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/")])

Managed domain:

      /host=<Your_host_name/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/")])

This will result in either host.xml for domain mode, or in standalone.xml:

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

Store a Sensitive String in the Password Vault

After invoking the vault script, 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

The following string can be used in configurations to provide an encrypted password. It should be wrapped with '${' and '}' to denote the string as a variable.

VAULT::vb::password::1

Use an Encrypted Sensitive String in Configuration

Example - Datasource Definition Using a Password in Masked Form

...
<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::vb::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>
...

For Future JBoss EAP versions
There is a Content from issues.jboss.org is not included.feature request for the upstream project to include automatic encryption of passwords. This is planned to be implemented in the coming EAP 7.4.0.GA release, where it will be possible to enable automatic encryption of passwords stored in configuration. But, it would require moving to the new Elytron security subsystem and usage of the CredentialStore feature. Refer to documentation on Securely Storing Credentials in EAP using the Elytron Credential Store.

Diagnostic Steps

If you see these exception when running vault.sh, see Invalid secret key format with vault in JBoss EAP

  Caused by: java.io.IOException: Invalid secret key format
      at com.sun.crypto.provider.JceKeyStore.engineLoad(JceKeyStore.java:856)
      at java.security.KeyStore.load(KeyStore.java:1445)
      at org.picketbox.util.KeyStoreUtil.getKeyStore(KeyStoreUtil.java:201)
      at org.picketbox.util.KeyStoreUtil.getKeyStore(KeyStoreUtil.java:151)
      at org.picketbox.plugins.vault.PicketBoxSecurityVault.getKeyStore(PicketBoxSecurityVault.java:688)
      ... 11 more

SBR

JBoss Security

Product(s)

Red Hat JBoss Enterprise Application Platform

Components

jbossas

Category

Secure

Tags

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.