Search This Blog

Wednesday, May 28, 2014

Tomcat to Support HTTPS / SSL Apache Portable Runtime (APR) with Private key Public Key

1 System Configuration

This document applies to Windows systems running Tomcat 5.5, not to Tomcat 4.1, so it should only be used for sites running MIRC T27 or later. Further, these instructions apply to Tomcat sites running the Apache Portable Runtime (APR). On a Windows computer, this is a dynamically linked library (DLL) that is installed automatically during a Tomcat installation if the user selects the Native option. The APR is strongly recommended, especially on high volume sites, because it is more efficient than the normal Tomcat web server.
You can check whether your system has the APR installed by looking for Tomcat/bin/tcnative-1.dll. If that file is present, Tomcat will automatically use the APR. If your Windows system does not have the APR, you can get it at:

2 Overview of the Process

When an application (A) establishes an SSL connection to another application (B), it receives encrypted information that identifies B. This information is called a certificate. Certificates are encoded mathematically with keys.
Enabling SSL on a Tomcat installation that is running the APR involves the following steps:
  • Create a private key for Tomcat.
  • Create a certificate for Tomcat.
  • Place the private key and the certificate where Tomcat can find them.
  • Configure Tomcat to enable SSL and use the key and certificate.
  • Do any MIRC configuration necessary for clinical trials.
The first two steps require the use of an open source SSL tool called OpenSSL.

3 Getting OpenSSL

OpenSSL is developed by the OpenSSL Project. Its web site is:
A special OpenSSL installer for Windows is available on the Shining Light site at:
After downloading the installer, run it. The result is a directory called OpenSSL. Inside that directory is a bin directory. Although the installer will create entries in the Programs menu, those entries only point to documentation (and to the uninstaller). The OpenSSL program is a command-line utility. In the instructions that follow, it is assumed that the OpenSSL directory is located in the root of the D drive (D:\OpenSSL).

4 Creating a Private Key for Tomcat

To enable SSL communication, Tomcat must have a certificate. To create a certificate for Tomcat, you must first have a private key. This section will demonstrate how to create a private key using OpenSSL.
To start, create a directory in which to work. In this example, the directory is called sandbox.
  • Launch a DOS window. (Click Start -- Run… and type cmd. Then click OK.)
  • Navigate to your sandbox directory.
  • Enter the command:
  • OpenSSL will prompt with: OpenSSL>
  • Enter the command:
genrsa –des3 –out tomcatkey.pem 2048
  • OpenSSL will then ask you for a pass phrase for the key. Enter any phrase you want. In this example, we will use the pass phrase tomcat. After entering the pass phrase, OpenSSL will ask you to repeat it.
  • OpenSSL will then create the private key and store it in the sandbox directory in a file called tomcatkey.pem.
You can remain in the OpenSSL program for the next step.

5 Creating a Certificate for Tomcat

Once you have a private key for Tomcat, you must create a certificate. Assuming you are still running the OpenSSL program from the previous step, enter the command:
req –new –x509 –key tomcatkey.pem –out tomcatcert.pem –days 1095
OpenSSL will ask you for the pass phrase that you defined for the private key. This command creates a self-signed certificate with a lifetime of 3 years (1095 days), using the private key. OpenSSL will store that certificate in the sandbox directory in a file called tomcatcert.pem.

6 Storing the Private Key and the Certificate

You must now place the tomcatkey.pem and tomcatcert.pem files where Tomcat can find them. The easiest place to put them is in the top-level Tomcat directory.

7 Enabling SSL in the Tomcat server.xml File

Having put the files in the top-level Tomcat directory, you must now enable SSL in the server.xml file which is located in the conf directory under the top-level Tomcat directory. Using the Tomcat directory in the section above as an example, first make a backup copy of the Tomcat\conf\server.xml file (just in case) and store it somewhere safe. Then open Tomcat\conf\server.xml with a text editor.
Look for the section of code that contains the main connector:

About 10 lines under that look for the code for the SSL connector:

Remove the start and end comment lines, making the code read:

Next, it is necessary to tell Tomcat where the key and certificate are and how to access them. Add the four indented lines near the bottom of the box below, making the code read:

In place of tomcat in the SSLPassword attribute, you must use the pass phrase you chose for the private key. Then, save the file.
This will create an SSL connector on port 8443 when Tomcat is restarted. If you decide to use a different port than 8443, you must change the redirectPort attributes in other Connector elements to point to the port you chose; otherwise, redirections to the SSL port will not occur.
Note: enabling SSL on your site does not disable non-SSL connections, so your site will also continue to work with browsers that are not SSL-enabled.
When modifying XML files, it is usually a good idea to confirm that you have not made a mistake in typing and inadvertently created a file that is not well-formed. An easy way to check is to open the file with Internet Explorer, which will parse the file and either display the text in a nicely formatted window or tell you about the first error it found.
At this point, start (or restart) Tomcat. Launch a browser and go to:
If your certificate is self-signed, your browser will warn you. You should tell the browser to import the certificate and proceed. You should then see the little Tomcat logo. If you do, you’re done configuring Tomcat.

Enable SSL Https in Tomcat

1. Generate Keystore

First, uses “keytool” command to create a self-signed certificate. During the keystore creation process, you need to assign a password and fill in the certificate’s detail.
$Tomcat\bin>keytool -genkey -alias mkyong -keyalg RSA -keystore c:\mkyongkeystore
Enter keystore password:
Re-enter new password:
What is your first and last name?
  [Unknown]:  yong mook kim
What is the name of your organizational unit?
  //omitted to save space
  [no]:  yes
Enter key password for <mkyong>
        (RETURN if same as keystore password):
Re-enter new password:
Here, you just created a certificate named “mkyongkeystore“, which locate at “c:\“.

Certificate Details
You can use same “keytool” command to list the existing certificate’s detail
$Tomcat\bin>keytool -list -keystore c:\mkyongkeystore
Enter keystore password:
Keystore type: JKS
Keystore provider: SUN
Your keystore contains 1 entry
mkyong, 14 Disember 2010, PrivateKeyEntry,
Certificate fingerprint (MD5): C8:DD:A1:AF:9F:55:A0:7F:6E:98:10:DE:8C:63:1B:A5

2. Connector in server.xml

Next, locate your Tomcat’s server configuration file at $Tomcat\conf\server.xml, modify it by adding a connector element to support for SSL or https connection.
File : $Tomcat\conf\server.xml
 <!-- 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"
               clientAuth="false" sslProtocol="TLS" 
        keystorePass="password" />
keystorePass="password" is the password you assigned to your keystore via “keytool” command.

3. Done

Saved it and restart Tomcat, access to https://localhost:8443/

In this example, we are using Google Chrome to access the Tomcat configured SSL site, and you may notice a crossed icon appear before the https protocol :), this is caused by the self-signed certificate and Google chrome just do not trust it.
In production environment, you should consider buy a signed certificate from trusted SSL service provider like verisign/digicert or sign it with your own CA server

Hit Counter

View My Stats