Red Hat Summit Red Hat SummitSupportConsoleDéveloppeursCommencer un essaiContact

Ce contenu n'est pas disponible dans la langue sélectionnée.

Chapter 2. Securing the Server and Its Interfaces

2.1. Building Blocks
Copier lien

2.1.1. Interfaces and Socket Bindings
Copier lien

JBoss EAP utilizes its host’s interfaces (e.g. inet-address, nic, etc) and ports for communication for both its web applications as well as its management interfaces. These interfaces and ports are defined and configured through the interfaces and socket-binding-groups settings in the JBoss EAP configuration files (e.g. standalone.xml, domain.xml, host.xml, etc).

For more information on how to define and configure interfaces and socket-binding-groups, consult the Socket Bindings section of the Configuration Guide.

Example Interfaces

<interfaces>
  <interface name="management">
    <inet-address value="${jboss.bind.address.management:127.0.0.1}"/>
  </interface>
  <interface name="public">
    <inet-address value="${jboss.bind.address:127.0.0.1}"/>
  </interface>
</interfaces>
Copy to Clipboard Toggle word wrap

Example Socket Binding Group

<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
    <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:9993}"/>
    <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
    <socket-binding name="http" port="${jboss.http.port:8080}"/>
    <socket-binding name="https" port="${jboss.https.port:8443}"/>
    <socket-binding name="txn-recovery-environment" port="4712"/>
    <socket-binding name="txn-status-manager" port="4713"/>
    <outbound-socket-binding name="mail-smtp">
        <remote-destination host="localhost" port="25"/>
    </outbound-socket-binding>
</socket-binding-group>
Copy to Clipboard Toggle word wrap

2.1.2. Security Realms
Copier lien

JBoss EAP uses security realms to define authentication and authorization mechanisms (e.g. local, LDAP, properties, etc) which can then be used by the management interfaces. For more background information on security realms, consult the Security Realms section of the Red Hat JBoss Enterprise Application Platform Security Architecture Guide.

Example Security Realms

<security-realms>
  <security-realm name="ManagementRealm">
    <authentication>
      <local default-user="$local" skip-group-loading="true"/>
      <properties path="mgmt-users.properties" relative-to="jboss.server.config.dir"/>
    </authentication>
    <authorization map-groups-to-roles="false">
      <properties path="mgmt-groups.properties" relative-to="jboss.server.config.dir"/>
    </authorization>
  </security-realm>
  <security-realm name="ApplicationRealm">
    <authentication>
      <local default-user="$local" allowed-users="*" skip-group-loading="true"/>
      <properties path="application-users.properties" relative-to="jboss.server.config.dir"/>
    </authentication>
    <authorization>
      <properties path="application-roles.properties" relative-to="jboss.server.config.dir"/>
    </authorization>
  </security-realm>
</security-realms>
Copy to Clipboard Toggle word wrap

Note

In addition to updating the existing security realms, JBoss EAP also allows you to create new security realms. You can create new security realms via the management console as well as invoking the following command from the management CLI: 

/core-service=management/security-realm=NEW-REALM-NAME:add()
Copy to Clipboard Toggle word wrap

If you create a new security realm and want to use a properties file for authentication or authorization, you must create new properties files specifically for the new security domain. JBoss EAP does not reuse existing files used by other security domains nor does it automatically create new files specified in the configuration if they do not exist.

By default, JBoss EAP defines an http-interface to connect to the management interfaces. This interface is defined in the <management-interfaces> section of the JBoss EAP configuration: 

<management-interfaces>
  <http-interface security-realm="ManagementRealm" http-upgrade-enabled="true">
    <socket-binding http="management-http"/>
  </http-interface>
</management-interfaces>
Copy to Clipboard Toggle word wrap

Notice that the interface specifies a security-realm and socket-binding. Updating the configuration for the specified security realm and socket binding allows for the management interfaces to be secured in different ways. In addition to being able to secure each of these interfaces via security realms and socket bindings, both of these interfaces also may be completely disabled, and users of these interfaces may be configured to have various roles and access rights. There are also a few topics in this guide, such as security auditing, secure passwords and JMX that overlap with other subsystems within JBoss EAP , but still relate to securing JBoss EAP.

2.2. How to Secure the Management Interfaces
Copier lien

The following sections show how to perform various operations related to securing the JBoss EAP management interfaces and related subsystems.

Note

The management CLI commands shown assume that you are running a JBoss EAP standalone server. For more details on using the management CLI for a JBoss EAP managed domain, please see the JBoss EAP Management CLI Guide.

2.2.1. Configuring the Networking and Ports Used by JBoss EAP
Copier lien

Depending on the configuration of the host, JBoss EAP may be configured to use various network interfaces and ports. This allows JBoss EAP to work with different host, networking, and firewall requirements.

For more information on the Networking and Ports used by JBoss EAP as well as how to configure those settings, please see the Network and Port Configuration section of the Configuration Guide.

2.2.2. Configure the Management Interfaces for HTTPS
Copier lien

Configuring the JBoss EAP management interfaces for communication only using HTTPS provides increased security. All network traffic between the client and management interfaces is encrypted, which reduces the risk of security attacks such as a man-in-the-middle attack.

In this procedure unencrypted communication with the JBoss EAP instance is disabled. This procedure applies to both standalone server and managed domain configurations. For a managed domain, prefix the management CLI commands with the name of the host, for example: /host=master.

Important

While performing the steps for enabling HTTPS on the management interfaces, do not reload the configuration unless explicitly instructed. Doing so may cause you to be locked out of the management interfaces.

  1. Create a keystore to secure the management interfaces.

    Note

    This keystore must be in JKS format as the management interfaces are not compatible with keystores in JCEKS format.

    Use the following to generate a keystore, replacing the example values for the parameters, for example alias, keypass, keystore, storepass and dname, with the correct values for the environment.

    Note

    The parameter validity specifies for how many days the key is valid. A value of 730 equals two years.

    Using the keytool command to generate a keystore from the terminal

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

  2. Ensure the management interfaces bind to HTTPS.

    1. Running a Standalone Server.

      To ensure the management interfaces bind to HTTPS, you must add the management-https configuration and remove the management-http configuration.

      Use the following CLI commands to bind the management interfaces to HTTPS: 

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

    2. Running a Managed Domain

      Change the socket element within the management-interface section by adding secure-port and removing port configuration.

      Use the following commands to bind the management interfaces to HTTPS: 

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

/host=master/core-service=management/management-interface=http-interface:undefine-attribute(name=port)
      Copy to Clipboard Toggle word wrap

  3. Optional: Use custom socket-binding-group. If you want to use a custom socket-binding-group, you must ensure the management-https binding is defined, which by default is bound to port 9993. You can verify this by reviewing the socket-binding-group section of the server’s configuration file or by using the management CLI:

    Example Reading the socket-binding-group Configuration Using the Management CLI

    /socket-binding-group=standard-sockets/socket-binding=management-https:read-resource(recursive=true)

{
    "outcome" => "success",
    "result" => {
        "client-mappings" => undefined,
        "fixed-port" => false,
        "interface" => "management",
        "multicast-address" => undefined,
        "multicast-port" => undefined,
        "name" => "management-https",
        "port" => expression "${jboss.management.https.port:9993}"
    }
}
    Copy to Clipboard Toggle word wrap

  4. Create a new security realm. In this example, the new security realm using HTTPS, ManagementRealmHTTPS, uses a properties file named https-mgmt-users.properties located in the EAP_HOME/standalone/configuration/ directory for storing usernames and passwords. Usernames and passwords can be added to the file later, but for now, you need to create an empty file named https-mgmt-users.properties and save it to that location. The below example shows using the touch command, but you may also use other mechanisms, such as a text editor.

    Example using the touch command to create an empty file

    $ touch EAP_HOME/standalone/configuration/https-mgmt-users.properties
    Copy to Clipboard Toggle word wrap

    Next, enter the following CLI commands to create a new security realm named ManagementRealmHTTPS: 

    /core-service=management/security-realm=ManagementRealmHTTPS:add

/core-service=management/security-realm=ManagementRealmHTTPS/authentication=properties:add(path=https-mgmt-users.properties,relative-to=jboss.server.config.dir)
    Copy to Clipboard Toggle word wrap

    At this point, you have created a new security realm and configured it to use a properties file for authentication. You must now add users to that properties file using the add-user script, which is available in the EAP_HOME/bin/ directory. When running the add-user script, you must specify both the properties file and the security realm using the -up and -r options respectively. From there, the add-user script will interactively prompt you for the username and password information to store in the https-mgmt-users.properties file. 

    $ EAP_HOME/bin/add-user.sh -up EAP_HOME/standalone/configuration/https-mgmt-users.properties -r ManagementRealmHTTPS
...
Enter the details of the new user to add.
Using realm 'ManagementRealmHTTPS' as specified on the command line.
...
Username : httpUser
Password requirements are listed below. To modify these restrictions edit the add-user.properties configuration file.
 - The password must not be one of the following restricted values {root, admin, administrator}
 - The password must contain at least 8 characters, 1 alphabetic character(s), 1 digit(s), 1 non-alphanumeric symbol(s)
 - The password must be different from the username
...
Password :
Re-enter Password :
About to add user 'httpUser' for realm 'ManagementRealmHTTPS'
...
Is this correct yes/no? yes
..
Added user 'httpUser' to file 'EAP_HOME/configuration/https-mgmt-users.properties'
...
Is this new user going to be used for one AS process to connect to another AS process?
e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server EJB calls.
yes/no? no
    Copy to Clipboard Toggle word wrap
    Important

    When configuring security realms that use properties files to store usernames and passwords, it is recommended that each realm use a distinct properties file that is not shared with another realm.

  5. Configure the management interfaces to use the new security realm. 

    /core-service=management/management-interface=http-interface:write-attribute(name=security-realm,value=ManagementRealmHTTPS)
    Copy to Clipboard Toggle word wrap

  6. Configure the management interfaces to use the keystore.

    Use the below CLI command to configure the management interfaces to use the keystore. For the parameters file, password and alias their values must be copied from the first step.

    CLI Command for Adding a Keystore to a Security Realm

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

    Note

    To update the keystore password, use the following CLI command: 

    /core-service=management/security-realm=ManagementRealmHTTPS/server-identity=ssl:write-attribute(name=keystore-password,value=newpassword)
    Copy to Clipboard Toggle word wrap

    At this point, you need to reload the server’s configuration: 

    reload
    Copy to Clipboard Toggle word wrap

    After reloading the server configuration, the log should contain the following, just before the text which states the number of services that are started: 

    13:50:54,160 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0061: Http management interface listening on https://127.0.0.1:9993/management
13:50:54,162 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0052: Admin console listening on https://127.0.0.1:9993
    Copy to Clipboard Toggle word wrap

    The management interfaces are now listening on port 9993, which confirms that the procedure was successful.

    Important

    At this point, the CLI will disconnect and will be unable to reconnect since the port bindings have changed. Proceed to the next step to update the jboss-cli.xml to allow the CLI to reconnect.

  7. Update the jboss-cli.xml.

    If using the management CLI to perform management actions, the following changes must to be made to the EAP_HOME/bin/jboss-cli.xml file:

    • Update the value of <default-protocol> to https-remoting.
    • In <default-controller>, update the value of <protocol> to https-remoting.

    • In <default-controller>, update the value of <port> to 9993.

      Example jboss-cli.xml

      <jboss-cli xmlns="urn:jboss:cli:2.0">
    <default-protocol use-legacy-override="true">https-remoting</default-protocol>
    <!-- The default controller to connect to when 'connect' command is executed w/o arguments -->
    <default-controller>
        <protocol>https-remoting</protocol>
        <host>localhost</host>
        <port>9993</port>
    </default-controller>
...
      Copy to Clipboard Toggle word wrap

      The next time you connect to the management interface using the management CLI, you must accept the server certificate and authenticate against the ManagementRealmHTTPS security realm:

      Example Accepting Server Certificate and Authenticating

      $ ./jboss-cli.sh -c
Unable to connect due to unrecognised server certificate
Subject    - CN=appserver,OU=Sales,O=Systems Inc,L=Raleigh,ST=NC,C=US
Issuer     - CN=appserver, OU=Sales, O=Systems Inc, L=Raleigh, ST=NC, C=US
Valid From - Tue Jun 28 13:38:48 CDT 2016
Valid To   - Thu Jun 28 13:38:48 CDT 2018
MD5 : 76:f4:81:8b:7e:c3:be:6d:ee:63:c1:7a:b7:b8:f0:fb
SHA1 : ea:e3:f1:eb:53:90:69:d0:c9:69:4a:5a:a3:20:8f:76:c1:e6:66:b6

Accept certificate? [N]o, [T]emporarily, [P]ermenantly : p
Authenticating against security realm: ManagementRealmHTTPS
Username: httpUser
Password:
[standalone@localhost:9993 /]
      Copy to Clipboard Toggle word wrap

2.2.3. Disabling Just the Management Console
Copier lien

Other clients, such as JBoss Operations Network, operate using the HTTP interface for managing JBoss EAP. In order to continue using these services, just the web-based management console itself may be disabled. This is accomplished by setting the console-enabled attribute to false:

CLI Command for Disabling the Web-Based Management Console

/core-service=management/management-interface=http-interface/:write-attribute(name=console-enabled,value=false)
Copy to Clipboard Toggle word wrap

Two-way SSL/TLS authentication, also known as client authentication, authenticates both the client and the server using SSL/TLS certificates. This differs from the Configure the Management Interfaces for HTTPS section in that both the client and server each have a certificate. This provides assurance that not only is the server who it says it is, but the client is also who it says it is.

In this section the following conventions are used:

HOST1
The JBoss server hostname. For example: jboss.redhat.com.
HOST2
A suitable name for the client. For example: myclient. Note this is not necessarily an actual hostname.
CA_HOST1
The DN (distinguished name) to use for the HOST1 certificate. For example: cn=jboss,dc=redhat,dc=com.
CA_HOST2
The DN (distinguished name) to use for the HOST2 certificate. For example: cn=myclient,dc=redhat,dc=com.
Prerequisites

If a password vault is used to store the keystore and truststore passwords (recommended), the password vault should already be created. For more information on the password vault, please see the Password Vault section as well as the Password Vault System section of the Red Hat JBoss Enterprise Application Platform 7 Security Architecture Guide.

Warning

Red Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 or TLSv1.2 in all affected packages.

  1. Generate the keystores. 

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

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

  3. Import the certificates into the opposing truststores. 

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

  4. Define a CertificateRealm.

    Define a CertificateRealm in the configuration for the server (host.xml or standalone.xml) and point the interface to it. This can be done 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)
    Copy to Clipboard Toggle word wrap

  5. Change the security-realm of the http-interface to the new CertificateRealm. 

    /core-service=management/management-interface=http-interface:write-attribute(name=security-realm,value=CertificateRealm)
    Copy to Clipboard Toggle word wrap

  6. Add the SSL/TLS configuration for the CLI.

    Important

    In addition to adding the two-way SSL/TLS, the management interface should also be configured to bind to HTTPS.

    Add the SSL/TLS configuration for the CLI, which uses EAP_HOME/bin/jboss-cli.xml as a settings file.

    To store the keystore and truststore passwords in plain text, edit EAP_HOME/bin/jboss-cli.xml and add the SSL/TLS configuration using the appropriate values for the variables:

    Example jboss-cli.xml XML

    <ssl>
  <alias>HOST2_alias</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>
    Copy to Clipboard Toggle word wrap

    To use the keystore and truststore passwords stored in a password vault, you need to add the vault configuration and appropriate vault values to EAP_HOME/bin/jboss-cli.xml:

    Example jboss-cli.xml XML

    <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="EAP_HOME/vault/"/>
  </vault>
  <alias>HOST2_alias</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>
    Copy to Clipboard Toggle word wrap

2.2.5. Setting Up SSL/TLS for Applications
Copier lien

In addition to supporting HTTPS and two-way SSL/TLS for the management interfaces, JBoss EAP also enables SSL/TLS (via an HTTPS listener) to be set up for use by security domains.

Important

As a prerequisite, an SSL/TLS Encryption Key and Certificate should be created and place in an accessible directory. Additionally, relevant information (e.g. keystore aliases and passwords, desired cipher suites, etc) should also be accessible. For examples on generating SSL/TLS Keys and Certificates, please see the first two steps in the Setting up Two-Way SSL/TLS for the Management Interfaces section. For more information about the HTTPS listener (including cipher suites) please see the HTTPS Listener Reference section.

Setting up One-Way SSL/TLS

This example assumes that the keystore, identity.jks, has been copied to the server configuration directory and configured with the given properties. Administrators should substitute their own values for the example ones.

Note

The management CLI commands shown assume that you are running a JBoss EAP standalone server. For more details on using the management CLI for a JBoss EAP managed domain, please see the JBoss EAP Management CLI Guide.

  1. Add and configure an HTTPS security realm first. Once the HTTPS security realm has been configured, configure an https-listener in the undertow subsystem that references the security realm: 

    batch

/core-service=management/security-realm=HTTPSRealm/:add

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

/subsystem=undertow/server=default-server/https-listener=https:add( \
socket-binding=https, security-realm=HTTPSRealm)

run-batch
    Copy to Clipboard Toggle word wrap
    Warning

    Red Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 or TLSv1.2 in all affected packages.

  2. Reload the server for the changes to take effect. 

    reload
    Copy to Clipboard Toggle word wrap

2.2.6. Setting up Two-Way SSL/TLS for Applications
Copier lien

Setting up two-way SSL/TLS for applications follows many of the same procedures outlined in Setting up Two-Way SSL/TLS for the Management Interfaces. To set up Two-Way SSL/TLS for applications, you need to do the following:

  1. Generate the stores for both the client and server
  2. Export the certificates for both the client and server
  3. Import the certificates into the opposing truststores
  4. Define a security realm, for example CertificateRealm, on the server that uses the server’s keystore and truststore
  5. Update the undertow subsystem to use the security realm and require client verification

The first four steps are covered in Setting up Two-Way SSL/TLS for the Management Interfaces.

Important

If the server has not been reloaded since the new security realm has been added, you must reload the server before performing the next step.

Update the Undertow Subsystem

Once the keystores, certificates, truststores, and security realms have been created and configured, you need to add an HTTPS listener to the undertow subsystem, use the security realm you created, and require client verification: 

/subsystem=undertow/server=default-server/https-listener=https:add( \
socket-binding=https, security-realm=CertificateRealm, verify-client=REQUIRED)
Copy to Clipboard Toggle word wrap
Important

Any client connecting to a JBoss EAP instance with two-way SSL/TLS enabled for applications must have access to a client certificate or keystore, in other words a client keystore whose certificate is included in the server’s truststore. If the client is using a browser to connect to the JBoss EAP instance, you need to import that certificate or keystore into the browser’s certificate manager.

Note

More details on using certificate-based authentication in applications in addition to two-way SSL/TLS with applications can be found in Configuring a Security Domain to Use Certificate-Based Authentication in How to Configure Identity Management for JBoss EAP.

2.2.7. HTTPS Listener Reference
Copier lien

For a full list of attributes available for the HTTPS listener, please see Undertow Subsystem Attributes in the JBoss EAP Configuration Guide.

2.2.7.1. About Cipher Suites
Copier lien

You can configure a list of the encryption ciphers which are allowed. For JSSE syntax, it must be a comma-separated list. For OpenSSL syntax, it must be a colon-separated list. Ensure that only one syntax is used. The default is the JVM default.

Important

Using weak ciphers is a significant security risk. See http://www.nist.gov/manuscript-publication-search.cfm?pub_id=915295 for NIST recommendations on cipher suites.

For a list of available OpenSSL ciphers, see https://www.openssl.org/docs/manmaster/apps/ciphers.html#CIPHER-STRINGS. Note that the following are not supported:

  • @SECLEVEL
  • SUITEB128
  • SUITEB128ONLY
  • SUITEB192

For a list of the standard JSSE ciphers, see http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#Cipher.

To update the list of enabled cipher suites, use the enabled-cipher-suites attribute of the HTTPS listener in the undertow subsystem.

Example CLI

/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=enabled-cipher-suites,value="TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA")
Copy to Clipboard Toggle word wrap

Note

The example only lists two possible ciphers, but real-world examples will likely use more.

You can configure Undertow to use FIPS 140-2 compliant cryptography for SSL/TLS. The scope of this configuration example is limited to Red Hat Enterprise Linux 6, using the Mozilla NSS library in FIPS mode.

Important

Red Hat Enterprise Linux 6 must already be configured to be FIPS 140-2 compliant. Refer to https://access.redhat.com/knowledge/solutions/137833 for more information.

Warning

The TLS 1.2 protocol is not supported by the Oracle/OpenJDK and JBoss EAP when running in FIPS mode and can cause a NoSuchAlgorithmException to occur. More details on this issue can be found here.

Important

If you run jboss-cli.sh in an environment with FIPS 140-2 compliant cryptography for SSL/TLS enabled, you will see the following error: FIPS mode: only SunJSSE TrustManagers may be used. It is possible to workaround the issue by updating the javax.net.ssl.keyStore and javax.net.ssl.trustStore system properties in the jboss-cli.sh file: 

JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=NONE -Djavax.net.ssl.trustStoreType=PKCS11"
JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.keyStore=NONE -Djavax.net.ssl.keyStoreType=PKCS11 -Djavax.net.ssl.keyStorePassword=imapassword"
Copy to Clipboard Toggle word wrap

To configure Undertow to use FIPS 140-2 compliant cryptography for SSL/TLS, you must do the following:

  • Configure the NSS database
  • Configure Undertow

2.2.8.1. Configuring the NSS database
Copier lien

  1. Create a directory owned by the appropriate user to house the NSS database.

    Example Commands for Creating the NSS Database Directory

    $ mkdir -p  /usr/share/jboss-as/nssdb
$ chown jboss /usr/share/jboss-as/nssdb
$ modutil -create -dbdir /usr/share/jboss-as/nssdb
    Copy to Clipboard Toggle word wrap

    Note

    The jboss user is only an example. You need to replace it with a user on your operating system that you plan on using for running JBoss EAP.

  2. Create the NSS configuration file: /usr/share/jboss-as/nss_pkcsll_fips.cfg.

    It must specify:

    • a name
    • the directory where the NSS library is located

    • the directory where the NSS database was created in the previous step

      Example nss_pkcsll_fips.cfg

      name = nss-fips
nssLibraryDirectory=/usr/lib64
nssSecmodDirectory=/usr/share/jboss-as/nssdb
nssDbMode = readOnly
nssModule = fips
      Copy to Clipboard Toggle word wrap

      Note

      If you are not running a 64-bit version of Red Hat Enterprise Linux 6 then set nssLibraryDirectory to /usr/lib instead of /usr/lib64.

  3. Edit the $JAVA_HOME/jre/lib/security/java.security configuration file.

    Add the following line to $JAVA_HOME/jre/lib/security/java.security:

    Example java.security

    security.provider.1=sun.security.pkcs11.SunPKCS11  /usr/share/jboss-as/nss_pkcsll_fips.cfg
    Copy to Clipboard Toggle word wrap

    Note

    The nss_pkcsll_fips.cfg configuration file specified in the above line is the file created in the previous step.

    You also need to update the following link in $JAVA_HOME/jre/lib/security/java.security from: 

    security.provider.5=com.sun.net.ssl.internal.ssl.Provider
    Copy to Clipboard Toggle word wrap

    to 

    security.provider.5=com.sun.net.ssl.internal.ssl.Provider  SunPKCS11-nss-fips
    Copy to Clipboard Toggle word wrap
    Important

    Any other security.provider.X lines in this file, for example security.provider.2, must have the value of their X increased by one to ensure that this provider is given priority.

  4. Run the modutil command on the NSS database directory you created in the previous step to enable FIPS mode. 

    modutil -fips true -dbdir /usr/share/jboss-as/nssdb
    Copy to Clipboard Toggle word wrap
    Note

    You may get a security library error at this point requiring you to regenerate the library signatures for some of the NSS shared objects.

  5. Set the password on the FIPS token.

    The name of the token must be NSS FIPS 140-2 Certificate DB. 

    modutil -changepw "NSS FIPS 140-2 Certificate DB" -dbdir /usr/share/jboss-as/nssdb
    Copy to Clipboard Toggle word wrap
    Important

    The password used for the FIPS token must be a FIPS compliant password. If the password is not strong enough, you may receive an error: ERROR: Unable to change password on token "NSS FIPS 140-2 Certificate DB".

  6. Create a certificate using the NSS tools.

    Example Command

    certutil -S -k rsa -n undertow  -t "u,u,u" -x -s "CN=localhost, OU=MYOU, O=MYORG, L=MYCITY, ST=MYSTATE, C=MY" -d /usr/share/jboss-as/nssdb
    Copy to Clipboard Toggle word wrap

2.2.8.2. Configuring Undertow
Copier lien

To complete the setup of FIPS 140-2 compliant cryptography for SSL/TLS:

  1. Configure Undertow to use SSL/TLS.

    Note

    The following commands below must either be run in batch mode, or the server must be reloaded after adding the ssl server identity. The example below is shown using batch mode. 

    batch

/core-service=management/security-realm=HTTPSRealm:add

/core-service=management/security-realm=HTTPSRealm/server-identity=ssl:add(keystore-provider=PKCS11, keystore-password="strongP@ssword1")

/subsystem=undertow/server=default-server/https-listener=https:add(socket-binding=https, security-realm=HTTPSRealm, enabled-protocols="TLSv1.1")

run-batch
    Copy to Clipboard Toggle word wrap

    The basic details for configuring Undertow to SSL/TLS are covered in Setting up an SSL/TLS for Applications.

  2. Configure the cipher suites used by Undertow.

    Once you have SSL/TLS configured, you need to configure the https listener and security realm to have a specific set of cipher suites enabled:

    Required Cipher Suites

    SSL_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_DSS_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_DHE_DSS_WITH_AES_256_CBC_SHA, TLS_DHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_RSA_WITH_AES_128_CBC_SHA, TLS_ECDH_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_anon_WITH_AES_128_CBC_SHA, TLS_ECDH_anon_WITH_AES_256_CBC_SHA
    Copy to Clipboard Toggle word wrap

    The basics behind enabling cipher suites for the https listener are covered in About Cipher Suites. To enable cipher suites on the https listener:

    Example Command for Enabling Cipher Suites on the Https Listener

    /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=enabled-cipher-suites,value="SSL_RSA_WITH_3DES_EDE_CBC_SHA,SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_DSS_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_DSS_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_anon_WITH_AES_128_CBC_SHA,TLS_ECDH_anon_WITH_AES_256_CBC_SHA")
    Copy to Clipboard Toggle word wrap

  3. Enable cipher suites on the security realm.

    Example Command for Enabling Cipher Suites on the Security Realm

    /core-service=management/security-realm=HTTPSRealm/server-identity=ssl:write-attribute(name=enabled-cipher-suites, value=[SSL_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_DSS_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_DHE_DSS_WITH_AES_256_CBC_SHA, TLS_DHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_RSA_WITH_AES_128_CBC_SHA, TLS_ECDH_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_anon_WITH_AES_128_CBC_SHA, TLS_ECDH_anon_WITH_AES_256_CBC_SHA])
    Copy to Clipboard Toggle word wrap

  4. Verify that the JVM can read the private key from the PKCS11 keystore by running the following command: 

    keytool -list -storetype pkcs11
    Copy to Clipboard Toggle word wrap

2.2.9. FIPS 140-2 Compliant Cryptography on IBM JDK
Copier lien

On the IBM JDK, the IBM JCE (Java Cryptographic Extension) IBMJCEFIPS provider and the IBM JSSE (Java Secure Sockets Extension) FIPS 140-2 Cryptographic Module (IBMJSSE2) for Multi-platforms provide FIPS 140-2 compliant cryptography.

For more information on the IBMJCEFIPS provider, refer to the IBM Documentation for IBM JCEFIPS, and the NIST IBMJCEFIPS – Security Policy. More information on IBMJSSE2, can be found here.

2.2.9.1. Key storage
Copier lien

The IBM JCE does not provide a keystore. The keys are stored on the computer and do not leave its physical boundary. If the keys are moved between computers they must be encrypted.

To run keytool in FIPS-compliant mode use the -providerClass option on each command like this: 

keytool -list -storetype JCEKS -keystore mystore.jck -storepass mystorepass -providerClass com.ibm.crypto.fips.provider.IBMJCEFIPS
Copy to Clipboard Toggle word wrap

2.2.9.2. Examine FIPS provider information
Copier lien

To examine information about the IBMJCEFIPS used by the server, enable debug-level logging by adding -Djavax.net.debug=true to standalone.conf or domain.conf. Information about the FIPS provider is logged to server.log, for example: 

04:22:45,685 INFO  [stdout] (http-/127.0.0.1:8443-1) JsseJCE:  Using MessageDigest SHA from provider IBMJCEFIPS version 1.7
04:22:45,689 INFO  [stdout] (http-/127.0.0.1:8443-1) DHCrypt:  DH KeyPairGenerator  from provider from init IBMJCEFIPS version 1.7
04:22:45,754 INFO  [stdout] (http-/127.0.0.1:8443-1) JsseJCE:  Using KeyFactory DiffieHellman from provider IBMJCEFIPS version 1.7
04:22:45,754 INFO  [stdout] (http-/127.0.0.1:8443-1) JsseJCE:  Using KeyAgreement DiffieHellman from provider IBMJCEFIPS version 1.7
04:22:45,754 INFO  [stdout] (http-/127.0.0.1:8443-1) DHCrypt:  DH KeyAgreement  from provider IBMJCEFIPS version 1.7
04:22:45,754 INFO  [stdout] (http-/127.0.0.1:8443-1) DHCrypt:  DH KeyAgreement  from provider from initIBMJCEFIPS version 1.7
Copy to Clipboard Toggle word wrap
Important

It is assumed you have a managed domain, FIPS configured, as well as all necessary certificates configured. This includes having imported the domain controller’s certificate into each controller’s truststore. For more details on configuring a managed domain, see Domain Management in the JBoss EAP Configuration Guide. For more details on configuring FIPS, see Enable FIPS 140-2 Cryptography for SSL/TLS on Red Hat Enterprise Linux 6.

You need to update each host controller and the master domain controller to use SSL/TLS for communication.

Warning

Red Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 in all affected packages.

  1. Create an SSL/TLS security realm on the master domain controller.

    You need to create an SSL/TLS security realm on the master domain controller configured to use your NSS database as a PKCS11 provider.

    Example Security Realm

    <security-realm name="HTTPSRealm">
    <server-identities>
        <ssl>
            <engine enabled-protocols="TLSv1.1"/>
            <keystore provider="PKCS11" keystore-password="strongP@ssword1"/>
        </ssl>
    </server-identities>
    <authentication>
        <local default-user="\$local"/>
        <properties path="https-users.properties" relative-to="jboss.domain.config.dir"/>
    </authentication>
</security-realm>
    Copy to Clipboard Toggle word wrap

  2. Create an SSL/TLS security realm on each host controller.

    You need to create a security realm with an SSL/TLS truststore for authentication.

    Example Security Realm

    <security-realm name="HTTPSRealm">
  <authentication>
    <truststore provider="PKCS11" keystore-password="strongP@ssword1"/>
  </authentication>
</security-realm>
    Copy to Clipboard Toggle word wrap

    Note

    You need to repeat this process on each host.

  3. Secure the native interface on the master domain controller.

    You need to ensure that the native interface on the master domain controller is secured with the security realm you just created.

    Example Native Interface

    <management-interfaces>
  ...
  <native-interface security-realm="HTTPSRealm">
    <socket interface="management" port="${jboss.management.native.port:9999}"/>
   </native-interface>
</management-interfaces>
    Copy to Clipboard Toggle word wrap

  4. Use the SSL/TLS realm on each host controller to connect to the master domain controller.

    You need to update the security realm used for connecting to the master domain controller. This change must be done directly in the host controller’s configuration file, for example host.xml or host-slave.xml, while the server is not running.

    Example Host Controller Configuration File

    <domain-controller>
  <remote security-realm="HTTPSRealm">
    <discovery-options>
      <static-discovery name="primary" protocol="${jboss.domain.master.protocol:remote}" host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9999}"/>
    </discovery-options>
  </remote>
</domain-controller>
    Copy to Clipboard Toggle word wrap

  5. Update how each server connects back to its host controller.

    You also need to update how each server connects back to its host controller.

    Example Server Configuration

    <server name="my-server" group="my-server-group">
  <ssl ssl-protocol="TLS" trust-manager-algorithm="SunX509" truststore-type="PKCS11" truststore-password="strongP@ssword1"/>
</server>
    Copy to Clipboard Toggle word wrap

  6. Configure two-way SSL/TLS in a managed domain.

    To enable two-way SSL/TLS, add a truststore authentication method to the SSL/TLS security realm for the master domain controller, execute the following management CLI commands: 

    /host=master/core-service=management/security-realm=HTTPSRealm/authentication=truststore:add(keystore-provider="PKCS11",keystore-password="strongP@ssword1")

reload --host=master
    Copy to Clipboard Toggle word wrap

    You also need to update each host controller’s security realm to have an SSL server identity, execute the following management CLI commands: 

    /host=host1/core-service=management/security-realm=HTTPSRealm/server-identity=ssl:add(keystore-provider=PKCS11, keystore-password="strongP@ssword1",enabled-protocols=["TLSv1.1"])

reload --host=host1
    Copy to Clipboard Toggle word wrap
    Important

    You also need to ensure that each host’s certificate is imported into the domain controller’s truststore.

2.2.11. Disabling Remote Access to JMX
Copier lien

Remote access to the jmx subsystem allows for JDK and application management operations to be triggered remotely. To disable remote access to JMX in JBoss EAP, remove the remoting connector in the jmx subsystem:

Removing the Remoting Connector

/subsystem=jmx/remoting-connector=jmx/:remove
Copy to Clipboard Toggle word wrap

For more information on JMX, please see the JMX section of the Red Hat JBoss Enterprise Application Platform Security Architecture Guide

2.2.12. Using JAAS for Securing the Management Interfaces
Copier lien

JAAS is a declarative security API used by JBoss EAP to manage security. For more details and background regarding JAAS and declarative security, see the Declarative Security and JAAS section of the Red Hat JBoss Enterprise Application Platform Security Architecture Guide.

Note

When JBoss EAP instances are configured to run in ADMIN_ONLY mode, using JAAS to secure the management interfaces is not supported. For more information on ADMIN_ONLY mode, please see the Running JBoss EAP in ADMIN_ONLY Mode section of the JBoss EAP Configuration Guide.

To use JAAS to authenticate to the management interfaces, the following steps must be performed:

  1. Create a security domain.

    In this example, a security domain is created with the UserRoles login module, but other login modules may be used as well: 

    /subsystem=security/security-domain=UsersLMDomain:add(cache-type=default)

/subsystem=security/security-domain=UsersLMDomain/authentication=classic:add

/subsystem=security/security-domain=UsersLMDomain/authentication=classic/login-module=UsersRoles:add(code=UsersRoles, flag=required,module-options=[("usersProperties"=>"users.properties"),("rolesProperties"=>"roles.properties")])
    Copy to Clipboard Toggle word wrap

  2. Create a security realm with JAAS authentication. 

    /core-service=management/security-realm=SecurityDomainAuthnRealm:add

/core-service=management/security-realm=SecurityDomainAuthnRealm/authentication=jaas:add(name=UsersLMDomain)
    Copy to Clipboard Toggle word wrap

  3. Update the http-interface management interface to use new security realm. 

    /core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=SecurityDomainAuthnRealm)
    Copy to Clipboard Toggle word wrap

  4. Optional: Assign group membership.

    The attribute assign-groups determines whether loaded user membership information from the security domain is used for group assignment in the security realm. When set to true, this group assignment is used for Role-Based Access Control (RBAC). 

    /core-service=management/security-realm=SecurityDomainAuthnRealm/authentication=jaas:write-attribute(name=assign-groups,value=true)
    Copy to Clipboard Toggle word wrap

2.2.13. Silent Authentication
Copier lien

The default installation of JBoss EAP contains a method of silent authentication for a local management CLI user. This allows the local user the ability to access the management CLI without username or password authentication. This functionality is enabled as a convenience, and to assist local users running management CLI scripts without requiring authentication. It is considered a useful feature given that access to the local configuration typically also gives the user the ability to add their own user details or otherwise disable security checks.

The convenience of silent authentication for local users can be disabled where greater security control is required. This can be achieved by removing the local element within the security-realm section of the configuration file. This applies to both the standalone instances as well as domains.

Important

The removal of the local element should only be done if the impact on the JBoss EAP instance and its configuration is fully understood.

To remove silent authentication from a realm: 

/core-service=management/security-realm=REALM_NAME/authentication=local:remove
Copy to Clipboard Toggle word wrap

2.2.14. Removing Undertow Response Headers
Copier lien

The default JBoss EAP undertow subsystem includes two response headers that are appended to each HTTP response by the default-host:

  • Server, which is set to JBoss-EAP/7
  • X-Powered-By, which is set to Undertow/1

Although these can be useful for development and debugging purposes, you might want to remove these headers if you do not want to disclose information about the server in use.

Use the following management CLI commands to remove these response headers from the default-host. 

/subsystem=undertow/server=default-server/host=default-host/filter-ref=server-header:remove

/subsystem=undertow/server=default-server/host=default-host/filter-ref=x-powered-by-header:remove

reload
Copy to Clipboard Toggle word wrap

2.3. Security Auditing
Copier lien

Security auditing refers to triggering events, such as writing to a log, in response to an event that happens within the security subsystem or the management interfaces. Auditing mechanisms are configured as part of a security domain or management interface.

Auditing uses provider modules. Both included provider modules as well as custom implementations may be used.

2.3.1. Configure Security Auditing for Security Domains
Copier lien

To configure security auditing settings for a security domain, the following steps must be performed from the management console:

  1. Open the security domain’s detailed view.

    • Click Configuration at the top of the screen.
    • In a managed domain, select a profile to modify from the Profile selection box at the top left.
    • Click on Subsystems, then Security.
    • Click on the security domain to edit and click View.

  2. Navigate to the Auditing configuration.

    Click on Audit at the left side of the screen.

    The configuration area is divided into two areas: Provider Modules and Details. The provider module is the basic unit of configuration. A security domain can include several provider modules each of which can include attributes and options.

  3. Add a provider module.

    Click Add and fill in the Code section with the classname of the provider module. Also fill in the Name section with the desired name.

  4. Verify the module is working.

    The goal of an audit module is to provide a way to monitor the events in the security subsystem. This monitoring can be done by means of writing to a log file, email notifications, or any other measurable auditing mechanism.

    For example, JBoss EAP includes the org.jboss.security.audit.providers.LogAuditProvider module by default. If enabled following the steps above , this audit module writes security notifications to a audit.log file in the log subfolder within the EAP_HOME directory.

    To verify if the steps above have worked in the context of the org.jboss.security.audit.providers.LogAuditProvider, perform an action that is likely to trigger a notification and then check the audit log file.

  5. Optional: Add, edit, or remove module options.

    To add options to your module, click its entry in the Modules list, and select the Module Options tab in the Details section of the page. Click Add, and provide the key and value for the option.

    To edit an option that already exists, click Remove to remove it, and click Add to add it again with the correct options.

Retour au début
Red Hat logoGithubredditYoutubeTwitter

Apprendre

Essayez, achetez et vendez

Communautés

À propos de la documentation Red Hat

Nous aidons les utilisateurs de Red Hat à innover et à atteindre leurs objectifs grâce à nos produits et services avec un contenu auquel ils peuvent faire confiance. Découvrez nos récentes mises à jour.

Rendre l’open source plus inclusif

Red Hat s'engage à remplacer le langage problématique dans notre code, notre documentation et nos propriétés Web. Pour plus de détails, consultez le Blog Red Hat.

À propos de Red Hat

Nous proposons des solutions renforcées qui facilitent le travail des entreprises sur plusieurs plates-formes et environnements, du centre de données central à la périphérie du réseau.

Theme

© 2025 Red Hat