Monday, September 19, 2011

Enabling SSL in Apache Tomcat 6 The Easy Way

NOTE: This article does not use the APR tomcat module but rather the default Tomcat 6 deployment.

To enable SSL for Apache Tomcat 6, perform the following:

1. Create an SSL certificate using the java supplied keytool:

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA

NOTE: If you get the error:
keytool error: java.lang.Exception: Key pair not generated, alias <tomcat> already exists
Then most probably you have a key file already in your user directory. If you are root, this will be /root/.keystore

2. You will be requested for data that will show on your user browser's certificate, fill them all in.
Notice that the bold font is my input. No problem if you stick to the password "changeit" as it is the default password used by tomcat.

Enter keystore password: changeit
Re-enter new password: changeit
What is your first and last name: Jeremy Atkins
What is your organizational unit: OU
What is the name of your organization: NOYO
What is the name of your city or your locality: MyCity
What is the name of your state or province: Saudi Arabia
What is the two-letter country code for this unit:  uk
Is the entered data correct: yes

Enter key password for <tomcat>
        (RETURN if same as keystore password): PRESS RETURN KEY

It is important to have the keystore password and the key password the same. This is done by pressing the RETURN KEY in the last step. This is necessary since Tomcat doesn't support having different passwords in the keystore and key.

3. When you're done with the previous step, a keystore file gets created in the user directory named keystore. Since I'm the root user, I will find it in /root/.keystore.
Check that the file /root/.keystore got created.

4. Next, open the tomcat server.xml for editing:
vi ${tomcat_installation_dir}/conf/server.xml

And uncomment the following section by removing the <!-- and the --> surrounding them from top and bottom:

   <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
               maxThreads="150" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS"
               />

5. Change the port number from 8443 to 443 which is the default SSL port known to all browsers.
Switch to 8443 while in development if needed.

   <Connector port="443" protocol="HTTP/1.1" SSLEnabled="true"
               maxThreads="150" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS"
               />


6. Now add the following line in between to tell tomcat where to locate the keystore and specify the password you specified:

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
   maxThreads="150" scheme="https" secure="true"
   clientAuth="false" sslProtocol="TLS"
   keystoreFile="${user.home}/.keystore" keystorePass="changeit"
               />

Tomcat will automatically replace ${user.home} with the path of the home directory for the user tomcat is running under. Which in my case is "/root"

7. Restart apache tomcat using:
<tomcat_installation_dir>/bin/catalina.sh stop
<tomcat_installation_dir>/bin/catalina.sh start


No comments: