This FlashGuide^TM covers adding SSL capabilities to Tomcat 4.1.x on Unix.

This guides describes two different ways of creating certificates: using Java's keytool utility to create the keystore ("Java KeyStore" or "JKS" format) or using OpenSSL to create the keystore ("PKCS12" format). If you just want to use Java's keytool, then skip steps 3 and 4. If you want to use OpenSSL, skip step 2.

1. Installing Tomcat 5 on Linux

1. Download the latest Tomcat binary from the Tomcat 5 section of http://jakarta.apache.org/site/binindex.cgi. Currently, Tomcat 5.0.28 is the latest.
2. Install Tomcat by unzipping/untaring the download file and placing in the desired directory (I used /usr/local)

   cd /usr/local
   tar zxf ./jakarta-tomcat-5.0.28.tar.gz
      

3. Note the location of your Tomcat installation - we will refer to this as $CATALINA_HOME
4. Optionally, save time on typing by creating a symbolic link like this:

   ln -s jakarta-tomcat-5.0.28 tomcat5
      

2. Configuring Tomcat 5 for SSL (with keytool)

1. Skip this step if you want to generate certificates with OpenSSL.
2. If you are using Java 1.3.x, download the latest Java Secure Sockets Extension (JSSE) 1.0.2 at http://java.sun.com/products/jsse/
3. Install JSSE by unpacking it into the desired directory
4. Copy jcert.jar, jnet.jar and jsse.jar to $JAVA_HOME/jre/lib/ext

   cd jsse1.0.2/lib
   cp *.jar $JAVA_HOME/jre/lib/ext
     

5. Add the bin directory of the JSSE installation to your $PATH:

   export PATH=$PATH:/usr/local/jsse1.0.2/bin
     

6. Generate a certificate:

   cd jsse1.0.2/bin
   keytool -genkey -alias tomcat -keyalg RSA -keystore /etc/keystore -storepass mysecretpass
     

   Set the -keystore parameter to wherever you want the generated keys to be stored. Set the -storepass to whatever password you want. When prompted, provide the other requested info (name, company, location, etc.).

7. Edit $CATALINA_HOME/conf/server.xml and undefine the SSL connector:

       <Connector port="6443" 
            maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
            enableLookups="false" disableUploadTimeout="true"
            acceptCount="100" debug="0" scheme="https" secure="true"
            clientAuth="false" sslProtocol="TLS" keystoreType="JKS"
            keystoreFile="/etc/.keystore" keystorePass="mysecretpass"/>
     

   Set port and the other parameters as desired. Note that if you change the port you should also change the "redirect" parameter for the non-HTTPS connector to the same value. In the Factory tag, set keystoreFile to point to the location where you placed the keystore. You'll need to set keystorePass if you changed the password from the default of "changeit" to something else.

   The "keystoreType" attribute is set to JKS for "Java Keystore": the format produced by Java's keytool.

3. Building OpenSSL on Linux

1. Download the latest OpenSSL distribution from http://www.openssl.org/source/. As of this writing, the latest version is 0.9.7e.
2. Unpack the distribution

   tar zxvf openssl-0.9.7e.tar.gz
     

3. Configure OpenSSL

   cd openssl-0.9.7e
   ./config -fPIC --prefix=/usr --openssldir=/usr/openssl
     

   If you omit the --prefix and --openssldir parameters, openssl will install into /usr/local/openssl.

4. Compile OpenSSL

   make
   make test
     

   The "make test" step is optional, but useful to make sure all works as it is supposed to.

5. Install OpenSSL

   make install
     

4. Configuring Tomcat 5 for SSL (with OpenSSL)

1. Skip this step if you want to generate certificates with Java's keytool.
2. Generate an RSA key for signing the certificate:

   openssl genrsa -out mykey.pem 2048
     

3. Generate a certificate using the new key:

   openssl req -new -x509 -key mykey.pem -out mycert.pem -days 365
     

   Enter your name, organization name and address as prompted.

   In this example, we've created a key file, mykey.pem, and a self-signed certificate. Normally, you want a certificate from a "certificate authority" or CA. Using a self-signed certificate IS NOT FOR PRODUCTION!

4. Since the certificate is in PEM format, convert it to PKCS12 for Tomcat:

   openssl pkcs12 -export -in mycert.pem -inkey mykey.pem -out mycert.p12 -name tomcat
     

   You MUST specify an export password! Tomcat expects one.

5. Edit $CATALINA_HOME/conf/server.xml and undefine the SSL connector:

       <Connector port="6443" 
            maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
            enableLookups="false" disableUploadTimeout="true"
            acceptCount="100" debug="0" scheme="https" secure="true"
            clientAuth="false" sslProtocol="TLS" keystoreType="PKCS12"
            keystoreFile="/opt/openssl/mycert.p12" keystorePass="mysecretpass"/>
     

   Set port and the other parameters as desired. Note that if you change the port you should also change the "redirect" parameter for the non-HTTPS connector to the same value. In the Factory tag, set keystoreFile to point to the location where you placed the keystore. You'll need to set keystorePass if you changed the password from the default of "changeit" to something else.

   The "keystoreType" attribute must be set to PKCS12.

5. Testing

1. Start Tomcat:

   cd $CATALINA_HOME/bin
   catalina.sh start
     

2. Point your browser to the http://localhost:8443 (or whatever port you choose). If everything works right, you'll get prompted to accept the certificate and you should see the Tomcat splash page.