How to setup Transport Layer Security

All SOAP messages are signed to prevent tampering, but they are not encrypted. Instead, the connection itself should be over an encrypted HTTPS link. This prevents attackers from seeing the contents of the messages.

There are two ways to enable HTTPS connections (If unsure, choose SSL in tomcat as it is the easiest one to set up).

Enable SSL in Tomcat

For full details, see http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html.

Edit $TOMCAT_HOME/conf/server.xml and add the following section (or uncomment and edit the existing one). Make sure to change the keyStoreFile entry to the location of your service keystore.

<Connector
           port="8443"
	   keystoreFile="/path-to-config-directory/service-keystore.ks"
	   keystorePass="changeme"
	   keystoreType="JKS"
	   minProcessors="5" maxProcessors="75"
           enableLookups="true" disableUploadTimeout="true"
           acceptCount="100" debug="0" scheme="https" secure="true"
           clientAuth="false" sslProtocol="TLS"/>

Then restart tomcat.

If you are using an unpackaged version of tomcat, restart it using:

$ su tomcat
$ $TOMCAT_HOME/bin/shutdown.sh
$ $TOMCAT_HOME/tomcat/bin/startup.sh

Set up Apache with HTTPS and then set up forwarding to Tomcat

For extra security, clients should not be allowed to connect directly to Tomcat. Instead, they should establish a secure, encrypted, HTTPS connection to the Apache web server. Apache will handle encryption at the transport layer, but will pass requests on to Tomcat for processing.

Ensure that your GRIA server firewall allows access to Apache HTTPS port, for more information see the section "Configure the Firewall" in the GRIA installation documentation relevant to your package and operating system.

Tomcat's own port (8080) should not be accessible from anywhere except for the machine running Apache. Make sure that it is firewalled by attempting to connect to it from another machine.

Exporting keystore entries for Apache

Java stores keys and certificates in a keystore file, whose format is Java-specific. Apache also needs access to the same items, but cannot read the Java keystore format. Therefore, the key and the certificates must be exported to separate files. It is simplest to store the exported files in the configuration directory along with the keystore.

You should have already created a keystore. Begin by opening service-keystore.ks in KeyToolGUI.

Exporting certificates

To export the server's certificate:

1. Right click on the server's key (NOT the Certificate Authority's certificate!).
2. Choose Export from the menu.
3. Select Head Certificate and PEM Encoded when exporting.
4. Save with a .crt extension (eg, as server.crt in your configuration directory).

To export the Certificate Authority's own certificate:

1. Right click on the Certificate Authority's certificate.
2. Choose Export from the menu.
3. Select Head Certificate and PEM Encoded when exporting.
4. Save with a .crt extension (eg: CA.crt).

Exporting the private key

1. Right click on the server's key.
2. Choose Export from the menu.
3. Select Private Key and Certificates and PKCS #12 and click OK.
4. Enter the keystore password when prompted (use the same password for the exported key).
5. Save with a .p12 extension (eg: private-key.p12).
6. Convert from PKCS#12 format to PEM:

   $ openssl pkcs12 -in private-key.p12 -out private-key.pem -nodes

Once you have the three files (server.crt, CA.crt and private-key.pem) and the crl.pem file (which should be obtained from your Certificate Authority), you are ready to continue.

Installing Apache

Different Apache packages have different layouts. These pages describe some known setups.