Global Open Versity, Vancouver Canada Configuring Tomcat to Support SSL

HowTo Generate and Install SSL on Tomcat AS on Windows

By Kefa Rabah, krabah@globalopenversity.org April 10, 2009 SerengetiSys Labs

GENERAL
Secure connection can be provided through https protocol with secure certificate.

INTRODUCTION TO SSL
SSL, or Secure Sockets Layer, is a technology which allows web browsers and web servers to
communicate over a secured connection. This means that the data being sent is encrypted by one
side, transmitted, then decrypted by the other side prior to any processing. This is a two-way
process, meaning that both the server and the browser encrypt all traffic before sending out data.

Another important aspect of the SSL protocol is Authentication. This means that during your
initial attempt to communicate with a web server over a secure connection, that server will
present your web browser with a set of credentials, in the form of a Certificate, as proof that the
site is who and what it claims to be. In certain cases, the server may also request a certificate
from your web browser, asking for proof that you are who you claim to be. This is known as
Client Authentication, although in practice it is used primarily for business-to-business (B2B)
transactions rather than with typical site users. Most SSL-enabled web servers do not request
Client Authentication.

CONFIGURING TOMCAT TO SUPPORT SSL

1. Self-generated and self-signed certificates. The service provider using Tomcat Server can
create self-signed certificate using JAVA tools (keytool.exe program). In this case the
issuer of the certificate must be added to the list of trusted authorities on the server, and on
every client during the first use. This has to be done using an Internet Browser.

2. Certificate from a known authority (Comodo, Verisign, Thawte, etc.). Using this kind of
certificate does not require adding it to the list of trusted authorities.

SELF-SIGNED CERTIFICATE

1. JDK6 Setup and Configuration HowTo

The self-signed certificate can be issued using keytool.exe utility in JAVA. The utility resides in
%JAVA_HOME%\bin folder, and can be called with a number of keys depending on the task
performed.

When you have decided which JDK you are going to use under Windows 2k/XP/2k3/Vista/2k8,
then in a command-line (CMD) window type:

set JAVA_HOME=c:\jdk1.6.0_13
set JAVA_HOME=c:\Program Files\Java\jdk1.6.0_13

as appropriate.
1
© April 2007, Kefa Rabah, Global Open Versity, Vancouver Canada

www.globalopenversity.org A GOV Open Knowledge License Technical Publication

Global Open Versity, Vancouver Canada Configuring Tomcat to Support SSL

To verify that path is set correctly, do the following:

C:\>echo %JAVA_HOME%
C:\Program Files\Java\jdk1.6.0_13

To change to the %JAVA_HOME%\bin directory, from CMD, type:

C:\>cd %JAVA_HOME%\bin

2. SSL CONFIGURATION HOWTO

To install and configure SSL support on Tomcat 5, you need to follow these simple steps.

i) Creating the Public Key Certificate

To create public key containing self-signed certificate keystore the following command has to be
executed:

%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA

Which will store the key in the default directory. Alternatively, you can specify the location of
the keystore, as follows:

%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA

–keystore <path to the key>

%JAVA_HOME%\bin>keytool -genkey -alias tomcat -keyalg RSA

-keystore C:\mykeystore\mykey.keystore

And specify a password value of "changeit".

Follow the instructions. First and last name should be the exact site FQDN (e.g.,
www.example.com), localhost or IP address that you will use in Browser or an application to
connect to the Server.

Here is the complete setup sequence:

%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
Enter keystore password: "changeit"
Re-enter new password:
What is your first and last name?
[Unknown]: localhost
What is the name of your organizational unit?
[Unknown]: IT
What is the name of your organization?
[Unknown]: RS Inc.
What is the name of your City or Locality?
[Unknown]: Van
What is the name of your State or Province?
[Unknown]: BC
What is the two-letter country code for this unit?
[Unknown]: CA
Is CN=localhost, OU=IT, O=RS Inc., L=Van, ST=BC, C=CA correct?
[no]: y
Enter key password for <tomcat>
(RETURN if same as keystore password): "RETURN"
2
© April 2007, Kefa Rabah, Global Open Versity, Vancouver Canada

www.globalopenversity.org A GOV Open Knowledge License Technical Publication

Global Open Versity, Vancouver Canada Configuring Tomcat to Support SSL

Stop and start the tomcat server – for the above changes to take effect.

Note: The RSA algorithm should be preferred as a secure algorithm, and also to ensure general
compatibility with other servers and components such as Netscape and IIS.

ii) Importing the Public Key Certificate

To import your self-signed certificate to the list of trusted authorities it is necessary to export the
certificate out of the keystore that’ been previously created as follows.
%JAVA_HOME%\bin\keytool -export -alias tomcat -keystore
<path to the key> –file <desired certificate name>

After the certificate has been exported you can open your browser. Go to: Tools\Internet
Options\Content\Certificates\Trusted Root Certification Authorities.

Click Import and point to your certificate file when prompted.

3. CERTIFICATE ISSUED BY A KNOWN AUTHORITY

Using keytool.exe program creates a keystore for the certificate. See above.

i) Generate certificate request as follows:

%JAVA_HOME%\bin\keytool -certreq -keyalg RSA -alias tomcat

-file certreq.csr -keystore <path to the key>

Now you have a file called certreq.csr that you can submit to the Certificate Authority (look at
the documentation of the Certificate Authority website on how to do this). In return you get a
Certificate or a number of Certificates.

ii) Now you have to import those certificates into a keystore file that you have previously
created.
%JAVA_HOME%\bin\keytool -import -alias root -keystore <path to the key>
-trustcacerts -file <filename_of_the_chain_certificate>

And finally import your new Certificate

%JAVA_HOME%\bin\keytool -import -alias tomcat -keystore <path to the key>

-trustcacerts -file <your_certificate_filename>

4. CONFIGURE THE SSL CONNECTOR IN SERVER.XML

Uncomment the "SSL HTTP/1.1 Connector" entry in $CATALINA_HOME/conf/server.xml and
tweak as necessary.

3
© April 2007, Kefa Rabah, Global Open Versity, Vancouver Canada

www.globalopenversity.org A GOV Open Knowledge License Technical Publication

Global Open Versity, Vancouver Canada Configuring Tomcat to Support SSL

After this an SSL connector has to be enabled in Tomcat at $CATALINA_HOME/conf/server.xml

<-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<!--
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
minProcessors="5" maxProcessors="75"
disableUploadTimeout="true"
maxThreads="150" scheme="https" secure="true"
enableLookups="true" acceptCount="10" debug="0"
clientAuth="want" sslprotocol="TLS"
keystoreFile=<path to the key>
keystorePass=<your password>/>
-->

Note: ClientAuth value can be set as follows:

i) To false (by default) if you do not want Tomcat to require any client to require secure
SSL connections.
ii) To true if you want Tomcat to require all SSL clients to present a client Certificate in
order to use this socket.
iii) To want if you want Tomcat to request a client Certificate, but not fail if one isn't
presented.

5. STOP & START THE TOMCAT SERVER AND TEST HTTPS

After completing these configuration changes you must restart Tomcat and try to connect
securely via SSL from Browser using the following URL:

https://localhost:8443
or

https://www.your-domain.com:8443

If all goes well you will be asked if you want to proceed using the Security Certificate. Click Yes,
and you should be in business, and you should see the usual Tomcat splash page. Henceforth, you
should be able to access any web application supported by Tomcat via SSL.

If this does not work, the following section contains some troubleshooting tips

NOTE: If you’re behind a router don’t forget to open its port to 8443 (or 433)!

Test MS SQL 2k5 Secure Connectivity

REFERENCE:
1. Critical Steps to Secure Tomcat on Windows NT-2K-XP:
http://www.developer.com/java/ent/article.php/2241061
2. The Apache Tomcat 5_5 Servlet-JSP Container - SSL Configuration HOW-TO:
http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html

4
© April 2007, Kefa Rabah, Global Open Versity, Vancouver Canada

www.globalopenversity.org A GOV Open Knowledge License Technical Publication

Global Open Versity, Vancouver Canada Configuring Tomcat to Support SSL

3. Custom SSL for advanced JSSE developers:

http://www.ibm.com/developerworks/java/library/j-customssl/
4. SSL Certificate Installation - Tomcat Servers: http://www.digicert.com/ssl-certificate-
installation-tomcat.htm
5. Tomcat and SSL – Creating Keys & Setup - Excellent:
http://www.apachefrance.com/Manuels/Tomcat_3.0/tomcat-ssl-howto.html
6. Nabble - Tomcat - User - Tomcat 5_5_26 SSL Issue - Windows 2003 - Excellent:
http://www.nabble.com/Tomcat-5.5.26-SSL-Issue---Windows-2003-td16728994.html
7. ManageEngine Discussions How to install a private SSL certificate – Win2k3 CA:
http://forums.manageengine.com/viewtopic.php?t=710121
8. Force users to use SSL for a specific dir – httpd.conf https configuration:
http://www.webmasterworld.com/apache/3596252.htm
9. Configuring Tomcat to Support SSL on Win2k3 with Tomcat – MircWiki:
http://mircwiki.rsna.org/index.php?title=Configuring_Tomcat_to_Support_SSL
10. How To Generate and Install SSL CSR in JBoss Webserver Windows Wowtutorial:
http://wowtutorial.org/en/tutorial/39.html
11. mod_ssl and OpenSSL – Excellent Win2k3 Apache httpd Setup: http://www.jm-
solutions.com/OpenSSL/Introduction/introduction.php
12. DraftIdPTomcatTestShibCookbook - Shibboleth 2 Documentation - Internet2 Wiki:
https://spaces.internet2.edu/display/SHIB2/DraftIdPTomcatTestShibCookbook
13. Using JDK within Computer Science – Set JAVA_HOME:
http://intranet.cs.man.ac.uk/software/java/using-jdk.html
14. Apache + Tomcat HOWTO - Windows 2k/XP/2k3/Vista/2k8:
http://www.johnturner.com/howto/winxp-howto.html
15. Michael Vorburger's Blog Setting up two-way (mutual) SSL with Tomcat on Java5 is easy!:
http://www.vorburger.ch/blog1/2006/08/setting-up-two-way-mutual-ssl-with.html
16. CSRJakarta-Tomcat: http://certs.ipsca.com/Support/CSRJakarta-Tomcat.asp
17. Install a custom SSL certificate:
http://helpdesk.computerlabsolutions.com/index.php?_m=knowledgebase&_a=viewarticle&k
barticleid=28
18. Novell Doc Novell iManager 2_7 Installation Guide - Self-Signed Certificates:
http://www.novell.com/documentation/imanager27/imanager_install_27/index.html?page=/d
ocumentation/imanager27/imanager_install_27/data/bu3uiv1.html
19. Re tomcat and SSL (keyfile password) msg#02583 jakarta_tomcat_user:
http://osdir.com/ml/jakarta.tomcat.user/2002-04/msg02583.html

5
© April 2007, Kefa Rabah, Global Open Versity, Vancouver Canada

www.globalopenversity.org A GOV Open Knowledge License Technical Publication