How do I set up SSL on Tomcat?
Author: Deron Eriksson
Description: This tutorial describes setting up a self-signed certificate on Tomcat.
Tutorial created using: Windows XP || JDK 1.5.0_09 || Eclipse Web Tools Platform 1.5.1 || Tomcat 5.5.20


Page:    1 2 >

TomcatSW comes with great instructions for setting up SSL. The documentation can be found at http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html.

In a typical production environment, SSL is handled by a web server such as ApacheSW, which unencrypts the requests and forwards them on to Tomcat. As a result, usually Tomcat doesn't need to be concerned with SSL. However, it is possible to set things up so that you talk to Tomcat directly rather than through a web server, and in this situation SSL needs to be set up for secure communication between browsers (clients) and Tomcat. When you set up SSL, a 'certificate' is created that identifies your server by IP address.

Certificate Authorities like Verisign exist to verify to clients that your server is who your certificate says it is. If you run an eCommerce site, you would definitely want your server to be registered with a Certificate Authority so that clients know they can trust that your server to be the server they think it is.

However, this type of registration can be fairly involved and expensive. What should you do if you just want to make sure that certain communication between a client browser and your Tomcat server is encrypted? A quick solution is to create a 'self-signed' certificate. If you do this, clients can't really trust that you are who you say you are, but communication between a client and your server will be encrypted.

JavaSW provides a handy tool for creating a self-signed certificate. This can be done using the 'keytool' utility, as shown below.

C:\>cd jdk*
C:\jdk1.5.0_09>cd bin
C:\jdk1.5.0_09\bin>keytool -genkey -alias tomcat -keyalg RSA
Enter keystore password:  changeit
What is your first and last name?
  [Unknown]:  teamcakes
What is the name of your organizational unit?
  [Unknown]:  
What is the name of your organization?
  [Unknown]:  
What is the name of your City or Locality?
  [Unknown]:  
What is the name of your State or Province?
  [Unknown]:  
What is the two-letter country code for this unit?
  [Unknown]:  
Is CN=teamcakes, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?
  [no]:  yes
Enter key password for <tomcat>
	(RETURN if same as keystore password):  
C:\jdk1.5.0_09\bin>

The magic is in the call to keytool, which generates a certificate in your home directory, which is something like is C:\Documents and Settings\TeamCakes\ and is called '.keystore'. The keystore password is 'changeit', and the tomcatSW password is set to the same as the keystore password.

keytool -genkey -alias tomcat -keyalg RSA

After doing that, I went to Tomcat's server.xml file and uncommented the port 8443 SSL Connector that came with Tomcat. Normally, SSL HTTP runs on port 443 (and nonsecure HTTP runs on port 80 for a web server), but I'll keep the 8443 port number. If you want browsers to be able to communicate securely and directly with Tomcat without requiring the addition of the port number after the host name in the URL, change 8443 to 443. The SSL HTTP Connector is shown below:

    <!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
    <Connector port="8443" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS" />

Believe it or not, that's all that's required to set up a self-signed certificate! Let's try firing up a project to test our self-signed certificate. I'll fire up my java-tutorials project in EclipseSW.

project started in Eclipse

First, let's try hitting our web application via regular HTTP (on port 8080).

hitting web application on port 8080

Now, let's try hitting our web application via SSL HTTP (on port 8443). When we try this in IE7, we receive a warning message. This is basically telling the browser user that the certificate hasn't been verified by a Certificate Authority. This is because we created a self-signed certificate, which encrypts the communication between browser and server but doesn't guarantee that we are who we say we are.

hitting web application on port 8443

If we click to continue to the website, we can see that we indeed are able to hit are web application using SSL.

hitting web application on port 8443

(Continued on page 2)

Page:    1 2 >