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
4.1.1. Credential stores provided by Elytron
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
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
4.1.1.2. PropertiesCredentialStore/secret-key-credential-store
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
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
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
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}
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.
4.1.3. Credential types supported by Elytron credential stores
The following table illustrates which credential type is supported by which credential store:
Credential type | KeyStoreCredentialStore/credential-store | PropertiesCredentialStore/secret-key-credential-store |
---|---|---|
PasswordCredential | Yes | No |
KeyPairCredential | Yes | No |
SecretKeyCredential | Yes | Yes |
Additional resources
4.1.4. Credential store operations using the JBoss EAP management CLI
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.
You can do these operation only on modifiable credential stores. All credential store types are modifiable by default.
4.1.4.1. Creating a KeyStoreCredentialStore/credential-store for a standalone server
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.
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)
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"}
4.1.4.2. Creating a KeyStoreCredentialStore/credential-store for a managed domain
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.
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
.
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
- 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.
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.NoteTo 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)
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)
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>"})
Example
/profile=full-ha/subsystem=elytron/credential-store=exampleCredentialStoreHA:add(path=/usr/local/etc/example-cred-store-ha.cs, credential-reference={clear-text="password"})
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>"})
Example
/host=master/subsystem=elytron/credential-store=exampleCredentialStoreHost:add(path=/usr/local/etc/example-cred-store-host.cs, credential-reference={clear-text="password"})
4.1.4.3. Creating a PropertiesCredentialStore/secret-key-credential-store for a standalone server
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>)
Example
/subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:add(path=examplePropertiesCredentialStore.cs, relative-to=jboss.server.config.dir) {"outcome" => "success"}
4.1.4.4. Adding a PasswordCredential to a KeyStoreCredentialStore/credential-store
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
You have created a KeyStoreCredentialStore.
For information about creating a KeyStoreCredentialStore, see Creating a KeyStoreCredentialStore/credential-store for a standalone server.
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>)
Example
/subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:add-alias(alias=passwordCredentialAlias, secret-value=StrongPassword) {"outcome" => "success"}
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()
Example
/subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:read-aliases() { "outcome" => "success", "result" => ["passwordcredentialalias"] }
4.1.4.5. Generating a SecretKeyCredential in a KeyStoreCredentialStore/credential-store
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
You have created a KeyStoreCredentialStore.
For information about creating a KeyStoreCredentialStore, see Creating a KeyStoreCredentialStore/credential-store for a standalone server.
Procedure
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>)
Example
/subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:generate-secret-key(alias=secretKeyCredentialAlias)
Verification
Issue the following command to verify that Elytron stored your SecretKeyCredential in the KeyStoreCredentialStore:
Syntax
/subsystem=elytron/credential-store=<credential_store>:read-aliases()
Example
/subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:read-aliases() { "outcome" => "success", "result" => [ "secretkeycredentialalias" ] }
4.1.4.6. Generating a SecretKeyCredential in a PropertiesCredentialStore/secret-key-credential-store
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.
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
You have created a PropertiesCredentialStore.
For information about creating a PropertiesCredentialStore, see Creating a PropertiesCredentialStore/secret-key-credential-store for a standalone server.
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>)
Example
/subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:generate-secret-key(alias=secretKeyCredentialAlias) {"outcome" => "success"}
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()
Example
/subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:read-aliases() { "outcome" => "success", "result" => [ "secretkeycredentialalias", "key" ] }
4.1.4.7. Importing a SecretKeyCredential to PropertiesCredentialStore/secret-key-credential-store
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
You have created a PropertiesCredentialStore.
For information about creating a PropertiesCredentialStore, see Creating a PropertiesCredentialStore/secret-key-credential-store for a standalone server.
You have exported a SecretKeyCredential.
For information about exporting a SecretKeyCredential, see Exporting a SecretKeyCredential from a PropertiesCredentialStore/secret-key-credential-store.
Procedure
Disable caching of commands in the management CLI using the following command:
ImportantIf you do not disable caching, the secret key is visible to anyone who can access the management CLI history file.
history --disable
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>")
Example
/subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:import-secret-key(alias=imported, key="RUxZAUs+Y1CzEPw0g2AHHOZ+oTKhT9osSabWQtoxR+O+42o11g==")
Re-enable the caching of commands using the following management CLI command:
history --enable
4.1.4.8. Listing credentials in the KeyStoreCredentialStore/credential-store
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()
Example
/subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:read-aliases() { "outcome" => "success", "result" => [ "passwordcredentialalias", "secretkeycredentialalias" ] }
Additional resources
4.1.4.9. Listing credentials in the PropertiesCredentialStore/secret-key-credential-store
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()
Example
/subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:read-aliases() { "outcome" => "success", "result" => [ "secretkeycredentialalias", "key" ] }
4.1.4.10. Exporting a SecretKeyCredential from a KeyStoreCredentialStore/credential-store
You can export an existing SecretKeyCredential from a KeyStoreCredentialStore to use the SecretKeyCredential or to create a backup of the SecretKeyCredential.
Prerequisites
You have generated a SecretKeyCredential the KeyStoreCredentialStore.
For information about generating a SecretKeyCredential in a KeyStoreCredentialStore, see Generating a SecretKeyCredential in a KeyStoreCredentialStore/credential-store.
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>)
Example
/subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:export-secret-key(alias=secretKeyCredentialAlias) { "outcome" => "success", "result" => {"key" => "RUxZAUui+8JkoDCE6mFyA3cCIbSAZaXq5wgYejj1scYgdDqWiw=="} }
Additional resources
4.1.4.11. Exporting a SecretKeyCredential from a PropertiesCredentialStore/secret-key-credential-store
You can export an existing SecretKeyCredential from a PropertiesCredentialStore to use the SecretKeyCredential or to create a backup of the SecretKeyCredential.
Prerequisites
You have either generated a SecretKeyCredential in the PropertiesCredentialStore or imported one to it.
For information on generating a SecretKeyCredential in a PropertiesCredentialStore, see Generating a SecretKeyCredential in a PropertiesCredentialStore/secret-key-credential-store.
For information on importing a SecretKeyCredential to a PropertiesCredentialStore, see Importing a SecretKeyCredential to PropertiesCredentialStore/secret-key-credential-store
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>)
Example
/subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:export-secret-key(alias=secretkeycredentialalias) { "outcome" => "success", "result" => {"key" => "RUxZAUtxXcYvz0aukZu+odOynIr0ByLhC72iwzlJsi+ZPmONgA=="} }
4.1.4.12. Removing a credential from KeyStoreCredentialStore/credential-store
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>)
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" } }]} }
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" } }]} }
Verification
Issue the following command to verify that Elytron removed the credential:
Syntax
/subsystem=elytron/credential-store=<name_of_credential_store>:read-aliases()
Example
/subsystem=elytron/credential-store=exampleKeyStoreCredentialStore:read-aliases() { "outcome" => "success", "result" => [] }
The credential you removed is not listed.
Additional resources
4.1.4.13. Removing a credential from the PropertiesCredentialStore/secret-key-credential-store
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>)
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" } }]} }
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()
Example
/subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:read-aliases() { "outcome" => "success", "result" => [] }
The credential you removed is not listed.
4.1.5. Credential store operations using the WildFly Elytron tool
4.1.5.1. Creating a KeyStoreCredentialStore/credential-store using the WildFly Elytron tool
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>
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
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.
4.1.5.2. Creating a KeyStoreCredentialStore/credential-store using the Bouncy Castle provider
Create a KeyStoreCredentialStore using the Bouncy Castle provider.
Prerequisites
Make sure that your environment is configured to use Bouncy Castle.
For more information, see Configure Your Environment to use the Bouncy Castle Provider.
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
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>
ImportantMake sure that the keystore
keypass
andstorepass
attributes are identical. If they aren’t, theBCFKS
keystore in theelytron
subsystem can’t define them.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>
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>"
4.1.5.3. Creating a PropertiesCredentialStore/secret-key-credential-store using WildFly Elytron tool
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
Example
$ bin/elytron-tool.sh credential-store --create --location=standalone/configuration/properties-credential-store.cs --type PropertiesCredentialStore Credential Store has been successfully created
4.1.5.4. WildFly Elytron tool KeyStoreCredentialStore/credential-store operations
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>
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
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>
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
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>
Example
$ EAP_HOME/bin/elytron-tool.sh credential-store --import-secret-key=imported --location=../cred_stores/example-credential-store.jceks --password=storePassword
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
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
- 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>
Example
$ EAP_HOME/bin/elytron-tool.sh credential-store --location "../cred_stores/example-credential-store.jceks" --password storePassword --exists examplepasswordcredential Alias "examplepasswordcredential" exists
- 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
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==
- 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>
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
Additional resources
4.1.5.5. WildFly Elytron tool PropertiesCredentialStore/secret-key-credential-store operations
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
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
- 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
Example
$ EAP_HOME/bin/elytron-tool.sh credential-store --import-secret-key=imported --location "standalone/configuration/properties-credential-store.cs" --type PropertiesCredentialStore
- 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
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
- 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
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==
- 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
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
Additional resources
4.1.5.6. Adding a credential store created with the WildFly Elytron tool to a JBoss EAP Server
After you have created a credential store with the WildFly Elytron tool, you can add it to your running JBoss EAP server.
Prerequisites
You have created a credential store with the WildFly Elytron tool.
For more information, see Creating a KeyStoreCredentialStore/credential-store using the WildFly Elytron tool.
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>})
For example:
/subsystem=elytron/credential-store=my_store:add(location="../cred_stores/example-credential-store.jceks",credential-reference={clear-text=storePassword})
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.
Additional resources
4.1.5.7. WildFly Elytron tool key pair management operations
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 isexample
.$ EAP_HOME/bin/elytron-tool.sh credential-store --location=<path_to_store_file> --generate-key-pair example --algorithm RSA --size 3072
- 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>
- 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=
NoteAfter 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.
4.1.5.8. Example use of stored key pair in the Elytron configuration files
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>
After you configure the elytron
configuration file, the key pair can be used for SSH authentication.
Additional resources
4.1.5.9. Generating masked encrypted strings using the WildFly Elytron tool
You can use the WildFly Elytron tool to generate PicketBox-compatible MASK-
encrypted strings to use instead of a plain text password for a credential store.
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>
For example:
$ EAP_HOME/bin/elytron-tool.sh mask --salt 12345678 --iteration 123 --secret supersecretstorepassword MASK-8VzWsSNwBaR676g8ujiIDdFKwSjOBHCHgnKf17nun3v;12345678;123
If you do not want to provide the secret in the command, you can omit that argument and you will be prompted to enter the secret manually using standard input.
For more information, use the EAP_HOME/bin/elytron-tool.sh mask --help
command for a detailed listing of available options.
4.1.6. Encrypted expressions in Elytron
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}
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=}
If you create an encrypted expression with a default resolver, it looks like this:
Syntax when using the default resolver
${ENC::ENCRYPTED_STRING}
Example
${ENC::RUxZAUMQE+L5zx9LmCRLyh5fjdfl1WM7lhfthKjeoEU+x+RMi6s=}
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, ... }] }
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.
Additional resources
4.1.7. Creating an encrypted expression in Elytron
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
You have generated a secret key in some credential store.
For information on creating a secret key in a
KeyStoreCredentialStore
, see Generating a SecretKeyCredential in a KeyStoreCredentialStore/credential-storeFor information on creating a secret key in a
PropertiesCredentialStore
, see Generating a SecretKeyCredential in a PropertiesCredentialStore/secret-key-credential-store
Procedure
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>}])
Example
/subsystem=elytron/expression=encryption:add(resolvers=[{name=exampleResolver, credential-store=examplePropertiesCredentialStore, secret-key=key}])
If an error message about a duplicate resource displays, use the
list-add
operation instead ofadd
, 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>})
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" } }
Reload the server using the following management CLI command:
reload
Disable caching of commands in the management CLI:
ImportantIf you do not disable caching, the secret key is visible to anyone who can access the management CLI history file.
history --disable
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>)
Example
/subsystem=elytron/expression=encryption:create-expression(resolver=exampleResolver, clear-text=TestPassword) { "outcome" => "success", "result" => {"expression" => "${ENC::exampleResolver:RUxZAUMQgtpG7oFlHR2j1Gkn3GKIHff+HR8GcMX1QXHvx2uGurI=}"} }
${ENC::exampleResolver:RUxZAUMQgtpG7oFlHR2j1Gkn3GKIHff+HR8GcMX1QXHvx2uGurI=}
is the encrypted expression you use instead ofTestPassword
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.
Re-enable the command caching using the following management CLI command:
history --enable
4.1.8. Using a PasswordCredential in your JBoss EAP configuration
To refer to a password or sensitive string stored in a credential store, use the credential-reference
attribute in your JBoss EAP configuration. You can use credential-reference
as an alternative to providing a password or other sensitive string in most places throughout the JBoss EAP configuration.
Prerequisites
You have added a PasswordCredential to a KeyStoreCredentialStore.
For information on adding PasswordCredential to a KeyStoreCredentialStore, see Adding a PasswordCredential to a KeyStoreCredentialStore.
Procedure
Reference the existing KeyStoreCredentialStore and the alias to the PasswordCredential in the
credential-reference
attribute:Syntax
credential-reference={store=<store_name>, alias=<alias>}
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]
In this example, an existing PasswordCredential with the alias
passwordCredentialAlias
in a KeyStoreCredentialStoreexampleKeyStoreCredentialStore
is used instead of the plain text password for the database, protecting the database password.
4.1.9. Using an encrypted expression to secure a KeyStoreCredentialStore/credential-store
You can use an encrypted expression to secure a KeyStoreCredentialStore.
Prerequisites
You have created an encrypted expression.
For information about creating an encrypted expression, see Creating an encrypted expression in Elytron.
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>})
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"}
Additional resources
4.1.10. Automatic update of credentials in credential store
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" }} }
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" } }
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.
4.1.11. Defining FIPS 140-2 compliant credential stores
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.
4.1.11.1. Defining a FIPS 140-2 compliant credential store using an NSS database
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
Create a secret key to be used in the credential store.
NoteFor the
keytool
command to work, in thenss_pkcsll_fips.cfg
file, you must assign thenssDbMode
attribute asreadWrite
.$ keytool -keystore NONE -storetype PKCS11 -storepass <keystore_password> -genseckey -alias <key_alias> -keyalg <key_algorithm> -keysize <key_size>
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 thecredential-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)
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>")
Confirm that the alias has been added successfully by reading from the credential store.
/subsystem=elytron/credential-store=<store_name>:read-aliases()
4.1.11.2. Defining a FIPS 140-2 compliant credential store using Bouncy Castle providers
Define a Federal Information Processing Standards (FIPS) 140-2 compliant credential store using Bouncy Castle providers.
Prerequisites
Ensure that your environment is configured to use the
BouncyCastle
provider.For more information, see Configure Your Environment to use the
BouncyCastle
Provider .
Procedure
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>
ImportantThe
keypass
andstorepass
for the keystore must be identical for FIPS credential stores to be defined in theelytron
subsystem.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)
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>")
Confirm that the alias has been added successfully by reading from the credential store.
/subsystem=elytron/credential-store=<BCFKS_credential_store>:read-aliases()
4.1.12. Using a custom implementation of the credential store
Use a custom implementation of the credential store.
Procedure
-
Create a class that extends the Service Provider Interface (SPI)
CredentialStoreSpi
abstract class. -
Create a class that implements the Java Security
Provider
. The provider must add the custom credential store class as a service. 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
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)
Create a credential store using the custom implementation.
NoteEnsure that you specify the correct
providers
andtype
values. The value oftype
is what is used in your provider class where it adds your custom credential store class as a service.For example:
/subsystem=elytron/credential-store=my_store:add(providers=myCustomLoader,type=CustomKeyStorePasswordStore,location="cred_stores/my_store.jceks",relative-to=jboss.server.data.dir,credential-reference={clear-text=supersecretstorepassword},create=true)
Alternatively, if you have created multiple providers, you can specify the additional providers using another provider loader with
other-providers
. This allows you to have other additional implementations for new types of credentials. These specified other providers are automatically accessible in the custom credential store’sinitialize
method as theProvider[]
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)
4.1.13. Obtain the password for the credential store from an external source
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"}
- 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"}
- MASK
Masked password using PBE, or Password-Based Encryption. It must be in the following format, which includes the
SALT
andITERATION
values:credential-reference={clear-text="MASK-MASKED_VALUE;SALT;ITERATION"}
Example
credential-reference={clear-text="MASK-NqMznhSbL3lwRpDmyuqLBW==;12345678;123"}
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})
Additional resources
4.1.14. Providing an initial key to JBoss EAP to unlock secured resources
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.
4.1.14.1. Creating a PropertiesCredentialStore/secret-key-credential-store for a standalone server
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>)
Example
/subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:add(path=examplePropertiesCredentialStore.cs, relative-to=jboss.server.config.dir) {"outcome" => "success"}
4.1.14.2. Creating an encrypted expression in Elytron
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
You have generated a secret key in some credential store.
For information on creating a secret key in a
KeyStoreCredentialStore
, see Generating a SecretKeyCredential in a KeyStoreCredentialStore/credential-storeFor information on creating a secret key in a
PropertiesCredentialStore
, see Generating a SecretKeyCredential in a PropertiesCredentialStore/secret-key-credential-store
Procedure
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>}])
Example
/subsystem=elytron/expression=encryption:add(resolvers=[{name=exampleResolver, credential-store=examplePropertiesCredentialStore, secret-key=key}])
If an error message about a duplicate resource displays, use the
list-add
operation instead ofadd
, 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>})
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" } }
Reload the server using the following management CLI command:
reload
Disable caching of commands in the management CLI:
ImportantIf you do not disable caching, the secret key is visible to anyone who can access the management CLI history file.
history --disable
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>)
Example
/subsystem=elytron/expression=encryption:create-expression(resolver=exampleResolver, clear-text=TestPassword) { "outcome" => "success", "result" => {"expression" => "${ENC::exampleResolver:RUxZAUMQgtpG7oFlHR2j1Gkn3GKIHff+HR8GcMX1QXHvx2uGurI=}"} }
${ENC::exampleResolver:RUxZAUMQgtpG7oFlHR2j1Gkn3GKIHff+HR8GcMX1QXHvx2uGurI=}
is the encrypted expression you use instead ofTestPassword
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.
Re-enable the command caching using the following management CLI command:
history --enable
4.1.14.3. Using an encrypted expression to secure a KeyStoreCredentialStore/credential-store
You can use an encrypted expression to secure a KeyStoreCredentialStore.
Prerequisites
You have created an encrypted expression.
For information about creating an encrypted expression, see Creating an encrypted expression in Elytron.
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>})
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"}
Additional resources
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.
4.1.15. Converting password vaults to credential stores
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.
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
.
4.1.15.1. Converting a single password vault to a Credential Store using the WildFly Elytron tool
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>
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
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.
4.1.15.2. Bulk converting password vault to a credential store using the WildFly Elytron tool
Bulk convert multiple password vaults to credential stores.
Procedure
Put the details of the vaults you want to convert into a description file in the following format:
keystore:<path_to_vault_file> keystore-password:<vault_password> enc-dir:<path_to_vault_directory> salt:<salt> 1 iteration:<iteration_count> location:<path_to_converted_cred_store> 2 alias:<vault_alias> properties:<parameter1>=<value1>;<parameter2>=<value2>; 3
- 1
salt
anditeration
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 (
;
). SeeEAP_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
Run the bulk convert command with your description file from the previous step:
$ EAP_HOME/bin/elytron-tool.sh vault --bulk-convert vaultdescriptions.txt
For more information, use the EAP_HOME/bin/elytron-tool.sh vault --help
command for a detailed listing of available options.
4.1.16. Example of using a credential store with Elytron client
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>
4.2. Password Vault
Configuration of JBoss EAP and associated applications requires potentially sensitive information, such as user names and passwords. Instead of storing the password as plain text in configuration files, the password vault feature can be used to mask the password information and store it in an encrypted keystore. Once the password is stored, references can be included in management CLI commands or applications deployed to JBoss EAP.
The password vault uses the Java keystore as its storage mechanism. Password vault consists of two parts: storage and key storage. Java keystore is used to store the key, which is used to encrypt or decrypt sensitive strings in Vault storage.
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
Follow the steps below to set up and use a Password Vault.
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.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.
Run the keytool command, ensuring
keypass
andstorepass
contain the same value.$ keytool -genseckey -alias vault -storetype jceks -keyalg AES -keysize 128 -storepass vault22 -keypass vault22 -keystore EAP_HOME/vault/vault.keystore
This results in a keystore that has been created in the file
EAP_HOME/vault/vault.keystore
. It stores a single key, with the alias vault, which will be used to store encrypted strings, such as passwords, for JBoss EAP.
4.2.2. Initialize the Password Vault
The password vault can be initialized either interactively, where you are prompted for each parameter’s value, or non-interactively, where all parameter values are provided on the command line. Each method gives the same result, so either may be used.
The following parameters will be needed:
- keystore URL (KEYSTORE_URL)
-
The file system path or URI of the keystore file. The examples use
EAP_HOME/vault/vault.keystore
. - keystore password (KEYSTORE_PASSWORD)
- The password used to access the keystore.
- Salt (SALT)
- The salt value is a random string of eight characters used, together with the iteration count, to encrypt the content of the keystore.
- keystore Alias (KEYSTORE_ALIAS)
- The alias by which the keystore is known.
- Iteration Count (ITERATION_COUNT)
- The number of times the encryption algorithm is run.
- Directory to store encrypted files (ENC_FILE_DIR)
- The path in which the encrypted files are to be stored. This is typically the directory containing the password vault. It is convenient but not mandatory to store all of your encrypted information in the same place as the keystore. This directory should be only accessible to limited users. At a minimum the user account under which JBoss EAP 7 is running requires read-write access. The keystore should be located in the directory you created when you set up the password vault. Note that the trailing backslash or forward slash on the directory name is required. Ensure the correct file path separator is used: / (forward slash) for Red Hat Enterprise Linux and similar operating systems, \ (backslash) for Windows Server.
- Vault Block (VAULT_BLOCK)
- The name to be given to this block in the password vault.
- Attribute (ATTRIBUTE)
- The name to be given to the attribute being stored.
- Security Attribute (SEC-ATTR)
- The password which is being stored in the password vault.
To run the password vault command non-interactively, the vault
script located in EAP_HOME/bin/
can be invoked with parameters for the relevant information:
$ vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --vault-block VAULT_BLOCK --attribute ATTRIBUTE --sec-attr SEC-ATTR --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT
Example: Initializing Password Vault
$ vault.sh --keystore EAP_HOME/vault/vault.keystore --keystore-password vault22 --alias vault --vault-block vb --attribute password --sec-attr 0penS3sam3 --enc-dir EAP_HOME/vault/ --iteration 120 --salt 1234abcd
Example: Output
========================================================================= JBoss Vault JBOSS_HOME: EAP_HOME JAVA: java ========================================================================= Nov 09, 2015 9:02:47 PM org.picketbox.plugins.vault.PicketBoxSecurityVault init INFO: PBOX00361: Default Security Vault Implementation Initialized and Ready WFLYSEC0047: Secured attribute value has been stored in Vault. Please make note of the following: ******************************************** Vault Block:vb Attribute Name:password Configuration should be done as follows: VAULT::vb::password::1 ******************************************** WFLYSEC0048: Vault Configuration in WildFly configuration file: ******************************************** </extensions> <vault> <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/> <vault-option name="KEYSTORE_PASSWORD" value="MASK-5dOaAVafCSd"/> <vault-option name="KEYSTORE_ALIAS" value="vault"/> <vault-option name="SALT" value="1234abcd"/> <vault-option name="ITERATION_COUNT" value="120"/> <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/> </vault><management> ... ********************************************
To run the password vault command interactively, the following steps are required:
Launch the password vault command interactively.
Run
EAP_HOME/bin/vault.sh
on Red Hat Enterprise Linux and similar operating systems orEAP_HOME\bin\vault.bat
on Windows Server. Start a new interactive session by typing0
(zero).Complete the prompted parameters.
Follow the prompts to input the required parameters.
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.
Exit the interactive console
Type
2
(two) to exit the interactive console.
Example: Input and Output
Please enter a Digit:: 0: Start Interactive Session 1: Remove Interactive Session 2: Exit 0 Starting an interactive session Enter directory to store encrypted files:EAP_HOME/vault/ Enter Keystore URL:EAP_HOME/vault/vault.keystore Enter Keystore password: vault22 Enter Keystore password again: vault22 Values match Enter 8 character salt:1234abcd Enter iteration count as a number (Eg: 44):120 Enter Keystore Alias:vault Initializing Vault Nov 09, 2015 9:24:36 PM org.picketbox.plugins.vault.PicketBoxSecurityVault init INFO: PBOX000361: Default Security Vault Implementation Initialized and Ready Vault Configuration in AS7 config file: ******************************************** ... </extensions> <vault> <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/> <vault-option name="KEYSTORE_PASSWORD" value="MASK-5dOaAVafCSd"/> <vault-option name="KEYSTORE_ALIAS" value="vault"/> <vault-option name="SALT" value="1234abcd"/> <vault-option name="ITERATION_COUNT" value="120"/> <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/> </vault><management> ... ******************************************** Vault is initialized and ready for use Handshake with Vault complete
+ The keystore password has been masked for use in configuration files and deployments. In addition, the vault is initialized and ready to use.
4.2.3. Use a Password Vault
Before passwords and other sensitive attributes can be masked and used in configuration files, JBoss EAP 7 must be made aware of the password vault which stores and decrypts them.
The following command can be used to configure JBoss EAP 7 to use the password vault:
/core-service=vault:add(vault-options=[("KEYSTORE_URL" => PATH_TO_KEYSTORE),("KEYSTORE_PASSWORD" => MASKED_PASSWORD),("KEYSTORE_ALIAS" => ALIAS),("SALT" => SALT),("ITERATION_COUNT" => ITERATION_COUNT),("ENC_FILE_DIR" => ENC_FILE_DIR)]) /core-service=vault:add(vault-options=[("KEYSTORE_URL" => "EAP_HOME/vault/vault.keystore"),("KEYSTORE_PASSWORD" => "MASK-5dOaAVafCSd"),("KEYSTORE_ALIAS" => "vault"),("SALT" => "1234abcd"),("ITERATION_COUNT" => "120"),("ENC_FILE_DIR" => "EAP_HOME/vault/")])
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.
4.2.4. Store a Sensitive String in the Password Vault
Including passwords and other sensitive strings in plaintext configuration files is a security risk. Store these strings instead in the Password Vault for improved security, where they can then be referenced in configuration files, management CLI commands and applications in their masked form.
Sensitive strings can be stored in the Password Vault either interactively, where the tool prompts for each parameter’s value, or non-interactively, where all the parameters' values are provided on the command line. Each method gives the same result, so either may be used. Both of these methods are invoked using the vault
script.
To run the password vault command non-interactively, the vault
script (located in EAP_HOME/bin/
) can be invoked with parameters for the relevant information:
$ vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --vault-block VAULT_BLOCK --attribute ATTRIBUTE --sec-attr SEC-ATTR --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT
The keystore password must be given in plaintext form, not masked form.
$ vault.sh --keystore EAP_HOME/vault/vault.keystore --keystore-password vault22 --alias vault --vault-block vb --attribute password --sec-attr 0penS3sam3 --enc-dir EAP_HOME/vault/ --iteration 120 --salt 1234abcd
Example: Output
========================================================================= JBoss Vault JBOSS_HOME: EAP_HOME JAVA: java ========================================================================= Nov 09, 2015 9:24:36 PM org.picketbox.plugins.vault.PicketBoxSecurityVault init INFO: PBOX00361: Default Security Vault Implementation Initialized and Ready WFLYSEC0047: Secured attribute value has been stored in Vault. Please make note of the following: ******************************************** Vault Block:vb Attribute Name:password Configuration should be done as follows: VAULT::vb::password::1 ******************************************** WFLYSEC0048: Vault Configuration in WildFly configuration file: ******************************************** ... </extensions> <vault> <vault-option name="KEYSTORE_URL" value="../vault/vault.keystore"/> <vault-option name="KEYSTORE_PASSWORD" value="MASK-5dOaAVafCSd"/> <vault-option name="KEYSTORE_ALIAS" value="vault"/> <vault-option name="SALT" value="1234abcd"/> <vault-option name="ITERATION_COUNT" value="120"/> <vault-option name="ENC_FILE_DIR" value="../vault/"/> </vault><management> ... ********************************************
After invoking the vault
script, a message prints to standard output, showing the vault block, attribute name, masked string, and advice about using the string in your configuration. Make note of this information in a secure location. An extract of sample output is as follows:
Vault Block:vb Attribute Name:password Configuration should be done as follows: VAULT::vb::password::1
To run the password vault command interactively, the following steps are required:
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) orEAP_HOME\bin\vault.bat
(on Microsoft Windows Server). Start a new interactive session by typing0
(zero).Complete the prompted parameters.
Follow the prompts to input the required parameters. These values must match those provided when the Password Vault was created.
NoteThe keystore password must be given in plaintext form, not masked form.
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.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
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
4.2.5. Use an Encrypted Sensitive String in Configuration
Any sensitive string which has been encrypted can be used in a configuration file or management CLI command in its masked form, providing expressions are allowed.
To confirm if expressions are allowed within a particular subsystem, run the following management CLI command against that subsystem:
/subsystem=SUBSYSTEM:read-resource-description(recursive=true)
From the output of running this command, look for the value of the expressions-allowed
parameter. If this is true
, then expressions can be used within the configuration of this subsystem.
Use the following syntax to replace any plaintext string with the masked form.
${VAULT::VAULT_BLOCK::ATTRIBUTE_NAME::MASKED_STRING}
Example: Datasource Definition Using a Password in Masked Form
... <subsystem xmlns="urn:jboss:domain:datasources:5.0"> <datasources> <datasource jndi-name="java:jboss/datasources/ExampleDS" enabled="true" use-java-context="true" pool-name="H2DS"> <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url> <driver>h2</driver> <pool></pool> <security> <user-name>sa</user-name> <password>${VAULT::ds_ExampleDS::password::1}</password> </security> </datasource> <drivers> <driver name="h2" module="com.h2database.h2"> <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class> </driver> </drivers> </datasources> </subsystem> ...
4.2.6. Use an Encrypted Sensitive String in an Application
Encrypted strings stored in the password vault can be used in an application’s source code. The below example is an extract of a servlet’s source code, illustrating the use of a masked password in a datasource definition, instead of the plaintext password. The plaintext version is commented out so that you can see the difference.
Example: Servlet Using a Vaulted Password
@DataSourceDefinition( name = "java:jboss/datasources/LoginDS", user = "sa", password = "VAULT::DS::thePass::1", className = "org.h2.jdbcx.JdbcDataSource", url = "jdbc:h2:tcp://localhost/mem:test" ) /*old (plaintext) definition @DataSourceDefinition( name = "java:jboss/datasources/LoginDS", user = "sa", password = "sa", className = "org.h2.jdbcx.JdbcDataSource", url = "jdbc:h2:tcp://localhost/mem:test" )*/
4.2.7. Check if a Sensitive String is in the Password Vault
Before attempting to store or use a sensitive string in the Password Vault it can be useful to first confirm if it is already stored.
This check can be done either interactively, where the user is prompted for each parameter’s value, or non-interactively, where all parameters' values are provided on the command line. Each method gives the same result, so either may be used. Both of these methods are invoked using the vault
script.
Use the non-interative method to provide all parameters' values at once. For a description of all parameters, see Initialize the Password Vault. To run the password vault command non-interactively, the vault
script located in EAP_HOME/bin/
can be invoked with parameters for the relevant information:
$ vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --check-sec-attr --vault-block VAULT_BLOCK --attribute ATTRIBUTE --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT
Substitute the placeholder values with the actual values. The values for parameters KEYSTORE_URL, KEYSTORE_PASSWORD and KEYSTORE_ALIAS must match those provided when the password vault was created.
The keystore password must be given in plaintext form, not masked form.
If the sensitive string is stored in the vault block specified, the following message will be displayed:
Password already exists.
If the value is not stored in the specified block, the following message will be displayed:
Password doesn't exist.
To run the password vault command interactively, the following steps are required:
Launch the password vault command interactively.
Run
EAP_HOME/bin/vault.sh
(on Red Hat Enterprise Linux and similar operating systems) orEAP_HOME\bin\vault.bat
(on Windows Server). Start a new interactive session by typing0
(zero).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.
NoteWhen 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.
-
Enter
If the sensitive string is stored in the vault block specified, a confirmation message like the following will be output:
A value exists for (VAULT_BLOCK, ATTRIBUTE)
If the sensitive string is not stored in the specified block, a message like the following will be output:
No value has been store for (VAULT_BLOCK, ATTRIBUTE)
Example: Check For a Sensitive String Interactively
========================================================================= JBoss Vault JBOSS_HOME: EAP_HOME JAVA: java ========================================================================= ********************************** **** JBoss Vault *************** ********************************** Please enter a Digit:: 0: Start Interactive Session 1: Remove Interactive Session 2: Exit 0 Starting an interactive session Enter directory to store encrypted files:EAP_HOME/vault Enter Keystore URL:EAP_HOME/vault/vault.keystore Enter Keystore password: Enter Keystore password again: Values match Enter 8 character salt:1234abcd Enter iteration count as a number (Eg: 44):120 Enter Keystore Alias:vault Initializing Vault Nov 09, 2015 9:24:36 PM org.picketbox.plugins.vault.PicketBoxSecurityVault init INFO: PBOX000361: Default Security Vault Implementation Initialized and Ready Vault Configuration in AS7 config file: ******************************************** ... </extensions> <vault> <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/> <vault-option name="KEYSTORE_PASSWORD" value="MASK-5dOaAVafCSd"/> <vault-option name="KEYSTORE_ALIAS" value="vault"/> <vault-option name="SALT" value="1234abcd"/> <vault-option name="ITERATION_COUNT" value="120"/> <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/> </vault><management> ... ******************************************** Vault is initialized and ready for use Handshake with Vault complete Please enter a Digit:: 0: Store a secured attribute 1: Check whether a secured attribute exists 2: Remove secured attribute 3: Exit 1 Task: Verify whether a secured attribute exists Enter Vault Block:vb Enter Attribute Name:password A value exists for (vb, password) Please enter a Digit:: 0: Store a secured attribute 1: Check whether a secured attribute exists 2: Remove secured attribute 3: Exit
4.2.8. Remove a Sensitive String from the Password Vault
For security reasons it is best to remove sensitive strings from the Password Vault when they are no longer required. For example, if an application is being decommissioned, any sensitive strings used in datasource definitions should be removed at the same time.
As a prerequisite, before removing a sensitive string from the Password Vault, confirm if it is used in the configuration of JBoss EAP.
This operation can be done either interactively, where the user is prompted for each parameter’s value, or non-interactively, where all parameters' values are provided on the command line. Each method gives the same result, so either may be used. Both of these methods are invoked using the vault
script.
Use the non-interative method to provide all parameters' values at once. For a description of all parameters, see Initialize the Password Vault. To run the password vault command non-interactively, the vault
script (located in EAP_HOME/bin/
) can be invoked with parameters for the relevant information:
$ vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --remove-sec-attr --vault-block VAULT_BLOCK --attribute ATTRIBUTE --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT
Substitute the placeholder values with the actual values. The values for parameters KEYSTORE_URL, KEYSTORE_PASSWORD and KEYSTORE_ALIAS must match those provided when the password Vault was created.
The keystore password must be given in plaintext form, not masked form.
If the sensitive string is successfully removed, a confirmation message like the following will be displayed:
Secured attribute [VAULT_BLOCK::ATTRIBUTE] has been successfully removed from vault
If the sensitive string is not removed, a message like the following will be displayed:
Secured attribute [VAULT_BLOCK::ATTRIBUTE] was not removed from vault, check whether it exist
Example: Output
$ ./vault.sh --keystore EAP_HOME/vault/vault.keystore --keystore-password vault22 --alias vault --remove-sec-attr --vault-block vb --attribute password --enc-dir EAP_HOME/vault/ --iteration 120 --salt 1234abcd ========================================================================= JBoss Vault JBOSS_HOME: EAP_HOME JAVA: java ========================================================================= Dec 23, 2015 1:54:24 PM org.picketbox.plugins.vault.PicketBoxSecurityVault init INFO: PBOX000361: Default Security Vault Implementation Initialized and Ready Secured attribute [vb::password] has been successfully removed from vault
Remove a Sensitive String Interactively
To run the password vault command interactively, the following steps are required:
Launch the password vault command interactively.
Run
EAP_HOME/bin/vault.sh
(on Red Hat Enterprise Linux and similar operating systems) orEAP_HOME\bin\vault.bat
(on Microsoft Windows Server). Start a new interactive session by typing0
(zero).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.
NoteWhen 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.
-
Enter
If the sensitive string is successfully removed, a confirmation message like the following will be displayed:
Secured attribute [VAULT_BLOCK::ATTRIBUTE] has been successfully removed from vault
If the sensitive string is not removed, a message like the following will be displayed:
Secured attribute [VAULT_BLOCK::ATTRIBUTE] was not removed from vault, check whether it exist
Example: Output
********************************** **** JBoss Vault *************** ********************************** Please enter a Digit:: 0: Start Interactive Session 1: Remove Interactive Session 2: Exit 0 Starting an interactive session Enter directory to store encrypted files:EAP_HOME/vault/ Enter Keystore URL:EAP_HOME/vault/vault.keystore Enter Keystore password: Enter Keystore password again: Values match Enter 8 character salt:1234abcd Enter iteration count as a number (Eg: 44):120 Enter Keystore Alias:vault Initializing Vault Dec 23, 2014 1:40:56 PM org.picketbox.plugins.vault.PicketBoxSecurityVault init INFO: PBOX000361: Default Security Vault Implementation Initialized and Ready Vault Configuration in configuration file: ******************************************** ... </extensions> <vault> <vault-option name="KEYSTORE_URL" value="EAP_HOME/vault/vault.keystore"/> <vault-option name="KEYSTORE_PASSWORD" value="MASK-5dOaAVafCSd"/> <vault-option name="KEYSTORE_ALIAS" value="vault"/> <vault-option name="SALT" value="1234abcd"/> <vault-option name="ITERATION_COUNT" value="120"/> <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/> </vault><management> ... ******************************************** Vault is initialized and ready for use Handshake with Vault complete Please enter a Digit:: 0: Store a secured attribute 1: Check whether a secured attribute exists 2: Remove secured attribute 3: Exit 2 Task: Remove secured attribute Enter Vault Block:vb Enter Attribute Name:password Secured attribute [vb::password] has been successfully removed from vault
4.2.9. Configure Red Hat JBoss Enterprise Application Platform to Use a Custom Implementation of the Password Vault
In addition to using the provided password vault implementation, a custom implementation of SecurityVault
can also be used.
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:
-
Create a class that implements the interface
SecurityVault
. -
Create a module containing the class from the previous step, and specify a dependency on
org.picketbox
where the interface isSecurityVault
. 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.
-
code - The fully qualified name of class that implements
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)])
4.2.10. Obtain Keystore Password From External Source
The EXT
, EXTC
, CMD
, CMDC
or CLASS
methods can be used in vault configuration for obtaining the Java keystore password.
<vault-option name="KEYSTORE_PASSWORD" value="METHOD_TO_OBTAIN_PASSWORD"/>
The description for the methods are listed as:
- {EXT}…
-
Refers to the exact command, where the
…
is the exact command. For example:{EXT}/usr/bin/getmypassword --section 1 --query company
, run the/usr/bin/getmypassword
command, which displays the password on standard output and use it as password for Security Vault’s keystore. In this example, the command is using two options:--section 1
and--query company
. - {EXTC[:expiration_in_millis]}…
-
Refers to the exact command, where the
…
is the exact command line that is passed to theRuntime.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 forexpiration_in_millis
milliseconds. Default cache expiration is0 = 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 classnamector
. Thectorargs
is a comma delimited list of strings. For example,{CLASS@org.test.passwd}org.test.passwd.ExternamPassworProvider
. In this example, theorg.test.passwd.ExternamPassworProvider
class is loaded fromorg.test.passwd
module and uses thetoCharArray()
method to get the password. IftoCharArray()
is not available thetoString()
method is used. Theorg.test.passwd.ExternamPassworProvider
class must have the default constructor.