Setting up two-way (mutual) SSL with Tomcat on Java5 is easy!

I recently wanted to set up Tomcat for two-way (mutual) SSL. It turns out this is fairly easy, particularly with Java5 since it now provides writes, and not just reads, of PKCS#12 keystores directly, so you don't actually need to use openssl anymore, as most of the instructions I found online about this suggest. I needed this for a test of something, and wasn't interested in using a Certificate Authority (CA) etc. All I wanted was an easy set up with Tomcat (v5.5.15/17 used) for testing; other people were going to worry about CA and issuing procedures and all later. Here is how:

1) Create the key & cert for the Tomcat server:

%JAVA_HOME%\bin\keytool -genkey -v -alias tomcat -keyalg RSA -validity 3650 -keystore /path/to/my/tomcat.keystore -dname "CN=localhost, OU=MYOU, O=MYORG, L=MYCITY, ST=MYSTATE, C=MY" -storepass=password -keypass=password

Note that the storepass and keypass *HAS* to be the same here. The CN should be the host/machine name that will appear in the HTTPS URL when accessing this Tomcat, so e.g. localhost, or also *.domain.com I believe.

2) Enable the SSL connector in Tomcat's conf/server.xml:

<connector port="8443" maxhttpheadersize="8192" maxthreads="150" minsparethreads="25" maxsparethreads="75" enablelookups="false" disableuploadtimeout="true" acceptcount="100" scheme="https" secure="true" sslprotocol="TLS" clientauth="true" keystorefile="path/to/my/tomcat.keystore" keystorepass="password" truststorefile="path/to/my/tomcat.keystore" truststorepass="password">

In keystoreFile you can specify an absolute pathname, or a relative pathname that is resolved against the Tomcat root installation directory. You also have to specify the truststore. (The stores don't have to be in a user home directory.)

If all you wanted is well-known one-way SSL with no client certificate, you would have to change the above to clientAuth="false" and stop here, else do as above and keep reading for the interesting part.

3) Create the client (yours, or a machine's) key & cert:

keytool -genkey -v -alias vorburgerKey -keyalg RSA -storetype PKCS12 -keystore vorburger.p12 -dname "CN=Michael Vorburger NEU, OU=DerTest, O=DieOrg, L=Lausanne, ST=VD, C=CH" -storepass mypassword -keypass mypassword

This looks and is similar to 1) above, but we are storing this into a different keystore (because the server/Tomcat doesn't have your private key) of storetype PKCS12. On Windows, you can double-click and import this *.p12 file into IE, or add it to Firefox via Tools / Options, Security, Certificates, View Certificates, Import. You'll have to type in the mypassword (above). BTW, again the storepass and keypass *HAS* to be the same here, else Windows/IE or Mozilla Certificate importing will fail.

4) Now we need to add the certificate (containing the public key) to the Tomcat keystore so that it recognizes this client certificate, by first exporting it from the keystore from step 3 and then importing it into the keystore from step 1: (Typically you probably would not import each client cert but a CA root cert and then sign each client cert with that one, but as said, I am showing a simple setup for tests here.)

keytool -export -alias vorburgerCert -keystore vorburger.p12 -storetype PKCS12 -storepass mypassword -rfc -file vorburger.cer

keytool -import -v -file vorburger.cer -keystore tomcat.keystore -storepass password

On Windows, you can double-click and see the vorburger.cer. You may also would like to list the contents of the tomcat.keystore via this command, and notice how the entry for the 'tomcat' alias is a keyEntry, but the entry for the 'vorburgerCert' is a trustedCertEntry here - makes sense?

keytool -list -keystore ..\tomcat-server.keystore -storepass password

5) Just like with BASIC authentication, you still have to add this user to the usual conf/tomcat-users.xml, by specifying that dname from step 3) as username, and any password (will be ignored) and the roles you'd like that user to have:

<user username="CN=Michael Vorburger NEU, OU=DerTest, O=DieOrg, L=Lausanne, ST=VD, C=CH" password="null" roles="admin">

That's it! You should now be able to access e.g. https://localhost:8443, the browser should ask you for, or automatically send, the client certificate which the server used to 'strongly' authenticate you - done!

Some instructions also suggest to set <login-config><auth-method>CLIENT-CERT</auth-method> in web.xml, but apparently that's not actually needed on Tomcat with clientAuth="true" in server.xml.

Some notes for testing/debugging/trying that may be useful if you would like to try this too: IE just says "Cannot find server" if the server does not accept the client cert - not very helpful! Firefox says "Could not establish an encrypted connection because your certificate was rejected by localhost.", better. Also, if for test you remove a cert from IE again, you have to close it, all windows, shut it down - else it's still in memory although it does not appear in respective dialog anymore.


PS: Some copy/pasted background information that may be of interest... "The PKCS#12 (Personal Information Exchange Syntax Standard, specifies a portable format for storage and/or transport of a user's private keys, certificates, miscellaneous secrets, and other items. The SunJSSE provider supplies a complete implementation of the PKCS12 java.security.KeyStore format for reading and write pkcs12 files. This format is also supported by other toolkits and applications for importing and exporting keys and certificates, such as Netscape/Mozilla, Microsoft's Internet Explorer, and OpenSSL. For example, these implementations can export client certificates and keys into a file using the ".p12" filename extension.

J2SE 1.4.x provided read-only support for PKCS#12 keystores, and a small number of protection algorithms. The enhanced PKCS#12 keystore in J2SE 5 supports reads and writes of PKCS#12 keystores, and provides more protection algorithms (such as those supported by popular browsers). This improves interoperability of PKCS#12 keystores imported/exported by J2SE, browsers, and other security applications."