Accessing Web Service via SSL

Summary: This document is a step by step guide to deploy the web services in SSL 
using axis2 and consuming such web services.  

Introduction:  For the secure  web service communication, the web service must be 
deployed over the https  protocol.  Https protocol uses digital certificate for the 
authentication and to ensure that no body can intercept the data except two authenticated 
parties. Once both parties has been authenticated, data is exchanged in encrypted   format 
using public key and private keys. This document outlines the basic steps  required to 
deploying the web service over the https protocol and writing the java client for accessing 
the web service deployed over the secure site. We will be using Axis2  SOAP Engine  for 
web services and tomcat  will  be used as the servlet container. It is assumed that you are 
familiar with writing web services using axis2, otherwise please read user guide first.

1.0 Configuring Tomcat Server for HTTPS
The first step in deploying the web services over a secure protocol HTTPS  is configuring 
the servlet container.  Since we want the server to be authenticated by client, we need to 
generate digital certificate for  the tomcat server.  So lets generate the servers certificate.

1.1 Generate Server Certificate
Java provides very useful utility keytool to generate and manage certificate. We will use 
this utility to  create a keystore and self signed  certificate for the server. Keystore is a file 
where the  the information related to the certificate is stored. 
[root@suprety program]#$JAVA_HOME/bin/keytool -genkey -alias
tomcatServer -keyalg RSA -keystore tomcatKeyStore
Enter keystore password: changeit
What is your first and last name?
[Unknown]: myName
What is the name of your organizational unit?
[Unknown]: research
What is the name of your organization?
[Unknown]: Free Software
What is the name of your City or Locality?
[Unknown]: Kathmandu
What is the name of your State or Province?
[Unknown]: Nepal
What is the two-letter country code for this unit?
[Unknown]: NP
Is CN=myName, OU=research, O=Free Software, L=Kathmandu, ST=Nepal, C=NP
correct? [no]: yes

Enter key password for <tomcatServer>

(RETURN if same as keystore password):
Provide all the information it asks. Finally a file tomcatKeyStore will be saved in
working directory which is a keystore with password changeit. It contains the a single
certificate with alias tomcatServer. To list the keyEntry in the tomcatKeyStore, give
following command

[root@suprety program]#$JAVA_HOME/bin/keytool -list -v -keystore

tomcatKeyStore

Enter keystore password: changeit

Keystore type: jks

Keystore provider: SUN

Your keystore contains 1 entry

Alias name: tomcatserver

Creation date: Aug 16, 2005
Entry type: keyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=myName, OU=research, O=Free Software, L=Kathmandu, ST=Nepal,
C=NP
Issuer: CN=myName, OU=research, O=Free Software, L=Kathmandu, ST=Nepal,
C=NP
Serial number: 4301745e
Valid from: Tue Aug 16 10:51:38 NPT 2005 until: Mon Nov 14 10:51:38 NPT
2005
Certificate fingerprints:
MD5: 6D:2D:C5:80:3E:1B:1C:56:02:79:F8:60:81:1A:DE:3A
SHA1:
5F:28:97:25:6A:18:A3:4C:18:C5:FA:7F:AD:0B:72:8B:ED:71:25:99

*******************************************
*******************************************

The above information tells us that  in the keystore named tomcatKeyStore, there is a 
single certificate and private key for alias tomcatserver. 

1.1.1 Export Server Certificate
We now need to  export  server  certificate so that they can be used by the client. 

[root@suprety program]# $JAVA_HOME/bin/keytool -export -alias

tomcatserver -keystore tomcatKeyStore -rfc -file tomcatserver.cer
Enter keystore password: changeit
Certificate stored in file <tomcatserver.cer>

The certificate for the tomcatserver is now exported to the file tomcatserver.cer, Lets
examine the tomcatserver.cer
[root@suprety program]# cat tomcatserver.cer
-----BEGIN CERTIFICATE-----
MIICTDCCAbUCBEMBdF4wDQYJKoZIhvcNAQEEBQAwbTELMAkGA1UEBhMCTlA
xDjAMBgNVBAgTBU5lcGFsMRIwEAYDVQQHEwlLYXRobWFuZHUxFjAUBgNVBA
oTDUZyZWUgU29mdHdhcmUxETAPBgNVBAsTCHJlc2VhcmNoMQ8wDQYDVQQDE
wZteU5hbWUwHhcNMDUwODE2MDUwNjM4WhcNMDUxMTE0MDUwNjM4WjBtMQsw
CQYDVQQGEwJOUDEOMAwGA1UECBMFTmVwYWwxEjAQBgNVBAcTCUthdGhtYW5
kdTEWMBQGA1UEChMNRnJlZSBTb2Z0d2FyZTERMA8GA1UECxMIcmVzZWFyY2
gxDzANBgNVBAMTBm15TmFtZTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCg
YEAvNXtW+gioHpLIQN2ILm3se/imjKSYk5lWjVt1zeVzYQcBfq2F6XLM8kK
zgT0msvjfSO7bwBizzyiGyUEM7cp/iKuNKkFTvxua4mTESwS0tc9/XmuuAU
eCpkLA13b/EdY9ZCQHqvnnEeVL+f6Gmh1hwJfAAnTyqdTtL6cUliEthMCAw
EAATANBgkqhkiG9w0BAQQFAAOBgQCvNjGjbzbeR2ZhuLh7DBwWJD7jqnX6E
Pf2SKs5mPKDs5zBWXhROGZDdvfuyKLmpFF3mKL3LE+14kEm8uWqepgZNU50
MQC0GmWx5Pq3s+zgBlMhfSlC3qCFxph/gjwhAonAymIK7fLIYP89heatlqc
VhQabOD6ijnU/0ta4GbHTCA==
-----END CERTIFICATE-----

1.1.2 Import Server Certificate to Client TrustStore

For Our web service client to communicate to server over SSL, it must have an a
truststore file. The truststore file should have imported the the certificate of the other
party so as to authenticate them. Since we want to authenticate the tomcat server, we
need to import the server certificate to this truststore. To import the server certificate,
[root@suprety program]# $JAVA_HOME/bin/keytool -import -alias
tomcatCert -file tomcatserver.cer -keystore clientTrustStore
Enter keystore password: changeit
Owner: CN=myName, OU=research, O=Free Software, L=Kathmandu, ST=Nepal,
C=NP
Issuer: CN=myName, OU=research, O=Free Software, L=Kathmandu, ST=Nepal,
C=NP
Serial number: 4301745e
Valid from: Tue Aug 16 10:51:38 NPT 2005 until: Mon Nov 14 10:51:38 NPT
2005
Certificate fingerprints:
MD5: 6D:2D:C5:80:3E:1B:1C:56:02:79:F8:60:81:1A:DE:3A
SHA1:
5F:28:97:25:6A:18:A3:4C:18:C5:FA:7F:AD:0B:72:8B:ED:71:25:99
Trust this certificate? [no]: yes
Certificate was added to keystore

The above command generate a truststore file named  clientTrustStore with the
tomcatserver certificate as a trusted certificate.

1.2 Configure server.xml File

After generating the keys, now lets configure the tomcat server. Tomcat server I have
used is 4.1.31. Edit the $TOMCAT_HOME/conf/server.xml file and uncomment the
setting for the SSL. Add two lines printed in bold.
<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->

<Connector
className= "org.apache.coyote.tomcat4.CoyoteConnector"
port="8443" minProcessors="5"
maxProcessors="75"
enableLookups="true"
acceptCount="100" debug="0"
scheme="https" secure="true"
useURIValidationHack="false" disableUploadTimeout="true">

<Factory
className="org.apache.coyote.tomcat4.CoyoteServerSocketFactory"
keystoreFile="/usr/lib/ooo-1.1/program/tomcatKeyStore"
keystorePass="changeit"

clientAuth="false" protocol="TLS" />

</Connector>

We added two parameters in above file, the first one is the keystoreFile, it values is
keystore file that we created in previous step. You need to change the path of the file to
make it work in your environment. The second parameter is the keystorePassword, its
values should be same as the password for the keystore.

1.3 Start Tomcat Server

Save server.xml file and restart the tomcat server. Access the index page as
https://localhost:8443/index.jsp, with your favorite browser. If everything is ok, the
browser shows an warning message as our server certificate is self singed and not singed
by any CA. Select accept the certificate temporarily for this session only and click ok.
2.0 Deploy Web Service
After the https has been sets up, its time to deploy some web services. Download axis2
(version 0.91) from http://ws.apache.org/axis2. Extract the axis2-0.91-bin.zip file. Copy
the axis2-0.91-bin/webapps/axis2.war file to webapps folder of tomcat home
($TOMCAT_HOME/webapps). Now browse https://localhost:8443/axis2, it will show
the axis home page. Click on the list available service. It will display the all available
services. By default, there is a Version service whose EPR (End Point Reference) is
https://localhost:8443/axis2/services/Version this service has a single operation called
getVersion. We will now write the client code to access this web service.

3.0 Writing Java Client

Axis2 uses JSSE (Java Secure Socket Extension) to accesses the secure web services.
JSSE has been integrated into the Java 2 platform as of version 1.4. If you are using older
java 2 version, JSSE needs to be manually installed and configured. For java version
1.4.x, axis2 works out of the box. You need to set couple of JVM properties. To access
the secure site from web service client, you need to set the following properties.
i. javax.net.ssl.trustStore
ii. javax.net.ssl.trustStorePassword
The value of the javax.net.ssl.trustStore should be the path of the trustStore file. The
trustStore file should have imported the certificate of the server to whom the client is
going to communicate with. Since we are going to access web service deployed in the
tomcat server, we need to create a trustStore which must have imported the certificate
that tomcat is using. We have already created such trustStore in step 1.1.2. In my system,
the path of the trustStore file is /usr/lib/ooo-1.1/program/clientTrustStore. The password
for this trustStore is changeit. We need to set this password to property
javax.net.ssl.trustStorePassword. Example:

public static void main(String[] args) throws Exception{

.....
.....
System.setProperty("javax.net.ssl.trustStore",
"/usr/lib/ooo-1.1/program/clientTrustStore");

System.setProperty("javax.net.ssl.trustStorePassword",
"changeit");
....
....

This is all we have to do, now we call the secure web service with out any problem. 
Source  code of the https web service client is given below.
//FileName: HttpsWebServiceClient.java
package test;

import javax.xml.namespace.QName;
import javax.xml.stream.XMLOutputFactory;
import javax.xml.stream.XMLStreamWriter;

import org.apache.axis2.AxisFault;
import org.apache.axis2.Constants;
import org.apache.axis2.addressing.EndpointReference;
import org.apache.axis2.clientapi.Call;
import org.apache.axis2.om.OMAbstractFactory;
import org.apache.axis2.om.OMElement;
import org.apache.axis2.om.OMFactory;
import org.apache.axis2.om.OMNamespace;
import org.apache.axis2.om.impl.OMOutputImpl;

/**
* @author Shankar Raj Uprety
*/

public class HttpsWebServiceClient {

private EndpointReference targetEPR;
private QName operationName = new QName("version");

private OMElement createRequestMethod() {

System.out.println("creating envelop");
OMFactory fac = OMAbstractFactory.getSOAP11Factory();
OMNamespace omNs = fac.createOMNamespace("http://localhost/d2", "d2");
OMElement requestMethod = fac.createOMElement("getVersion", omNs);
OMElement firstElement = fac.createOMElement("firstElement", null);
 requestMethod.addChild(firstElement);
System.out.println("request methode returned..");
return requestMethod;
}

public static void main(String[] args) throws Exception{

System.setProperty("javax.net.ssl.trustStore",
"/usr/lib/ooo-1.1/program/clientTrustStore");
System.setProperty("javax.net.ssl.trustStorePassword","changeit");
HttpsWebServiceClient client=new HttpsWebServiceClient();
client.getAxisVersion();
}

private void getAxisVersion() throws AxisFault{

OMElement payload =createRequestMethod();
Call call = new Call();
targetEPR=new EndpointReference("https://localhost:8443/axis2/services/Version");
call.setTo(targetEPR);
call.setTransportInfo(Constants.TRANSPORT_HTTP,
Constants.TRANSPORT_HTTP, false);

OMElement result = (OMElement) call.invokeBlocking(operationName

.getLocalPart(), payload);

if(result!=null){
displayResult(result);
}else{
System.out.println("Got Null Result");

}
}

private void displayResult(OMElement result){

try {
XMLStreamWriter writer = XMLOutputFactory.newInstance().
createXMLStreamWriter(System.out);
result.serialize(new OMOutputImpl(writer));
System.out.println("trying to serialize the result");
writer.flush();
} catch (Exception e) {
System.out.println("got Exexption while prinring");
e.printStackTrace();
}
}
}

Output of the above client program is

creating envelop
request methode returned..
trying to serialize the result
<my:Version xmlns:my="http://localhost/my">Hello I am Axis2 versionning
service , My version is Axis2 0.91 !! </my:Version>

Note:
This Client program runs only with latest release of the axis2 (version 0.91). You will get
connection reset exception if you try with older releases.

4.0 Conclusion
Web services overs https for the secure communication between the web service and
client can be implemented using Axis2 SOAP Engine by carrying out above outlined
steps.

5.0 References:
1. JSSE Reference Guide
     http://java.sun.com/j2se/1.5.0/docs/guide/security/jsse/JSSERefGuide.html
2. Setting up Apache Tomcat and a Simple Apache SOAP Client for SSL 
Communication
 http://ws.apache.org/soap/docs/install/FAQ_Tomcat_SOAP_SSL.html
3. Axis2 User Guide
http://ws.apache.org/axis2/userguide.html