Global Open Versity, Vancouver Canada Configuring Tomcat to Support SSL

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

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

1

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.

Global Open Versity, Vancouver Canada Configuring Tomcat to Support SSL

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

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

2

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"

Global Open Versity, Vancouver Canada Configuring Tomcat to Support SSL

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

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

3

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.

Global Open Versity, Vancouver Canada Configuring Tomcat to Support SSL

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

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

4

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

Global Open Versity, Vancouver Canada Configuring Tomcat to Support SSL

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

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

5

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&kbarticleid=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=/documentation/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