Configuring Tomcat 7 to support SSL

Foreword

• This post talks about how to get SSL up and running with Tomcat 7, this means you'll be able to accept https/secure connections to your websites, this is especially relevant as Facebook now require all canvas apps to support https. 
• I'm assuming that you're using Tomcat as your client-facing server as described in my previous post, i.e. it isn't proxied behind Apache httpd.
• While I specifically target Tomcat 7, much of this post is relevant to all prior Tomcat versions.
• Many of the required processes are well documented on the web, rather than reproduce content instead I'll point you to the best resources I know.

Acquiring an SSL Certificate
When establishing an https connection the server will present the client/browser with an ssl certificate to aid the client in knowing whether to accept the ssl connection. In setting up SSL for Tomcat you'll need such a certificate. There are 2 ways:

1) Make your own certificate.
In this scenario you generate your private key and sign your own certificate. There are several tools to help you do this including keytool for Java , openssl on linux and Key-Manager on windows.
It's useful to sign your own cert if you are only worried about establishing data encryption on your private sites but it isn't too much use for hosting customer facing sites as your customers will get a scary browser warning that will probably scare them off for good. For this reason I won't dwell on this any further.

2) Buy a signed certificate
There's a huge variation in pricing and offerings, if you just want the padlock symbol on your site you can buy the cheapest offering from a company such as Comodo InstantSSL, they also offer a 90 day trial which is longer than the most free trials.

You'll need to create a private key which will be used to generate a Certificate Signing Request (CSR).
You send this CSR to your chosen certificate vendor, they'll review it and send you back a certificate you can use. Once again there are several alternative tools to help:

• To use openssl follow the procedure described here. This article covers generating a new private key AND CSR. If you already have an exiting private key you can just generate a new CSR with the command:  openssl req -out www_mydomain.csr -key myserver.key -new
• To use java keytool follow the procedure described here.

You may also want to convert your private key to pem format for use later, you can do this with openssl like this: 

openssl rsa -in myserver.key -out myserver.pem

Once you have received the signed certificate back from your vendor, your ready to install if to Tomcat (or Apache)

Configuring Tomcat for SSL
It's time to install our new ssl cert into tomcat. Life is never easy with Tomcat and here is no exception, it supports SSL in one of 2 ways and will select the most appropriate based on your operating system. Briefly these are:
1) Using a keystore file capable of containing many certificates and keys. Certificates are referenced by an alias name. Java JSSE is used here and thus is platform independent, but slower than method 2.
2) Using APR (Apache Runtime Library) that can access certificates and keys directly as files thus bypassing the keystore mechanism of method 1.

I recommend method 2, APR brings benefits to your entire tomcat distribution including native SSL handling and speed improvements, also you won't have to use the keytool command to insert certs into the keystore!
The downside is the APR can be troublesome to install:
Here's the official APR howto.
Here's how I do it:

cd $CATALINA_HOME/bin

tar xvfz tomcat-native.tar.gz
cd tomcat-native-<version>-src/jni/native

yum install apr openssl apr-devel openssl-devel

./configure --with-apr=/usr/bin/apr-1-config
make
make install
Note that it's very important to have the ssl packages installed by yum (as above) before you make APR, without them apr will still build but without SSL support and you'll get browser errors later. If you do this correctly apr will install to /usr/local/apr/lib

If you have followed my previous post on running tomcat using jsvc then you can benefit from switching the secure port to 443, you'll also need to insert the line:

export LD_LIBRARY_PATH="/usr/local/apr/lib"

at the top of your /etc/init.d/tomcat7 file, this ensures the APR library can be found by Tomcat.



Now we need to modify the $CATALINA_HOME/conf/server.xml file.
In server.xml locate the connector with port=8443 and uncomment it. You will need to add additional attributes to make it work. Unfortunately the attributes you use in configuring this vary depending on whether you're using method 1 or 2 I outline above.
With method 1 you reference the keystore, with method 2 you reference the certificates and key file directly. Here's a link to the supported attributes for each method.
As I'm advocating method 2, here's what it will look like:

    <Connector port="443" protocol="HTTP/1.1" SSLEnabled="true"
               maxThreads="150" scheme="https" secure="true"
               SSLCertificateFile="/home/tomcat/ssl/www_yourdomain_com.crt"
               SSLCertificateKeyFile="/home/tomcat/ssl/myserver.pem"
               SSLCertificateChainFile="/home/tomcat/ssl/www_yourdomain_com.ca-bundle"
               clientAuth="false" sslProtocol="TLS" />

Where:
SSLCertificateFile and SSLCertificateChainFile were provided by your signing authority.
and SSLCertificateKeyFile is your private key (don't share this with anyone)


Save the server.xml file and start tomcat.

When starting tomcat you can determine whether it has loaded APR successfully by looking at the start of the $CATALINA_HOME/logs/catalina.<date>.log file.

It will either contain something like:

INFO: The APR based Apache Tomcat Native library which allows optimal performance in production environments was not found on the java.library.path: /usr/java/latest/jre..etc

or
INFO: Loaded APR based Apache Tomcat Native library 1.1.22.
or
a bunch of errors saying why it didn't work out.



You should now be able to hit your site securely https://www.yoursite.com :-)


Conclusion
If you've followed my recommendations you'll have a best of breed tomcat install running SLL natively fast for not much financial outlay. It's overly complex though, but I'm afraid there's no easy way when talking SSL.