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)
- -alias
- alias name of the entry to process
- -keyalg
- -keysize
- -keystore
- -keypass
- -storepass
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)
- -alias
- alias name of the entry to process
- -keystore
- -file
- -keypass
- -storepass
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)
- -alias
- alias name of the entry to process
- -keyalg
- -keysize
- -keystore
- -keypass
- -storepass
- -validity
- -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)
- -alias
- alias name of the entry to process
- -file
- -keystore
- -keypass
- -storepass
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
- -keystore
- -keypass
- -storepass
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
- -keystore
- -keypass
- -storepass
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:
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:
- 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.
