How to enable SSL in Tomcat

In this tutorial, we will learn how to configure and enable SSL support at port 8443 by a Tomcat sever.

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. In Tomcat, this key pair is stored in a "keystore" file, which is an encrypted and password protected file. You can do this using the keytool command in Java like the following:

cs144@class-vm:~$ sudo keytool -genkey -alias cs144.tomcat -keyalg RSA -keystore /etc/tomcat7/ssl.keystore

The above command will try to create a private/public keypair named "cs144.tomcat", and store them in the keystore file /etc/tomcat7/ssl.keystore. When you execute the above command, it will prompt you with a number of questions. We show example answers to the questions here:

Enter keystore password:  mylittlesecret
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 <cs144.tomcat>
	(RETURN if same as keystore password):

For all questions, you can provide any answer of your choosing, except "your first and last name". This has to be the fully qualified host name of your Tomcat server, which is "localhost" in our case.

Once it finishes, keytool will create a keystore file /etc/tomcat7/ssl.keystore and store a newly-generated a public and private key pair there. Make sure that the file /etc/tomcat7/ssl.keystore has been generated.

NOTE: 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". This type of certificate is referred to as a "self-signed certificate". When web browsers see a self-signed certificate, they will complain that they cannot "trust" it, because it has not been signed by one of their trusted CAs.

2. Enable SSL in Tomcat

Now that your key pair is ready, the final step is to change your /etc/tomcat7/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 -->
         This connector uses the JSSE configuration, when using APR, the
         connector should be using the OpenSSL style configuration
         described in the APR documentation -->
    <!--
    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
        maxThreads="150" scheme="https" secure="true"
        clientAuth="false" sslProtocol="TLS" /> 
    -->

Remove the comment around <Connector> element (highlighted as red) and add the following two attributes to the Connector element to indicate the location and the password of the keystore:

        keystoreFile="/etc/tomcat7/ssl.keystore" keystorePass="mylittlesecret"

(If you used a different password from "mylittlesecret" when you created the keystore, please replace it with your own password.) Since the server.xml file is owned by root, you need to edit the file with the root permission, such as:

cs144@class-vm:~$ sudo nano /etc/tomcat7/server.xml

3. Restart your tomcat

Now that everything is ready, you need to restart your Tomcat server.

cs144@class-vm:~$ sudo /etc/init.d/tomcat7 restart

4. Test your https

The port 8443 on your VM is redirected to the same port 8443 on your host machine, so you can open url https://localhost:8443/ using a browser on your host machine. This will establish an HTTPS connection between your browser and the Tomcat server. 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 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.

For the purpose of this project, threfore, we ignore this warning and proceed to our next step. In practice, however, most users will be turned away by a warning message like this, being too scared of what they see, so you will have to obtain a certificate signed by one of the trusted CAs.