Certificates

One of the (many, many) requirements of 21 CFR Part 11 is that all traffic to and from the server where OpenClinica runs must be encrypted. If anything is intercepted, at least it is not readable. For encryption you will need a certificate on your server. (This certificate can also be used to authenticate your server, i.e. to guarantee anyone who connects to your server that indeed this is the server they expect to connect to.)

Production-environment

In a production-environment you will probably be using Apache or IIS as the main web-server. In the main web-server you define connectors that describe where and how to redirect requests that must be handled by Tomcat. If you install a certificate on Apache/IIS the encryption/decryption is done there. This has the considerable advantage that Tomcat gets plain requests and can send back plain responses and does not need to spend processing power on encryption/decryption.
On this page we will not explain how to install a certificate for Apache or IIS. Most Certificate Authorities have their own how-to-pages for requesting a certificate and installing it.

A self-signed certificate for Tomcat

But let's say you have a relatively small OpenClinca environment and you want to secure it, but without bothering to request a certificate (or without the funding to pay for a certificate). Before we do this, a word of warning: such a certificate will always give a security warning in the browsers of your users! You will have to explain to your users where this warning comes from and what the procedures are to add your site to the "trusted sites" or how they can "accept the risk" of connecting to a server with a non-certified certificate.

(The following information was mostly taken from http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html: an excellent starting point.)

Having said all this, let's look at the works: we need to do two things: 1- generate a certificate and 2- configure Tomcat to accept requests on another port (8443) and where to find the information concerning the certificate.

Generating the certificate

Our first step is to generate the certificate. (This example is for Windows, Unix is almost the same.) This is done by using the keytool, located in your JAVA_HOME. For our Windows example this will be C:\Program Files\Java\jdk1.6.0_18\bin

Open a command prompt. First create the directory for your keystore-file, that is the file that will hold your certificate. We will put the keystore-file in the Tomcat-directory: C:\Tomcat\Keystore.

C:\>mkdir C:\Tomcat\Keystore

The command you are going to use, keytool.exe, is part of your Java-installation. Switch to your JAVA_HOME directory, in the example C:\Program Files\Java\jdk1.6.0_18 and from there to the bin directory.
Start the keytool, with the following parameters: keytool -genkey -alias tomcat -keyalg RSA -keystore c:\tomcat\keystore\.keystore. This means more or less: generate a certificate/key called tomcat, using RSA as key-algorithm and store the certificate in the keystore, located in C:\Tomcat\Keystore.

C:\>cd %JAVA_HOME%
C:\Program Files\Java\jdk1.6.0_18>cd bin
C:\Program Files\Java\jdk1.6.0_18\bin>keytool -genkey -alias tomcat -keyalg RSA -keystore c:\tomcat\keystore\.keystore

Now you must supply several parameters. None of these are very important, except the keystore password. Standard is changeit, but of course you can use anything. But whatever you choose: write it down. You will need this password in the server.xml file, so Tomcat can open the keystore and read the certificate. A typical output of the keystore is:

Enter keystore password:
Re-enter new password:
What is your first and last name?
[Unknown]: GR Visser
What is the name of your organizational unit?
[Unknown]: TrialDataSolutions
What is the name of your organization?
[Unknown]: TrialDataSolutions
What is the name of your City or Locality?
[Unknown]: Amsterdam
What is the name of your State or Province?
[Unknown]: NH
What is the two-letter country code for this unit?
[Unknown]: NL
Is CN=GR Visser, OU=TrialDataSolutions, O=TrialDataSolutions, L=Amsterdam, ST=NH
, C=NL correct?
[no]: y

Enter key password for <tomcat>
(RETURN if same as keystore password):<tomcat>

Configuring Tomcat

You have your certificate in place, but you still must configure Tomcat. Shutdown Tomcat. Go to the C:\Tomcat\conf directory and copy the file server.xml, so you have a backup-copy in case you mess it up. Scroll to the comment-line that says "Define a SSL HTTP/1.1 Connector on port 8443". Uncomment it (and add your own comment, so you can find back later what you've changed). You must add information about where the keystore with the certificate is and what the password for the keystore is: keystoreFile="c:\tomcat\keystore\.keystore" keystorePass="changeit"


fig. 1: modified server.xml

And that's it. Save your file and start Tomcat. Open your browser and use as address https://localhost:8443 Tell your browser this is a trusted site or add an exception etc.

Other how-to-pages can be found here.