How to enable SSL in TOMCAT 6

How to enable SSL in TOMCAT 6

Last Modified: 02/26/2009

---

To install and configure SSL support on Tomcat 6, you need to follow these simple steps.

0. Download a default keystore

The "keytool" command is a Key and Certificate Management Tool provided by Java. You can use keytool command to generate public/private key pair or use it to import a public key from a third party. The keystore is essentialy a "encrypted" and passowrd protected file residing in your home directory (/home/cs144). First download the deafult keystore file and unzip it to your home directory.

/* Download the keystore file */
cs144@cs144:~$ wget http://oak.cs.ucla.edu/cs144/projects/project5/vm_keystore.zip

/* Unzip the keystore file into you home directory */
cs144@cs144:~$ unzip vm_keystore.zip -d ~/

When you unzip the file, the keystore file named ".keystore" will be added to your home directory (this is a hidden file that is listed only when you use "ls -a" command). The keystore file is protected by the default password "changeit".

1. Generate a private/public key pair

In order to activate the HTTPS protocol of Tomcat, you first need create a public and private key pair to be used for encryption. You can use keytool command to generate a key pair. The following sequence of commands show you how to do it:

cs144@cs144:~$ keytool -genkey -alias tomcat -keyalg RSA

Enter keystore password:  changeit
What is your first and last name?
  [Unknown]:  localhost
What is the name of your organizational unit?
  [Unknown]:  cs144
What is the name of your organization?
  [Unknown]:  UCLA
What is the name of your City or Locality?
  [Unknown]:  Los Angeles
What is the name of your State or Province?
  [Unknown]:  California
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=localhost, OU=cs144, O=UCLA, L=Los Angeles, ST=California, C=US correct?
  [no]:  yes

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

NOTE:

• Type password for keystore, which is "changeit".
• [firstname and lastname] give the fully qualified host name. In this project, you will have to use localhost becuase this is the machine name that you use to access the Tomcat server from the VM.
• You need type some information about your organization, location, etc. (You can make it up as you like)

When you execute the above command, keytool will generate a public key and private key pair and store it to your keystore file. More precisely, the generated public key is stored in the form of certificate. A certificate is nothing more than a statement like "the name of this host is localhost and its public key is XX:XX:...:XX:XX. This certificate is valid from XX/XX/XX until XX/XX/XX". All certificates need to be signed by a certificate authority (CA), but since you have not asked any third party CA to sign your certificate, it has been signed "by itself" at this point. This type of certificate is often referred to as a "self-signed certificate".

2. Enable SSL in TOMCAT 6

Now that your key pair is ready, the final step is to change your $CATALINA_HOME/conf/server.xml file to enable the SSL connection, An example <Connector> element for an SSL connector is already included in the default server.xml file, which looks something like this:

    <!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
    <!--
    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
        maxThreads="150" scheme="https" secure="true"
        clientAuth="false" sslProtocol="TLS" /> 
    -->

Remove the comment around <Connector> node. (Red code) to enable SSL.

3. Restart your tomcat

Now that everything is ready, you need to restart your Tomcat server. Stop:
> $CATALINA_HOME/bin/catalina.sh stop
Start:
> $CATALINA_HOME/bin/catalina.sh start

4. Test your https

Use Firefox to open url "https://localhost:8443/" which tries to establish an HTTPS connection to the Tomcat server through the port number 8443.
You shall see something similar to the following screen:


Note that the Firefox reports that the secure connection has failed because localhost is using "invalid" certificate. This is because the certificate of your tomcat server (that was generated by keytool in an earlier step) has not been signed by one of the CAs trusted by Firefox. Since Firefox cannot verify the authenticity of the certificate, it cannot trust any statement in the certificate and cannot be really sure that it is really talking to "localhost". You can simply ignore this warning and proceed by adding a "security exception". Ignoring this warning is OK if all you care about is the secure communication between your browser and the Web site, not the authenticity of the site. Even though the certificate has not been signed by a trusted CA, it still contains a public key of the site that the browser is currently communicating with, so the browser can use this public key to encrypt any message that it sends to the site for confidentiality. In most cases, however, users will be turned away by a warning message like this, being too scared of what they see. Now let us get your certificate to be signed by one of the trusted CA to avoid this warning.

5. Install a trusted certificate

The first step to obtaining a trusted certificate (your certificate signed by one of the trusted CA) is to create the "certificate signing request".

Create a certificate signing request

> keytool -certreq -keyalg RSA -alias tomcat -file certreq.txt

If you run the above command, you will see that a request file, named certreq.txt, is generated in your current directory. A request file is nothing more than your public key together with some information about your site (like the fully qualified name of your site and other information that you provided when you created your public key/private key pair).

Obtain a trusted certificate

In real world, you will have to send the certificate signing request to one of the real trusted CA. Once a CA receives a signing request, the CA uses a number of different mechanisms to ensure that the request really came from the authentic owner of the site (like calling the company over the phone, asking the requester for an government-issued document, etc.) Only when the CA is confident that the request really came from the owner of the site, it signs the certificate for your site with the its own private key and return the certificate back to the requester. All broswers come with a default list of the trusted CAs and their public keys, so when a browser sees a certificate signed by the private key of one of the trusted CAs, it can safely assume that the statements in the certificate have been validated and are trustable. The Firefox browser in our VM, fortunately, has "oak.cs.ucla.edu" as one of the trusted CAs, so you do not really have to go through all the hassle and the expense of getting your certificate signed by a trusted CA. All you have to do is to upload your request to http://oak.cs.ucla.edu/cs144/projects/project5/cert/, and get it signed by oak.cs.ucla.edu. After uploading your request file certreq.txt through the above page, download the generated certificate file and save it inside your VM.

Install the certificate for tomcat

Now that you have a trusted certificate, import it to your keystore, so that your Tomcat server can use it. > keytool -import -alias tomcat -file <downloaded, signed cert file>

6. Restart your tomcat

Now everything is ready. As the final step, restart your Tomcat server. Stop:

> $CATALINA_HOME/bin/catalina.sh stop

Start:

> $CATALINA_HOME/bin/catalina.sh start

7. Test your https again

Use Firefox to open url "https://localhost:8443/".
If you can successfully open the page, you are done.

---

Reference: http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html
http://oak.cs.ucla.edu/cs144/projects/project5/ssl_tomcat_tutorial.html