SSL Support to Tomcat 6 on Windows/Linux

Setting up SSL on Tomcat 6 is easy and you don't have to do much for converting your web application to work with the Https protocol. But however, the problem you would find to set up SSL is the documentation available over the web. The documentation source is available on the Apache site but it starts off good and ends with a lot of confusion. Especially I was confused on the OpenSSL part where it says to use OpenSSL.

It might be good in a production environment to use OpenSSL but if you just want to test out SSL with Tomcat 6 alone then it is more than enough to just have your JDK and Tomcat setups. So I would make you walk through the same steps which I did while getting SSL up and running and building a secured web app within a matter of minutes.

The things which I have used to setup SSL consists of:

• JDK 1.6
• Tomcat 6

Even though I have used the latest version I don't see any problems which you might face in carrying out the same set of steps for JDK 1.5 which I am about to explain. JDK comes shipped with a keytool executable which is required to generate a keystore. The keytool can be found in the earlier version of JDK too. The 3 steps which would make you to get started with setting up SSL are:

1. Generating the Keystore file
2. Configuring Tomcat for using the Keystore file
3. Configuring your web application to work with SSL

Let's get this party started now.

1. Generating the KeyStore file

The keystore file is the one which would store the details of the certificates necessary to make the protocol secured. Certificates contain the information as to who is the source from which you are receiving the application data and to authenticate whether it is the intended party or not. To make this keystore you would have to use the keytool. So open command prompt in Windows or the shell in Linux and type:

cd %JAVA_HOME%/bin on Windows

cd $JAVA_HOME/bin on Linux

You would land up in the Java bin directory. Now time to run the keytool command. You have to provide some parameters to the command as follows :

keytool -genkey -alias techtracer -keypass ttadmin -keystore techtracer.bin -storepass ttadmin

The highlighted words are the ones which you would have to change according to your requirements. But keep one thing in mind that both the keypass and storepass passwords should be the same. The .bin file is actually your keystore file. It would now start a questionnaire. So fill in the relevant details accordingly. Look below for a reference as to what to answer for the questions.

What is your first and last name?
[Unknown]: sakthiv r
What is the name of your organizational unit?
[Unknown]: vetti
What is the name of your organization?
[Unknown]: IGS
What is the name of your City or Locality?
[Unknown]: CHN
What is the name of your State or Province?
[Unknown]: TN
What is the two-letter country code for this unit?
[Unknown]: IN
Is CN=shekhar raj, OU=home, O=techtracer, L= CHN, ST=TN, C=IN correct?
[no]: yes

The command would then conclude. It would make a .bin file with the name you had provided inside the bin directory itself. In my case it was techtracer.bin which was located in

C:\Program Files\Java\jdk1.6.0_02\bin\

Put the .bin file in the webapps directory of Tomcat. This is required to avoid the need to give an absolute path of the file in the next step.

2. Configuring Tomcat 6 for using the Keystore file

Here we would be making some changes to the server.xml file inside tomcat to tell it to use the keystore which was created in the earlier step for configuring SSL. Open the file server.xml which can be found as:

/conf/server.xml

Now you have to modify it. Find the Connector element which has port="8443″ and uncomment it if already not done. Add two lines. The highlighted lines are the newly added ones.

keystoreFile="../webapps/techtracer.bin"
keystorePass="ttadmin" />

You can notice that I have given the path to the keystoreFile property as relative to tomcat bin directory because the startup command will look for the .bin file. Now all you have to do is start your server and check the working of SSL by pointing your browser to the URL to:

https://localhost:8443/

Now that you have your tomcat running in the SSL mode you are ready to deploy an application to test its working. You must note that still your tomcat can run in normal mode too at the same time i.e on port 8080 with http. So it is but obvious that any application deployed to the server will be running on http and https at the same time. This is something that we don't want. We want our application to run only in the secured mode.

3. Configuring your web application to work with SSL

In order to do this for our test, take any application which has already been deployed successfully in Tomcat and first access it through http and https to see if it works fine. If yes, then open the web.xml of that application and just add this XML fragment before web-app ends i.e

securedapp
/*


CONFIDENTIAL

Explanation of the fragment is beyond the scope of this tutorial but all you should notice is that the /* indicates that now, any resource in your application can be accessed only with https be it Servlets or JSP's. The term CONFIDENTIAL is the term which tells the server to make the application work on SSL. If you want to turn the SSL mode for this application off then just turn don't delete the fragment. Just put the value as NONE instead of CONFIDENTIAL. That's it!

Conclusion

These were the 3 easy steps in which you can make Tomcat 6 to work in the SSL mode and also it tells you how easily you can turn the SSL mode on and off. If you find any difficulty or are not clear on any of the above steps feel free to drop in your queries. If you like this tutorial it would be nice of you to drop in a comment of appreciation or feedback as to how this tutorial can be improved.

SSL Support to Tomcat 6

I recently had an enjoyable experience trying to figure out how to configure SSL support within Tomcat. I figured it would be pretty easy, but I bumped into some troubles along the way so it ended up taking a couple hours. The key issue is that there isn't a way to use Java's keytool to import a private key for an SSL certificate. Now that I have a handle on things and SSL is working, I figured I would post a walkthrough to help anybody who may be running into the same roadblock.

My Environment

• I am currently using Apache Tomcat 6 as a stand-alone web server
• I am using Java JDK 6, Standard Edition
• My web host provides Windows Server 2003 64-bit (Getting Tomcat to run as a 64-bit Windows service is a story for another day)

If you are running in a similar hosting environment, these steps should guide you through setting up SSL.

Step 1

The first step is to get a copy of your private key and a certificate for that key. You will also need a copy of the root certificate from your CA (such as VeriSign or GeoTrust). These were provided to me in Base64 format by my web host, and you should save these all as .pem files.

• My web host first provided me with a private key. I downloaded it as a .txt file, and then proceeded to open it using notepad. The file started with
  -----BEGIN PRIVATE KEY----- and ended with
  -----END PRIVATE KEY----- with a block of text in between. Take this file and save it as private.pem (you can either just rename the file you download, or copy and past the text into a new file).
• My web host then ordered the SSL certificate for me, and a little later I was sent an e-mail containing a similar chunk of text as before. The difference was that it started with
  -----BEGIN CERTIFICATE----- and ended with
  -----END CERTIFICATE-----. Again, open notepad, paste the text, and save this file as cert.pem
• Lastly, you will need to obtain a copy of the root certificate. My SSL certificate came from GeoTrust, and after a bit of searching I found their root certificates are available from their web site. Downloaded the certificate in Base-64 encoded X.509 format and save this file as root.pem

Step 2

We now have the keys and certificates that we need to configure SSL on our server. However, we need to convert them into a format that Tomcat supports. For this, I used a free tool called OpenSSL. Among other capabilities, OpenSSL will help you convert keys between different formats, which is exactly what we're looking for. I'm lazy and didn't want to compile the source code myself, so after a bit of searching I found that Shining Light Productions provides the binaries for Windows. Download this package and use the installer to get everything setup.

Step 3

Once OpenSSL is installed, you must take the three .pem files and combine them into a single .pem file. First, open notepad and copy the contents of root.pem into the file. Next, copy the contents of cert.pem on to the next line. Last, copy the contents of private.pem at the end. The data should look something like this (with more text in between):

-----BEGIN CERTIFICATE-----
MIIDIDCCAomgAwIBAgIENd70zzANB
1voqZiegDfqnc1zqcPGUIWVEX/r87
yloqaKHee9570+sB3c4
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIDIDCCAomgAwIBAgIENd70zzANB
1voqZiegDfqnc1zqcPGUIWVEX/r87
yloqaKHee9570+sB3c4
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
MIIDIDCCAomgAwIBAgIENd70zzANB
1voqZiegDfqnc1zqcPGUIWVEX/r87
yloqaKHee9570+sB3c4
-----END PRIVATE KEY-----

Save this file as ssl.pem.

Step 4

Open up a command prompt window and navigate into the "bin" directory of your OpenSSL installation. We want to take the ssl.pem file and convert it into a PKCS12 keystore, which we will call ssl.p12. This can be accomplished by running the following command:

openssl pkcs12 -export -in ssl.pem -out ssl.p12 -name tomcat

Note: Be sure to use the correct paths for your ssl.pem and ssl.p12 files. You will be prompted to create a password for this keystore.

Step 5 (Optional)

You can verify the PKCS12 conversion worked by using Java's keytool command. First switch to the "bin" directory of your JDK and run:

keytool -v -list -keystore ssl.p12 -storetype pkcs12

Note: Be sure to use the correct path for your ssl.p12 file. You will be prompted to enter the password you created earlier. Keytool will then list out the contents of the keystore. Look towards the top of the output to ensure that the keystore type is PKCS12, that the keystore contains 1 entry, the entry type is a PrivateKeyEntry, and the certificate chain length is 2.

Keystore type: PKCS12
Keystore provider: SunJSSE

Your keystore contains 1 entry

Alias name: tomcat
Creation date: Jun 16, 2007
Entry type: PrivateKeyEntry
Certificate chain length: 2


Step 6

Now we just need to configure Tomcat's server.xml file to use this keystore. First, take the ssl.p12 file and store it on your web server. Then navigate to the "conf" folder within your Tomcat installation directory. Open the server.xml file in notepad and add the following connector:

Note: Be sure to use the correct path to your keystore and the correct password. Depending on your setup, you may need to use a different connector configuration. In particular, Tomcat needs a different setup if you are using the Tomcat Native Library. Please consult the Tomcat documentation for more details.

Step 7

Reboot the Tomcat server and try accessing your web site using https. If everything is configured correctly, you should be able to successfully view your web site without any errors or warnings.

Conclusion

Hopefully you found this walkthrough to be helpful. I am aware that most of these steps are pretty specific to my environment and how my web host provided me with my SSL certificate. However, I would think with some hacking around you can adapt these steps to suit your needs. If you run across any difficulties or these steps don't work for your situation, feel free to post a comment describing your environment and I will do my best to provide some assistance .