Tomcat and SSL

By Gomez Henri <hgomez@slib.fr>

Table of Contents

• Tomcat and SSL
• Building tomcat with SSL support
• Tomcat with Apache and mod_jk
• SSL via Apache
• Direct SSL
• Credits

Tomcat and SSL

Tomcat can use SSL directly (via an HTTP connector supporting SSL) or via an SSL-capable Apache (Apache-SSL or apache+mod_ssl) with the mod_jk connector.

Building tomcat with SSL support

If you want to rebuild tomcat with SSL, be careful of your CLASSPATH. I used to clear the CLASSPATH environment variable to avoid conflict in jar. A common cause of conflict is XML parsers (xerces & jaxp). Tomcat needs a recent XML parser like the Apache Group's xerces 1.1.2 or Sun's jaxp 1.0.1.

At build time, (via ant), tomcat will check for some libs and will then include various options, possibly including SSL support. If you have the JSSE 1.0.2 jars in your CLASSPATH, tomcat will be built with SSL (SSLSocketFactory). Tomcat will use the JSSE jars (jcert.jar, jsse.jar, jnet.jar). This software COULDN'T BE INCLUDED in tomcat. You'll have to go to the jsse home page and download the domestic (US/Canada) or global archive from there. Then copy the 3 jars into tomcat's runtime classpath lib ($TOMCAT_HOME/lib).

Tomcat with Apache and mod_jk

If you use Apache with SSL (Apache-SSL or apache+mod_ssl) and the JkExtractSSL directive in httpd.conf, the apache connector mod_jk will be able to pass some SSL information to tomcat.

This information is:

Since Apache-SSL and apache+mod_ssl use different environment variables, you can set SSL variables from the following JK variables

• JkExtractSSL
• JkHTTPSIndicator
• JkSESSIONIndicator
• JkCIPHERIndicator
• JkCERTSIndicator:

here is an example of directives to include in httpd.conf for use with mod_ssl:

# Should mod_jk send SSL information to Tomcat (default is On)
JkExtractSSL On
# What is the indicator for SSL (default is HTTPS)
JkHTTPSIndicator HTTPS
# What is the indicator for SSL session (default is SSL_SESSION_ID)
JkSESSIONIndicator SSL_SESSION_ID
# What is the indicator for client SSL cipher suit (default is SSL_CIPHER)
JkCIPHERIndicator SSL_CIPHER
# What is the indicator for the client SSL certificated (default is SSL_CLIENT_CERT)
JkCERTSIndicator SSL_CLIENT_CERT

When using mod_jk with Apache & mod_ssl it is essential to specify "SSLOptions +StdEnvVars +ExportCertData" in the httpd.conf file.
Otherwise mod_ssl will not produce the necessary environment variables for mod_jk. (Tilo Christ <tilo.christ@med.siemens.de>)

Warning: Even if mod_jk supports both ajp12 (the old version from Apache JServ) and ajp13, only ajp13 can forward SSL information to tomcat.

SSL via Apache

mod_jk seems to support the VirtualHost directive of Apache. It's especially useful when using apache+mod_ssl with tomcat.
This config will easily secure your webapps via Apache SSL support. Just take care of setting these JK variables outside VirtualHost directives:

JkWorkersFile /etc/httpd/conf/workers.properties
JkLogFile /var/log/httpd/mod_jk.log
JkLogLevel warn

The JK redirect stuff could be set in virtual hosts: <virtualhost _default_:443>

<VirtualHost _default_:443>
SSLEngine on
SSLCipherSuite ALL:!ADH:!EXP56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL 
# other SSL stuff
Alias /alesia "/var/tomcat/webapps/alesia"

<Directory "/var/tomcat/webapps/alesia"> 
  <Directory "/var/tomcat/webapps/alesia"></Directory>
  <Directory "/var/tomcat/webapps/alesia">Options Indexes FollowSymLinks </Directory>
</Directory>

JkMount /alesia/servlet/* ajp13
JkMount /alesia/*.jsp ajp13

<Location "/alesia/WEB-INF/">
</Location>

<Location "/alesia/WEB-INF/">
  AllowOverride None
  Deny from all
</Location>

</VirtualHost>

Direct SSL

If you want tomcat to serve HTTP/SSL (https) directly, you need to create a SSL certificate. For more information about SSL and certificates, I suggest you could take a look at OpenSSL (Open Source SSL implementation) and mod_ssl (SSL support for Apache)

Verify tomcat server.xml configuration file

To use the HTTP with SSL connector in tomcat, verify that it is activated in server.xml

<Connector className="org.apache.tomcat.service.PoolTcpConnector">
<Parameter name="handler" value="org.apache.tomcat.service.http.HttpConnectionHandler"/>
<Parameter name="port" value="8443"/>
<Parameter name="socketFactory" value="org.apache.tomcat.net.SSLSocketFactory"/>
<Parameter name="keystore" value="/var/tomcat/conf/keystore" />
<Parameter name="keypass" value="changeit"/>
<Parameter name="clientAuth" value="true"/>
</Connector>

In this example we indicate the keystore is file /var/tomcat/conf/keystore. The keystore password is changeit and we want clients to authentificate.

Generate a SSL certificate (RSA) for tomcat

I succeed (at least) with my IBM JDK 1.3 after:

• jsse jars MUST BE IN BOTH CLASSPATH and $JAVA_HOME/jre/lib/ext (JAVA > 1.2)
• from server.xml doc.You _need_ to set up a server certificate if you want this to work, and you need JSSE.
  • Add JSSE jars to CLASSPATH
  • Edit $JAVA_HOME/jre/lib/security/java.security
    Add: security.provider.2=com.sun.net.ssl.internal.ssl.Provider
  • Do: keytool -genkey -alias tomcat -keyalg RSA
    RSA is essential to work with Netscape and IIS. Use "changeit" as password (or add keypass attribute). You don't need to sign the certificate. You can set parameter keystore and keypass if you want to change the default ($HOME/.keystore with changeit)
• I suggest you install jcert.jar, jnet.jar and jsse.jar in $JAVA_HOME/jre/lib/ext and then add them to your CLASSPATH export
  
  

  CLASSPATH=$JAVA_HOME/jre/lib/ext/jcert.jar:$CLASSPATH 
  export CLASSPATH=$JAVA_HOME/jre/lib/ext/jnet.jar:$CLASSPATH
  export CLASSPATH=$JAVA_HOME/jre/lib/ext/jsse.jar:$CLASSPATH
  

  You could also copy the 3 jars into $TOMCAT_HOME/lib/ so they are under the existing CLASSPATH at tomcat startup (tomcat.sh).

Importing SSL certificates

It's possible to import certificates generated with OpenSSL. Here are the steps needed to generate such certs with OpenSSL:

• To generate a new request and a new key
  openssl req -new -out REQ.pem -keyout KEY.pem
• To generate a self signed x509 certificate from a certificate request using a supplied key, and see the text form of the output certificate (which we will put into the file selfSign.pem
  openssl req -x509 -in REQ.pem -key KEY.pem -out CERT.pem
• Verify that the signature is correct on a certificate request.
  openssl req -verify -in REQ.pem
• Verify that the signature was made using a specified public key
  openssl req -verify -in REQ.pem -key KEY.pem
• Print the contents of a certificate request
  openssl req -text -in REQ.pem
• To import the CERT in keystore, just:
  keytool -import -v -trustcacerts -alias tomcat -file CERT.pem

Credits

This document was created by Gomez Henri. Thanks to hgopal@cmcltd.com for import info. Feel free to contact me for more updates.