SSL-Enabled Web Services with Apache Axis2/C

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By Dushshantha Chandradasa
  • 17 Oct, 2008

In this article by Dushshantha Chandradasa, an introduction to the use of the Secure Socket Layer (SSL) protocol for securing online transactions is provided.

Introduction

When communicating over the Internet, all transactions between your Web browser (the client) and the server takes place in an unsecured way. Anyone, with the right tools, can snoop on anyone’s traffic. An example is when one is communicating very sensitive data such as credit card numbers and performing bank transactions. In such situations, snooping activities can cause serious damage to the legitimate parties concerned. Is there a way to ensure communication with the correct server and send our requests and sensitive information to the server in an encrypted format that only the two parties can understand?

As a solution to this problem, the Secure Socket Layer (SSL) protocol was introduced by Netscape in 1994. The SSL is used to encrypt the data stream between a Web server and  a client. The protocol uses Asymmetric Cryptography, also known as Public Key Cryptography and trusted certificates to achieve its goal. In Public Key Cryptography, two keys are created: a private key and a public key. Anything encrypted with either key can only be decrypted using its corresponding key. For example, the data encrypted with the server's private key can only be decrypted using its public key. This ensures that the data could have originated only from the corresponding server. The role of the certificate signed by a trusted Certificate Authority (CA) is to ensure the legitimate identity of the certificate holder.

When a Web service using Axis2/C is provided (or consumed), the above mentioned problems become common to the provider as well as the consumer. Is it possible to use SSL to overcome these issues? Yes; using Axis2/C with SSL enabled, the power of SSL can be leveraged to consume and provide Web services in a secured manner. In this article, the following is discussed:  how an Axis2/C Web service hosted on an Apache HTTP server can be secured and how that Web service can be consumed in a secured manner with a SSL enabled Axis2/C Web service client.

Table of Contents

Build Axis2/C with SSL Enabled

In order to consume Web services hosted in an SSL enabled server, Axis2/C with SSL enabled should be built. Axis2/C uses OpenSSL library to provide SSL capabilities. Therefore, as a prerequisite, it is first required that OpenSSL be installed in your system. If a Linux system is being used, make sure libssl dev package is installed if that system does not have it already. If using Windows, a binary distribution of the latest OpenSSL can be installed from here. Make sure that an OpenSSL header file is included as well. These headers are used to build Axis2/C with SSL.

Now, it can be demonstrated how Axis2/C with SSL enabled can be built. In order to do this, you have to use a source distribution of Axis2/C.  The latest source release can be downloaded from the Axis2/C download site (http://ws.apache.org/axis2/c/download.cgi). Once this has been downloaded and the source pack extracted, it can be built as follows.

For Linux:

% ./configure --enable-openssl=yes --with-apache2=/usr/local/apache2/include --prefix=${AXIS2C_HOME}/deploy

% make

% make install

In the Linux system, the --enable-openssl configuration option must be set equal to ‘yes’ and to ‘build Axis2/C’ to enable SSL support. For the --with-apache2 option, it must be specified that the apache2 includes directory, in this case /usr/local/apache2/include. If everything goes well, the SSL enabled Axis2/C binary package will be installed in the ${AXIS2C_HOME}/deploy directory.

For Windows:

When using a Windows platform, the configure.in file located in <axis2/c source>\build\win32 directory must be edited.  Along with the other required settings, the ENABLE_SSL option must be set to 1 and OPENSSL_BIN_DIR to your OpenSSL installation directory. For a Windows built system, use these options to build Axis2/C with SSL capabilities.

# enables https support

ENABLE_SSL = 1         

#

# openssl  binary location

# required if ENABLE_SSL = 1

OPENSSL_BIN_DIR = c:\OpenSSL

#

After saving the changes to configure.in file, execute bindist.bat to build the Axis2/C When all steps have been followed up to this stage,  your system can be configured to deploy Web services with SSL enabled. The following section is a guide to the process of configuring the Apache Web server and hosting the Axis2/C Web services there.

Configuration and Deployment of Services

The power of SSL can be leveraged to protect Web services by hosting Axis2/c Web services on an Apache HTTPD server. It will now be discussed how an Apache server can be set up to enable SSL. For this, a private key must be generated for the server and signed by a trusted Certificate Authority (CA), who will verify the identity of the requesting party and issue a signed certificate. The CA is acting as a trusted third party who verified the identity of the client and the server. Commercial CAs such as Thawte or Verisign can perform this service. Once a private key has been generated and a certificate signing request obtained, this can be sent to one of the CAs and a signed certificate obtained for the server. For demonstration purposes, a CA has been created to sign the server certificate. This can be performed using an openssl toolkit to generate our own CA as shown below.

Type the following commands in the command prompt in a chosen directory where the CA certificate is required.

openssl genrsa -des3 -out ca.key 4096

openssl req -new -x509 -days 365 -key ca.key -out ca.crt

Now that a CA key and a certificate to sign your server's key has been established,  a private key is required for our server. The following command generates a RSA private key which is encrypted using Triple-DES encryption algorithm.

openssl genrsa -des3 -out server.key 4096

To sign this key with the CA created earlier, a Certificate Signing Request (CSR) must be generated. The following command will do this for you.

openssl req -new -key server.key -out server.csr

Sometimes the Apache server may present problems when presented with a pass-phrased key. So, before proceeding further, remove the pass-phrase from the key as follows.

Rename your server.key file to the name server.key.bac and run the following command.

openssl rsa -in server.key.bac -out server.key

Now the server key can be signed with your CA using the server.csr file with the following command.

openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt

Please note that the certificate thus generated will only be valid for 356 days. After this period, a new certificate must be generated again. When doing so, do not forget to set a new serial key (Eg:  -set_serial 02 ). Now a CA signed certificate has been established in server.crt file.

With everything ready, the Apache server can now be set to enable SSL. It is simply a matter of editing a few configuration files in it. This can be carried out by following this step by step procedure. In your server's configuration directory, there is a sub-directory called extra. This is where Apache has its extra configuration files. In this folder is a file called httpd-ssl.conf which has the SSL configuration settings. Change this file to the following settings to point to the files just created. For example:

SSLCertificateFile "C:/Program Files/Apache Software Foundation/Apache2.2/conf/keys/server.crt"

SSLCertificateKeyFile "C:/Program Files/Apache Software Foundation/Apache2.2/conf/keys/server.key"

SSLCACertificateFile "C:/Program Files/Apache Software Foundation/Apache2.2/conf/keys/ca.crt"

SSLVerifyClient require

SSLVerifyDepth 1

Save this file with the changes that have been made and open the httpd.conf file positioned inside the configuration directory.  httpd.conf is the main configuration file for an Apache Web server. In this, the mod_ssl apache module must be enabled and the httpd-ssl.conf file included in it. This can be done as follows. Uncomment the following lines in your httpd.conf file.

LoadModule ssl_module modules/mod_ssl.so

Include conf/extra/httpd-ssl.conf

Now, it's time to deploy Apache Axis2/C in Apache HTTPD server. Add the following entries to httpd.conf file and save the changes:

LoadModule axis2_module "modules/mod_axis2.dll"

Axis2RepoPath "C:/axis2c/build/axis2c-bin-1.5.0-win32"

Axis2LogFile "C:/axis2c/build/axis2c-bin-1.5.0-win32/logs/axis2.log"

Axis2LogLevel debug

Axis2MaxLogFileSize 10

<Location /axis2>

 SetHandler axis2_module

</Location>

Please note that the above settings are for a server in a Windows system. You will have to change mod_axis2.dll to mod_axis2.so and the corresponding directory paths accordingly if you are using a Linux system.

Now copy the mod_axis2.dll/mod_axis2.so file into the Apache's modules folder. Start the Apache server to check whether everything has been configured correctly. If you have any problem starting Apache, please verify whether the configurations are correct.

Configuring Axis2/C clients to communicate through SSL

In this section, the client side configuration of Axis2/C to allow Axis2/C clients to communicate through a secured channel, will be discussed. For this, the client needs a private key and a certificate file signed by a trusted CA. As a self-signed CA has already been created, this can be used to sign our client certificate.

First, generate a private key for the client and have it signed by the CA already created. The following commands, which are the same ones used for the server side, will do this.  Therefore, please refer to the earlier commands for all the steps.

openssl genrsa -des3 -out client.key 4096

openssl req -new -key client.key -out client.csr

openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out client.crt

At this stage, a client key and a client.crt file in the location the above commands have been run, have been created. Using these files, it is necessary to create a certificate chain file to configure it with Axis2/C. Certificate Chain file is a file which contains the certificate and the relevant private key.  A certificate chain file can be created by simply concatenating the certificate and the private key. With a Linux system, simply run the following command to perform that.

cat client.crt client.key > client.pem

If you are in Windows, simply copy the contents of client.crt file and client.key file into a single file client.pem. Now that you have created all the necessary files, configuration of the Axis2/C client side can proceed by editing axis2.xml file which can be found in the Axis2/C home directory.

Uncomment the following sections in the axis2.xml file to enable https transport in Axis2/C.

<transportReceiver name="https" class="axis2_http_receiver">

 <parameter name="port" locked="false">6060</parameter>

 <parameter name="exposeHeaders" locked="true">false</parameter>

</transportReceiver>

<transportSender name="https" class="axis2_http_sender">

 <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>

</transportSender>

Then set the following parameters under Transport Outs section.

SERVER_CERT     - This should be pointed to the CA certificate by which your server.crt is signed.

KEY_FILE        - This should be pointed to your Certificate Chain file

SSL_PASSPHRASE  - The pass phrase of the client key

<parameter name="SERVER_CERT">C:\keys\ca.crt</parameter>

<parameter name="KEY_FILE">C:\keys\client.pem</parameter>

<parameter name="SSL_PASSPHRASE">passphrase</parameter>

Please note that the KEY_FILE and SSL_PASSPHRASE parameters need to be set only if you specify 'SSLVerifyClient' option as required in your httpd-ssl.conf file.

Congratulations.  Axis2/C SSL has been configured successfully.  A simple sample client will verify whether everything has been configured successfully. In the following section,  an echo sample which comes with Axis2/C distribution to communicate with the sample Web Service echo in SSL, was used.

Invoking a client with SSL

In the previous sections, the Axis2/C server side and the client side with SSL enabled were configured and deployed.   A simple web service client can now be run against an SSL enabled web service as a trial. To demonstrate this,   echo service and echo client will be used which come as samples with Axis2/C distributions. The echo service can be found in <AXIS2C_HOME>\services\echo folder and the echo client can be found in <AXIS2C_HOME>\bin\samples directory. The source code for these samples can be found in <AXIS2C_HOME>\samples directory.

Now to trial run the sample with SSL. First, start the apache server. This will host Axis2/C sample services through a local host. Then invoke the echo sample client in a secured manner. To do that, go to <AXIS2C_HOME>\bin\samples from the command prompt and execute the following command.

For Linux

 ./echo https://localhost/axis2/services/echo

For Windows

echo.exe https://localhost/axis2/services/echo

Please note that the endpoint URL for the service with the prefix https, which means communication, will be through the secure socket layer. The following output can be found in the command prompt indicating that you have successfully communicated securely with a Web service.

Using endpoint : https://localhost/axis2/services/echo

Sending OM : <ns1:echoString xmlns:ns1="http://ws.apache.org/axis2/services/echo"><text>Hello World!</text></ns1:echoString>

Received OM : <ns1:echoString xmlns:ns1="http://ws.apache.org/axis2/c/samples"><text>Hello World!</text></ns1:echoString>

echo client invoke SUCCESSFUL!

Sending OM : <ns1:echoString xmlns:ns1="http://ws.apache.org/axis2/services/echo"><text>Hello World!</text></ns1:echoString>

Received OM : <ns1:echoString xmlns:ns1="http://ws.apache.org/axis2/c/samples"><text>Hello World!</text></ns1:echoString>

echo client invoke SUCCESSFUL!

Summary

In this article, how to host an Axis2/C Web service secured with SSL and how to communicate with a web service which is protected with SSL, has been discussed. With the proven interoperability of Axis2/C, appropriate parties can successfully communicate with SSL enabled Web services implemented in .NET, Java and other WS-* compliant Web service platforms.

Author

Dushshantha Chandradasa , Senior Software Engineer- QA , dushshantha at wso2 dot com

About Author

  • Dushshantha Chandradasa
  • Senior Engineer - Software Engineering
  • Highmark Health Services