JBoss AS7: Configuring SSL on JBoss Web

There are 3 sets of connectors that one can configure with JBossWeb.

  • AJP Connectors
  • HTTP/HTTPS Connectors
  • Native Connectors

 

AJP Connectors are primarily used to service requests coming from a web server such as Apache Httpd with mod_jk, mod_cluster etc in between.

HTTP/HTTPS Connectors are the standard connectors that can service web requests directly.

Native Connectors use the APR native libraries which some users may prefer.

 

 

In JBoss AS7, the web subsystem configuration is performed in the web module in standalone.xml or domain.xml

Important Points to remember:

  1. The intention of the JBossWeb developers has been to unify the SSL configuration for all the connectors via the <ssl/> subelement.
  2. When the native modules exist in JBoss AS (in the lib folder of JBOSS_HOME/modules/org/jboss/as/web/main), the Native Connector settings come into play. You can turn this behavior off, by the attribute "native=false" on the connector setting.

 

jboss-as-7.1.0.Final-SNAPSHOT/modules/org/jboss/as/web/main$ ls
jasper-jdt-7.0.3.Final.jar        jboss-as-web-7.1.0.Final-SNAPSHOT.jar        jbossweb-7.0.8.Final.jar        lib
jasper-jdt-7.0.3.Final.jar.index  jboss-as-web-7.1.0.Final-SNAPSHOT.jar.index  jbossweb-7.0.8.Final.jar.index  module.xml

anil@localhost:~jboss-as-7.1.0.Final-SNAPSHOT/modules/org/jboss/as/web/main$ ls lib/
linux-i686  linux-x86_64  macosx-i686  macosx-x86_64  win-i686  win-x86_64

 

As you can see the native libraries for each os architecture is available here.

 

===> If you do not want the native connector settings kicking in, you should remove the lib directory under modules/org.jboss/as/web/main and its contents.  You can also get the same behavior by setting native=false on the connector setting.<====

 

How Do I Know Which Connector Is Getting Activated?

You can see the use of native code in the following two lines when JBoss AS7 starts up.

 

 12:05:31,786 INFO  [org.apache.coyote.http11.Http11AprProtocol] (MSC service thread 1-3) Starting Coyote HTTP/1.1 on http--127.0.0.1-8080
12:05:31,837 INFO  [org.apache.coyote.http11.Http11AprProtocol] (MSC service thread 1-1) Starting Coyote HTTP/1.1 on http--127.0.0.1-8443

See  the presence of Http11AprProtocol class.  This indicates that the APR module libraries are kicking into action.  If you do not desire this, then remove the lib directory contents as described above or set the attribute native to false on the connector setting.

 

 

If you do not have the apr module libraries anymore, then you will see the following:

 

org.apache.coyote.http11.Http11Protocol

This means the HttpConnector is coming into play.  So we can use the JSSE settings with the Java Keytool.

 

Working With KeyStores

 

For SSL settings, we will need access to a keystore.

 

If there is Client Certificate based authentication, then we will need to have access to a trust store also.

 

Preferred KeyStores

 

For Native Connector settings,  use the OpenSSL generated certificates and Keys.

For the Https Connector settings, you can use the Java Keytool generated keystore.

 

APR/Native Connectors

OpenSSL Generated Key and Certificate

Three Steps are involved.

 

Step 1: Create a Key.

 

$ openssl genrsa -des3 -out newkey.pem 1024
Generating RSA private key, 1024 bit long modulus
...........................................++++++
.........++++++
e is 65537 (0x10001)
Enter pass phrase for newkey.pem:
Verifying - Enter pass phrase for newkey.pem:

I used a pass phrase of "mykey"

 

 

Step 2:  Create a Certificate Signing Request (CSR) using the generated key.

 

$ openssl req -new -key newkey.pem -out server.csr
Enter pass phrase for newkey.pem:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:US
State or Province Name (full name) []:IL
Locality Name (eg, city) [Default City]:Chicago
Organization Name (eg, company) [Default Company Ltd]:RedHat
Organizational Unit Name (eg, section) []:JBoss
Common Name (eg, your name or your server's hostname) []:Anil
Email Address []:anil@apache.org

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:mykey
An optional company name []:

 

Step 3:  Create a x509 certificate in PEM format.

 

$ openssl x509 -req -days 365 -in server.csr -signkey newkey.pem -out newcert.pem
Signature ok
subject=/C=US/ST=IL/L=Chicago/O=RedHat/OU=JBoss/CN=Anil/emailAddress=anil@apache.org
Getting Private key
Enter pass phrase for newkey.pem:


anil@localhost:~/opensslKeys$ ls
newcert.pem  newkey.pem  server.csr

I used a pass phrase "mykey"

 

Configure the Web Subsystem

 

In my standalone.xml, I now have:

 

  <subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host">
            <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
            <connector name="https" protocol="HTTP/1.1" scheme="https" socket-binding="https" enable-lookups="false" secure="true">
                <ssl password="mykey" certificate-key-file="/home/anil/opensslKeys/newkey.pem" protocol="TLSv1" verify-client="false" certificate-file="/home/anil/opensslKeys/newcert.pem"/>
            </connector>
            <virtual-server name="default-host" enable-welcome-root="true">
                <alias name="localhost"/>
                <alias name="example.com"/>
            </virtual-server>
        </subsystem>

 

Now If I have the same web application as deployed in https://community.jboss.org/wiki/JBossAS7SecurityAuditing,   I can access the application at https://localhost:8443/form-auth/  successfully.

 

 

 

Settings for Https Connector (in the absence of APR module libraries)

Using the KeyTool

 

Now create a KeyStore along with a keypair using the JDK KeyTool.

 

$ keytool -genkey -alias tomcat -keyalg RSA -keystore ~/opensslKeys/KEYTOOL/https.keystore
Enter keystore password:  
Re-enter new password: 
What is your first and last name?
  [Unknown]:  Anil S
What is the name of your organizational unit?
  [Unknown]:  JBoss
What is the name of your organization?
  [Unknown]:  RedHat
What is the name of your City or Locality?
  [Unknown]:  Chicago
What is the name of your State or Province?
  [Unknown]:  IL
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=Anil S, OU=JBoss, O=RedHat, L=Chicago, ST=IL, C=US correct?
  [no]:  yes

Enter key password for <tomcat>
        (RETURN if same as keystore password): 

 

I used the password "mykeystore".  In this case, the key alias is tomcat.

 

 

Web Subsystem Configuration

 

<subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host">
            <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
            <connector name="https" protocol="HTTP/1.1" scheme="https" socket-binding="https" enable-lookups="false" secure="true">
                <ssl password="mykeystore" certificate-key-file="/home/anil/opensslKeys/KEYTOOL/https.keystore" protocol="TLSv1" verify-client="false" certificate-file="/home/anil/opensslKeys/KEYTOOL/https.keystore"/>
            </connector>
            <virtual-server name="default-host" enable-welcome-root="true">
                <alias name="localhost"/>
                <alias name="example.com"/>
            </virtual-server>
        </subsystem>

 

When I start JBoss AS 7.1,  I should see the following line:

 

17:06:37,405 INFO  [org.apache.coyote.http11.Http11Protocol] (MSC service thread 1-4) Starting Coyote HTTP/1.1 on http--127.0.0.1-8443

 

I can access the https://localhost:8443/form-auth/  as before.

 

Advanced Topics

 

Mask Connector Keystore Password


When you want to mask the keystore password in the ssl subelement of the connector setting.

 

You should definitely read on the Vault in JBoss AS7.1 at https://community.jboss.org/wiki/JBossAS7SecuringPasswords

 

 

bin/util$ sh vault.sh 
=========================================================================

  JBoss Vault

  JBOSS_HOME: /home/anil/as7/jboss-as/build/target/jboss-as-7.1.0.Final-SNAPSHOT

  JAVA: /usr/java/jdk1.6.0_30/bin/java

  VAULT Classpath: /home/anil/as7/jboss-as/build/target/jboss-as-7.1.0.Final-SNAPSHOT/modules/org/picketbox/main/*:/home/anil/as7/jboss-as/build/target/jboss-as-7.1.0.Final-SNAPSHOT/modules/org/jboss/logging/main/*:/home/anil/as7/jboss-as/build/target/jboss-as-7.1.0.Final-SNAPSHOT/modules/org/jboss/common-core/main/*:/home/anil/as7/jboss-as/build/target/jboss-as-7.1.0.Final-SNAPSHOT/modules/org/jboss/as/security/main/*
=========================================================================

**********************************
****  JBoss Vault ********
**********************************
Please enter a Digit::   0: Start Interactive Session  1: Remove Interactive Session  2: Exit
0
Starting an interactive session
Enter directory to store encrypted files (end with either / or \ based on Unix or Windows:/home/anil/vault/
Enter Keystore URL:/home/anil/vault/vault.keystore
Enter Keystore password: 
Enter Keystore password again: 
Values match
Enter 8 character salt:1234567
Enter 8 character salt:1234567
Enter 8 character salt:12345678
Enter iteration count as a number (Eg: 44):50

Please make note of the following:
********************************************
Masked Password:MASK-5WNXs8oEbrs
salt:12345678
Iteration Count:50
********************************************

Enter Keystore Alias:vault
Jan 24, 2012 10:23:26 AM org.jboss.security.vault.SecurityVaultFactory get
INFO: Getting Security Vault with implementation of org.picketbox.plugins.vault.PicketBoxSecurityVault
Obtained Vault
Intializing Vault
Jan 24, 2012 10:23:26 AM org.picketbox.plugins.vault.PicketBoxSecurityVault init
INFO: Default Security Vault Implementation Initialized and Ready
Vault is initialized and ready for use
Handshake with Vault complete
Please enter a Digit::   0: Store a password  1: Check whether password exists  2: Exit
0
Task:  Store a password
Please enter attribute value: 
Please enter attribute value again: 
Values match
Enter Vault Block:keystore_pass
Enter Attribute Name:password
Attribute Value for (keystore_pass, password) saved

Please make note of the following:
********************************************
Vault Block:keystore_pass
Attribute Name:password
Shared Key:NmZiYmRmOGQtMTYzZS00MjE3LTllODMtZjI4OGM2NGJmODM4TElORV9CUkVBS3ZhdWx0
Configuration should be done as follows:
VAULT::keystore_pass::password::NmZiYmRmOGQtMTYzZS00MjE3LTllODMtZjI4OGM2NGJmODM4TElORV9CUkVBS3ZhdWx0
********************************************

Please enter a Digit::   0: Store a password  1: Check whether password exists  2: Exit
2
anil@sadbhav:~/as7/jboss-as/build/target/jboss-as-7.1.0.Final-SNAPSHOT/bin/util$

 

NOTE:  the attribute value was given as "mykeystore".  This is what we are trying to mask.

 

 

Now my standalone.xml contains the following settings:

 

<?xml version='1.0' encoding='UTF-8'?>

<server name="sadbhav" xmlns="urn:jboss:domain:1.1" xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance">

   <extensions>
     ...
    </extensions>

  <vault>
        <vault-option name="KEYSTORE_URL" value="${user.home}/vault/vault.keystore"/>
        <vault-option name="KEYSTORE_PASSWORD" value="MASK-3y28rCZlcKR"/>
        <vault-option name="KEYSTORE_ALIAS" value="vault"/>
        <vault-option name="SALT" value="12438567"/>
        <vault-option name="ITERATION_COUNT" value="50"/>
        <vault-option name="ENC_FILE_DIR" value="${user.home}/vault/"/>
    </vault>
     ....


        <subsystem xmlns="urn:jboss:domain:web:1.1" native="false" default-virtual-server="default-host">
            <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
            <connector name="https" protocol="HTTP/1.1" scheme="https" socket-binding="https" enable-lookups="false" secure="true">
                <ssl password="${VAULT::keystore_pass::password::NmZiYmRmOGQtMTYzZS00MjE3LTllODMtZjI4OGM2NGJmODM4TElORV9CUkVBS3ZhdWx0}" 
                                      certificate-key-file="/home/anil/opensslKeys/KEYTOOL/https.keystore" 
                                      protocol="TLSv1" verify-client="false" 
                                     certificate-file="/home/anil/opensslKeys/KEYTOOL/https.keystore"/>
            </connector>
            <virtual-server name="default-host" enable-welcome-root="true">
                <alias name="localhost"/>
                <alias name="example.com"/>
            </virtual-server>
        </subsystem>

   ....