Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 4. Secure storage for 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.

4.1. Credential stores in Elytron
Copy link

4.1.1. Credential stores provided by Elytron
Copy link

Elytron provides two default credential store types you can use to save your credentials: KeyStoreCredentialStore and PropertiesCredentialStore. You can manage credential stores with the JBoss EAP management CLI, or you can use the WildFly Elytron tool to manage them offline. In addition to the two default store types, you can also create, use, and manage your own custom credential stores.

4.1.1.1. KeyStoreCredentialStore/credential-store
Copy link

You can store all the Elytron credential types in a KeyStoreCredentialStore. The resource name for KeyStoreCredentialStore in the elytron subsystem is credential-store. The KeyStoreCredentialStore protects your credentials using the mechanisms provided by the KeyStore implementations in the Java Development Kit (JDK).

Access a KeyStoreCredentialStore in the management CLI as follows: 

/subsystem=elytron/credential-store
Copy to Clipboard Toggle word wrap

To start properly, JBoss EAP requires an initial key to unlock certain secure resources. Use the secret-key-credential-store to provide this master secret key to unlock these necessary server resources. You can also use the PropertiesCredentialStore to store SecretKeyCredential, which supports storing Advanced Encryption Standard (AES) secret keys. Use file system permissions to restrict access to the credential store. Ideally, you should give access only to your application server to restrict access to this credential store. The resource name in the elytron subsystem for PropertiesCredentialStore is secret-key-credential-store, and you can access it in the management CLI as follows: 

/subsystem=elytron/secret-key-credential-store
Copy to Clipboard Toggle word wrap

For information on creating and providing the initial key, see Providing an initial key to JBoss EAP to unlock secured resources. Alternately, you can get the master key or password from an external source. For information about obtaining the password from an external source, see Obtain the password for the credential store from an external source.

4.1.2. Credential types in Elytron
Copy link

Elytron provides the following three credential types to suit your various security needs, and you can store these credentials in one of Elytron’s credential stores.

PasswordCredential

With this credential type, you can securely store plain text, or unencrypted, passwords. For the JBoss EAP resources that require a password, use a reference to the PasswordCredential instead of the plain text password to maintain the secrecy of the password.

Example of connecting to a database

data-source add ... --user-name=db_user --password=StrongPassword
Copy to Clipboard Toggle word wrap

In this example database connection command, you can see the password: StrongPassword. This means that others can also see it in the server configuration file.

Example of connecting to a database using a PasswordCredential

data-source add ... --user-name=db_user --credential-reference={store=exampleKeyStoreCredentialStore, alias=passwordCredentialAlias}
Copy to Clipboard Toggle word wrap

When you use a credential reference instead of a password to connect to a database, others can only see the credential reference in the configuration file, not your password

KeyPairCredential

You can use both Secure Shell (SSH) and Public-Key Cryptography Standards (PKCS) key pairs as KeyPairCredential. A key pair includes both a shared public key and a private key that only a given user knows.

You can manage KeyPairCredential using only the WildFly Elytron tool.

SecretKeyCredential
A SecretKeyCredential is an Advanced Encryption Standard (AES) key that you can use to create encrypted expressions in Elytron. For information about encrypted expressions, see Encrypted expressions in Elytron.

The following table illustrates which credential type is supported by which credential store:

Expand
Credential typeKeyStoreCredentialStore/credential-storePropertiesCredentialStore/secret-key-credential-store

PasswordCredential

Yes

No

KeyPairCredential

Yes

No

SecretKeyCredential

Yes

Yes

To manage JBoss EAP credentials in a running JBoss EAP server, use the provided management CLI operations. You can manage PasswordCredential and SecretKeyCredential using the JBoss EAP management CLI.

Note

You can do these operation only on modifiable credential stores. All credential store types are modifiable by default.

Create a KeyStoreCredentialStore for a JBoss EAP running as a standalone server in any directory on the file system. For security, the directory containing the store should be accessible to only limited users.

Prerequisites

  • You have provided at least read/write access to the directory containing the KeyStoreCredentialStore for the user account under which JBoss EAP is running.
Note

You cannot have the same name for a credential-store and a secret-key-credential-store because they implement the same Elytron capability: org.wildfly.security.credential-store.

Procedure

  • Create a KeyStoreCredentialStore using the following management CLI command:

    Syntax

    /subsystem=elytron/credential-store=<name_of_credential_store>:add(path="<path_to_store_file>", relative-to=<base_path_to_store_file>, credential-reference={clear-text=<store_password>}, create=true)
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:add(path="exampleKeyStoreCredentialStore.jceks", relative-to=jboss.server.data.dir, credential-reference={clear-text=password}, create=true)
{"outcome" => "success"}
    Copy to Clipboard Toggle word wrap

You can create a KeyStoreCredentialStore in a managed domain, but you must first use the WildFly Elytron tool to prepare your KeyStoreCredentialStore. If you have multiple host controllers in a single managed domain, choose one of the following options:

  • Create a KeyStoreCredentialStore in each host controller and add credentials to each KeyStoreCredentialStore.
  • Copy a populated KeyStoreCredentialStore from one host controller to all the other host controllers.
  • Save your KeyStoreCredentialStore file in your Network File System (NFS), then use that file for all the KeyStoreCredentialStore resources you create.

Alternatively, you can create a KeyStoreCredentialStore file with credentials on a host controller without using the WildFly Elytron tool.

Note

You don’t have to define a KeyStoreCredentialStore resource on every server, because every server on the same profile contains your KeyStoreCredentialStore file. You can find the KeyStoreCredentialStore file in the server data directory, relative-to=jboss.server.data.dir.

Important

You cannot have the same name for a credential-store and a secret-key-credential-store because they implement the same Elytron capability: org.wildfly.security.credential-store.

The following procedure describes how to use the NFS to provide the KeyStoreCredentialStore file to all host controllers.

Procedure

  1. Use the WildFly Elytron tool to create a KeyStoreCredentialStore storage file. For more information on this, see Credential store operations using the WildFly Elytron tool.

  2. Distribute the storage file. For example, allocate it to each host controller by using the scp command, or store it in your NFS and use it for all of your KeyStoreCredentialStore resources.

    Note

    To maintain consistency, for a KeyStoreCredentialStore file that multiple resources and host controllers use and which you stored in your NFS, you must use the KeyStoreCredentialStore in read-only mode. Additionally, make sure you provide an absolute path for your KeyStoreCredentialStore file.

    Syntax

    /profile=<profile_name>/subsystem=elytron/credential-store=<name_of_credential_store>:add(path=<absolute_path_to_store_keystore>,credential-reference={clear-text="<store_password>"},create=false,modifiable=false)
    Copy to Clipboard Toggle word wrap

    Example

    /profile=full-ha/subsystem=elytron/credential-store=exampleCredentialStoreDomain:add(path=/usr/local/etc/example-cred-store.cs,credential-reference={clear-text="password"},create=false,modifiable=false)
    Copy to Clipboard Toggle word wrap

  3. Optional: If you need to define the credential-store resource in a profile, use the storage file to create the resource.

    Syntax

    /profile=<profile_name>/subsystem=elytron/credential-store=<name_of_credential_store>:add(path=<path_to_store_file>,credential-reference={clear-text="<store_password>"})
    Copy to Clipboard Toggle word wrap

    Example

    /profile=full-ha/subsystem=elytron/credential-store=exampleCredentialStoreHA:add(path=/usr/local/etc/example-cred-store-ha.cs, credential-reference={clear-text="password"})
    Copy to Clipboard Toggle word wrap

  4. Optional: Create the KeyStoreCredentialStore resource for a host controller.

    Syntax

    /host=<host_controller_name>/subsystem=elytron/credential-store=<name_of_credential_store>:add(path=<path_to_store_file>,credential-reference={clear-text="<store_password>"})
    Copy to Clipboard Toggle word wrap

    Example

    /host=master/subsystem=elytron/credential-store=exampleCredentialStoreHost:add(path=/usr/local/etc/example-cred-store-host.cs, credential-reference={clear-text="password"})
    Copy to Clipboard Toggle word wrap

Create a PropertiesCredentialStore using the management CLI. When you create a PropertiesCredentialStore, JBoss EAP generates a secret key by default. The name of the generated key is key and its size is 256-bit.

Prerequisites

  • You have provided at least read/write access to the directory containing the PropertiesCredentialStore for the user account under which JBoss EAP is running.

Procedure

  • Use the following command to create a PropertiesCredentialStore using the management CLI:

    Syntax

    /subsystem=elytron/secret-key-credential-store=<name_of_credential_store>:add(path="<path_to_the_credential_store>", relative-to=<path_to_store_file>)
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:add(path=examplePropertiesCredentialStore.cs, relative-to=jboss.server.config.dir)
{"outcome" => "success"}
    Copy to Clipboard Toggle word wrap

Add a plain text password for those resources that require one as a PasswordCredential to the KeyStoreCredentialStore to hide that password in the configuration file. You can then reference this stored credential to access those resources, without ever exposing your password.

Prerequisites

Procedure

  • Add a new PasswordCredential to a KeyStoreCredentialStore:

    Syntax

    /subsystem=elytron/credential-store=<name_of_credential_store>:add-alias(alias=<alias>, secret-value=<secret-value>)
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:add-alias(alias=passwordCredentialAlias, secret-value=StrongPassword)
{"outcome" => "success"}
    Copy to Clipboard Toggle word wrap

Verification

  • Issue the following command to verify that the PasswordCredential was added to the KeyStoreCredentialStore:

    Syntax

    /subsystem=elytron/credential-store=<name_of_credential_store>:read-aliases()
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:read-aliases()
{
    "outcome" => "success",
    "result" => ["passwordcredentialalias"]
}
    Copy to Clipboard Toggle word wrap

Generate a SecretKeyCredential in a KeyStoreCredentialStore. By default, Elytron creates a 256-bit key. If you want a different size, you can specify either a 128-bit or 192-bit key in the key-size attribute.

Prerequisites

Procedure

  1. Generate a SecretKeyCredential in a KeyStoreCredentialStore using the following management CLI command:

    Syntax

    /subsystem=elytron/credential-store=<name_of_credential_store>:generate-secret-key(alias=<alias>, key-size=<128_or_192>)
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:generate-secret-key(alias=secretKeyCredentialAlias)
    Copy to Clipboard Toggle word wrap

Verification

  • Issue the following command to verify that Elytron stored your SecretKeyCredential in the KeyStoreCredentialStore:

    Syntax

    /subsystem=elytron/credential-store=<credential_store>:read-aliases()
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:read-aliases()
{
    "outcome" => "success",
    "result" => [
        "secretkeycredentialalias"
    ]
}
    Copy to Clipboard Toggle word wrap

Generate a SecretKeyCredential in a PropertiesCredentialStore. By default, Elytron creates a 256-bit key. If you want a different size, you can specify either a 128-bit or 192-bit key in the key-size attribute.

When you generate a SecretKeyCredential, Elytron generates a new random secret key and stores it as the SecretKeyCredential. You can view the contents of the credential by using the export operation on the PropertiesCredentialStore.

Important

Make sure that you create a backup of either PropertiesCredentialStore, SecretKeyCredential, or both, because JBoss EAP cannot decrypt or retrieve lost Elytron credentials.

You can use the export operation on the PropertiesCredentialStore to get the value of the SecretKeyCredential. You can then save this value as a backup. For information, see Exporting a SecretKeyCredential from a PropertiesCredentialStore/secret-key-credential-store.

Prerequisites

Procedure

  • Generate a SecretKeyCredential in a PropertiesCredentialStore using the following management CLI command:

    Syntax

    /subsystem=elytron/secret-key-credential-store=<name_of_the_properties_credential_store>:generate-secret-key(alias=<alias>, key-size=<128_or_192>)
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:generate-secret-key(alias=secretKeyCredentialAlias)
{"outcome" => "success"}
    Copy to Clipboard Toggle word wrap

Verification

  • Issue the following command to verify that Elytron created a SecretKeyCredential:

    Syntax

    /subsystem=elytron/secret-key-credential-store=<name_of_the_properties_credential_store>:read-aliases()
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:read-aliases()
{
    "outcome" => "success",
    "result" => [
        "secretkeycredentialalias",
        "key"
    ]
}
    Copy to Clipboard Toggle word wrap

You can import a SecretKeyCredential created outside of the PropertiesCredentialStore into an Elytron PropertiesCredentialStore. Suppose you exported a SecretKeyCredential from another credential store — a KeyStoreCredentialStore, for example — you can import it to the PropertiesCredentialStore.

Prerequisites

Procedure

  1. Disable caching of commands in the management CLI using the following command:

    Important

    If you do not disable caching, the secret key is visible to anyone who can access the management CLI history file. 

    history --disable
    Copy to Clipboard Toggle word wrap

  2. Import the secret key using the following management CLI command:

    Syntax

    /subsystem=elytron/secret-key-credential-store=<name_of_credential_store>:import-secret-key(alias=<alias>, key="<secret_key>")
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:import-secret-key(alias=imported, key="RUxZAUs+Y1CzEPw0g2AHHOZ+oTKhT9osSabWQtoxR+O+42o11g==")
    Copy to Clipboard Toggle word wrap

  3. Re-enable the caching of commands using the following management CLI command: 

    history --enable
    Copy to Clipboard Toggle word wrap

To view all the credentials stored in the KeyStoreCredentialStore, you can list them using the management CLI.

Procedure

  • List the credentials stored in a KeyStoreCredentialStore using the following management CLI command:

    Syntax

    /subsystem=elytron/credential-store=<name_of_credential_store>:read-aliases()
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:read-aliases()
{
    "outcome" => "success",
    "result" => [
        "passwordcredentialalias",
        "secretkeycredentialalias"
    ]
}
    Copy to Clipboard Toggle word wrap

To view all the credentials stored in the PropertiesCredentialStore, you can list them using the management CLI.

Procedure

  • List the credentials stored in a PropertiesCredentialStore using the following management CLI command:

    Syntax

    /subsystem=elytron/secret-key-credential-store=<name_of_credential_store>:read-aliases()
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:read-aliases()
{
    "outcome" => "success",
    "result" => [
        "secretkeycredentialalias",
        "key"
    ]
}
    Copy to Clipboard Toggle word wrap

You can export an existing SecretKeyCredential from a KeyStoreCredentialStore to use the SecretKeyCredential or to create a backup of the SecretKeyCredential.

Prerequisites

Procedure

  • Export a SecretKeyCredential from the KeyStoreCredentialStore using the following management CLI command:

    Syntax

    /subsystem=elytron/credential-store=<name_of_credential_store>:export-secret-key(alias=<alias>)
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:export-secret-key(alias=secretKeyCredentialAlias)
{
    "outcome" => "success",
    "result" => {"key" => "RUxZAUui+8JkoDCE6mFyA3cCIbSAZaXq5wgYejj1scYgdDqWiw=="}
}
    Copy to Clipboard Toggle word wrap

You can export an existing SecretKeyCredential from a PropertiesCredentialStore to use the SecretKeyCredential or to create a backup of the SecretKeyCredential.

Prerequisites

Procedure

  • Export a SecretKeyCredential from the PropertiesCredentialStore using the following management CLI command:

    Syntax

    /subsystem=elytron/secret-key-credential-store=<name_of_credential_store>:export-secret-key(alias=<alias>)
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:export-secret-key(alias=secretkeycredentialalias)
{
    "outcome" => "success",
    "result" => {"key" => "RUxZAUtxXcYvz0aukZu+odOynIr0ByLhC72iwzlJsi+ZPmONgA=="}
}
    Copy to Clipboard Toggle word wrap

You can store every credential type in the KeyStoreCredentialStore but, by default, when you remove a credential, Elytron assumes it’s a PasswordCredential. If you want to remove a different credential type, specify it in the entry-type attribute.

Procedure

  • Remove a credential from the KeyStoreCredentialStore using the following management CLI command:

    Syntax

    /subsystem=elytron/credential-store=<name_of_credential_store>:remove-alias(alias=<alias>, entry-type=<credential_type>)
    Copy to Clipboard Toggle word wrap

    Example removing a PasswordCredential

    /subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:remove-alias(alias=passwordCredentialAlias)
{
    "outcome" => "success",
    "response-headers" => {"warnings" => [{
        "warning" => "Update dependent resources as alias 'passwordCredentialAlias' does not exist anymore",
        "level" => "WARNING",
        "operation" => {
            "address" => [
                ("subsystem" => "elytron"),
                ("credential-store" => "exampleKeyStoreCredentialStore")
            ],
            "operation" => "remove-alias"
        }
    }]}
}
    Copy to Clipboard Toggle word wrap

    Example removing a SecretKeyCredential

    /subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:remove-alias(alias=secretKeyCredentialAlias, entry-type=SecretKeyCredential)
{
    "outcome" => "success",
    "response-headers" => {"warnings" => [{
        "warning" => "Update dependent resources as alias 'secretKeyCredentialAl
ias' does not exist anymore",
        "level" => "WARNING",
        "operation" => {
            "address" => [
                ("subsystem" => "elytron"),
                ("credential-store" => "exampleKeyStoreCredentialStore")
            ],
            "operation" => "remove-alias"
        }
    }]}
}
    Copy to Clipboard Toggle word wrap

Verification

  • Issue the following command to verify that Elytron removed the credential:

    Syntax

    /subsystem=elytron/credential-store=<name_of_credential_store>:read-aliases()
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:read-aliases()
{
    "outcome" => "success",
    "result" => []
}
    Copy to Clipboard Toggle word wrap

    The credential you removed is not listed.

You can store only the SecretKeyCredential type in a PropertiesCredentialStore. This means that, when you remove a credential from a PropertiesCredentialStore, you don’t have to specify an entry-type.

Procedure

  • Remove a SecretKeyCredential from the PropertiesCredentialStore using the following command:

    Syntax

    /subsystem=elytron/secret-key-credential-store=<name_of_credential_store>:remove-alias(alias=<alias>)
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:remove-alias(alias=secretKeyCredentialAlias)
{
    "outcome" => "success",
    "response-headers" => {"warnings" => [{
        "warning" => "Update dependent resources as alias 'secretKeyCredentialAlias' does not exist anymore",
        "level" => "WARNING",
        "operation" => {
            "address" => [
                ("subsystem" => "elytron"),
                ("secret-key-credential-store" => "examplePropertiesCredentialSt
ore")
            ],
            "operation" => "remove-alias"
        }
    }]}
}
    Copy to Clipboard Toggle word wrap

Verification

  • Issue the following command to verify that Elytron removed the credential:

    Syntax

    /subsystem=elytron/secret-key-credential-store=<name_of_credential_store>:read-aliases()
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:read-aliases()
{
    "outcome" => "success",
    "result" => []
}
    Copy to Clipboard Toggle word wrap

    The credential you removed is not listed.

In Elytron, you can create a KeyStoreCredentialStore offline where you can save all the credential types.

Procedure

  • Create a KeyStoreCredentialStore using the WildFly Elytron tool with the following command:

    Syntax

    $ EAP_HOME/bin/elytron-tool.sh credential-store --create --location "<path_to_store_file>" --password <store_password>
    Copy to Clipboard Toggle word wrap

    Example

    $ EAP_HOME/bin/elytron-tool.sh credential-store --create --location "../cred_stores/example-credential-store.jceks" --password storePassword
Credential Store has been successfully created
    Copy to Clipboard Toggle word wrap

    If you don’t want to include your store password in the command, omit that argument and then enter the password manually at the prompt. You can also use a masked password generated by the WildFly Elytron tool. For information about generating masked passwords, see Generating masked encrypted strings using the WildFly Elytron tool.

Create a KeyStoreCredentialStore using the Bouncy Castle provider.

Prerequisites

Note

You cannot have the same name for a credential-store and a secret-key-credential-store because they implement the same Elytron capability: org.wildfly.security.credential-store.

Procedure

  1. Define a Bouncy Castle FIPS Keystore (BCFKS) keystore. FIPS stands for Federal Information Processing Standards. If you already have one, move on to the next step. 

    $ keytool -genkeypair -alias <key_pair_alias> -keyalg <key_algorithm> -keysize <key_size> -storepass <key_pair_and_keystore_password> -keystore <path_to_keystore> -storetype BCFKS -keypass <key_pair_and_keystore_password>
    Copy to Clipboard Toggle word wrap
    Important

    Make sure that the keystore keypass and storepass attributes are identical. If they aren’t, the BCFKS keystore in the elytron subsystem can’t define them.

  2. Generate a secret key for the KeyStoreCredentialStore. 

    $ keytool -genseckey -alias <key_alias> -keyalg <key_algorithm> -keysize <key_size> -keystore <path_to_keystore> -storetype BCFKS -storepass <key_and_keystore_password> -keypass <key_and_keystore_password>
    Copy to Clipboard Toggle word wrap

  3. Define the KeyStoreCredentialStore using the WildFly Elytron tool with the following command: 

    $ EAP_HOME/bin/elytron-tool.sh credential-store -c -a <alias> -x <alias_password> -p <key_and_keystore_password> -l <path_to_keystore> -u "keyStoreType=BCFKS;external=true;keyAlias=<key_alias>;externalPath=<path_to_credential_store>"
    Copy to Clipboard Toggle word wrap

In Elytron, you can create a PropertiesCredentialStore offline where you can save SecretKeyCredential instances.

Procedure

  • Create a PropertiesCredentialStore using the WildFly Elytron tool with the following command:

    Syntax

    $ EAP_HOME/bin/elytron-tool.sh credential-store --create --location "<path_to_store_file>" --type PropertiesCredentialStore
    Copy to Clipboard Toggle word wrap

    Example

    $ bin/elytron-tool.sh credential-store --create --location=standalone/configuration/properties-credential-store.cs --type PropertiesCredentialStore
Credential Store has been successfully created
    Copy to Clipboard Toggle word wrap

You can do various KeyStoreCredentialStore tasks using the WildFly Elytron tool, including the following:

Add a PasswordCredential

You can add a PasswordCredential to a KeyStoreCredentialStore using the following WildFly Elytron tool command:

Syntax

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "<path_to_store_file>" --password <store_password> --add <alias> --secret <sensitive_string>
Copy to Clipboard Toggle word wrap

Example

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "../cred_stores/example-credential-store.jceks" --password storePassword --add examplePasswordCredential --secret speci@l_db_pa$$_01
Alias "examplePasswordCredential" has been successfully stored
Copy to Clipboard Toggle word wrap

If you don’t want to put your secret in the command, omit that argument, then enter the secret manually when prompted.

Generate a SecretKeyCredential

You can add a SecretKeyCredential to a KeyStoreCredentialStore using the following WildFly Elytron tool command:

Syntax

$ EAP_HOME/bin/elytron-tool.sh credential-store --generate-secret-key=example --location=<path_to_the_credential_store> --password <store_password>
Copy to Clipboard Toggle word wrap

Example

$ EAP_HOME/bin/elytron-tool.sh credential-store --generate-secret-key=example --location "../cred_stores/example-credential-store.jceks" --password storePassword
Alias "example" has been successfully stored
Copy to Clipboard Toggle word wrap

If you don’t want to put your secret in the command, omit that argument, then enter the secret manually when prompted.

By default, when you create a SecretKeyCredential in JBoss EAP, you create a 256-bit secret key. If you want to change the size, you can specify --size=128 or --size=192 to create 128-bit or 192-bit keys respectively.

Import a SecretKeyCredential

You can import a SecretKeyCredential using the following WildFLy Elytron tool command:

Syntax

$ EAP_HOME/bin/elytron-tool.sh credential-store --import-secret-key=imported --location=<path_to_credential_store> --password=<store_password>
Copy to Clipboard Toggle word wrap

Example

$ EAP_HOME/bin/elytron-tool.sh credential-store --import-secret-key=imported --location=../cred_stores/example-credential-store.jceks --password=storePassword
Copy to Clipboard Toggle word wrap

Enter the secret key you want to import.

List all the credentials

You can list the credentials in the KeyStoreCredentialStore using the following WildFly Elytron tool command:

Syntax

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "<path_to_store_file>" --password <store_password> --aliases
Copy to Clipboard Toggle word wrap

Example:

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "../cred_stores/example-credential-store.jceks" --password storePassword --aliases
Credential store contains following aliases: examplepasswordcredential example
Copy to Clipboard Toggle word wrap

Check if an alias exists

Use the following command to check whether an alias exists in a credential store:

Syntax

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "<path_to_store_file>" --password <store_password> --exists <alias>
Copy to Clipboard Toggle word wrap

Example

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "../cred_stores/example-credential-store.jceks" --password storePassword --exists examplepasswordcredential
Alias "examplepasswordcredential" exists
Copy to Clipboard Toggle word wrap

Export a SecretKeyCredential

You can export a SecretKeyCredential from a KeyStoreCredentialStore using the following command:

Syntax

$ EAP_HOME/bin/elytron-tool.sh credential-store --export-secret-key=<alias> --location=<path_to_credential_store> --password=storePassword
Copy to Clipboard Toggle word wrap

Example

$ EAP_HOME/bin/elytron-tool.sh credential-store --export-secret-key=example --location=../cred_stores/example-credential-store.jceks --password=storePassword
Exported SecretKey for alias example=RUxZAUtBiAnoLP1CA+i6DtcbkZHfybBJxPeS9mlVOmEYwjjmEA==
Copy to Clipboard Toggle word wrap

Remove a credential

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

Syntax

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "<path_to_store_file>" --password <store_password> --remove <alias>
Copy to Clipboard Toggle word wrap

Example

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "../cred_stores/example-credential-store.jceks" --password storePassword --remove examplepasswordcredential
Alias "examplepasswordcredential" has been successfully removed
Copy to Clipboard Toggle word wrap

You can do the following PropertiesCredentialStore operations for SecretKeyCredential using the WildFly Elytron tool:

Generate a SecretKeyCredential

You can generate a SecteKeyCredential in a PropertiesCredentialStore using the following WildFly Elytron tool command:

Syntax

$ EAP_HOME/bin/elytron-tool.sh credential-store --generate-secret-key=example --location "<path_to_the_credential_store>" --type PropertiesCredentialStore
Copy to Clipboard Toggle word wrap

Example

$ EAP_HOME/bin/elytron-tool.sh credential-store --generate-secret-key=example --location "standalone/configuration/properties-credential-store.cs" --type PropertiesCredentialStore
Alias "example" has been successfully stored
Copy to Clipboard Toggle word wrap

Import a SecretKeyCredential

You can import a SecretKeyCredential using the following WildFLy Elytron tool command:

Syntax

$ EAP_HOME/bin/elytron-tool.sh credential-store --import-secret-key=imported --location=<path_to_credential_store> --type PropertiesCredentialStore
Copy to Clipboard Toggle word wrap

Example

$ EAP_HOME/bin/elytron-tool.sh credential-store --import-secret-key=imported --location "standalone/configuration/properties-credential-store.cs" --type PropertiesCredentialStore
Copy to Clipboard Toggle word wrap

List all the credentials

You can list the credentials in the PropertiesCredentialStore using the following WildFly Elytron tool command:

Syntax

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "<path_to_store_file>"  --aliases --type PropertiesCredentialStore
Copy to Clipboard Toggle word wrap

Example

$ EAP_HOME/bin/elytron-tool.sh credential-store  --location "standalone/configuration/properties-credential-store.cs" --aliases --type PropertiesCredentialStore
Credential store contains following aliases: example
Copy to Clipboard Toggle word wrap

Export a SecretKeyCredential

You can export a SecretKeyCredential from a PropertiesCredentialStore using the following command:

Syntax

$ EAP_HOME/bin/elytron-tool.sh credential-store --export-secret-key=<alias> --location "<path_to_credential_store>"  --type PropertiesCredentialStore
Copy to Clipboard Toggle word wrap

Example

$ EAP_HOME/bin/elytron-tool.sh credential-store --export-secret-key=example --location "standalone/configuration/properties-credential-store.cs" --type PropertiesCredentialStore
Exported SecretKey for alias example=RUxZAUt1EZM7PsYRgMGypkGirSel+5Eix4aSgwop6jfxGYUQaQ==
Copy to Clipboard Toggle word wrap

Remove a credential

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

Syntax

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "<path_to_store_file>" --remove <alias> --type PropertiesCredentialStore
Copy to Clipboard Toggle word wrap

Example

$ EAP_HOME/bin/elytron-tool.sh credential-store --location "standalone/configuration/properties-credential-store.cs"  --remove example --type PropertiesCredentialStore
Alias "example" has been successfully removed
Copy to Clipboard Toggle word wrap

After you have created a credential store with the WildFly Elytron tool, you can add it to your running JBoss EAP server.

Prerequisites

Procedure

  • Add the credential store 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>})
    Copy to Clipboard Toggle word wrap

    For example: 

    /subsystem=elytron/credential-store=my_store:add(location="../cred_stores/example-credential-store.jceks",credential-reference={clear-text=storePassword})
    Copy to Clipboard Toggle word wrap

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.

You can use the following arguments to operate the elytron-tool.sh to manipulate a credential store, such as generating a new key pair that you can store under an alias in a credential store.

Generate a key pair

Use the generate-key-pair command to create a key pair. You can then store the key pair under an alias in the credential store. The following example shows the creation of an RSA key pair, which has an allocated size of 3072 bits that is stored in the location specified for the credential store. The alias given to the key pair is example. 

$ EAP_HOME/bin/elytron-tool.sh credential-store --location=<path_to_store_file> --generate-key-pair example --algorithm RSA --size 3072
Copy to Clipboard Toggle word wrap
Import a key pair

Use the import-key-pair command to import an existing SSH key pair into a credential store with a specified alias. The following example imports a key pair with the alias of example from the /home/user/.ssh/id_rsa file containing the private key in the OpenSSH format: 

$ EAP_HOME/bin/elytron-tool.sh credential-store --import-key-pair example --private-key-location /home/user/.ssh/id_rsa --location=<path_to_store_file>
Copy to Clipboard Toggle word wrap
Export a key pair

Use the export-key-pair-public-key command to display the public key of a key pair. The public key has a specified alias in the OpenSSH format. The following example displays the public key for the alias example: 

$ EAP_HOME/bin/elytron-tool.sh credential-store --location=<path_to_store_file> --export-key-pair-public-key example

Credential store password:
Confirm credential store password:
ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBMfncZuHmR7uglb0M96ieArRFtp42xPn9+ugukbY8dyjOXoi
cZrYRyy9+X68fylEWBMzyg+nhjWkxJlJ2M2LAGY=
Copy to Clipboard Toggle word wrap
Note

After issuing the export-key-pair-public-key command, you are prompted to enter the credential store passphrase. If no passphrase exists, leave the prompt blank.

A key pair consists of two separate, but matching, cryptographic keys: a public key and a private key. You need to store a key pair in a credential store before you can reference the key pair in an elytron configuration file. You can then provide Git with access to manage your standalone server configuration data.

The following example references a credential store and its properties in the <credential-stores> element of an elytron configuration file. The <credential> element references the credential store and the alias, which stores the key pair. 

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <authentication-client xmlns="urn:elytron:client:1.6">

     <credential-stores>
        <credential-store name="${credential_store_name}">
           <protection-parameter-credentials>
              <clear-password password="${credential_store_password}"/>
           </protection-parameter-credentials>
           <attributes>
              <attribute name="path" value="${path_to_credential_store}"/>
           </attributes>
        </credential-store>
     </credential-stores>

     <authentication-rules>
        <rule use-configuration="${configuration_file_name}"/>
     </authentication-rules>

     <authentication-configurations>
        <configuration name="${configuration_file_name}">
           <credentials>
              <credential-store-reference store="${credential_store_name}" alias="${alias_of_key_pair}"/>
           </credentials>
        </configuration>
     </authentication-configurations>

  </authentication-client>
</configuration>
Copy to Clipboard Toggle word wrap

After you configure the elytron configuration file, the key pair can be used for SSH authentication.

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.

Procedure

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

    For example: 

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

MASK-8VzWsSNwBaR676g8ujiIDdFKwSjOBHCHgnKf17nun3v;12345678;123
    Copy to Clipboard Toggle word wrap

    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.

4.1.6. Encrypted expressions in Elytron
Copy link

To maintain the secrecy of your sensitive strings, you can use encrypted expressions instead of the sensitive strings in the server configuration file.

An encrypted expression is one that results from encrypting a string with a SecretKeyCredential, then combining it with its encoding prefix and resolver name. The encoding prefix tells Elytron that the expression is an encrypted expression. The resolver maps the encrypted expression to its corresponding SecretKeyCredential in a credential store.

The expression=encryption resource in Elytron uses an encrypted expression to decode the encrypted string inside it at run time. By using an encrypted expression instead of the sensitive string itself in the configuration file, you protect the secrecy of the string. An encrypted expression takes the following format:

Syntax when using a specific resolver

${ENC::RESOLVER_NAME:ENCRYPTED_STRING}
Copy to Clipboard Toggle word wrap

ENC is the prefix that denotes an encrypted expression.

RESOLVER_NAME is the resolver Elytron uses to decrypt the encrypted string.

Example

${ENC::initialresolver:RUxZAUMQE+L5zx9LmCRLyh5fjdfl1WM7lhfthKjeoEU+x+RMi6s=}
Copy to Clipboard Toggle word wrap

If you create an encrypted expression with a default resolver, it looks like this:

Syntax when using the default resolver

${ENC::ENCRYPTED_STRING}
Copy to Clipboard Toggle word wrap

Example

${ENC::RUxZAUMQE+L5zx9LmCRLyh5fjdfl1WM7lhfthKjeoEU+x+RMi6s=}
Copy to Clipboard Toggle word wrap

In this case, Elytron uses the default resolver you defined in the expression=encryption resource to decrypt an expression. You can use an encrypted expression on any resource attribute that supports it. To find out whether an attribute supports encrypted expression, use the read-resource-description operation, for example:

Example read-resource-description on mail/mail-session

/subsystem=mail/mail-session=*/:read-resource-description(recursive=true,access-control=none)
{
  "outcome"=>"success",
  "result"=>[{
  ...
    "from"=>{
      ...
      "expression-allowed"=>true,
      ...
   }]
}
Copy to Clipboard Toggle word wrap

In this example, the attribute from supports encrypted expressions. This means that you can hide your email address in the from field by encrypting it and then using the encrypted expression instead.

4.1.7. Creating an encrypted expression in Elytron
Copy link

Create an encrypted expression from a sensitive string and a SecretKeyCredential. Use this encrypted expression instead of the sensitive string in the management model - the server configuration file, to maintain the secrecy of the sensitive string.

Prerequisites

Procedure

  1. Create a resolver that references the alias of an existing SecretKeyCredential in a credential store using the following management CLI command:

    Syntax

    /subsystem=elytron/expression=encryption:add(resolvers=[{name=<name_of_the_resolver>, credential-store=<name_of_credential_store>, secret-key=<secret_key_alias>}])
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/expression=encryption:add(resolvers=[{name=exampleResolver, credential-store=examplePropertiesCredentialStore, secret-key=key}])
    Copy to Clipboard Toggle word wrap

    If an error message about a duplicate resource displays, use the list-add operation instead of add, as follows:

    Syntax

    /subsystem=elytron/expression=encryption:list-add(name=resolvers, value={name=<name_of_the_resolver>, credential-store=<name_of_credential_store>, secret-key=<secret_key_alias>})
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/expression=encryption:list-add(name=resolvers,value={name=exampleResolver, credential-store=examplePropertiesCredentialStore, secret-key=key})
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}
    Copy to Clipboard Toggle word wrap

  2. Reload the server using the following management CLI command: 

    reload
    Copy to Clipboard Toggle word wrap

  3. Disable caching of commands in the management CLI:

    Important

    If you do not disable caching, the secret key is visible to anyone who can access the management CLI history file. 

    history --disable
    Copy to Clipboard Toggle word wrap

  4. Create an encrypted expression using the following management CLI command:

    Syntax

    /subsystem=elytron/expression=encryption:create-expression(resolver=<existing_resolver>, clear-text=<sensitive_string_to_protect>)
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/expression=encryption:create-expression(resolver=exampleResolver, clear-text=TestPassword)
{
    "outcome" => "success",
    "result" => {"expression" => "${ENC::exampleResolver:RUxZAUMQgtpG7oFlHR2j1Gkn3GKIHff+HR8GcMX1QXHvx2uGurI=}"}
}
    Copy to Clipboard Toggle word wrap

    ${ENC::exampleResolver:RUxZAUMQgtpG7oFlHR2j1Gkn3GKIHff+HR8GcMX1QXHvx2uGurI=} is the encrypted expression you use instead of TestPassword in the management model.

    If you use the same plain text in different locations, repeat this command each time before you use the encrypted expression instead of the plain text in that location. When you repeat the same command for the same plain text, you get a different result for the same key because Elytron uses a unique initialization vector for each call.

    By using different encrypted expressions you make sure that, if one encrypted expression on a string is somehow compromised, users cannot discover that any other encrypted expressions might also contain the same string.

  5. Re-enable the command caching using the following management CLI command: 

    history --enable
    Copy to Clipboard Toggle word wrap

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.

Prerequisites

Procedure

  • Reference the existing KeyStoreCredentialStore and the alias to the PasswordCredential in the credential-reference attribute:

    Syntax

    credential-reference={store=<store_name>, alias=<alias>}
    Copy to Clipboard Toggle word wrap

    Example

    data-source add --name=example_data_source --jndi-name=java:/example_data_source --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=exampleKeyStoreCredentialStore, alias=passwordCredentialAlias}
16:17:23,024 INFO  [org.jboss.as.connector.subsystems.datasources] (MSC service thread 1-2) WFLYJCA0001: Bound data source [java:/example_data_source]
    Copy to Clipboard Toggle word wrap

    In this example, an existing PasswordCredential with the alias passwordCredentialAlias in a KeyStoreCredentialStore exampleKeyStoreCredentialStore is used instead of the plain text password for the database, protecting the database password.

You can use an encrypted expression to secure a KeyStoreCredentialStore.

Prerequisites

Procedure

  • Create a KeyStoreCredentialStore that uses an encrypted expression as the clear-text:

    Syntax

    /subsystem=elytron/credential-store=<name_of_credential_store>:add(path=<path_to_the_credential_store>, create=true, modifiable=true, credential-reference={clear-text=<encrypted_expression>})
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/credential-store=secureKeyStoreCredentialStore:add(path="secureKeyStoreCredentialStore.jceks", relative-to=jboss.server.data.dir, create=true, modifiable=true, credential-reference={clear-text=${ENC::exampleResolver:RUxZAUMQgtpG7oFlHR2j1Gkn3GKIHff+HR8GcMX1QXHvx2uGurI=}})
{"outcome" => "success"}
    Copy to Clipboard Toggle word wrap

If you have a credential store, you are not required to add credentials or update existing credentials before you can reference them from a credential reference. Elytron automates this process. When configuring a credential reference, specify both the store and clear-text attributes. Elytron automatically adds or updates a credential in the credential store specified by the store attribute. Optionally, you can specify the alias attribute.

Elytron updates the credential store as follows:

  • If you specify an alias:

    • If an entry for the alias exists, the existing credential is replaced with the specified clear text password.
    • If an entry for the alias does not exist, a new entry is added to the credential store with the specified alias and the clear text password.
  • If you do not specify an alias, Elytron generates an alias and adds a new entry to the credential store with the generated alias and the specified clear text password.

The clear-text attribute is removed from the management model when the credential store is updated.

The following example illustrates how to create a credential reference that specifies the store, clear-text, and alias attributes: 

/subsystem=elytron/key-store=exampleKS:add(relative-to=jboss.server.config.dir, path=example.keystore, type=JCEKS, credential-reference={store=exampleKeyStoreCredentialStore, alias=myNewAlias, clear-text=myNewPassword})
{
    "outcome" => "success",
    "result" => {"credential-store-update" => {
        "status" => "new-entry-added",
        "new-alias" => "myNewAlias"
    }}
}
Copy to Clipboard Toggle word wrap

You can update the credential for the myNewAlias entry that was added to the previously defined credential store with the following command: 

/subsystem=elytron/key-store=exampleKS:write-attribute(name=credential-reference.clear-text,value=myUpdatedPassword)
{
    "outcome" => "success",
    "result" => {"credential-store-update" => {"status" => "existing-entry-updated"}},
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}
Copy to Clipboard Toggle word wrap
Note

If an operation that includes a credential-reference parameter fails, no automatic credential store update occurs.

The credential store that was specified by the credential-reference attribute does not change.

You can define a Federal Information Processing Standards (FIPS) 140-2-compliant credential store using a Network Security Services (NSS) database, or with a Bouncy Castle provider.

To get a Federal Information Processing Standards (FIPS)-compliant keystore, use a Sun PKCS#11 (PKCS stands for Public Key Cryptography Standards) provider accessing a Network Security Services (NSS) database. For instructions on defining the database, see Configuring the NSS Database.

Procedure

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

    Note

    For the keytool command to work, in the nss_pkcsll_fips.cfg file, you must assign the nssDbMode attribute as readWrite. 

    $ keytool -keystore NONE -storetype PKCS11 -storepass <keystore_password> -genseckey -alias <key_alias> -keyalg <key_algorithm> -keysize <key_size>
    Copy to Clipboard Toggle word wrap

  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 Java Cryptography Extension Keystore (JCEKS) keystore. In addition to the credential-store attributes, Elytron uses the credential-store KeyStoreCredentialStore implementation properties to configure external credential stores. 

    /subsystem=elytron/credential-store=<store_name>:add(modifiable=true, implementation-properties={"keyStoreType"=>"PKCS11", "external"=>"true", "keyAlias"=>"<key_alias>", externalPath="<path_to_JCEKS_file>"}, credential-reference={clear-text="<keystore_password>"}, create=true)
    Copy to Clipboard Toggle word wrap

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

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

    /subsystem=elytron/credential-store=<store_name>:read-aliases()
    Copy to Clipboard Toggle word wrap

Define a Federal Information Processing Standards (FIPS) 140-2 compliant credential store using Bouncy Castle providers.

Prerequisites

Procedure

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

    $ keytool -genseckey -alias<key_alias> -keyalg <key_algorithm> -keysize <key_size> -keystore <path_to_keystore> -storetype BCFKS -storepass <key_and_keystore_password> -keypass <key_and_keystore_password>
    Copy to Clipboard Toggle word wrap
    Important

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

  2. 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=<key_and_keystore_password>},implementation-properties={keyAlias=<key_alias>,external=true,externalPath=<path_to_credential_store>,keyStoreType=BCFKS},create=true,location=<path_to_keystore>,modifiable=true)
    Copy to Clipboard Toggle word wrap

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

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

    /subsystem=elytron/credential-store=<BCFKS_credential_store>:read-aliases()
    Copy to Clipboard Toggle word wrap

Use a custom implementation of the credential store.

Procedure

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

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

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

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

Instead of providing your credential store’s password in clear text format, you can choose to provide the password by using a pseudo credential store.

You have the following options for providing a password:

EXT

External command using java.lang.Runtime#exec(java.lang.String). You can supply parameters to the command with a space-separated list of strings. An external command refers to any executable file from the operating system, for example, a shell script or an executable binary file. Elytron reads the password from the standard output of the command that you run.

Example

credential-reference={clear-text="{EXT}/usr/bin/getThePasswordScript.sh par1 par2", type="COMMAND"}
Copy to Clipboard Toggle word wrap

CMD

External command using java.lang.ProcessBuilder. You can supply parameters to the command with a comma-separated list of strings. An external command refers to any executable file from the operating system, for example, a shell script or an executable binary file. Elytron reads the password from the standard output of the command that you run.

Example

credential-reference={clear-text="{CMD}/usr/bin/getThePasswordScript.sh par1,par2", type="COMMAND"}
Copy to Clipboard Toggle word wrap

MASK

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

credential-reference={clear-text="MASK-MASKED_VALUE;SALT;ITERATION"}
Copy to Clipboard Toggle word wrap

Example

credential-reference={clear-text="MASK-NqMznhSbL3lwRpDmyuqLBW==;12345678;123"}
Copy to Clipboard Toggle word wrap

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 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=cred-store, alias=pwd})
Copy to Clipboard Toggle word wrap

For security, some JBoss EAP components are protected by a PasswordCredential in KeyStoreCredentialStore. This KeyStoreCredentialStore is in turn protected by a secret key stored external to JBoss EAP. This is referred to as a master key. JBoss EAP uses this master key during startup to unlock the KeyStoreCredentialStore to obtain the PasswordCredential stored in the KeyStoreCredentialStore.

You can use a PropertiesCredentialStore in Elytron to provide the master key. Alternately, you can obtain the master key or password from an external source. For information about obtaining the password from an external source, see Obtain the password for the credential store from an external source.

Create a PropertiesCredentialStore using the management CLI. When you create a PropertiesCredentialStore, JBoss EAP generates a secret key by default. The name of the generated key is key and its size is 256-bit.

Prerequisites

  • You have provided at least read/write access to the directory containing the PropertiesCredentialStore for the user account under which JBoss EAP is running.

Procedure

  • Use the following command to create a PropertiesCredentialStore using the management CLI:

    Syntax

    /subsystem=elytron/secret-key-credential-store=<name_of_credential_store>:add(path="<path_to_the_credential_store>", relative-to=<path_to_store_file>)
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:add(path=examplePropertiesCredentialStore.cs, relative-to=jboss.server.config.dir)
{"outcome" => "success"}
    Copy to Clipboard Toggle word wrap

Create an encrypted expression from a sensitive string and a SecretKeyCredential. Use this encrypted expression instead of the sensitive string in the management model - the server configuration file, to maintain the secrecy of the sensitive string.

Prerequisites

Procedure

  1. Create a resolver that references the alias of an existing SecretKeyCredential in a credential store using the following management CLI command:

    Syntax

    /subsystem=elytron/expression=encryption:add(resolvers=[{name=<name_of_the_resolver>, credential-store=<name_of_credential_store>, secret-key=<secret_key_alias>}])
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/expression=encryption:add(resolvers=[{name=exampleResolver, credential-store=examplePropertiesCredentialStore, secret-key=key}])
    Copy to Clipboard Toggle word wrap

    If an error message about a duplicate resource displays, use the list-add operation instead of add, as follows:

    Syntax

    /subsystem=elytron/expression=encryption:list-add(name=resolvers, value={name=<name_of_the_resolver>, credential-store=<name_of_credential_store>, secret-key=<secret_key_alias>})
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/expression=encryption:list-add(name=resolvers,value={name=exampleResolver, credential-store=examplePropertiesCredentialStore, secret-key=key})
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}
    Copy to Clipboard Toggle word wrap

  2. Reload the server using the following management CLI command: 

    reload
    Copy to Clipboard Toggle word wrap

  3. Disable caching of commands in the management CLI:

    Important

    If you do not disable caching, the secret key is visible to anyone who can access the management CLI history file. 

    history --disable
    Copy to Clipboard Toggle word wrap

  4. Create an encrypted expression using the following management CLI command:

    Syntax

    /subsystem=elytron/expression=encryption:create-expression(resolver=<existing_resolver>, clear-text=<sensitive_string_to_protect>)
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/expression=encryption:create-expression(resolver=exampleResolver, clear-text=TestPassword)
{
    "outcome" => "success",
    "result" => {"expression" => "${ENC::exampleResolver:RUxZAUMQgtpG7oFlHR2j1Gkn3GKIHff+HR8GcMX1QXHvx2uGurI=}"}
}
    Copy to Clipboard Toggle word wrap

    ${ENC::exampleResolver:RUxZAUMQgtpG7oFlHR2j1Gkn3GKIHff+HR8GcMX1QXHvx2uGurI=} is the encrypted expression you use instead of TestPassword in the management model.

    If you use the same plain text in different locations, repeat this command each time before you use the encrypted expression instead of the plain text in that location. When you repeat the same command for the same plain text, you get a different result for the same key because Elytron uses a unique initialization vector for each call.

    By using different encrypted expressions you make sure that, if one encrypted expression on a string is somehow compromised, users cannot discover that any other encrypted expressions might also contain the same string.

  5. Re-enable the command caching using the following management CLI command: 

    history --enable
    Copy to Clipboard Toggle word wrap

You can use an encrypted expression to secure a KeyStoreCredentialStore.

Prerequisites

Procedure

  • Create a KeyStoreCredentialStore that uses an encrypted expression as the clear-text:

    Syntax

    /subsystem=elytron/credential-store=<name_of_credential_store>:add(path=<path_to_the_credential_store>, create=true, modifiable=true, credential-reference={clear-text=<encrypted_expression>})
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/credential-store=secureKeyStoreCredentialStore:add(path="secureKeyStoreCredentialStore.jceks", relative-to=jboss.server.data.dir, create=true, modifiable=true, credential-reference={clear-text=${ENC::exampleResolver:RUxZAUMQgtpG7oFlHR2j1Gkn3GKIHff+HR8GcMX1QXHvx2uGurI=}})
{"outcome" => "success"}
    Copy to Clipboard Toggle word wrap

After you have secured a KeyStoreCredentialStore with an encrypted expression, you can generate a SecretKeyCredential in the KeyStoreCredentialStore and use the secret key to create another encrypted expression. You can then use this new encrypted expression instead of a sensitive string in the management model - the server configuration file. You can create an entire chain of credential stores for security. Such a chain makes it harder to guess the sensitive string because the string is protected as follows:

  • The first encrypted expression secures a KeyStoreCredentialStore.
  • Another encrypted expression secures a sensitive string.
  • To decode the sensitive string, you would need to decrypt both the encrypted expressions.

As the chain of encrypted expressions becomes longer, it gets harder to decrypt the sensitive string.

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 to a Credential Store using the WildFly Elytron tool.

Procedure

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

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

Procedure

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

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

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

Clients connecting to JBoss EAP, such as Jakarta Enterprise Beans, 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:client: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>
Copy to Clipboard Toggle word wrap

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

4.2. Password Vault
Copy link

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

4.2.1. Set Up a Password Vault
Copy link

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

    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.

4.2.2. Initialize the Password Vault
Copy link

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

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

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

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

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

4.2.3. Use a Password Vault
Copy link

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

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

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

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

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

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

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

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

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

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

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

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

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

Password doesn't exist.
Copy to Clipboard Toggle word wrap

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

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

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

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

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

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

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

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

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

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

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

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

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.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

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

Making open source more inclusive

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

About Red Hat

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

Theme

© 2026 Red HatBack to top