Configuring Tomcat to Support SSL

From MircWiki
Jump to navigation Jump to search

This article describes how to enable Secure Sockets Layer (SSL) communication on MIRC sites. This allows browsers to access the site via both HTTP and HTTPS. It also supports encryption of data transfers between field centers and storage services that participate in clinical trials. The intended audience for this information is MIRC system administrators.

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: 

    
<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
<Connector
    port="8080" maxHttpHeaderSize="8192"
    maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
    enableLookups="false" redirectPort="8443" acceptCount="100"
    connectionTimeout="20000" disableUploadTimeout="true" />

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

    
<!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
<!--
<Connector port="8443" maxHttpHeaderSize="8192"
    maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
    enableLookups="false" disableUploadTimeout="true"
    acceptCount="100" scheme="https" secure="true"
    clientAuth="false" sslProtocol="TLS" />
-->

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

<!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
<Connector port="8443" maxHttpHeaderSize="8192"
    maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
    enableLookups="false" disableUploadTimeout="true"
    acceptCount="100" scheme="https" secure="true"
    clientAuth="false" sslProtocol="TLS" />

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: 

<!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
<Connector port="8443" maxHttpHeaderSize="8192"
    maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
    enableLookups="false" disableUploadTimeout="true"
    acceptCount="100" scheme="https" secure="true"
    clientAuth="false" sslProtocol="TLS"
	SSLEngine="on"
	SSLCertificateFile="${catalina.home}/tomcatcert.pem"
	SSLCertificateKeyFile="${catalina.home}/tomcatkey.pem"
	SSLPassword="tomcat"
     />

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.

8 Configuring trial.xml for Exporting to SSL-enabled Sites

If your site is used for clinical trials and it only imports images or other data, no further configuration is necessary.

If your clinical trial site exports images to other SSL-enabled clinical trial sites, you must change the trial.xml file elements that identify those sites. By far the easiest way to do so is to go to your clinical trial storage service’s admin page and click the Update Configuration button in the DICOM Service column. This will display a web page showing all the configuration parameters in the trial.xml file. Near the bottom of the page, the HttpExportService sites are listed. For each site to which you want to export using SSL, change its protocol from http to https and change its port from 8080 to 8443. For example, if the site’s URL is shown as: 

http://university.edu:8080/trial/import/doc

change it to: 

https://university.edu:8443/trial/import/doc

where trial is the name of the storage service supporting the trial.

You can support both http and https sites in the same clinical trial.

9 Other Security Considerations for Clinical Trials

The use of SSL provides secure communications among the HttpImportServices and HttpExportServices in clinical trial sites. Administrators should not lose sight of the need to restrict access to documents on the storage service itself.

The template.xml file, used by the storage service to create clinical trial MIRCdocuments, should include authorization child elements that restrict access to clinical trial documents to users possessing the appropriate clinical trial role. A separate article describes how to create and modify template files.

Additionally, if users are able to access the clinical trial's storage service from the Internet, administrators should be aware that if they export the document or download DICOM images while viewing the document, the images will be transmitted in the clear. If the images contain PHI, it is advisable in those circumstances to discuss additional security restrictions with the RSNA MIRC software developers.

Retrieved from "http://mircwiki.rsna.org/index.php?title=Configuring_Tomcat_to_Support_SSL&oldid=4605"