NCSA CyberSecurity: Testing X.509 Proxy Certificates - Java Client ⇔ Axis Web Service

Note: For printing purposes, you can SHOW ALL or HIDE ALL instructions.

Author: Terry Fleury (tfleury@ncsa.uiuc.edu)

Last Update: April 13, 2006

Implementation

This document shows you how to deploy a very simple Axis-based web service and how to connect to it with a simple Java application. We asssume the use of Java 1.5 and Axis 1.2.1, but other versions may work as well. We would appreciate hearing from people who have had success with different versions of software.

Web Service / Server-Side Setup

Quick link: SampleService.jws (web service)

Here we give instructions for installing the server-side software. We will be using Tomcat as our Web Services (WS) server. Tomcat requires Java. We will be using Axis as the SOAP implementation, but you should be able to deploy other web services and still use the approaches in the sample code files given below.

In each step below, a 'general' instruction is given first, followed by a link for specific instructions. These specific instructions are initially hidden and can be viewed by clicking on the appropriate link.

Note: For printing purposes, you can SHOW ALL or HIDE ALL the Server-Side specific instructions.

Install and configure Tomcat to work with Proxy Certificates.
Tomcat does not, by default, accept proxy certificates. So you need to download some special software and configure Tomcat appropriately. Detailed instructions can be found on this page.
Configure Tomcat to perform delgation of GSI credentials.
In the $CATALINA_HOME/conf/server.xml file, change the mode="ssl" entry to mode="gsi".
Detailed Instructions...

When you configured Tomcat to work with proxy certificates in the previous step, you specified mode="ssl" in the new <Connector ...> section of the $CATALINA_HOME/conf/server.xml file. This allowed you to connect to the Tomcat server with Internet Explorer via "https://...:8443/". However, with this method you do not delegate the credential from the client to the server. You would delegate a (proxy) credential from a client to a server when you want the server to act on behalf of the client, e.g. submitting a GRAM job. In order to get delegation of credentials working, you need to change the mode option to be mode="gsi".
When set to this configuration, the credential is delegated from client to server via a TLS (transport layer security) mechanism. This happens by performing an additional handshake just after the standard SSL handshake. This means that once Tomcat is configured for GSI security, you MUST connect to the server via "httpg://...:8443/". If you attempt to connect with https, the service will "hang" since it is expecting the additional GSI handshake after the SSL handshake, but the standard https SSL connection does not provide it.
Install Axis into Tomcat.
The sample web service we will be using is a JWS endpoint, which is basically a .java file renamed to .jws. This is a very simple deployment mechanism which relies on Axis being installed in Tomcat.
Detailed Instructions...
First, you need to download Axis 1.2.1. You will want to get the "axis-bin-1_2_1.tar.gz" file since you don't need the source code. Unzip/untar this file to anywhere you like. We won't be referencing the directory after this step. We only need to copy a few files to our Tomcat installation. The files are extracted to a directory named "axis-1_2_1". Issue the following command to copy one Axis subdirectory to Tomcat:
```
cp -R axis-1_2_1/webapps/axis $CATALINA_HOME/webapps
```
Note that you may need root access to copy the files from Axis to Tomcat. More information on installing Axis into Tomcat can be found in the Axis documentation.
Install the sample web service.
Detailed Instructions...

A very simple JWS-endpoint-based web service was written by Jarek Gawor, one of the CoG Kit developers responsible for adding proxy certificate support to Tomcat. Download this SampleService.jws file and copy it to the "$CATALINA_HOME/webapps/axis/" directory. For the purposes of this sample application, no other configuration is required. However, the code in the setMessageContextProperties() method in that file must be copied to your web service so as to set the GSI properties for the message context.

Finally, restart the Tomcat server.
Detailed Instructions...

If the Tomcat server is running, you can run the following commands to "restart" the server:

> shutdown.sh ; startup.sh
Using CATALINA_BASE:   /usr/tomcat/apache-tomcat-5.5.17
Using CATALINA_HOME:   /usr/tomcat/apache-tomcat-5.5.17
Using CATALINA_TMPDIR: /usr/tomcat/apache-tomcat-5.5.17/temp
Using JRE_HOME:       /usr/java/jdk1.5.0_06
Using CATALINA_BASE:   /usr/tomcat/apache-tomcat-5.5.17
Using CATALINA_HOME:   /usr/tomcat/apache-tomcat-5.5.17
Using CATALINA_TMPDIR: /usr/tomcat/apache-tomcat-5.5.17/temp
Using JRE_HOME:       /usr/java/jdk1.5.0_06

If the server isn't running, you may see error messages like this after the first set of four lines (above):

Mar 10, 2006 2:59:54 PM org.apache.catalina.startup.Catalina stopServer
SEVERE: Catalina.stop: 
java.net.ConnectException: Connection refused
        at java.net.PlainSocketImpl.socketConnect(Native Method)
        at java.net.PlainSocketImpl.doConnect(PlainSocketImpl.java:333)
        at java.net.PlainSocketImpl.connectToAddress(PlainSocketImpl.java:195)
        at java.net.PlainSocketImpl.connect(PlainSocketImpl.java:182)
        at java.net.SocksSocketImpl.connect(SocksSocketImpl.java:366)
        at java.net.Socket.connect(Socket.java:507)
        at java.net.Socket.connect(Socket.java:457)
        at java.net.Socket.<init>(Socket.java:365)
        at java.net.Socket.<init>(Socket.java:178)
        at org.apache.catalina.startup.Catalina.stopServer(Catalina.java:394)
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
        at java.lang.reflect.Method.invoke(Method.java:585)
        at org.apache.catalina.startup.Bootstrap.stopServer(Bootstrap.java:324)
        at org.apache.catalina.startup.Bootstrap.main(Bootstrap.java:415)

Don't worry about it. It's just Java's way of saying that there was nothing to shut down. You may also notice that there isn't a lot of output when starting up. That's because all output (other than the 4 lines above) is written to files in the $CATALINA_HOME/logs/ directory. It's a good practice when first configuring Tomcat to look at the contents of $CATALINA_HOME/logs/catalina.out to make sure that there are no error messages when starting up. One way to do this is to change your "restart" command to something like this:

shutdown.sh ; startup.sh ; tail -f $CATALINA_HOME/logs/catalina.out

The tail -f command will "follow" the output of the catalina.out file as it is being written.

Note that once you have set up Tomcat using the method shown above, you will no longer be able to access the https port using Internet Explorer. This is due to the configuration change in $CATALINA_HOME/conf/server.xml where you set mode="gsi". This configuration requires that httpg be used for the SSL port, and since Internet Explorer does not see httpg as a valid connection protocol, all connections will need to be made with Java clients such as the one shown below.

Client-Side Setup

Quick link: SampleClient.java (Java client)

Now that you have your web service set up and running, you'll probably want to test it out. While the server-side .jws file was rather simple, the client-side .java file is a little more complex because of all the initialization required to connect to a web service.

Note: For printing purposes, you can SHOW ALL or HIDE ALL the Client-Side specific instructions.

Download the sample client Java code.
Detailed Instructions...

Download this SampleClient.java and save it whereever you want. If you edit the file, you will notice that quite a few special jar libraries are required to compile and run the application. If the client is on the same machine as the Tomcat server, then you have all the libraries you need. However, let's assume instead that you are on a separate machine and have not downloaded all of the required jar libraries.
Download Globus/CoG Kit libraries.
All of the jars needed for compilation and execution of the sample client code can be found in the cvs distribution of Globus (which itself is based on the cvs distribution of the CoG Kit). If you had previously downloaded these globus cvs files, you don't need to download them again. But, if those files were downloaded for the Tomcat server and you are running the client on a different machine, you will need to download them for the client machine.
Detailed Instructions...
You need to have cvs installed to get the Globus libraries. If you don't have it installed, you can use yum as "yum install cvs". Then run the following commands:
```
> cd /tmp
> cvs -d:pserver:anonymous@cvs.globus.org:/home/globdev/CVS/globus-packages login
Logging in to :pserver:anonymous@cvs.globus.org:2401/home/globdev/CVS/globus-packages
CVS password:   (here, type <ENTER> for an empty password)
> cvs -d:pserver:anonymous@cvs.globus.org:/home/globdev/CVS/globus-packages \
      co wsrf/java/common/source/lib
cvs checkout: Updating wsrf/java/common/source/lib
U wsrf/java/common/source/lib/LICENSE-DOM.html
     ... and a bunch of other files ...
```
For the sake of brevity in the following instructions, let's set an environment variable $COG_LIB to reference the directory of jars you just downloaded. In the bash shell, the command is:
```
export COG_LIB=/tmp/wsrf/java/common/source/lib
```
Set the Java CLASSPATH to include the Globus/CoG Kit libraries.
Detailed Instructions...
For compiling the SampleClient.java code, your Java CLASSPATH must include the following libraries:
- axis.jar
- cog-axis.jar
- cog-jglobus.jar
- jaxrpc.jar
- log4j.jar
For the purposes of executing the sample client, you Java CLASSPATH must include the following additional libraries:
- cog-url.jar
- commons-discovery.jar
- commons-logging.jar
- cryptix32.jar
- cryptix-asn1.jar
- jce-jdk13-131.jar
- puretls.jar
- saaj.jar
- wsdl4j.jar
Note that if you already have any of the above in your current CLASSPATH, it's probably not necessary to include these specific versions. If you experience problems with a different version of a particular jar, then you should use the appropriate file from the globus cvs library you downloaded above.
While you can specify Java's CLASSPATH when compiling or running by using the "-classpath" command line option, it's probably simpler to set your CLASSPATH variable to include all jar files for both compilation and execution. In the bash shell, you can use the following command to set your CLASSPATH to use these jars:
```
> export COG_LIB=/tmp/wsrf/java/common/source/lib ; \
export CLASSPATH=.:\
$COG_LIB/axis.jar:\
$COG_LIB/cog-axis.jar:\
$COG_LIB/cog-jglobus.jar:\
$COG_LIB/cog-url.jar:\
$COG_LIB/commons-discovery-0.2.jar:\
$COG_LIB/commons-logging-1.0.4.jar:\
$COG_LIB/cryptix32.jar:\
$COG_LIB/cryptix-asn1.jar:\
$COG_LIB/jaxrpc.jar:\
$COG_LIB/jce-jdk13-131.jar:\
$COG_LIB/log4j-1.2.13.jar:\
$COG_LIB/puretls.jar:\
$COG_LIB/saaj.jar:\
$COG_LIB/wsdl4j.jar:\
$CLASSPATH
```
Compile and execute the sample client.
Detailed Instructions...
With your CLASSPATH set as shown in the previous step, you compile the .java source code file with the following command:
```
javac SampleClient.java
```
This will generate a SampleClient.class file in the same directory.
To execute the program, type the following command:
```
java SampleClient -?
```
This will show the help text of the program and tell you the various command line options available to you. As you are connecting to the web service using a proxy certificate, you need to have a proxy certificate available to you. The sample client can read the proxy certificate either from a local file or from a MyProxy server. If you don't have a local proxy certificate file, you can generate one yourself. For information on using a MyProxy server, consult the main MyProxy documentation.
Note that when connecting to the web service with your proxy certificate, the Tomcat server will do client authentication. To have this work correctly, you need to have your "$HOME/.globus/cog.properties" file configured correctly. Here's an example:
```
# /home/msmith/.globus/cog.properties
# Java CoG Kit Configuration File
# Mon March 23 11:21:30 CST 2006
usercert=/home/msmith/.globus/usercert.pem
userkey=/home/msmith/.globus/userkey.pem
cacert=/home/msmith/.globus/certificates/4a6cd8b1.0
proxy=/tmp/x509up_u_msmith
ip=141.142.220.20
```
Once everything is configured and compiled, you would see the following output from the program, assuming you read the proxy certificate from a local file:
```
> java SampleClient httpg://testing.ncsa.uiuc.edu:8443/axis/SampleService.jws
[main] INFO  SampleClient  - Getting proxy certificate from Local File.
[main] INFO  SampleClient  - Local proxy file name = /tmp/x509up_u_msmith
[main] INFO  SampleClient  - Web service URL = httpg://testing.ncsa.uiuc.edu:8443/axis/SampleService.jws
[main] INFO  SampleClient  - Got Proxy DN = /C=US/O=NCSA/CN=Mike Smith
Sending message "Testing..." to Web Service
Web Service Response : User '/C=US/O=NCSA/CN=Mike Smith' authorized locally
    as 'null' with Tomcat4 credential of 'null' and Tomcat 5 credential of
    'org.globus.gsi.gssapi.GlobusGSSCredentialImpl@190a0d6' sent the text
    'Testing...'
>
```

Author:	Terry Fleury (tfleury@ncsa.uiuc.edu)
Last Update:	April 13, 2006

NCSA CyberSecurity

Projects and Software

Implementation

Web Service / Server-Side Setup

Client-Side Setup