SSL, tomcat and self signed certificates

I have been through the process of getting an application to work via https before but I have always muddled through and never documented exactly what I have done.

I must also admit that I never quite understood exactly what I had done and why.

One problem is that I can not find one place that covers everything you need in one place.

Now I think I am pretty well there.

This post describes what I have done to get a simple client application working using HTTPS posting to tomcat server and using a self signed certificate with the help of several refereneces in particular:

1. How to create a self signed certificate
2. Tomcat SSL Configuration How-To
3. Developing Web Services with Apache Axis by Tong Ka Iok, Kent ISBN 1-4116-7032-9

The last reference has a chapter which is pretty well SSL for dummies and explains things very nicely.

The steps that need to be done are:

1. Create a self signed certificate authority (CA)
2. Sign a test key via the CA
3. Add both these keys to a keystore
4. Setup the application (client) and tomcat (the server) to use this keystore.

1) Create a self signed certificate authority (CA) and keystore

This is described in How to create a self signed certificate, but I will show the steps here

What is happening here:

you will create a CA that later will be added to your keystore file. By adding this CA to your keystore you are saying it is trusted like verisign and any certificates signed by it are then also trusted.

1.1) make a directory to hold the certs and keystore. This might be something like:

C:\ssl

1.2) generate a private key for the server

openssl genrsa -des3 -out server.key 1024

1.3) generate a CSR (Certificate Signing Request)

openssl req -new -key server.key -out server.csr

1.4) Remove the passphrasse from the key

cp server.key server.key.org

openssl rsa -in server.key.org -out server.key

1.5) Generate the self signed certificate

openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

2) Create a certificate for tomcat and add both to the keystore

2.1) cd to where the keystore is held. This might be something like:

C:\ssl

2.2) Create a keypair for 'tomcat'

keytool -genkey -alias tomcat  -keyalg RSA -keystore tomcat.ks

2.3) Generate a CSR (Certificate Signing Request) for tomcat

keytool -keystore tomcat.ks -alias tomcat -certreq -file tomcat.csr

2.4) create unique serial number

echo 02 > serial.txt

2.5) Sign the tomcat CSR

openssl x509 -CA server.crt -CAkey server.key -CAserial serial.txt -req -in tomcat.csr -out tomcat.cer -days 365

2.6) Import the server CA certificate into the keystore

keytool -import -alias serverCA -file server.crt -keystore tomcat.ks

2.7) add the tomcat certificate to the keystore

keytool -import -alias tomcat -file tomcat.cer -keystore tomcat.ks

3) Tomcat configuration

3.1) Tomcat needs to be configured to use SSL

This is described in more detail at Tomcat SSL Configuration How-To

However all that is needed here is to edit the server.xml to enable SSL

This section is already in the server.xml but commented out.

NB that the location of the keystore has been added.

<!-- 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"

keystoreFile="C:\ssl\tomcat.ks"

keystorePass="changeit"

clientAuth="false" sslProtocol="TLS" />

3.2) test tomcat

start tomcat and go to https://localhost:8443/

your browser will return an error such as "sites certificate is not trusted"

3.3) import the CA certificate server.crt into your browser's tructed root certificates

3.4) test again at https://localhost:8443/

this time you should see the tomcat home page

4) Test your application

4.1) I have a unit test run from eclipse that I have been using to post off to my test server. This produces the error;

Caused by: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

at sun.security.provider.certpath.SunCertPathBuilder.engineBuild(SunCertPathBuilder.java:174)

at java.security.cert.CertPathBuilder.build(CertPathBuilder.java:238)

at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:289)

4.2) The reason for this is that eclipse is not referring to the keystore that we have created. At the time of writing I have not sussed out how to make eclipse use this - Do you know ?

So instead I have added the same two certs to javas keystore

4.3) cd to the directory where java's keystore is held. This might be something like:

C:\java\jdk1.6.0_18\jre\lib\security

4.4) the keystore is a file called cacerts

4.5) copy the files c:\ssl\server.crt and c:\ssl\tomcat.cer to this directory

4.6) import the server CA into the java keystore

keytool -import -alias serverCA -file server.crt -keystore cacerts

4.7 import tomcats cert into the java keystore

keytool -import -alias tomcat -file tomcat.cer -keystore cacerts

5) Test your app again.

Hopefully all will be hunkdory. Enjoy.

6) Caveats:

6.1) the passwords for all keystores and certs are 'changeit'. this is the default keystore password

and I suggest you change this for a production system

6.2) Using a self signed cert is great for a test environment of for a private system but not for a commercial released application. For this you will need to get & pay for a signed certificate from an approved authority such as Verisign.