Configuring a One-Way SSL in JBoss EAP 5 or 6

Environment

• Red Hat JBoss Enterprise Application Platform (EAP)
  • 5
  • 6

• Transport Layer Security (TLS) / Secure Socket Layer (SSL) without client authentication (one-way)
• Hypertext Transfer Protocol Secure (HTTPS) or Apache APR
• JBossWeb subsystem
• Certificate Authority (CA) or self-signed certificates

Issue

• Configure server for applications over secure channel in standalone.xml
• Integrate CA signed certificates

Resolution

1. Make sure you have properly Setup the Certificate Store.

2. Configuration

   • JBoss EAP 6

     1. Put the created keystore.jks file under $JBOSS_HOME/standalone/configuration/ or $JBOSS_HOME/domain/configuration/ directory

     2. Connect to the server using the CLI

     3. Running the following commands.

        Prefix all commands /profile=NAME and replace "jboss.server.config.dir" with "jboss.domain.config.dir" managed domain mode

         /subsystem=web/connector=HTTPS/:add(socket-binding=https,scheme=https,protocol=HTTP/1.1,secure=true)
        
         /subsystem=web/connector=HTTPS/ssl=configuration:add(name=https,certificate-key-file="${jboss.server.config.dir}/keystore.jks",password=password, key-alias=jboss, cipher-suite=CIPHERS)
        

        "key-alias" is the alias in the keystore, and "CIPHERS" should be replaced with a list of strong encryption ciphers to use (see documentation below). Leaving it off will not restrict

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

        This is the resuling XML. cipher-suite was left off here, but it should not be in a production environment:

         <connector name="https" protocol="HTTP/1.1" scheme="https" socket-binding="https" secure="true" >
             <ssl name="ssl" key-alias="jboss" password="password" 
                 certificate-key-file="${jboss.server.config.dir}/keystore.jks" 
                 verify-client="false" protocol="TLSv1"/>
         </connector>
        

     4. See Implement SSL Encryption for the JBoss EAP 6 Web Server for more information.

   • JBoss EAP 5

     1. Put the created keystore.jks file under /jboss-as/server/$PROFILE/conf/ directory

     2. Configure $JBOSS_HOME/server/$PROFILE/deploy/jbossweb.sar/server.xml:

        <connector protocol="HTTP/1.1" SSLEnabled="true" 
            port="8443" address="${jboss.bind.address}"
            scheme="https" secure="true" clientAuth="false" 
            keystoreFile="${jboss.server.home.dir}/conf/keystore.jks"
            keystorePass="password" SSLProtocol = "TLS" />
        

   • JBoss EAP 5 or 6 APR with native components

     1. Make sure that you have your server certificate and matching private key. See diagnostic steps of Creating a Certificate Signing Request should you need an openssl command to confirm.

        Note: This method certificates are often created by following on of the examples from, Knowledge Base article: Creating a Certificate Signing Request.

        The location of the certificates does not matter so long as JBoss can read the files.

     2. Set the protocol to protocol="org.apache.coyote.http11.Http11AprProtocol" in the connector, as this enables the SSLCertificateFile and SSLCertificateKeyFile options.

         <connector port="8443" maxThreads="200" scheme="https" secure="true" SSLEnabled="true"
             protocol="org.apache.coyote.http11.Http11AprProtocol"
             SSLCertificateFile="/usr/local/ssl/server.crt" 
             SSLCertificateKeyFile="/usr/local/ssl/server.key"
             clientAuth="optional" SSLProtocol="TLSv1"/>
        

3. Start/Restart the server after changing making the SSL configuration. Note sslProtocol does not work. Please use the uppercase SSLProtocol.

Root Cause

Some of these older examples are using TLSv1 / SSL. Red Hat recommends that you explicitly disable SSL in favor of TLSv1.1 or TLSv1.2 in all affected packages. Red Hat also recommends selectively whitelisting a set of strong ciphers to use for cipher-suite. Enabling weak ciphers is a significant security risk. Consult your JDK vendor's documentation before deciding on particular cipher suites as there may be compatibility issues.

You can also refer to this link for configuring a CA certificate and then using that keystore in the above mentioned EAP 6.x or 5.x configuration for https connector.

Diagnostic Steps

• You can test the SSL configuration¹, by using your browser, simply browse to https://localhost:8443/ or https://HOSTNAME:8443/.
• Keep in mind that you may need to import the certificate in the browser, which may mean that it needs to be converted to a PKCS12 file.

    keytool -importkeystore -srckeystore identity.jks -srcstoretype JKS -deststoretype PKCS12 -destkeystore browser_key.p12

    Enter destination keystore password:  
    Re-enter new password: 
    Enter source keystore password:  
    Entry for alias mykey successfully imported.
    Import command completed:  1 entries successfully imported, 0 entries failed or cancelled

• Your browser may ask to add an exception, and then it should take you to your JBoss server.

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.