Thursday, January 28, 2016

Java client authentication for JBoss EAP over SSL

SSL Encryption for Web Server

Secure Sockets Layer (SSL) encrypts network traffic between two systems. Traffic between the two systems is encrypted using a two-way key, generated during the handshake phase of the connection and known only by those two systems.

In order for a browser to connect with JBoss EAP over SSL the following steps will need to be performed:
  • Create keystore containing public and private keys for the server
  • Configure a HTTPS connector in JBoss EAP 

In order for a Java client application to authenticate with JBoss EAP over SSL the following steps will need to be performed:
  • Create keystores for the server and client 
  • Configure a HTTPS connector in JBoss EAP 
  • Include the SSL configuration in your client application

SSL Encryption Keys and Certificate

For secure exchange of the two-way encryption key, SSL makes use of Public Key Infrastructure (PKI), a method of encryption that utilizes a key pair. A key pair consists of two separate but matching cryptographic keys:

  • public key - shared with others and used to encrypt data
  • private key - kept secret and used to decrypt data that has been encrypted using the public key

When a client requests a secure connection, a handshake phase takes place before secure communication can begin. During the SSL handshake the server passes its public key to the client in the form of a certificate. The certificate contains:

  • the identity of the server (its URL)
  • the public key of the server
  • a digital signature that validates the certificate. You can purchase a certificate from a Certificate Authority (CA), or you can use a self-signed certificate. Self-signed certificates are not considered trustworthy but are appropriate for internal testing purposes.

The client then validates the certificate and makes a decision about whether the certificate is trusted or not.

If the certificate is trusted, the client generates the two-way encryption key for the SSL connection, encrypts it using the public key of the server, and sends it back to the server.

The server decrypts the two-way encryption key, using its private key, and further communication between the two machines over this connection is encrypted using the two-way encryption key.

Generate a keystore containing public and private keys.

 keytool -genkeypair -alias jbossweb -keyalg RSA -keysize 1024 -keystore server.keystore -validity 3650 -keypass jbosswebpass -storepass jbosswebpass
  • -genkeypair (previously named genkey)
    • Generates a key pair
  • -alias
    • alias name of the entry to process
  • -keyalg                
    • key algorithm name
  • -keysize              
    • key bit size
  • -keystore            
    • keystore name
  • -keypass                  
    • key password
  • -storepass                
    • keystore password

Verify the key

 keytool -list -keystore server.keystore

Generate a certificate signing request.

 keytool -certreq -keyalg RSA -alias jbossweb -keystore server.keystore -file certreq.csr

Test the newly generated certificate signing request.

 openssl req -in certreq.csr -noout -text

CA signed / self-signed certificate

  • Submit your certificate signing request to a Certificate Authority (CA) who 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.
 keytool -import -trustcacerts -alias jbossweb -keystore server.keystore -file server.crt
  • If you only need certificate for testing or internal purposes, you can use a self-signed certificate. You can export one from the keystore you created in the first step above:
 keytool -export -alias jbossweb -keystore server.keystore -file server.crt

Create keystores for the Java client application

The following steps describe how to create keystores for the client and how to import these keystores into the truststores. 

Export the server's public key

  • Export the server public key created in the above steps by running the following command:
 
 keytool -exportcert -alias jbossweb -keystore server.keystore -file server.cer -keypass jbosswebpass -storepass jbosswebpass
  • -exportcert (previously named export) 
    • Exports certificate
  • -alias
    • alias name of the entry to process
  • -keystore            
    • keystore name
  • -file                  
    • output file name
  • -keypass                  
    • key password
  • -storepass                
    • keystore password

Create the client's keystore private/public key


  • Run the following command:
 
 keytool -genkeypair -alias clientalias -keyalg RSA -keysize 1024 -keystore client.keystore -keypass clientpass -storepass clientpass -validity 3650
  • -genkeypair (previously named genkey)
    • Generates a key pair
  • -alias
    • alias name of the entry to process
  • -keyalg                
    • key algorithm name
  • -keysize              
    • key bit size
  • -keystore            
    • keystore name
  • -keypass                  
    • key password
  • -storepass                
    • keystore password
  • -validity
    • validity number of days

Export the client's public key

  • Run the following command:
 
 keytool -exportcert -alias clientalias -file client.cer -keystore client.keystore -keypass clientpass -storepass clientpass
  • -exportcert (previously named export) 
    • Exports certificate
  • -alias
    • alias name of the entry to process
  • -file                  
    • output file name
  • -keystore            
    • keystore name
  • -keypass                  
    • key password
  • -storepass                
    • keystore password

Server truststore

  • Add the client's public key to the truststore of the server

 
 keytool -importcert -trustcacerts -alias clientalias -file client.cer -keystore server.keystore -keypass jbosswebpass -storepass jbosswebpass
  • importcert (previously named import)
    • Imports a certificate or a certificate chain
  • -trustcacerts                   
    • trust certificates from cacerts
  • -alias
    • alias name of the entry to process
  • -file                  
    • input file name
  • -keystore
    • keystore name
  • -keypass
    • key password
  • -storepass
    • keystore password

Client truststore

  • Add the server's public key to the truststore of the client
 
 keytool -importcert -trustcacerts -alias jbossweb -file server.cer -keystore client.keystore -keypass clientpass -storepass clientpass
  • importcert (previously named import)
    • Imports a certificate or a certificate chain
  • -trustcacerts                   
    • trust certificates from cacerts
  • -alias
    • alias name of the entry to process
  • -file                  
    • input file name
  • -keystore
    • keystore name
  • -keypass
    • key password
  • -storepass
    • keystore password

More information on how to use the keytool command can be found here.

Configure a HTTPS connector in JBoss EAP 6


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. This can be done via CLI or by editing the standalone.xml configuration file directly, this is what an example HTTPS connector configuration looks like:

<subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default-host" native="false">
  <connector name="HTTPS" protocol="HTTP/1.1" scheme="https" socket-binding="https" secure="true">
    <ssl name="https" key-alias="jbossweb" password="jbosswebpass" certificate-key-file="${jboss.server.config.dir}/keys/server.keystore" cipher-suite="RSA" protocol="TLSv1"/>
  </connector>
  <virtual-server name="default-host" enable-welcome-root="true">
    <alias name="localhost"/>
    <alias name="example.com"/>
  </virtual-server>
</subsystem>

Another example:

 <subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default-host" native="false">
   <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
   <connector name="HTTPS" protocol="HTTP/1.1" scheme="https" socket-binding="https" secure="true">
     <ssl name="https"
       key-alias="jbossweb"
       password="jbosswebpass"
       certificate-key-file="${jboss.server.config.dir}/server.keystore"
       verify-client="true"
       ca-certificate-file="${jboss.server.config.dir}/server.keystore"/>
   </connector>

   <virtual-server name="default-host" enable-welcome-root="true">
     <alias name="localhost"/>
     <alias name="example.com"/>
   </virtual-server>
 </subsystem>
  • In the above example the keystore (certificate-key-file) is also used as the truststore ( ca-certificate-file).
  • The verify-client attribute is equivalent to Tomcats clientAuth attribute. 
  • When using keytool to create keystores, JBoss will compare the value you enter in the name against the hostname and will complain if it does not match You can set the following JVM argument to have JBoss ignore the hostname:
  • -Dorg.jboss.security.ignoreHttpsHost=true

Include the SSL configuration in your client application

  • Within your standalone client application the following properties will need to be set to point to the client's keystore/truststore. 
  • Adding these system properties will set the keystore/truststore for the whole JVM.
 
 System.setProperty("javax.net.ssl.keyStore", "/path/to/client.keystore");
 System.setProperty("javax.net.ssl.keyStorePassword", "clientpass");
 System.setProperty("javax.net.ssl.trustStore", "/path/to/client.keystore");
 System.setProperty("javax.net.ssl.trustStorePassword", "clientpass");
  • Once those properties are set you should be able to make the necessary HTTPS call (an example would be a webservice request over SSL).

Keystore Explorer

Keystore Explorer is an open source GUI replacement for the Java command-line utilities keytool and jarsigner. KeyStore Explorer presents their functionality, and more, via an intuitive graphical user interface.