This sections describes what you have to do if you want to call a secure BioMoby web service. Please note, as stated in the section before, this tutorial does not explain the mechanism of SSL/secure transport. This only explains how to let you access a secure web service. If you require or wish to have more information about the theory behind I would refer you to google.

Additionally this section only covers the process for jMoby, so the Java part of BioMoby !

Basically the following steps are required (they will be explained in more detail afterwards):

1. Retrieve the certificate and authentication information from the service provider

2. Add the key to your local keystore

3. Modify the clients to access the services.

1. Retrieve the certificate from the service provider

The service provider has set up a secure web service and with that he/she has created a so-called private key and locked the entrance to the web service. Now to open this lock you need the so-called certificate from the service provider. A certificate (also known as a public-key certificate) is a digitally signed statement from one entity, saying that the public key (and some other information) of another entity has some specific value (source). How you obtain that is freely up to you - mostly asking is the best choice ;-). 

Also ask for the authentication information, namely a user name and the password for the service(s).

These two chunks of information are the two security layers - the secure transport of the data via SSL (therefore the certificate) and the authentication/authorization to restrict the accessibility (therefore the user name/password).

2. Add the key to your local keystore

The so-called keystore can be seen as a bunch of keys. Each key allows you to have access to different locks. To add a new certificate to the keystore you have to type the following:

keytool -keystore KEYSTORE -import -alias ALIAS -file CERTIFICATE

keytool is a java tool which can be found in the bin directory of your Java installation.

KEYSTORE: should be the path to your local keystore. If you already have a keystore enter the path to this keystore. If you don't have a keystore yet, enter the path to the location where you want to have the keystore to be saved (e.g. /local/user/mykeystore). If you omit this parameter Java will store the keystore in the file .keystore in your home directory.

ALIAS: an alias for the certificate you import into your keystore. It is not allowed to have the same alias twice !

CERTIFICATE: the path to the certificate you received from the service provider.

You are asked for the keystore password. If you already have a keystore enter the corresponding password, otherwise you are "free" to create a new one.

3. Modify the clients to access the services

3.1. Dashboard

First we need to provide Dashboard with the keystore with our trusted certificate(s).

3.1.1. Starting Dashboard with ant

If you use ant to start Dashboard, open the dashboard.xml file in the /moby-live/Java/xmls/ folder of your moby checkout with the text editor of your choice. You will find the following lines in there:

<!-- ================================================================== -->
<!-- Start Dashboard                                                    -->
<!-- ================================================================== -->
<target name="dashboard" depends="compile,dashboard-config"
  description="Start BioMoby Dashboard">
  // ...

  <java
    classname="org.biomoby.service.dashboard.Dashboard"
    taskname="Dashboard"
    classpathref="dashboard.build.classpath"
    fork="true"
    failonerror="true">
    <jvmarg value="-Xms32m"/>
    <jvmarg value="-Xmx256m"/>
    <arg value="${dashboard.arg.1}"/>
    <sysproperty key="log4j.configuration" value="${real.log4j.configuration}"/>
  </java>
</target>

Just add the following bold line like this:

<!-- ================================================================== -->
<!-- Start Dashboard                                                    -->
<!-- ================================================================== -->
<target name="dashboard" depends="compile,dashboard-config"
  description="Start BioMoby Dashboard">
  // ...

  <java
    classname="org.biomoby.service.dashboard.Dashboard"
    taskname="Dashboard"
    classpathref="dashboard.build.classpath"
    fork="true"
    failonerror="true">
    <jvmarg value="-Xms32m"/>
    <jvmarg value="-Xmx256m"/>
    <arg value="${dashboard.arg.1}"/>
    <sysproperty key="log4j.configuration" value="${real.log4j.configuration}"/>
    <sysproperty key="javax.net.ssl.trustStore" value="KEYSTORE"/>
  </java>
</target>

where KEYSTORE is the path to your keystore with the certificates.

Now you can start Dashboard by entering ant dashboard.

3.1.2. Start Dashboard with the run-dashboard script

In case you start the dashboard with the run-dashboard(.bat) script in the /moby-live/Java/build/run folder you have to edit the following line:

exec $JAVA -Xms32m -Xmx256m -cp $CLASSPATH "-Dlog4j.configuration=file:FILE"
org.biomoby.service.dashboard.Dashboard "$@"

(where FILE will be set correctly in your run-dashboard(.bat) file, I just leave it out here)

and add the following bold statement:

"-Dlog4j.configuration=file:FILE -Djavax.net.ssl.trustStore=KEYSTORE"

where KEYSTORE is the location of your local keystore. For Windows (.bat) the line looks a bit different, but its the same position where you have to add it. 

Now start Dashboard with either ant or the run-dashboard(.bat) script and select the 'Simple Client'. Basically its similar as calling a non-secure web service. The only difference is that you need to check the box 'Use a user/password for authentication'. If you then call the service by pressing 'Call service', a dialog will appear in which you have to provide your authentication information. Press 'Enter' afterwards and the service call is processed.

Please note that adding the line for the certificates is only required once, whereas different services might require different logins, which you need to provide each time you call a service via the 'Simple Client'.

3.2. MobyRequest

The MobyRequest class is another client you can use to call moby services. As this is a basic Java class setting the certificate is the same procedure as setting a system property. If you use the MobyRequest client in your application either set the following line at the start of your application:

System.setProperty("javax.net.ssl.trustStore", KEYSTORE);

or start your application with the -Djavax.net.ssl.trustStore=KEYSTORE parameter, where in both cases again KEYSTORE refers to the location of your local keystore.

To set the authentication you have to call

setAuthentication(String user, String password)

which is a method of the MobyRequest object.

3.3. FeatureClient

The FeatureClient is based on the MobyRequest class as described above. For setting the certificate it is the same procedure by either setting the system property javax.net.ssl.trustStore in your program or by supplying it via the -D parameter when calling it.

The authentication can also be set via the FeatureClient by calling

setAuthentication(String user, String password)

which is a method of the FeatureClient object.

3.4 Taverna

To use your keystore for Taverna you have to edit the runme.sh for Unix/Linux or the runme.bat for Wondows.

For the runme.sh add the bold line to the file

ARGS="-Xmx300m"
ARGS="$ARGS -Djava.system.class.loader=net.sf.taverna.tools.BootstrapClassLoader"
ARGS="$ARGS -Djava.protocol.handler.pkgs=uk.ac.rdg.resc.jstyx.client"
ARGS="$ARGS -Djavax.net.ssl.trustStore=KEYSTORE"

and for the runme.bat add the bold line to the file

set ARGS=-Xmx300m 
set ARGS=%ARGS% -Djava.system.class.loader=net.sf.taverna.tools.BootstrapClassLoader 
set ARGS=%ARGS% -Djava.protocol.handler.pkgs=uk.ac.rdg.resc.jstyx.client 
set ARGS=%ARGS% "-Dtaverna.dotlocation=%~dp0\bin\win32i386\dot.exe"
set ARGS=%ARGS% "-Djavax.net.ssl.trustStore=KEYSTORE"

whereas again KEYSTORE is the path to your local keystore.

Unfortunately - for now it is NOT possible to call services which require authentication in Taverna. This will be a feature which will be integrated into the Taverna2 platform and will most probably happen early next year !

3.5 General Java client (Axis & JAX-WS)

If you have written your own client which is either Axis or JAX-WS based it is almost the same for either of them.

As you might have guessed from the MobyRequest and FeatureClient, providing the certificate is always setting the right system property. So also for your client you have to set this at the beginning of the client either by using the System.setProperty method with the key 'javax.net.ssl.trustStore' in your code or by providing this via the -D parameter when calling the client.

3.5.1 Axis client

If you are using the axis library to make your web service call you have to provide the following line of code before you do the actual call:

Call call = ... // create your axis call and set all required information
call.setProperty(Call.USERNAME_PROPERTY, user); // setting the user
call.setProperty(Call.PASSWORD_PROPERTY, passwd); // setting the password
call.invoke(...); // service call

3.5.2. JAX - WS

If you are using the jax-ws library to make your web service call you have to provide the following line of code before you do the actual call:

HelloService service = new HelloService(); // create the service
Hello proxy = (service.getHelloPort());
((BindingProvider)proxy).getRequestContext().put(BindingProvider.USERNAME_PROPERTY,
user);
((BindingProvider)proxy).getRequestContext().put(BindingProvider.PASSWORD_PROPERTY,
passwd);

where user and passwd must be set to the correct values.

Please note: This only works that easy for BioMoby web services. If you are adopting this idea to general web services, you will face the problem that the libraries are trying to fetch the WSDL of the service and will fail because of the missing authentication information. How to cope with that is not the scope of this tutorial and can be investigated using the wonderful internet :)

Happy secure calling !