Procedure 2.1. Setup a new Java Security Manager Policy

1. Start policytool.

   Start the policytool tool in one of the following ways.

   • Red Hat Enterprise Linux

     From your GUI or a command prompt, run /usr/bin/policytool.

   • Microsoft Windows Server

     Run policytool.exe from your Start menu or from the bin\ of your Java installation. The location can vary.

2. Create a policy.

   To create a policy, select Add Policy Entry. Add the parameters you need, then click Done.

   Note

   Use VFS to specify paths for applications deployed on JBoss EAP. On Linux the path is: vfs:/content/application.war. On Microsoft Windows it is: vfs:/${user.dir}/content/application.war .

   For example:

   grant codeBase "vfs:/content/application.war/-" {
   permission java.util.PropertyPermission "*", "read";
   };
   

3. Edit an existing policy

   Select the policy from the list of existing policies, and select the Edit Policy Entry button. Edit the parameters as needed.

4. Delete an existing policy.

   Select the policy from the list of existing policies, and select the Remove Policy Entry button.

Procedure 2.2. Configure the Java Security Manager for JBoss EAP 6

1. Open the Configuration File

   Open the configuration file for editing. The configuration file you need to edit depends on whether you use a Managed Domain or standalone server, as well as your operating system.

   • Managed Domain

     • For Linux: EAP_HOME/bin/domain.conf
     • For Windows: EAP_HOME\bin\domain.conf.bat

   • Standalone Server

     • For Linux: EAP_HOME/bin/standalone.conf
     • For Windows: EAP_HOME\bin\standalone.conf.bat

2. Enable the Java Security Manager

   Use one of the methods below to enable the Java Security Manager:
   • Use the -secmgr option with your JBoss EAP 6 server startup script.
   • Uncomment the SECMGR="true" line in the configuration file:

     • On Linux:

       # Uncomment this to run with a security manager enabled
       SECMGR="true"

     • On Windows:

       rem # Uncomment this to run with a security manager enabled
       set "SECMGR=true"

3. Specify the Java Security Policy

   You can use -Djava.security.policy to specify the exact location of your security policy. It should go onto one line only, with no line break. Using == when setting -Djava.security.policy specifies that the security manager will use only the specified policy file. Using = specifies that the security manager will use the specified policy combined with the policy set in the policy.url section of JAVA_HOME/lib/security/java.security.
   In your relevant JBoss EAP 6 configuration file, add your security policy Java options. If you are using a Managed Domain, ensure that this is inserted before where PROCESS_CONTROLLER_JAVA_OPTS and HOST_CONTROLLER_JAVA_OPTS are set.

   • On Linux:

     JAVA_OPTS="$JAVA_OPTS -Djava.security.policy==$JBOSS_HOME/bin/server.policy -Djboss.home.dir=$JBOSS_HOME"

   • On Windows:

     set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.policy==%JBOSS_HOME%\bin\server.policy -Djboss.home.dir=%JBOSS_HOME%"

4. Start the Domain or Server

   Start the domain or server as normal.

Procedure 2.3. Enable general debugging

• This procedure will enable a sensible general level of security-related debug information.

  Add the following line to the server configuration file.

  • If the JBoss EAP 6 instance is running in a managed domain, the line is added to the bin/domain.conf file for Linux or the bin\domain.conf.bat file for Windows.
  • If the JBoss EAP 6 instance is running as a standalone server, the line is added to the bin/standalone.conf file for Linux, or the bin\standalone.conf.bat file for Windows.

1. Run the Management CLI.

   Start the jboss-cli.sh or jboss-cli.bat command and connect to the server.

2. Create the new security realm itself.

   Run the following command to create a new security realm named MyDomainRealm on a domain controller or a standalone server.
   For a domain instance, use this command:

   /host=master/core-service=management/security-realm=MyDomainRealm:add()

   For a standalone instance, use this command:

   /core-service=management/security-realm=MyDomainRealm:add()

3. Create the references to the properties file which will store information about the new role.

   Run the following command to create a pointer a file named myfile.properties, which will contain the properties pertaining to the new role.

   Note

   The newly created properties file is not managed by the included add-user.sh and add-user.bat scripts. It must be managed externally.
   For a domain instance, use this command:

   /host=master/core-service=management/security-realm=MyDomainRealm/authentication=properties:add(path=myfile.properties)

   For a standalone instance, use this command:

   /core-service=management/security-realm=MyDomainRealm/authentication=properties:add(path=myfile.properties)

1. Run the add-user.sh or add-user.bat command.

   Open a terminal and change directories to the EAP_HOME/bin/ directory. If you run Red Hat Enterprise Linux or another UNIX-like operating system, run add-user.sh. If you run Microsoft Windows Server, run add-user.bat.

2. Choose whether to add a Management User or Application User.

   For this procedure, type b to add an Application User.

3. Choose the realm the user will be added to.

   By default, the only available realm is ApplicationRealm. If you have added a custom realm, you can type its name instead.

4. Type the username, password, and roles, when prompted.

   Type the desired username, password, and optional roles when prompted. Verify your choice by typing yes, or type no to cancel the changes. The changes are written to each of the properties files for the security realm.

1. Stop JBoss EAP 6.

   Stop JBoss EAP 6 by sending an interrupt in the appropriate way for your operating system. If you are running JBoss EAP 6 as a foreground application, the typical way to do this is to press Ctrl+C.

2. Restart JBoss EAP 6, specifying the bind address.

   Use the -b command-line switch to start JBoss EAP 6 on a specific interface.

   Note

   In the following examples, the IP address used 10.1.1.1 must be available to you. To know the IP address, use the ifconfig command.

   Example 4.1. Specify the public interface.

   EAP_HOME/bin/domain.sh -b 10.1.1.1

   Example 4.2. Specify the management interface.

   EAP_HOME/bin/domain.sh -bmanagement=10.1.1.1

   Example 4.3. Specify different addresses for each interface.

   EAP_HOME/bin/domain.sh -bmanagement=127.0.0.1 -b 10.1.1.1

   Example 4.4. Bind the public interface to all network interfaces.

   EAP_HOME/bin/domain.sh -b 0.0.0.0

Procedure 4.1. Manage Network Firewalls and JBoss EAP 6 to work together

1. Log into the Management Console.

   Log into the Management Console. By default, it runs on http://localhost:9990/console/.

2. Determine the socket bindings used by the socket binding group.

   1. Click the Configuration label at the top of the Management Console.
   2. Expand the General Configuration menu. Select the Socket Binding.
   3. The Socket Binding Declarations screen appears. Initially, the standard-sockets group is shown. Choose a different group by selecting it from the combo box on the right-hand side.

   Note

   If you use a standalone server, it has only one socket binding group.
   The list of socket names and ports is shown, eight values per page. You can go through the pages by using the arrow navigation below the table.

3. Determine the ports you need to open.

   Depending on the function of the particular port and the requirements of your environment, some ports may need to be opened on your firewall.

4. Configure your firewall to forward traffic to JBoss EAP 6.

   Perform these steps to configure your network firewall to allow traffic on the desired port.
   1. Log into your firewall machine and access a command prompt, as the root user.
   2. Issue the command system-config-firewall to launch the firewall configuration utility. A GUI or command-line utility launches, depending on the way you are logged into the firewall system. This task makes the assumption that you are logged in via SSH and using the command-line interface.
   3. Use the TAB key on your keyboard to navigate to the Customize button, and press the ENTER key. The Trusted Services screen appears.
   4. Do not change any values, but use the TAB key to navigate to the Forward button, and press ENTER to advanced to the next screen. The Other Ports screen appears.
   5. Use the TAB key to navigate to the <Add> button, and press ENTER. The Port and Protocol screen appears.
   6. Enter 5445 in the Port / Port Range field, then use the TAB key to move to the Protocol field, and enter tcp. Use the TAB key to navigate to the OK button, and press ENTER.
   7. Use the TAB key to navigate to the Forward button until you reach the Port Forwarding screen.
   8. Use the TAB key to navigate to the <Add> button, and press the ENTER key.
   9. Fill in the following values to set up port forwarding for port 5445.
      • Source interface: eth1
      • Protocol: tcp
      • Port / Port Range: 5445
      • Destination IP address: 10.1.1.2
      • Port / Port Range: 5445
      Use the TAB key to navigate to the OK button, and press ENTER.
   10. Use the TAB key to navigate to the Close button, and press ENTER.
   11. Use the TAB key to navigate to the OK button, and press ENTER. To apply the changes, read the warning and click Yes.

5. Configure a firewall on your JBoss EAP 6 host.

   Some organizations choose to configure a firewall on the JBoss EAP 6 server itself, and close all ports that are not necessary for its operation. See Section 4.3, “Network Ports Used By JBoss EAP 6” and determine which ports to open, then close the rest. The default configuration of Red Hat Enterprise Linux 6 closes all ports except 22 (used for Secure Shell (SSH) and 5353 (used for multicast DNS). While you are configuring ports, ensure you have physical access to your server so that you do not inadvertently lock yourself out.

Procedure 4.2. Configuring Firewall on Microsoft Windows using PowerShell

1. Switch off firewall for debug purpose to determine whether the current network behavior is related to the firewall configuration.

   Start-Process "$psHome\powershell.exe" -Verb Runas -ArgumentList '-command "NetSh Advfirewall set allprofiles state off"'

2. Allow UDP connections on port 23364. For example:

   Start-Process "$psHome\powershell.exe" -Verb Runas -ArgumentList '-command "NetSh Advfirewall firewall add rule name="UDP Port 23364" dir=in  action=allow protocol=UDP localport=23364"'
   Start-Process "$psHome\powershell.exe" -Verb Runas -ArgumentList '-command "NetSh Advfirewall firewall add rule name="UDP Port 23364" dir=out action=allow protocol=UDP localport=23364"'

Procedure 4.3. Configure the Firewall on Red Hat Enterprise Linux 7 to Allow mod_cluster Advertising

• To allow mod_cluster advertising on Red Hat Enterprise Linux 7, you must enable the UDP port in the firewall as follows:

  firewall-cmd --permanent --zone=public --add-port=23364/udp

  Note

  224.0.1.105:23364 is the default address and port for mod_cluster balancer advertising UDP multicast.

Procedure 4.4. Configure the JBoss Web Server to use HTTPS

1. Add a new HTTPS connector.

   Create a secure connector, named HTTPS, which uses the https scheme, the https socket binding (which defaults to 8443), and is set to be secure.

   /profile=default/subsystem=web/connector=HTTPS/:add(socket-binding=https,scheme=https,protocol=HTTP/1.1,secure=true)
   

2. Configure the SSL encryption certificate and keys.

   Configure your SSL certificate, substituting your own values for the example ones. This example assumes that the keystore is copied to the server configuration directory, which is EAP_HOME/domain/configuration/ for a managed domain.

   /profile=default/subsystem=web/connector=HTTPS/ssl=configuration:add(name=https,certificate-key-file="${jboss.domain.config.dir}/keystore.jks",password=SECRET, key-alias=KEY_ALIAS, cipher-suite=CIPHERS)
   

3. Set the protocol to TLSv1.

   /profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=protocol,value=TLSv1)
   

4. Deploy an application.

   Deploy an application to a server group which uses the profile you have configured. If you use a standalone server, deploy an application to your server. HTTPS requests to it use the new SSL-encrypted connection.

Procedure 4.5. Generate a SSL Encryption Key and Certificate

1. Generate a keystore with public and private keys.

   Run the following command to generate a keystore named server.keystore with the alias jboss in your current directory.

   keytool -genkeypair -alias jboss -keyalg RSA -keystore server.keystore -storepass mykeystorepass --dname "CN=jsmith,OU=Engineering,O=mycompany.com,L=Raleigh,S=NC,C=US"

   The following table describes the parameters used in the keytool command:

   Parameter	Description
   -genkeypair	The keytool command to generate a key pair containing a public and private key.
   -alias	The alias for the keystore. This value is arbitrary, but the alias jboss is the default used by the JBoss Web server.
   -keyalg	The key pair generation algorithm. In this case it is RSA.
   -keystore	The name and location of the keystore file. The default location is the current directory. The name you choose is arbitrary. In this case, the file will be named server.keystore.
   -storepass	This password is used to authenticate to the keystore so that the key can be read. The password must be at least 6 characters long and must be provided when the keystore is accessed. In this case, we used mykeystorepass. If you omit this parameter, you will be prompted to enter it when you execute the command.
   -keypass	This is the password for the actual key. Note Due to an implementation limitation this must be the same as the store password.
   --dname	A quoted string describing the distinguished name for the key, for example: "CN=jsmith,OU=Engineering,O=mycompany.com,L=Raleigh,C=US". This string is a concatenation of the following components: CN - The common name or host name. If the hostname is "jsmith.mycompany.com", the CN is "jsmith". OU - The organizational unit, for example "Engineering" O - The organization name, for example "mycompany.com". L - The locality, for example "Raleigh" or "London" S - The state or province, for example "NC". This parameter is optional. C - The 2 letter country code, for example "US" or "UK",

   When you execute the above command, you are prompted for the following information:

   • If you did not use the -storepass parameter on the command line, you are asked to enter the keystore password. Re-enter the new password at the next prompt.
   • If you did not use the -keypass parameter on the command line, you are asked to enter the key password. Press Enter to set this to the same value as the keystore password.
   When the command completes, the file server.keystore now contains the single key with the alias jboss.

2. Verify the key.

   Verify that the key works properly by using the following command.

   keytool -list -keystore server.keystore

   You are prompted for the keystore password. The contents of the keystore are displayed (in this case, a single key called jboss). Notice the type of the jboss key, which is PrivateKeyEntry. This indicates that the keystore contains both a public and private entry for this key.

3. Generate a certificate signing request.

   Run the following command to generate a certificate signing request using the public key from the keystore you created in step 1.

   keytool -certreq -keyalg RSA -alias jboss -keystore server.keystore -file certreq.csr

   You are prompted for the password in order to authenticate to the keystore. The keytool command then creates a new certificate signing request called certreq.csr in the current working directory.

4. Test the newly generated certificate signing request.

   Test the contents of the certificate by using the following command.

   openssl req -in certreq.csr -noout -text

   The certificate details are shown.

5. Optional: Submit your certificate signing request to a Certificate Authority (CA).

   A Certificate Authority (CA) can authenticate your certificate so that it is considered trustworthy by third-party clients. The CA supplies you with a signed certificate, and optionally with one or more intermediate certificates.

6. Optional: Export a self-signed certificate from the keystore.

   If you only need it for testing or internal purposes, you can use a self-signed certificate. You can export one from the keystore you created in step 1 as follows:

   keytool -export -alias jboss -keystore server.keystore -file server.crt

   You are prompted for the password in order to authenticate to the keystore. A self-signed certificate, named server.crt, is created in the current working directory.

7. Import the signed certificate, along with any intermediate certificates.

   Import each certificate, in the order that you are instructed by the CA. For each certificate to import, replace intermediate.ca or server.crt with the actual file name. If your certificates are not provided as separate files, create a separate file for each certificate, and paste its contents into the file.

   Note

   Your signed certificate and certificate keys are valuable assets. Be cautious with how you transport them between servers.

   keytool -import -keystore server.keystore -alias intermediateCA -file intermediate.ca

   keytool -importcert -alias jboss -keystore server.keystore -file server.crt

8. Test that your certificates imported successfully.

   Run the following command, and enter the keystore password when prompted. The contents of your keystore are displayed, and the certificates are part of the list.

   keytool -list -keystore server.keystore

Procedure 5.1. Remove Silent Authentication from the Default Security Realm

• Remove silent authentication with the Management CLI

  Remove the local element from the Management Realm and Application Realm as required.
  1. Remove the local element from the Management Realm.

     • For Standalone Servers

       /core-service=management/security-realm=ManagementRealm/authentication=local:remove

     • For Managed Domains

       /host=HOST_NAME/core-service=management/security-realm=ManagementRealm/authentication=local:remove

  2. Remove the local element from the Application Realm.

     • For Standalone Servers

       /core-service=management/security-realm=ApplicationRealm/authentication=local:remove

     • For Managed Domains

       /host=HOST_NAME/core-service=management/security-realm=ApplicationRealm/authentication=local:remove

Procedure 5.2. 

1. Create a keystore to secure the management console.

   Note

   This keystore must be in JKS format as the management console is not compatible with keystores in JCEKS format.
   In a terminal emulator, enter the following command. For the parameters alias, keypass, keystore, storepass and dname, replace the example values with values of your choice.
   The parameter validity specifies for how many days the key is valid. A value of 730 equals two years.

   keytool -genkeypair -alias appserver -storetype jks -keyalg RSA -keysize 2048 -keypass password1 -keystore EAP_HOME/standalone/configuration/identity.jks -storepass password1 -dname "CN=appserver,OU=Sales,O=Systems Inc,L=Raleigh,ST=NC,C=US" -validity 730 -v

2. Ensure the Management Console Binds to HTTPS

   • Standalone Mode

     Ensure the management console binds to HTTPS for its interface by adding the management-https configuration and removing the management-http configuration.
     Ensure the JBoss EAP instance is running, then enter the following management CLI commands:

     /core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value=management-https)

     /core-service=management/management-interface=http-interface:undefine-attribute(name=socket-binding)

     The expected output from these commands is:

     {"outcome" => "success"}
     

     Note

     At this point the JBoss EAP log may display the following error message. This is to be expected because the SSL configuration is not yet completed.

     JBAS015103: A secure port has been specified for the HTTP interface but no SSL configuration in the realm.
     

   • Domain Mode

     Change the socket element within the management-interface section by adding secure-port and removing port configuration.
     Ensure the JBoss EAP instance is running, then enter the following management CLI commands:

     /host=master/core-service=management/management-interface=http-interface:write-attribute(name=secure-port,value=9443)
     /host=master/core-service=management/management-interface=http-interface:undefine-attribute(name=port)

     Note

     At this point the JBoss EAP log may display the following error message. This is to be expected because the SSL configuration is not yet completed.

     JBAS015103: A secure port has been specified for the HTTP interface but no SSL configuration in the realm.
     

3. Optional: Custom socket-binding group

   If you are using a custom socket-binding group, ensure the management-https binding is defined (it is present by default, bound to port 9443). Edit the master configuration file - for example standalone.xml - to match the following.

    <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
           <socket-binding name="management-native" interface="management" port="${jboss.management.native.port:9999}"/>
           <socket-binding name="management-http" interface="management" port="${jboss.management.http.port:9990}"/>
           <socket-binding name="management-https" interface="management" port="${jboss.management.https.port:9443}"/>
   
   

4. Create a new Security Realm

   Enter the following commands to create a new security realm named ManagementRealmHTTPS:

   /host=master/core-service=management/security-realm=ManagementRealmHTTPS/:add
   /host=master/core-service=management/security-realm=ManagementRealmHTTPS/authentication=properties/:add(path=ManagementUsers.properties, relative-to=jboss.domain.config.dir)

5. Configure Management Interface to use the new security realm

   Enter the following commands:

   /host=master/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=ManagementRealmHTTPS)

6. Configure the management console to use the keystore.

   Enter the following management CLI command. For the parameters file, password and alias their values must be copied from the step Create a keystore to secure the management console.

   /core-service=management/security-realm=ManagementRealmHTTPS/server-identity=ssl:add(keystore-path=identity.jks,keystore-relative-to=jboss.server.config.dir, keystore-password=password1, alias=appserver)

   The expected output from this command is:

   {
       "outcome" => "success",
       "response-headers" => {
           "operation-requires-reload" => true,
           "process-state" => "reload-required"
       }
   }

7. Restart the JBoss EAP server.

   On restarting the server the log should contain the following, just before the text which states the number of services that are started. The management console is now listening on port 9443, which confirms that the procedure was successful.

   14:53:14,720 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015962: Http management interface listening on https://127.0.0.1:9443/management
   14:53:14,721 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015952: Admin console listening on https://127.0.0.1:9443
   

Procedure 5.3. 

1. Generate the stores:

   keytool -genkeypair -alias HOST1_alias -keyalg RSA -keysize 1024 -validity 365 -keystore host1.keystore.jks -dname "CA_HOST1" -keypass secret -storepass secret

   keytool -genkeypair -alias HOST2_alias -keyalg RSA -keysize 1024 -validity 365 -keystore host2.keystore.jks -dname "CA_HOST2" -keypass secret -storepass secret

2. Export the certificates:

   keytool -exportcert  -keystore HOST1.keystore.jks -alias HOST1_alias -keypass secret -storepass secret -file HOST1.cer
   

   keytool -exportcert  -keystore HOST2.keystore.jks -alias HOST2_alias -keypass secret -storepass secret -file HOST2.cer
   

3. Import the certificates into the opposing trust stores:

   keytool -importcert -keystore HOST1.truststore.jks -storepass secret -alias HOST2_alias -trustcacerts -file HOST2.cer
   

   keytool -importcert -keystore HOST2.truststore.jks -storepass secret -alias HOST1_alias -trustcacerts -file HOST1.cer
   

4. Define a CertificateRealm in the configuration for your installation (host.xml or standalone.xml) and point the interface to it:
   This can be done by manually editing the configuration file (not recommended) or by using the following commands:

   /core-service=management/security-realm=CertificateRealm:add()

   /core-service=management/security-realm=CertificateRealm/server-identity=ssl:add(keystore-path=/path/to/HOST1.keystore.jks,keystore-password=secret, alias=HOST1_alias)

   /core-service=management/security-realm=CertificateRealm/authentication=truststore:add(keystore-path=/path/to/HOST1.truststore.jks,keystore-password=secret)

   Important

   The provided commands apply to standalone mode only. For domain mode, add /host=master before each command.
5. Change the security-realm of the native-interface to the new Certificate Realm.

   /host=master/core-service=management/management-interface=native-interface:write-attribute(name=security-realm,value=CertificateRealm)

6. Add the SSL configuration for the CLI, which uses EAP_HOME/bin/jboss-cli.xml as a settings file. Either use a password vault to store the keystore and truststore passwords (recommended), or store them in plain text:
   • To store the keystore and truststore passwords in a password vault:
     Edit EAP_HOME/bin/jboss-cli.xml and add the SSL configuration (using the appropriate values for the variables). Also add the vault configuration, replacing each value with those of your vault.

     <ssl>
       <vault>
         <vault-option name="KEYSTORE_URL" value="path-to/vault/vault.keystore"/>
         <vault-option name="KEYSTORE_PASSWORD" value="MASK-5WNXs8oEbrs"/>
         <vault-option name="KEYSTORE_ALIAS" value="vault"/>
         <vault-option name="SALT" value="12345678"/>
         <vault-option name="ITERATION_COUNT" value="50"/>
         <vault-option name="ENC_FILE_DIR" value="path-to/jboss-eap/vault/"/>
       </vault>
       <alias>$HOST2alias</alias>
       <key-store>/path/to/HOST2.keystore.jks</key-store>
       <key-store-password>VAULT::VB::cli_pass::1</key-store-password>
       <key-password>VAULT::VB::cli_pass::1</key-password>  
       <trust-store>/path/to/HOST2.truststore.jks</trust-store>
       <trust-store-password>VAULT::VB::cli_pass::1</trust-store-password>
       <modify-trust-store>true</modify-trust-store>
     </ssl>
     

   • To store the keystore and truststore passwords in plain text:
     Edit EAP_HOME/bin/jboss-cli.xml and add the SSL configuration (using the appropriate values for the variables):

     <ssl>
       <alias>$HOST2alias</alias>
       <key-store>/path/to/HOST2.keystore.jks</key-store>
       <key-store-password>secret</key-store-password>
       <trust-store>/path/to/HOST2.truststore.jks</trust-store>
       <trust-store-password>secret</trust-store-password>
       <modify-trust-store>true</modify-trust-store>
     </ssl>
     

Procedure 7.1. Basic steps to configure and use Password Vault

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

   Note

   To use an encrypted sensitive string in configuration, refer Section 7.9, “Use an Encrypted Sensitive String in Configuration”.

   To use an encrypted sensitive string in an application, refer Section 7.10, “Use an Encrypted Sensitive String in an Application”.

   To verify a sensitive string in Password Vault, refer Section 7.11, “Check if a Sensitive String is in the Password Vault”.

   To remove a sensitive string from Password Vault, refer Section 7.12, “Remove a Sensitive String from the Password Vault”.

Procedure 7.2. Set up a Java Keystore

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

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

2. Determine the parameters to use with keytool utility.

   Decide on values for the following parameters:

   alias

   The alias is a unique identifier for the vault or other data stored in the keystore. Aliases are case-insensitive.

   storetype

   The storetype specifies the keystore type. The value jceks is recommended.

   keyalg

   The algorithm to use for encryption. Use the documentation for your JRE and operating system to see which other choices may be available to you.

   keysize

   The size of an encryption key impacts how difficult it is to decrypt through brute force. For information on appropriate values, see the documentation distributed with the keytool utility.

   storepass

   The value of storepass is the password is used to authenticate to the keystore so that the key can be read. The password must be at least 6 characters long and must be provided when the keystore is accessed. If you omit this parameter, you will be prompted to enter it when you execute the command.

   keypass

   The value of keypass is the password used to access the specific key and must match the value of the storepass parameter.

   validity

   The value of validity is the period (in days) for which the key will be valid.

   keystore

   The value of keystore is the filepath and filename in which the keystore's values are to be stored. The keystore file is created when data is first added to it.

   Ensure you use the correct file path separator: / (forward slash) for Red Hat Enterprise Linux and similar operating systems, \ (backslash) for Microsoft Windows Server.

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

3. Run the keytool command

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

Procedure 7.3. Run the Password Vault Command Interactively

1. Launch the Password Vault command interactively.

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

2. Complete the prompted parameters.

   Follow the prompts to input the required parameters.

3. Make a note of the masked password information.

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

4. Exit the interactive console.

   Type 3 (three) to exit the interactive console.

Procedure 7.4. Run the Password Vault Command Non-interactively

• Launch your operating system's command line interface and run the Password Vault command. Refer to the list in the Overview, substituting the placeholder values with your preferred values.
  Use EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems) or EAP_HOME\bin\vault.bat (on Microsoft Windows Server).

  vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --vault-block VAULT_BLOCK --attribute ATTRIBUTE --sec-attr SEC-ATTR --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT

  Example 7.3. Run the Password Vault command non-interactively

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

  Command output

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

Procedure 7.5. Enable the Password Vault

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

  Note

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

  /core-service=vault:add(vault-options=[("KEYSTORE_URL" => "PATH_TO_KEYSTORE"), ("KEYSTORE_PASSWORD" => "MASKED_PASSWORD"), ("KEYSTORE_ALIAS" => "ALIAS"), ("SALT" => "SALT"),("ITERATION_COUNT" => "ITERATION_COUNT"), ("ENC_FILE_DIR" => "ENC_FILE_DIR")])

Procedure 7.6. Use a Custom Implementation of the Password Vault

1. Create a class that implements the interface SecurityVault.
2. Create a module containing the class from the previous step, and specify a dependency on org.picketbox where the interface is SecurityVault.
3. Enable the custom Password Vault in the JBoss EAP server configuration by adding the vault element with the following attributes:

   code

   The fully qualified name of class that implements SecurityVault.

   module

   The name of the module that contains the custom class.

   Optionally, you can use vault-options parameters to initialize the custom class for a Password Vault.

   Example 7.5.  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")])

Procedure 7.7. Store a Sensitive String Interactively

1. Run the Password Vault command

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

2. Complete the prompted parameters about the Password Vault

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

   Note

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

3. Complete the prompted parameters about the sensitive string

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

4. Make note of the information about the masked string

   A message prints to standard output, showing the vault block, attribute name, masked string, and advice about using the string in your configuration. Make note of this information in a secure location. An extract of sample output is as follows:

   Vault Block:ds_Example1
   Attribute Name:password
   Configuration should be done as follows:
   VAULT::ds_Example1::password::1
   

5. Exit the interactive console

   Enter 3 (three) to exit the interactive console.

Procedure 7.8. Store a Sensitive String Non-interactively

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

   Note

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

   EAP_HOME/bin/vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --vault-block VAULT_BLOCK --attribute ATTRIBUTE --sec-attr SEC-ATTR --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT

2. Make note of the information about the masked string

   A message prints to standard output, showing the vault block, attribute name, masked string, and advice about using the string in your configuration. Make note of this information in a secure location. An extract of sample output is as follows:

   Vault Block:vb
   Attribute Name:password
   Configuration should be done as follows:
   VAULT::vb::password::1
   

Procedure 7.9.  Check For a Sensitive String Interactively

1. Run the Password Vault command

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

2. Complete the prompted parameters about the Password Vault

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

   Note

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

Procedure 7.10.  Check For a Sensitive String Non-Interactively

• Launch your operating system's command line interface and run the Password Vault command. Use EAP_HOME/bin/vault.sh (on Red Hat Enterprise Linux and similar operating systems) or EAP_HOME\bin\vault.bat (on Microsoft Windows Server).
  Substitute the placeholder values with your own values. The values for parameters KEYSTORE_URL, KEYSTORE_PASSWORD-password and KEYSTORE_ALIAS must match those provided when the Password Vault was created.

  Note

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

  EAP_HOME/bin/vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --check-sec-attr --vault-block VAULT_BLOCK --attribute ATTRIBUTE --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT

Procedure 7.11. Remove a Sensitive String Interactively

1. Run the Password Vault command

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

2. Provide Authentication Details

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

   Note

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

Procedure 7.12.  Remove a Sensitive String Non-interactively

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

  Note

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

  EAP_HOME/bin/vault.sh --keystore KEYSTORE_URL --keystore-password KEYSTORE_PASSWORD --alias KEYSTORE_ALIAS --remove-sec-attr --vault-block VAULT_BLOCK --attribute ATTRIBUTE --enc-dir ENC_FILE_DIR --iteration ITERATION_COUNT --salt SALT