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