Tomcat with SSL

I have been tackling some server issues lately, trying to get Tomcat to play nicely with SSL and get everything locked down. And since there seems to be a lack of useful tutorials out there (at least nothing I could find) I made my own little how-to. If you have any questions just ask away in the comments!

What you need:

• Apache Tomcat
• The OpenSSL toolset which comes installed with Linux (this guide was done with CentOS, but should be applicable to other distributions)
• An account with startssl.com (or other certificate signing authority)

Summary:

This post will go through the various steps required to set up Tomcat with SSL. At the time of writing StartSSL were still offering free signed certificates.

1. Getting your ceritificate

I am going to assume that you have already got yourself an account with a certificate signing authority. Most of these services provide documentation on how you can get your very own certificate, but for the sake of thoroughness I will outline the steps I followed to get my certificate:

1. Run the following command on your server(where [server] should be changed into something unique for you)

openssl req -new -newkey rsa:2048 -nodes -keyout [server].key -out [server].csr


2. The system will now ask you a bunch of questions such as location, emails and passwords. Answer appropriately for your system.


3. Log-in to http://www.startssl.com/ (or whatever certificate signing authority you have chosen)


4. Select the option to upload your own cetificate signing request file (you don't need them to generate another key for you; step 1 already created that for us)


5. Once you uploaded the contents of the *.csr file, you should receive an encoded public certificate file (*.crt). It should also give you the root and intermediate certificates of the servers used to sign those certificates.


6. Save all files in a safe place (something with decent file permissions so that the files cannot be tampered with). For the rest of this guide we are going to assume /etc/pki/tls/certs/.

2. Configuring TomCat

1.  If your certificate authority has not already done so, create a chain file of the signing server's certificates:
   
   cat [cert1].pem [cert2]/pem > chain.pem
   


2. We need to put all out certificates into a keystore file, so that Tomcat only has to load up one object (not multiple files)

openssl pkcs12 -export -in [server].crt -inkey [server].key -out [server].p12 -name tomcat -CAfile chain.pem -chain

3. The final step is to let Tomcat know the existence of the keystore file. Edit the server.xml file (in CentOS it is /etc/tomcat5/server.xml) as follows:
   
   <!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
<Connector port="8443" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" algorithm="SunX509" keystoreType="PKCS12" keystoreFile="/etc/pki/tls/certs/server.p12" keystorePass="abc123" enableLookups="false" disableUploadTimeout="true acceptCount="100" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" />
   
   NOTE: The lines algorithm="..." and keystoreType="..." are crucial! This is where most of my headaches lay; apparently Tomcat couldn't auto-detect the algorithm and so HTTPS just didn't work.

References:

• Ars Technica guide to getting a free SSL certificate
• GoDaddy help article for generating certificates
• Mulesoft guide to configuring Tomcat with SSL
• Digicert guide to configuring Tomcat with SSL
• Ashraf Hossain's guide to redirecting all HTTP requests to HTTPS