Chapter 3. Securely Storing Credentials

JBoss EAP allows the encryption of sensitive strings outside of configuration files. These strings can be stored in a keystore, and subsequently decrypted for applications and verifications systems. Sensitive strings can be stored in either of the following:

  • Credential Store - Introduced in JBoss EAP 7.1, a credential store can safely secure sensitive and plain text strings by encrypting them in a storage file. Each JBoss EAP server can contain multiple credential stores.
  • Password Vault - Primarily used in legacy configurations, a password vault uses a Java Keystore to store sensitive strings outside of the configuration files. Each JBoss EAP server can only contain a single password vault.

All of the configuration files in EAP_HOME/standalone/configuration/ and EAP_HOME/domain/configuration/ are world readable by default. It is strongly recommended to not store plaintext passwords in the configuration files, and instead place these credentials in either a credential store or password vault.

If you decide to place plaintext passwords in the configuration files, then these files should only be accessible by limited users. At a minimum, the user account under which JBoss EAP 7 is running requires read-write access.

3.1. Credential Store

Introduced with the elytron subsystem, credential stores allow for secure storage and usage of credentials. You can find more background information on credential stores as well as other Elytron components in the Core Concepts and Components section of the Security Architecture guide.

Using a credential store is preferred to using a password vault to store passwords and other sensitive strings. Credential stores allow for easier credential management within the JBoss EAP management CLI, without having to use an external tool. You can also use multiple credential stores within a JBoss EAP server, compared to the limitation of only one password vault per JBoss EAP server.

The default credential store implementation uses a JCEKS keystore file to store credentials. When creating a new credential store, the default implementation also allows you to reference an existing keystore file or have JBoss EAP automatically create one for you. Currently, the default implementation only allows you to store clear text passwords.

Important

The elytron subsystem does not provide any checks for using the same file as storage to multiple credential stores. It is strongly advised not to use the same file for multiple credential stores or even to share the storage file using remote file systems.

If you need to use shared storage file, be sure to set the read-only flag on the credential stores accessing it. This will prevent the file from being modified. After the file is updated from outside, each credential store has to be reloaded to reflect the changed values. A similar process needs to be followed when using credential stores in a managed domain.

Since a credential store contains sensitive information, the directory containing the store should be accessible to only limited users. At a minimum the user account under which JBoss EAP is running requires read-write access.

Important

JBoss EAP reads the credential store file into memory and writes changes to it at varying times. You must ensure that the user running the JBoss EAP process has permissions to the store file, and that you do not externally modify the store file while JBoss EAP is running.

If the file is modified externally, you can use the reload() operation on the credential store to make JBoss EAP reload the content of the store file.

3.1.1. Create a Credential Store

To create a credential store, you must define a path to the new credential store file, and provide a master password that is used to encrypt the credential store. The directory containing the store should be accessible to only limited users. At a minimum the user account under which JBoss EAP is running requires read-write access.

Important

JCEKS keystore implementations differ between Java vendors, so the JBoss EAP instance must run a JDK from the same vendor that generated the JCEKS keystore.

Like providing paths in other JBoss EAP configuration, you can also use the relative-to attribute to provide a path relative to another.

Create a Credential Store for a Standalone Server

Use the following management CLI command to create a new credential store: 

/subsystem=elytron/credential-store=STORE_NAME:add(location="path/to/store_file", credential-reference={clear-text=STORE_PASSWORD},create=true)

For example, the following command creates a new store named my_store, and creates the file jboss.server.data.dir/cred_stores/my_store.jceks: 

/subsystem=elytron/credential-store=my_store:add(location="cred_stores/my_store.jceks", relative-to=jboss.server.data.dir,  credential-reference={clear-text=supersecretstorepassword},create=true)
Note

If you want to use an implementation other than default, you can explicitly define the type of a credential store. For more information, see the section on using a custom credential store implementation.

Create a Credential Store in a Managed Domain

Use the following management CLI command to create a new credential store in a managed domain: 

/profile=PROFILE_NAME/subsystem=elytron/credential-store=STORE_NAME:add(location=path/to/store_file,credential-reference={clear-text="STORE_PASSWORD"},create=true)

For example, the following command creates a new store named my_store, and creates the file jboss.server.data.dir/cred_stores/my_store.jceks: 

/profile=full/subsystem=elytron/credential-store=my_store:add(relative-to=jboss.server.data.dir,location="cred_stores/my_store.jceks",credential-reference={clear-text=supersecretstorepassword},create=true)
Note

There is no need to define a credential store resource at each server. Every server running the same profile, for which the credential store is created, contains our credential store. Therefore, it is good idea to locate the storage file at the server data directory, relative-to=jboss.server.data.dir.

For another way of creating a credential store in a managed domain, see Using Credential Stores in a Managed Domain.

3.1.2. Add a Credential to the Credential Store

To add a new credential to a credential store, you associate an alias to the sensitive string that you are wanting to store.

Note

Credential store aliases are case insensitive by default. Any stored alias is displayed in lowercase, and may be referenced using any combination of uppercase and lowercase letters.

If a custom credential store is used, then case sensitivity will be determined by the custom implementation.

The following management CLI command adds a credential to a credential store: 

/subsystem=elytron/credential-store=STORE_NAME:add-alias(alias=ALIAS, secret-value="SENSITIVE_STRING")

For example, to add a password with the alias database-pw to the store created in the previous section: 

/subsystem=elytron/credential-store=my_store:add-alias(alias=database-pw, secret-value="speci@l_db_pa$$_01")
Editing Credential Store Aliases Using the Management Console
  1. Log in to the management console and click on the Runtime tab.
  2. Select the server and select Security (Elytron) → Stores and click View.
  3. Select the credential store and click Aliases to edit the aliases.

3.1.3. Use a Stored Credential in a Configuration

To refer to a password or sensitive string stored in a credential store, use the credential-reference attribute in your JBoss EAP configuration. You can use credential-reference as an alternative to providing a password or other sensitive string in most places throughout the JBoss EAP configuration. 

credential-reference={store=STORE_NAME, alias=ALIAS}

For example, to create a new datasource using the password that was added to the credential store in the previous example, you can use credential-reference like the following: 

data-source add --name=my_DS --jndi-name=java:/my_DS --driver-name=h2 --connection-url=jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE --user-name=db_user --credential-reference={store=my_store, alias=database-pw}

In the above example, instead of providing a password using --password, a credential-reference including a store name and alias is provided. If you check the resulting datasource configuration, note that password is undefined and the credential-reference attribute is defined instead. 

/subsystem=datasources/data-source=my_DS:read-resource()
{
    "outcome" => "success",
    "result" => {
        ...
        "credential-reference" => {
            "store" => "my_store",
            "alias" => "database-pw"
        },
        ...
        "password" => undefined,
        ...
    }
}

3.1.4. List the Credentials in the Credential Store

You can list the aliases of all the credentials contained in a credential store using the following management CLI command: 

/subsystem=elytron/credential-store=STORE_NAME:read-aliases()

For example: 

/subsystem=elytron/credential-store=my_store:read-aliases()
{
    "outcome" => "success",
    "result" => [
        "database-pw"
    ]
}

3.1.5. Remove a Credential from the Credential Store

You can remove a credential from a credential store using the following command: 

/subsystem=elytron/credential-store=STORE_NAME:remove-alias(alias=ALIAS)

For example: 

/subsystem=elytron/credential-store=my_store:remove-alias(alias=database-pw)

3.1.6. Obtain the Master Password for the Credential Store from an External Source

Instead of providing your credential store’s master password in the clear, you can choose to provide that password using a pseudo credential store. You have the following options:

EXT

External command using java.lang.Runtime#exec(java.lang.String). If parameters are needed, they are supplied using a space-separated list of strings. An external command refers to any executable from the operation system, for example a shell script or an executable binary. The password is read from the standard output of the executed command.

Example

{EXT}/usr/bin/getTheMasterPassswordScript.sh par1 par2

CMD

External command using java.lang.ProcessBuilder. If parameters are needed, they are supplied using a comma-separated list of strings. An external command refers to any executable from the operation system, for example a shell script or an executable binary. The password is read from the standard output of the executed command.

Example

{CMD}/usr/bin/getTheMasterPassswordScript.sh par1,par2

MASK

Masked password using PBE, or Password Based Encryption. It must be in the following format, which includes the SALT and ITERATION values: 

MASK-MASKED_VALUE;SALT;ITERATION

Example

MASK-NqMznhSbL3lwRpDmyuqLBW==;12345678;123

Important

EXT, CMD, and MASK provide backward compatibility with the legacy security vault style of supplying an external password. For MASK you must use the above format that includes the SALT and ITERATION values.

You can also use a password located in another credential store as the master password for a new credential store.

Example Credential Store Created with a Password from Another Credential Store

/subsystem=elytron/credential-store=exampleCS:add(location="cred_stores/exampleCS.jceks", relative-to=jboss.server.data.dir, create=true, credential-reference={store=master-cred-store, alias=master-pw})

3.1.7. Define a FIPS 140-2 Compliant Credential Store

A FIPS 140-2 compliant credential store may be defined using either of the following methods.

3.1.7.1. Define a FIPS 140-2 Compliant Credential Store Using an NSS Database

To obtain a FIPS compliant keystore, use a Sun PKCS#11 provider accessing an NSS database. Instructions on defining the database are found at Configuring the NSS Database.

  1. Create a secret key to be used in the credential store. 

    $ keytool -keystore NONE -storetype PKCS11 -storepass STORE_PASSWORD -genseckey -alias ALIAS -keyalg AES -keysize 256

  2. Create an external credential store. An external credential store holds a secret key in a PKCS#11 keystore, and accesses this keystore using the alias defined in the previous step. This keystore is then used to decrypt the credentials in a JCEKS keystore. In addition to the credential-store attributes, the credential-store KeyStoreCredentialStore implementation properties are used to configure external credential stores. 

    /subsystem=elytron/credential-store=STORE_NAME:add(modifiable=true, implementation-properties={"keyStoreType"=>"PKCS11","external"=>"true","keyAlias"=>"ALIAS", externalPath="/path/to/EXTERNAL_STORAGE"},credential-reference={clear-text="STORE_PASSWORD"}, create=true)

  3. Once created, the credential store can be used to store aliases as normal. 

    /subsystem=elytron/credential-store=STORE_NAME:add-alias(alias="ALIAS", secret-value="SENSITIVE_STRING")

  4. Confirm that the alias has been added successfully by reading from the credential store. 

    /subsystem=elytron/credential-store=STORE_NAME:read-aliases()

3.1.7.2. Define a FIPS 140-2 Compliant Credential Store Using the BouncyCastle Providers

The following instructions outline how you can use a BouncyCastle provider to obtain a FIPS compliant keystore.

  1. Ensure your your environment is configured to use the BouncyCastle provider.

  2. Create a secret key to be used in the credential store. 

    $ keytool -genseckey -alias ALIAS -keyalg AES -keysize 128 -keystore KEYSTORE -storetype BCFKS -storepass PASSWORD -keypass PASSWORD
    Important

    The keypass and storepass for the keystore must be identical for FIPS credential stores to be defined in the elytron subsystem.

  3. Create an external credential store. An external credential store holds a secret key in a BCFKS keystore, and accesses this keystore using the alias defined in the previous step. This keystore is then used to decrypt the credentials in a JCEKS keystore. The credential-store KeyStoreCredentialStore implementation properties are used to configure external credential stores. 

    /subsystem=elytron/credential-store=BCFKS_CREDENTIAL_STORE:add(relative-to=jboss.server.config.dir,credential-reference={clear-text=PASSWORD},implementation-properties={keyAlias=ALIAS,external=true,externalPath=CREDENTIAL_STORE,keyStoreType=BCFKS},create=true,location=KEYSTORE,modifiable=true)

  4. Once created, the credential store can be used to store aliases as normal. 

    /subsystem=elytron/credential-store=BCFKS_CREDENTIAL_STORE:add-alias(alias="ALIAS", secret-value="SENSITIVE_STRING")

  5. Confirm that the alias has been added successfully by reading from the credential store. 

    /subsystem=elytron/credential-store=BCFKS_CREDENTIAL_STORE:read-aliases()

3.1.8. Use a Custom Implementation of the Credential Store

To use a custom implementation of the credential store:

  1. Create a class that extends the Service Provider Interface (SPI) CredentialStoreSpi abstract class.
  2. Create a class that implements the Java Security Provider. The provider must add the custom credential store class as a service.

  3. Create a module containing your credential store and provider classes, and add it to JBoss EAP with a dependency on org.wildfly.security.elytron. For example: 

    module add --name=org.jboss.customcredstore --resources=/path/to/customcredstoreprovider.jar --dependencies=org.wildfly.security.elytron --slot=main

  4. Create a provider loader for your provider. For example: 

    /subsystem=elytron/provider-loader=myCustomLoader:add(class-names=[org.wildfly.security.mycustomcredstore.CustomElytronProvider],module=org.jboss.customcredstore)

  5. Create a credential store using the custom implementation.

    Note

    Ensure that you specify the correct providers and type values. The value of type is what is used in your provider class where it adds your custom credential store class as a service.

    For example: 

    /subsystem=elytron/credential-store=my_store:add(providers=myCustomLoader,type=CustomKeyStorePasswordStore,location="cred_stores/my_store.jceks",relative-to=jboss.server.data.dir,credential-reference={clear-text=supersecretstorepassword},create=true)

    Alternatively, if you have created multiple providers, you can specify the additional providers using another provider loader with other-providers. This allows you to have other additional implementations for new types of credentials. These specified other providers are automatically accessible in the custom credential store’s initialize method as the Provider[] argument. For example: 

    /subsystem=elytron/credential-store=my_store:add(providers=myCustomLoader,other-providers=myCustomLoader2,type=CustomKeyStorePasswordStore,location="cred_stores/my_store.jceks",relative-to=jboss.server.data.dir,credential-reference={clear-text=supersecretstorepassword},create=true)

3.1.9. Create and Modify Credential Stores Offline with the WildFly Elytron Tool

You can use the WildFly Elytron tool, which you access using the elytron-tool script located in EAP_HOME/bin/, to create and modify a credential store for an offline, or stopped, JBoss EAP server.

Important

JCEKS keystore implementations differ between Java vendors, so the JBoss EAP instance must run a JDK from the same vendor that generated the JCEKS keystore.

Important

Using the WildFly Elytron tool to modify a credential store that is in use by a running JBoss EAP server can result in changes to the store being lost. Instead, you should create and modify credential stores for a running server by using the management CLI, as described in the previous sections.

The following commands are shown using elytron-tool.sh for Red Hat Enterprise Linux and Solaris systems. For Windows Server systems, use the elytron-tool.bat script instead.

Create a Credential Store Using the WildFly Elytron Tool

Create a credential store using the WildFly Elytron tool with the following command: 

$ EAP_HOME/bin/elytron-tool.sh credential-store --create --location "path/to/store_file" --password STORE_PASSWORD

For example: 

$ EAP_HOME/bin/elytron-tool.sh credential-store --create --location "../cred_stores/my_store.jceks" --password supersecretstorepassword

If you do not want to provide your store password in the command, you can omit that argument and you will be prompted to enter the password manually using standard input. You can also use a masked password generated by the WildFly Elytron tool for the store password.

Create a Credential Store Using the BouncyCastle Provider with the WildFly Elytron Tool

The following procedure outlines how to create a credential store using the WildFly Elytron tool.

  1. Ensure your environment is configured to use the BouncyCastle provider.

  2. Define a BCFKS keystore. If this keystore already exists, proceed to the next step. 

    $ keytool -genkeypair -alias ALIAS -keyalg RSA -keysize 2048 -keypass PASSWORD -keystore KEYSTORE -storetype BCFKS -storepass PASSWORD
    Important

    The keypass and storepass for the keystore must be identical for FIPS credential stores to be defined in the elytron subsystem.

  3. Generate a secret key for the credential store. 

    $ keytool -genseckey -alias ALIAS -keyalg AES -keysize 128 -keystore KEYSTORE -storetype BCFKS -storepass PASSWORD -keypass PASSWORD

  4. Define the credential store using the WildFly Elytron tool with the following command: 

    $ EAP_HOME/bin/elytron-tool.sh credential-store -c -a ALIAS -x ALIAS_PASSWORD -p PASSWORD -l CREDENTIAL_STORE -u "keyStoreType=BCFKS;external=true;keyAlias=ALIAS;externalPath=KEYSTORE"

Add a Credential to a Credential Store Using the WildFly Elytron Tool

Add a credential to a credential store using the WildFly Elytron tool with the following command: 

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "path/to/store_file" --password STORE_PASSWORD --add ALIAS --secret SENSITIVE_STRING

For example: 

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "../cred_stores/my_store.jceks" --password supersecretstorepassword --add database-pw --secret speci@l_db_pa$$_01

Similar to providing the credential store password, if you do not want to provide your secret in the command, you can omit that argument and you will be prompted to enter the secret manually using standard input.

List All the Credentials in the Credential Store Using the WildFly Elytron Tool

List the credentials in a credential store using the WildFly Elytron tool with the following command: 

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "path/to/store_file" --password STORE_PASSWORD --aliases

For example: 

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "../cred_stores/my_store.jceks" --password supersecretstorepassword --aliases

Check If an Alias Exists in the Credential Store Using the Wildfly Elytron Tool

Check if an alias exists in a credential store using the WildFly Elytron tool with the following command: 

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "path/to/store_file" --password STORE_PASSWORD --exists ALIAS

For example: 

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "../cred_stores/my_store.jceks" --password supersecretstorepassword --exists database-pw

Remove a Credential from the Credential Store Using the WildFly Elytron Tool

Remove a credential from a credential store using the WildFly Elytron tool with the following command: 

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "path/to/store_file" --password STORE_PASSWORD --remove ALIAS

For example: 

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "../cred_stores/my_store.jceks" --password supersecretstorepassword --remove database-pw

Add a Credential Store Created with the WildFly Elytron Tool to a JBoss EAP Server

After you have created a credential store with the WildFly Elytron tool, add it to your running JBoss EAP server with the following management CLI command: 

/subsystem=elytron/credential-store=STORE_NAME:add(location="path/to/store_file",credential-reference={clear-text=STORE_PASSWORD})

For example: 

/subsystem=elytron/credential-store=my_store:add(location="../cred_stores/my_store.jceks",credential-reference={clear-text=supersecretstorepassword})

After adding the credential store to the JBoss EAP configuration, you can then refer to a password or sensitive string stored in the credential store using the credential-reference attribute.

For more information, use the EAP_HOME/bin/elytron-tool.sh credential-store --help command for a detailed listing of available options.

3.1.9.1. Generate Masked Encrypted Strings Using the WildFly Elytron Tool

You can use the WildFly Elytron tool to generate PicketBox-compatible MASK- encrypted strings to use instead of a plain text password for a credential store.

To generate a masked string, use the following command and provide values for the salt and the iteration count: 

$ EAP_HOME/bin/elytron-tool.sh mask --salt SALT --iteration ITERATION_COUNT --secret PASSWORD

For example: 

$ EAP_HOME/bin/elytron-tool.sh mask --salt 12345678 --iteration 123 --secret supersecretstorepassword

MASK-8VzWsSNwBaR676g8ujiIDdFKwSjOBHCHgnKf17nun3v;12345678;123

If you do not want to provide the secret in the command, you can omit that argument and you will be prompted to enter the secret manually using standard input.

For more information, use the EAP_HOME/bin/elytron-tool.sh mask --help command for a detailed listing of available options.

3.1.9.2. Convert a Password Vault to a Credential Store Using the WildFly Elytron Tool

You can use the WildFly Elytron tool to convert a password vault to a credential store. To convert a password vault to a credential store, you need the vault’s values used when initializing the vault.

Note

When converting a password vault, aliases in the new credential store are named in the following format based on their equivalent password vault block and attribute name: VAULT_BLOCK::ATTRIBUTE_NAME.

Convert a Single Password Vault

Convert a single password vault to a credential store using the following command: 

$ EAP_HOME/bin/elytron-tool.sh vault --keystore "path/to/vault_file" --keystore-password VAULT_PASSWORD --enc-dir "path/to/vault_directory" --salt SALT --iteration ITERATION_COUNT --alias VAULT_ALIAS

For example, you can also specify the new credential store’s file name and location with the --location argument: 

$ EAP_HOME/bin/elytron-tool.sh vault --keystore ../vaults/vault.keystore --keystore-password vault22 --enc-dir ../vaults/ --salt 1234abcd --iteration 120 --alias my_vault --location ../cred_stores/my_vault_converted.cred_store
Note

You can also use the --summary argument to print a summary of the management CLI commands used to convert it. Note that even if a plain text password is used, it is masked in the summary output. The default SALT and ITERATION values are used unless they are specified in the command.

Bulk Convert Multiple Password Vaults

To bulk convert multiple password vaults:

  1. Put the details of the vaults you want to convert into a description file in the following format: 

    keystore:path/to/vault_file
keystore-password:VAULT_PASSWORD
enc-dir:path/to/vault_directory
salt:SALT 1
iteration:ITERATION_COUNT
location:path/to/converted_cred_store 2
alias:VAULT_ALIAS
properties:PARAMETER1=VALUE1;PARAMETER2=VALUE2; 3
    1
    salt and iteration can be omitted if you are providing a plain text password for the vault.
    2
    Specifies the location and file name for the converted credential store.
    3
    Optional: Specifies a list of optional parameters separated by semicolons (;). See EAP_HOME/bin/elytron-tool.sh vault --help for a list of available parameters.

    For example: 

    keystore:/vaults/vault1/vault1.keystore
keystore-password:vault11
enc-dir:/vaults/vault1/
salt:1234abcd
iteration:120
location:/cred_stores/vault1_converted.cred_store
alias:my_vault

keystore:/vaults/vault2/vault2.keystore
keystore-password:vault22
enc-dir:/vaults/vault2/
salt:abcd1234
iteration:130
location:/cred_stores/vault2_converted.cred_store
alias:my_vault2

  2. Run the bulk convert command with your description file from the previous step: 

    $ EAP_HOME/bin/elytron-tool.sh vault --bulk-convert vaultdescriptions.txt

For more information, use the EAP_HOME/bin/elytron-tool.sh vault --help command for a detailed listing of available options.

3.1.10. Using Credential Stores with Elytron Client

Clients connecting to JBoss EAP, such as EJBs, can authenticate using Elytron Client. Users without access to a running JBoss EAP server can create and modify credential stores using the WildFly Elytron tool, and then clients can use Elytron Client to access sensitive strings inside a credential store.

The following example shows you how to use a credential store in an Elytron Client configuration file.

Example custom-config.xml with a Credential Store

<configuration>
  <authentication-client xmlns="urn:elytron:1.2">
    ...
    <credential-stores>
      <credential-store name="my_store"> 1
        <protection-parameter-credentials>
          <credential-store-reference clear-text="pass123"/> 2
        </protection-parameter-credentials>
        <attributes>
          <attribute name="location" value="/path/to/my_store.jceks"/> 3
        </attributes>
      </credential-store>
    </credential-stores>
    ...
    <authentication-configurations>
      <configuration name="my_user">
        <set-host name="localhost"/>
        <set-user-name name="my_user"/>
        <set-mechanism-realm name="ManagementRealm"/>
        <use-provider-sasl-factory/>
        <credentials>
          <credential-store-reference store="my_store" alias="my_user"/> 4
        </credentials>
      </configuration>
    </authentication-configurations>
    ...
  </authentication-client>
</configuration>

1
A name for the credential store for use within the Elytron Client configuration file.
2
The master password for the credential store.
3
The path to the credential store file.
4
A credential reference for a sensitive string stored in the credential store.

See the JBoss EAP How to Configure Identity Management Guide for more information on configuring client authentication using Elytron Client.

3.1.11. Using Credential Stores in a Managed Domain

There are a few different ways of creating and setting up a credential store in a managed domain. One of the ways is:

  1. Use the WildFly Elytron Tool to prepare the credential store. For more information on this, see Create and Modify Credential Stores Offline with the WildFly Elytron Tool.
  2. Distribute the created credential store storage file. For example, distribute it to each server, for example by using scp, or store it in NFS and use it for all the created credential stores.

  3. You can then create a credential store with the create property set to false, using the already created file. 

    /profile=full/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,location="store.keystore",credential-reference={clear-text="secret2"},create=false)
    Note

    When using one credential store to store all credential stores, when storing it on NFS, you must use the credential store in read-only mode. The read-only mode is used to maintain consistency. It is also prefered to use an absolute path in this case. 

    /profile=full/subsystem=elytron/credential-store=test:add(location=/absolute/path/to/store.keystore,credential-reference={clear-text="secret2"},create=false,modifiable=false)

For other ways of creating a credential store in a managed domain, see Create a Credential Store in a Managed Domain.

3.2. Password Vault

Configuration of JBoss EAP and associated applications requires potentially sensitive information, such as user names and passwords. Instead of storing the password as plain text in configuration files, the password vault feature can be used to mask the password information and store it in an encrypted keystore. Once the password is stored, references can be included in management CLI commands or applications deployed to JBoss EAP.

The password vault uses the Java keystore as its storage mechanism. 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.

Important

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

JCEKS keystore implementations differ between Java vendors so the keystore must be generated using the keytool utility from the same vendor as the JDK used. Using a keystore generated by the keytool from one vendor’s JDK in a JBoss EAP 7 instance running on a JDK from a different vendor results in the following exception: java.io.IOException: com.sun.crypto.provider.SealedObjectForKeyProtector

3.2.1. Set Up a Password Vault

Follow the steps below to set up and use a Password Vault.

  1. Create a directory to store the keystore and other encrypted 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 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 file path and file name 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 Windows Server.

    The keytool utility has many other options. See the documentation for the JRE or the operating system for more details.

  3. Run the keytool command, ensuring keypass and storepass contain the same value. 

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

3.2.2. 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 parameter 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_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 keystore. 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 you created when you set up the password vault. 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 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 password which is being stored in the password vault.

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: 

$ 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: Initializing Password Vault

$ 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

Example: Output

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

  JBoss Vault

  JBOSS_HOME: EAP_HOME

  JAVA: java

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

Nov 09, 2015 9:02:47 PM 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> ...
********************************************

To run the password vault command interactively, the following steps are required:

  1. Launch the password vault command interactively.

    Run EAP_HOME/bin/vault.sh on Red Hat Enterprise Linux and similar operating systems or EAP_HOME\bin\vault.bat on 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 2 (two) to exit the interactive console.

Example: Input and Output

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
Nov 09, 2015 9:24:36 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

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

3.2.3. Use a 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: 

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

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

If Microsoft Windows Server is being used, use two backslashes (\\) in the file path instead using one. For example, C:\\data\\vault\\vault.keystore. This is because a single backslash character (\) is used for character escaping.

3.2.4. Store a Sensitive String in the Password Vault

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 stored in the Password Vault either interactively, where the tool prompts for each parameter’s value, or non-interactively, where all the parameters' values are provided on the command line. Each method gives the same result, so either may be used. Both of these methods are invoked using the vault script.

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: 

$ 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
Note

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

$ 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

Example: Output

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

  JBoss Vault

  JBOSS_HOME: EAP_HOME

  JAVA: java

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

Nov 09, 2015 9:24:36 PM 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="../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="../vault/"/>
</vault><management> ...
********************************************

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

To run the password vault command interactively, the following steps are required:

  1. Launch the Password Vault command interactively.

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

    Type 2 (two) to exit the interactive console.

Example: Input and Output

 =========================================================================
  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
Nov 09, 2015 9:24:36 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
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

3.2.5. Use an Encrypted Sensitive String in Configuration

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: 

/subsystem=SUBSYSTEM: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 expressions can be used 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: Datasource Definition Using a Password in Masked Form

...
  <subsystem xmlns="urn:jboss:domain:datasources:5.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>
...

3.2.6. Use an Encrypted Sensitive String in an Application

Encrypted strings stored in the password vault can be used in an application’s source code. The below 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.

Example: Servlet Using a Vaulted Password

@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"
)
/*old (plaintext) definition
@DataSourceDefinition(
        name = "java:jboss/datasources/LoginDS",
        user = "sa",
        password = "sa",
        className = "org.h2.jdbcx.JdbcDataSource",
        url = "jdbc:h2:tcp://localhost/mem:test"
)*/

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

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 the user is 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. Both of these methods are invoked using the vault script.

Use the non-interative method to provide all parameters' values at once. For a description of all parameters, see Initialize the Password Vault. 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: 

$ 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

Substitute the placeholder values with the actual 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.

If the sensitive string is stored in the vault block specified, the following message will be displayed: 

Password already exists.

If the value is not stored in the specified block, the following message will be displayed: 

Password doesn't exist.

To run the password vault command interactively, the following steps are required:

  1. Launch the password vault command interactively.

    Run EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems) or EAP_HOME\bin\vault.bat (on Windows Server). Start a new interactive session by typing 0 (zero).

  2. Complete the prompted parameters. Follow the prompts to input the required authentication parameters. These values must match those provided when the password vault was created.

    Note

    When prompted for authentication, the keystore password must be given in plaintext form, not masked form.

    • Enter 1 (one) to select Check whether a secured attribute exists.
    • Enter the name of the vault block in which the sensitive string is stored.
    • Enter the name of the sensitive string to be checked.

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: 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
Nov 09, 2015 9:24:36 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

3.2.8. Remove a Sensitive String from the Password Vault

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

Important

As a prerequisite, before removing a sensitive string from the Password Vault, confirm if it is used in the configuration of JBoss EAP.

This operation can be done either interactively, where the user is 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. Both of these methods are invoked using the vault script.

Use the non-interative method to provide all parameters' values at once. For a description of all parameters, see Initialize the Password Vault. 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: 

$ 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

Substitute the placeholder values with the actual 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.

If the sensitive string is successfully removed, a confirmation message like the following will be displayed: 

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 displayed: 

Secured attribute [VAULT_BLOCK::ATTRIBUTE] was not removed from vault, check whether it exist

Example: Output

$ ./vault.sh --keystore EAP_HOME/vault/vault.keystore --keystore-password vault22 --alias vault --remove-sec-attr --vault-block vb --attribute password --enc-dir EAP_HOME/vault/ --iteration 120 --salt 1234abcd
 =========================================================================
  JBoss Vault
  JBOSS_HOME: EAP_HOME
  JAVA: java
 =========================================================================
Dec 23, 2015 1:54:24 PM org.picketbox.plugins.vault.PicketBoxSecurityVault init
INFO: PBOX000361: Default Security Vault Implementation Initialized and Ready
Secured attribute [vb::password] has been successfully removed from vault

Remove a Sensitive String Interactively

To run the password vault command interactively, the following steps are required:

  1. Launch the password vault command interactively.

    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 authentication parameters. These values must match those provided when the password vault was created.

    Note

    When prompted for authentication, the keystore password must be given in plaintext form, not masked form.

    • Enter 2 (two) to choose option Remove secured attribute.
    • Enter the name of the vault block in which the sensitive string is stored.
    • Enter the name of the sensitive string to be removed.

If the sensitive string is successfully removed, a confirmation message like the following will be displayed: 

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 displayed: 

Secured attribute [VAULT_BLOCK::ATTRIBUTE] was not removed from vault, check whether it exist

Example: Output

 **********************************
 ****  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:vb
Enter Attribute Name:password
Secured attribute [vb::password] has been successfully removed from vault

3.2.9. Configure Red Hat JBoss Enterprise Application Platform to Use a Custom Implementation of the Password Vault

In addition to using the provided password vault implementation, a custom implementation of SecurityVault can also be used.

Important

As a prerequisite, ensure that the password vault has been initialized. For more information, see Initialize the Password Vault.

To use a custom implementation for 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 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, the vault-options parameters can be used to initialize the custom class for a password vault.

Example: 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)])

3.2.10. Obtain Keystore Password From External Source

The EXT, EXTC, CMD, CMDC or CLASS methods can be used in vault configuration for obtaining the Java keystore password. 

<vault-option name="KEYSTORE_PASSWORD" value="METHOD_TO_OBTAIN_PASSWORD"/>

The description for the methods are listed as:

{EXT}…​
Refers to the exact command, where the …​ 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 = infinity. For example: {EXTC:120000}/usr/bin/getmypassword --section 1 --query company verifies if the 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 minutes, that is 120000 milliseconds.
{CMD}…​ or {CMDC[:expiration_in_millis]}…​
The general command is a string delimited by , (comma) 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 : (colon) 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, the org.test.passwd.ExternamPassworProvider class is loaded from org.test.passwd module and uses the toCharArray() method to get the password. If toCharArray() is not available the toString() method is used. The org.test.passwd.ExternamPassworProvider class must have the default constructor.