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

Subject Alternative Name

When generating the keystore you might need to set the subject alternative name, Chrome for instance will block access to a site that just uses the common name field and not the subject alternative name. In order to specify a subject alternative name you can use the ext option in the keytool command like:

keytool -genkeypair -alias jbossweb -keyalg RSA -keysize 1024 -keystore server.jks -validity 3650 -keypass jbosswebpass -storepass jbosswebpass -ext SAN=dns:test.example.com

Verify the key

The following command is quite useful to print information on the keystore:

keytool -list -v -keystore server.jks

Generate a certificate signing request.

keytool -certreq -keyalg RSA -alias jbossweb -keystore server.jks -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.jks -file server.crt

• If you get the following error: "keytool error: java.lang.Exception: Failed to establish chain from reply" it might be because you need to import root certificates. You should be able to know if you need this by whoever issued the CA to you. You will need to do the following:
• Import root certificate to cacerts which will be available at JAVA_HOME/jre/lib/security folder using following command:

 keytool -importcert -alias root -file Root.cer -keystore cacerts

• Import root certificate using following command:

 keytool -importcert -alias root -file Root.cer -keystore server.jks

• Import intermediate certificate using following command

 keytool -importcert -alias sub -file Sub.cer -keystore server.jks

• Import site certificate using following command:

 keytool -trustcacerts -importcert -alias jbossweb -file server.crt -keystore jbossprep.jks

• 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.jks -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.jks -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.jks -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
• -storetype
• keystore type. Default is jks, for PKCS12 use -storetype PKCS12

Subject Alternative Name

The same as why mentioned above to specify a subject alternative name you can use the ext option in the keytool command like:

 
 keytool -genkeypair -alias clientalias -keyalg RSA -keysize 1024 -keystore client.jks -keypass clientpass -storepass clientpass -validity 3650 -ext SAN=dns:test.example.com

Export the client's public key

• Run the following command:

 
 keytool -exportcert -alias clientalias -file client.cer -keystore client.jks -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. The following imports the clients public key into the existing server.jks

 
 keytool -importcert -trustcacerts -alias clientalias -file client.cer -keystore server.jks -keypass jbosswebpass -storepass jbosswebpass

• Instead of doing the above you could also add the client's public key to a truststore file

 
 keytool -importcert -trustcacerts -alias clientalias -file client.cer -keystore truststore.jks -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.jks -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.

Export private key from server keystore

If you ever need to export your server JKS keytool format to PKCS #12 format and the private key you can follow these steps:

• Save JKS as PKCS:

 
keytool -importkeystore -srckeystore server.jks -destkeystore keystore.p12 -deststoretype PKCS12 -srcalias jbossweb -deststorepass jbosswebpass -destkeypass jbosswebpass

• Export certificate using openssl:

 
openssl pkcs12 -in keystore.p12  -nokeys -out cert.pem

• Export unencrypted private key:

 
openssl pkcs12 -in keystore.p12  -nodes -nocerts -out key.pem

• Verify that the Certificate and your Private Key go together:

 
diff <(openssl x509 -noout -in server.cer -modulus) <(openssl rsa -noout -in key.pem -modulus -passin pass:jbosswebpass)

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 one-way SSL authentication 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.jks" 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>

The following example is for two-way SSL authentication:

<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.jks"
       verify-client="true"
       ca-certificate-password="jbosswebpass"
       ca-certificate-file="${jboss.server.config.dir}/truststore.jks"/>
   </connector>

   <virtual-server name="default-host" enable-welcome-root="true">
     <alias name="localhost"/>
     <alias name="example.com"/>
   </virtual-server>
 </subsystem>

• The verify-client attribute is equivalent to Tomcats clientAuth attribute. When this value is set to true it means the SSL stack should require a valid certificate chain from the client before accepting a connection.
• 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

Standalone Java 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.jks");
 System.setProperty("javax.net.ssl.keyStorePassword", "clientpass");
 System.setProperty("javax.net.ssl.trustStore", "/path/to/client.jks");
 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).

Browser as the Client

In order to test the certificates through a browser you will need to import all the certificates (root, intermediates and the certificate you got back from the CA). If you have configured JBoss above to verify-client then you will also need to import the client.p12 keystore into the browser. The following applies to windows:

Server Certificate

• Open internet connections, an easy way to do it is by running: inetcpl.cpl
• Go to the content tab
• Certificates
• Trusted Root Certification Authorities 
• Import
• Choose the CA signed / self-signed certificate (server.crt)

Client Keystore

• Open internet connections, an easy way to do it is by running: inetcpl.cpl
• Go to the content tab
• Certificates
• Personal 
• Import
• Choose the PKCS12 client keystore (client.p12)

Configuring Debug Options

In order to print debug options you can run your java application / JBoss application server with this addtional system parameter:

 -Djavax.net.debug=ssl,handshake

or

 -Djavax.net.debug=all

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.