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:
http://tomcat.apache.org/tomcat-5.5-doc/apr.html
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:
http://www.openssl.org.
A special OpenSSL installer for Windows is available on the Shining Light site at:
http://www.slproweb.com/products/Win32OpenSSL.html.
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:
d:\openssl\bin\openssl.exe
- 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:
https://localhost:8443/tomcat.gif
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.
Posts
