Security Guide

Procedure 2.1. Configure the Security Manager for JBoss EAP 6

1. Open the configuration file.

   Open the configuration file for editing. This file is located in one of two places, depending on whether you use a managed domain or standalone server. This is not the executable file used to start the server or domain.

   • 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. Add the Java options to the file.

   To ensure the Java options are used, add them to the code block that begins with:

   if [ "x$JAVA_OPTS" = "x" ]; then
   

   You can modify the -Djava.security.policy value to specify the exact location of your security policy. It should go onto one line only, with no line break. Using == when setting the -Djava.security.policy property 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.

   Important

   JBoss Enterprise Application Platform releases from 6.2.2 onwards require that the system property jboss.modules.policy-permissions is set to true.

   Example 2.1. domain.conf

   JAVA_OPTS="$JAVA_OPTS -Djava.security.manager -Djava.security.policy==$PWD/server.policy -Djboss.home.dir=/path/to/EAP_HOME -Djboss.modules.policy-permissions=true"

   Example 2.2. domain.conf.bat

   set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.manager -Djava.security.policy==\path\to\server.policy -Djboss.home.dir=\path\to\EAP_HOME -Djboss.modules.policy-permissions=true"

   Example 2.3. standalone.conf

   JAVA_OPTS="$JAVA_OPTS -Djava.security.manager -Djava.security.policy==$PWD/server.policy -Djboss.home.dir=$JBOSS_HOME -Djboss.modules.policy-permissions=true"

   Example 2.4. standalone.conf.bat

   set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.manager -Djava.security.policy==\path\to\server.policy -Djboss.home.dir=%JBOSS_HOME% -Djboss.modules.policy-permissions=true"

3. Start the domain or server.

   Start the domain or server as normal.

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

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

   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.server.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. Setup a Java Keystore

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

   Create a directory to hold 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.

   Determine the following parameters:

   alias

   The alias is a unique identifier for the vault or other data stored in the keystore. The alias in the example command at the end of this procedure is vault. Aliases are case-insensitive.

   keyalg

   The algorithm to use for encryption. The example in this procedure uses AES. 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. The example in this procedure uses 128. For information on appropriate values, see the documentation distributed with the keytool.

   keystore

   The keystore is a database which holds encrypted information and the information about how to decrypt it. If you do not specify a keystore, the default keystore to use is a file called .keystore in your home directory. The first time you add data to a keystore, it is created. The example in this procedure uses the vault.keystore keystore.

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

3. Determine the answers to questions the keystore command will ask.

   The keystore needs the following information in order to populate the keystore entry:

   Keystore password

   When you create a keystore, you must set a password. In order to work with the keystore in the future, you need to provide the password. Create a strong password that you will remember. The keystore is only as secure as its password and the security of the file system and operating system where it resides.

   Key password (optional)

   In addition to the keystore password, you can specify a password for each key it holds. In order to use such a key, the password needs to be given each time it is used. Usually, this facility is not used.

   First name (given name) and last name (surname)

   This, and the rest of the information in the list, helps to uniquely identify the key and place it into a hierarchy of other keys. It does not necessarily need to be a name at all, but it should be two words, and must be unique to the key. The example in this procedure uses Accounting Administrator. In directory terms, this becomes the common name of the certificate.

   Organizational unit

   This is a single word that identifies who uses the certificate. It may be the application or the business unit. The example in this procedure uses AccountingServices. Typically, all keystores used by a group or application use the same organizational unit.

   Organization

   This is usually a single-word representation of your organization's name. This typically remains the same across all certificates used by an organization. This example uses MyOrganization.

   City or municipality

   Your city.

   State or province

   Your state or province, or the equivalent for your locality.

   Country

   The two-letter code for your country.

   All of this information together will create a hierarchy for your keystores and certificates, ensuring that they use a consistent naming structure but are unique.

4. Run the keytool command, supplying the information that you gathered.

   Example 7.1. Example input and output of keystore command

   $ keytool -genseckey -alias vault -storetype jceks -keyalg AES -keysize 128 -storepass vault22 -keypass vault22 -validity 730 -keystore EAP_HOME/vault/vault.keystore
   Enter keystore password: vault22 
   Re-enter new password:vault22 
   What is your first and last name?
     [Unknown]:  Accounting Administrator
   What is the name of your organizational unit?
     [Unknown]:  AccountingServices
   What is the name of your organization?
     [Unknown]:  MyOrganization
   What is the name of your City or Locality?
     [Unknown]:  Raleigh
   What is the name of your State or Province?
     [Unknown]:  NC
   What is the two-letter country code for this unit?
     [Unknown]:  US
   Is CN=Accounting Administrator, OU=AccountingServices, O=MyOrganization, L=Raleigh, ST=NC, C=US correct?
     [no]:  yes
   
   Enter key password for <vault>
           (RETURN if same as keystore password):
   

1. Run the vault.sh command.

   Run EAP_HOME/bin/vault.sh. Start a new interactive session by typing 0.

2. Enter the directory where encrypted files will be stored.

   This directory should be accessible to only limited users. At a minimum the user account under which JBoss EAP is running requires read-write access. If you followed Section 7.2, “Create a Java Keystore to Store Sensitive Strings”, your keystore is in a directory called EAP_HOME/vault/.

   Note

   Do not forget to include the trailing slash on the directory name. Either use / or \, depending on your operating system.

3. Enter the path to the keystore.

   Enter the full path to the keystore file. This example uses EAP_HOME/vault/vault.keystore.

4. Encrypt the keystore password.

   The following steps encrypt the keystore password, so that you can use it in configuration files and applications securely.

   1. Enter the keystore password.

      When prompted, enter the keystore password.

   2. Enter a salt value.

      Enter an 8-character salt value. The salt value, together with the iteration count (below), are used to create the hash value.

   3. Enter the iteration count.

      Enter a number for the iteration count.

   4. Make a note of the masked password information.

      The masked password, the salt, and the iteration count are printed to standard output. Make a note of them in a secure location. An attacker could use them to decrypt the password.

   5. Enter the alias of the vault.

      When prompted, enter the alias of the vault. If you followed Section 7.2, “Create a Java Keystore to Store Sensitive Strings” to create your vault, the alias is vault.

5. Exit the interactive console.

   Type 2 to exit the interactive console.

Procedure 7.2. Setup a Password Vault

1. Determine the correct values for the command.

   Determine the values for the following parameters, which are determined by the commands used to create the keystore itself. For information on creating a keystore, refer the following topics: Section 7.2, “Create a Java Keystore to Store Sensitive Strings” and Section 7.3, “Mask the Keystore Password and Initialize the Password Vault”.

   Parameter	Description
   KEYSTORE_URL	The file system path or URI of the keystore file, usually called something like vault.keystore
   KEYSTORE_PASSWORD	The password used to access the keystore. This value should be masked.
   KEYSTORE_ALIAS	The name of the keystore alias.
   SALT	The salt used to encrypt and decrypt keystore values.
   ITERATION_COUNT	The number of times the encryption algorithm is run.
   ENC_FILE_DIR	The path to the directory from which the keystore commands are run. Typically the directory containing the password vault.
   host (managed domain only)	The name of the host you are configuring

2. Use the Management CLI to enable the password vault.

   Run one of the following commands, depending on whether you use a managed domain or standalone server configuration. Substitute the values in the command with the ones from the first step of this procedure.

   Note

   If you use Microsoft Windows Server, in the CLI command, escape each \ character in a directory path with an additional \ character. For example, C:\\data\\vault\\vault.keystore. This is because single \ character is used for character escaping.

   • Managed Domain

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

   • Standalone Server

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

   The following is an example of the command with hypothetical values:

   /core-service=vault:add(vault-options=[("KEYSTORE_URL" => "/home/user/vault/vault.keystore"), ("KEYSTORE_PASSWORD" => "MASK-3y28rCZlcKR"), ("KEYSTORE_ALIAS" => "vault"), ("SALT" => "12438567"),("ITERATION_COUNT" => "50"), ("ENC_FILE_DIR" => "/home/user/vault/")])
   

Procedure 7.3. 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. For example:

   /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.4. Setup the Java Keystore

1. Run the vault.sh command.

   Run EAP_HOME/bin/vault.sh. Start a new interactive session by typing 0.

2. Enter the directory where encrypted files will be stored.

   If you followed Section 7.2, “Create a Java Keystore to Store Sensitive Strings”, your keystore is in the directory EAP_HOME/vault. In most cases, it makes sense to store all of your encrypted information in the same place as the key store. 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.

   Note

   Do not forget to include the trailing slash on the directory name. Either use / or \, depending on your operating system.

3. Enter the path to the keystore.

   Enter the full path to the keystore file. This example uses EAP_HOME/vault/vault.keystore.

4. Enter the keystore password, vault name, salt, and iteration count.

   When prompted, enter the keystore password, vault name, salt, and iteration count. A handshake is performed.

5. Select the option to store a password.

   Select option 0 to store a password or other sensitive string.

6. Enter the value.

   When prompted, enter the value twice. If the values do not match, you are prompted to try again.

7. Enter the vault block.

   Enter the vault block, which is a container for attributes which pertain to the same resource. An example of an attribute name would be ds_ExampleDS. This will form part of the reference to the encrypted string, in your datasource or other service definition.

8. Enter the attribute name.

   Enter the name of the attribute you are storing. An example attribute name would be password.
   Result

   A message such as the one below shows that the attribute has been saved.

   Secured attribute value has been stored in vault.

9. Make note of the information about the encrypted string.

   A message prints to standard output, showing the vault block, attribute name, shared key, and advice about using the string in your configuration. Make note of this information in a secure location. Example output is shown below.

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

10. Use the encrypted string in your configuration.

    Use the string from the previous step in your configuration, in place of a plain-text string. A datasource using the encrypted password above is shown below.

    ...
      <subsystem xmlns="urn:jboss:domain:datasources:1.0">
        <datasources>
          <datasource jndi-name="java:jboss/datasources/ExampleDS" enabled="true" use-java-context="true" pool-name="H2DS">
            <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
            <driver>h2</driver>
            <pool></pool>
            <security>
              <user-name>sa</user-name>
              <password>${VAULT::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>
    ...
    

    You can use an encrypted string anywhere in your domain or standalone configuration file where expressions are allowed.

    Note

    To check if expressions are allowed within a particular subsystem, run the following CLI command against that subsystem:

    /host=master/core-service=management/security-realm=TestRealm:read-resource-description(recursive=true)

    From the output of running this command, look for the value for the expressions-allowed parameter. If this is true, then you can use expressions within the configuration of this particular subsystem.
    After you store your string in the keystore, use the following syntax to replace any clear-text string with an encrypted one.

    ${VAULT::VAULT_BLOCK::ATTRIBUTE_NAME::ENCRYPTED_VALUE}

    Here is a sample real-world value, where the vault block is ds_ExampleDS and the attribute is password.

    <password>${VAULT::ds_ExampleDS::password::1}</password>

Procedure 8.1. Configure a Worker Node

1. Configure the network interfaces.

   By default, the network interfaces all default to 127.0.0.1. Every physical host that hosts either a standalone server or one or more servers in a server group needs its interfaces to be configured to use its public IP address, which the other servers can see.
   To change the IP address of a JBoss EAP 6 host, you need to shut it down and edit its configuration file directly. This is because the Management API which drives the Management Console and Management CLI relies on a stable management address.
   Follow these steps to change the IP address on each server in your cluster to the master's public IP address.
   1. Start the JBoss EAP server using the profile described earlier in this topic.
   2. Launch the Management CLI, using the EAP_HOME/bin/jboss-cli.sh command in Linux or the EAP_HOME\bin\jboss-cli.bat command in Microsoft Windows Server. Type connect to connect to the domain controller on the localhost, or connect IP_ADDRESS to connect to a domain controller on a remote server.
   3. Modify the external IP address for the management, public and unsecure interfaces by typing the following commands. Be sure to replace EXTERNAL_IP_ADDRESS in the command with the actual external IP address of the host.

      /interface=management:write-attribute(name=inet-address,value="${jboss.bind.address.management:EXTERNAL_IP_ADDRESS}"
      /interface=public:write-attribute(name=inet-address,value="${jboss.bind.address.public:EXTERNAL_IP_ADDRESS}"
      /interface=unsecure:write-attribute(name=inet-address,value="${jboss.bind.address.unsecure:EXTERNAL_IP_ADDRESS}"
      :reload

      You should see the following result for each command.

       "outcome" => "success"

   4. For hosts that participate in a managed domain but are not the master, you must change the host name from master to a unique name. This name must be unique across slaves and will be used for the slave to identify to the cluster, so make a note of the name you use.
      1. Start the JBoss EAP slave host using the following syntax:

         bin/domain.sh --host-config=HOST_SLAVE_XML_FILE_NAME

         For example:

         bin/domain.sh --host-config=host-slave01.xml

      2. Launch the Management CLI.
      3. Use the following syntax to replace the host name:

         /host=master:write-attribute(name="name",value=UNIQUE_HOST_SLAVE_NAME)

         For example:

         /host=master:write-attribute(name="name",value="host-slave01")

         You should see the following result.

          "outcome" => "success"

         This modifies the XML in the host-slave01.xml file as follows:

         <host name="host-slave01" xmlns="urn:jboss:domain:1.6">

   5. For newly configured hosts that need to join a managed domain, you must remove the local element and add the remote element host attribute that points to the domain controller. This step does not apply for a standalone server.
      1. Start the JBoss EAP slave host using the following syntax:

         bin/domain.sh --host-config=HOST_SLAVE_XML_FILE_NAME

         For example:

         bin/domain.sh --host-config=host-slave01.xml

      2. Launch the Management CLI.
      3. Use the following syntax specify the domain controller:

         /host=UNIQUE_HOST_SLAVE_NAME/:write-remote-domain-controller(host=DOMAIN_CONTROLLER_IP_ADDRESS,port=${jboss.domain.master.port:9999},security-realm="ManagementRealm") 

         For example:

         /host=host-slave01/:write-remote-domain-controller(host="192.168.1.200",port=${jboss.domain.master.port:9999},security-realm="ManagementRealm") 

         You should see the following result.

          "outcome" => "success"

         This modifies the XML in the host-slave01.xml file as follows:

         <domain-controller>
             <remote host="192.168.1.200" port="${jboss.domain.master.port:9999}" security-realm="ManagementRealm"/>
         </domain-controller>

2. Configure authentication for each slave server.

   Each slave server needs a username and password created in the domain controller's or standalone master's ManagementRealm. On the domain controller or standalone master, run the EAP_HOME/bin/add-user.sh command. Add a user with the same username as the slave, to the ManagementRealm. When asked if this user will need to authenticate to an external JBoss AS instance, answer yes. An example of the input and output of the command is below, for a slave called slave1, with password changeme.

   user:bin user$ ./add-user.sh
   
   What type of user do you wish to add? 
    a) Management User (mgmt-users.properties) 
    b) Application User (application-users.properties)
   (a): a
   
   Enter the details of the new user to add.
   Realm (ManagementRealm) : 
   Username : slave1
   Password : changeme
   Re-enter Password : changeme
   About to add user 'slave1' for realm 'ManagementRealm'
   Is this correct yes/no? yes
   Added user 'slave1' to file '/home/user/jboss-eap-6.0/standalone/configuration/mgmt-users.properties'
   Added user 'slave1' to file '/home/user/jboss-eap-6.0/domain/configuration/mgmt-users.properties'
   Is this new user going to be used for one AS process to connect to another AS process e.g. slave domain controller?
   yes/no? yes
   To represent the user add the following to the server-identities definition <secret value="Y2hhbmdlbWU=" />
   

3. Copy the Base64-encoded <secret> element from the add-user.sh output.

   If you plan to specify the Base64-encoded password value for authentication, copy the <secret> element value from the last line of the add-user.sh output as you will need it in the step below.

4. Modify the slave host's security realm to use the new authentication.

   You can specify the secret value in one of the following ways:

   • Specify the Base64-encoded password value in the server configuration file using the Management CLI.

     1. Launch the Management CLI, using the EAP_HOME/bin/jboss-cli.sh command in Linux or the EAP_HOME\bin\jboss-cli.bat command in Microsoft Windows Server. Type connect to connect to the domain controller on the localhost, or connect IP_ADDRESS to connect to a domain controller on a remote server.
     2. Specify the secret value by typing the following command. Be sure to replace the SECRET_VALUE with the secret value returned from the add-user output from the previous step.

        /core-service=management/security-realm=ManagementRealm/server-identity=secret:add(value="SECRET_VALUE") 
        :reload

        You should see the following result for each command.

         "outcome" => "success"

   • Configure the host to get the password from the vault.

     1. Use the vault.sh script to generate a masked password. It will generate a string like the following: VAULT::secret::password::ODVmYmJjNGMtZDU2ZC00YmNlLWE4ODMtZjQ1NWNmNDU4ZDc1TElORV9CUkVBS3ZhdWx0.
        You can find more information on the vault in the Password Vaults for Sensitive Strings section of this guide starting here: Section 7.1, “Password Vault System”.
     2. Launch the Management CLI, using the EAP_HOME/bin/jboss-cli.sh command in Linux or the EAP_HOME\bin\jboss-cli.bat command in Microsoft Windows Server. Type connect to connect to the domain controller on the localhost, or connect IP_ADDRESS to connect to a domain controller on a remote server.
     3. Specify the secret value by typing the following command. Be sure to replace the SECRET_VALUE with the masked password generated in the previous step.

        /core-service=management/security-realm=ManagementRealm/server-identity=secret:add(value="${VAULT::secret::password::SECRET_VALUE}") 
        :reload

        You should see the following result for each command.

         "outcome" => "success"

        Note

        When creating a password in the vault, it must be specified in plain text, not Base64-encoded.

   • Specify the password as a system property.

     The following examples use server.identity.password as the system property name for the password.
     1. Specify the system property for the password in the server configuration file using the Management CLI.
        1. Launch the Management CLI, using the EAP_HOME/bin/jboss-cli.sh command in Linux or the EAP_HOME\bin\jboss-cli.bat command in Microsoft Windows Server. Type connect to connect to the domain controller on the localhost, or connect IP_ADDRESS to connect to a domain controller on a remote server.
        2. Type the following command to configure the secret identity to use the system property.

           /core-service=management/security-realm=ManagementRealm/server-identity=secret:add(value="${server.identity.password}") 
           :reload

           You should see the following result for each command.

            "outcome" => "success"

     2. When you specify the password as a system property, you can configure the host in either of the following ways:
        • Start the server entering the password in plain text as a command line argument, for example:

          -Dserver.identity.password=changeme

          Note

          The password must be entered in plain text and will be visible to anyone who issues a ps -ef command.
        • Place the password in a properties file and pass the properties file URL as a command line argument.
          1. Add the key/value pair to a properties file. For example:

             server.identity.password=changeme

          2. Start the server with the command line arguments

             --properties=URL_TO_PROPERTIES_FILE

             .

5. Restart the server.

   The slave will now authenticate to the master using its host name as the username and the encrypted string as its password.

Procedure 9.1. Subscribe to the JBoss Watch List

1. Click the following link to go to the JBoss Watch mailing list page: JBoss Watch Mailing List.
2. Enter your email address in the Subscribing to Jboss-watch-list section.
3. [You may also wish to enter your name and select a password. Doing so is optional but recommended.]
4. Press the Subscribe button to start the subscription process.
5. You can browse the archives of the mailing list by going to: JBoss Watch Mailing List Archives.

Procedure 9.6. Apply a patch to a JBoss product via the RPM method

1. Get notified about the security patch either via being a subscriber to the JBoss watch mailing list or by browsing the JBoss watch mailing list archives.
2. Read the errata for the security patch and confirm that it applies to a JBoss product in your environment.
3. If the security patch applies to a JBoss product in your environment, then follow the link to download the updated RPM package which is included in the errata.
4. Use

   yum update

   to install the patch.

   Important

   When updating an RPM installation, your JBoss product is updated cumulatively with all RPM-released fixes.