Security in WSO2 WSF/C

Submitted on January 21, 2008 - 04:13. Story :

Tutorials

Level :

Introductory

Project :

WSF > C

Realm :

WS-Specifications

This tutorial by Malinda Kaushalye Kapuruge is an extension to his previous tutorial titled "Dummy's guide to WSO2 WSF/C". It is expected that you complete that tutorial before starting with this one. Here, we will discuss how to secure SOAP messages using the WSO2 WSF/C framework.

Applies To

WSO2 WSF/C	1.2.0
Environment	Linux - Debian, Ubuntu, Fedora, Windows

Prerequisites
Install WSO2 WSF/C with Rampart/C
The Module Deployed
Your Secured Service
Security Policies, Defining the Behavior
Writing a Secured Client
Trying Security Samples
- Service
- Client
- Run
Conclusion

Prerequisites

In order to follow this tutorial, the following packages must be installed in your system:

Libxml2 - http://www.xmlsoft.org/
libiconv - http://www.gnu.org/software/libiconv/(If UNIX)
zlib - http://www.zlib.net/
Microsoft VSExpress2005 edition and Platform SDK (If Win32)
OpenSSL - http://www.openssl.org/
WSO2 WSF/C - http://wso2.org/project/wsf/c

Install WSO2 WSF/C with Apache Rampart/C

Please refer the section "Setting WSF/C in your machine" in the tutorial titled "Dummy's guide to WSO2 WSF/C" for detailed instructions. By default, Apache Rampart/C, which is the security module of WSF/C is installed with the framework.

Alternatively, you may refer the Installation Guide here.

The Module Deployed

Once installed, WSF/C framework will copy the Rampart module to WSFC_HOME/modules directory. Along with that you'd see a bunch of other modules too. If you go to WSFC_HOME/modules/rampart, you will see the libraries and another file named module.xml that defines the phases Rampart handlers should be resident. To understand more on modules, handlers and phases in Axis2/C, please refer this article.

In the module.xml file, you'll see that we have added a phase called Security for the outflow (i.e the Outgoing message flow). This is a phase unique to Rampart/C. So please open the file named WSFC_HOME/axis2.xml and see whether the "Security" phase is defined for the outflow as given below:

<phaseOrder type="outflow">
        <phase name="RMPhase"/>
        <phase name="SavanPhase"/>
        <phase name="userphase1"/>
        <phase name="MessageOut"/>
        <phase name="Security"/>
    </phaseOrder>

Your Secured Service

Now, it is time to get your hands dirty by writing a secured service. The best place to start is with the sample security service available with WSF/C.

Go to the directory WSFC_HOME/rampartc/samples/server/sec_echo. The service is a simple one. It echoes the name of the first element included in the body of a SOAP request. The directory contains source code for the service and a descriptor file called services.xml. If you need to check whether a particular service is secured or not, this is the file you need to open. So go ahead and open it with a suitable text editor such as notepad or vi.

<service name="sec_echo">
    <parameter name="ServiceClass" locked="xsd:false">sec_echo</parameter>
    <description>
        This is a testing service , to test Rampart/C [Security] functionalities.
    </description>
    <operation name="echoString">
            <parameter name="wsamapping">http://example.com/ws/2004/09/policy/Test/EchoRequest</parameter>
    </operation>
    <module ref="rampart"/>
    <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
     <!--lines removed for clarity-->
    </wsp:Policy>
</service>

Note the following within the file:

Service name is sec_echo
Service module name is sec_echo (sec_echo.dll or libsec_echo.so)
Service has a description, so that the consumers know what the service does.
Service has only one operation called echoString.

Above properties can be seen in any service descriptor deployed with WSF/C that use Axis2/C as the Web services engine. Your service may contain different properties with multiple operations. But the structure should remain the same.

Now, our listing has a few additional properties that I have given in bold text.

The service has engaged the rampart module
Service has defined it's policies

These properties are the only differences between a secured services and a non-secured one. The interesting fact here is that you do not have to make any changes to the existing service code. This means that if you have deployed a service and think that you need to secure it, all you have to do is to add properties listed below to the service descriptor:

<module ref="rampart"/>

What the line above says is as a request arrives that it should first go through the Rampart module. In other words, the request in question must be approved by the security module before it actually invokes a particular business logic.

Your security requirements may vary from one service to another. In some services you may need authentication and in some others you may need to check the integrity of an incoming SOAP message.

In any case, your requirements or very specifically, the policies, should be defined in the same service descriptor file.

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
     <!--lines removed for clarity-->
    </wsp:Policy>

Security Policies, Defining the Behavior

The security module for WSF/C behaves according to the configurations defined in security policy. These policies fall into two categories.

Policies defined by the WS-Security policy specification
Policies specific to the WSF/C security module

The first category of policies confirms to the WS-Security Policy specification. Understanding these policies and how to structure them in a policy document needs time and effort. As a WSF/C user, you do not need to go through this process. WSF/C has packed such policy files according to different security requirements such as authentication, confidentiality, integrity etc. There are a couple of different scenarios available under WSFC_HOME/rampartc/samples/secpolicy. In each and every scenario, you find a services.xml file. Open the README file along with these sample scenarios and you'll see a short description that defines what each scenario does. For example, scenario3 gives you the security policy configurations for message level encryption.

The second category of policies are mainly for local settings. These policies are defined by the WSF/C security module and usually contains information such as, where to feed the certificates/keys, the valid duration (time to live) of a message etc. Following is an example of such a policy. It defines where to load the service's certificate:

<rampc:ReceiverCertificate>/WSFC_HOME/bin/samples/rampart/keys/bhome/alice_cert.cert</rampc:ReceiverCertificate>

At most times, it is necessary to combine both kinds of policies to enforce a particular security requirement. For example, if a service requests Username token based authentication, then the service deployer has to have a combination of both a custom policy (for password callback module) and a standard policy (for enforcing username tokens).

<!--Standard policy Enforcing Username tokens-->
<wsp:Policy>
    <sp:UsernameToken sp:IncludeToken="http://.../IncludeToken/Always"/>
</wsp:Policy>
 ...
<!--Custom policy for the password callback module-->
<rampc:PasswordCallbackClass>WSFC_HOME/bin/samples/rampart/callback/libpwcb.so</rampc:PasswordCallbackClass>

Writing a Secured Client

So far we have seen how to secure a service deployed with WSF/C. Now it's time to write a client to invoke the service. If a particular service comes with security requirements, the client must abide by those requirement. For instance, let's say that a service requires the message to be signed, then, the client must do so. In WS-Security terms, the client's policies must tally with the service's policies. Otherwise, a SOAP fault will be thrown from the service.

OK. For our convenience WSF/C has a sample client that shows how to enable security in WSFC_HOME/rampartc/samples/client/sec_echo. Go to the directory and open the file named echo.c. In order to write a secure client, follow steps given below:

Create a service client

svc_client = axis2_svc_client_create(env, client_home);

Set options, such as endpoint address and SOAP action

options = axis2_options_create(env);
 	axis2_options_set_to(options, env, endpoint_ref);
    	axis2_options_set_action(options, env,
            "http://example.com/ws/2004/09/policy/Test/EchoRequest");
	axis2_svc_client_set_options(svc_client, env, options);

Create policy object and set it to the service client

policy = neethi_util_create_policy_from_file(env, policy_file_name);
	axis2_svc_client_set_policy(svc_client, env, policy)

Engage the security module

axis2_svc_client_engage_module(svc_client, env, "rampart");

Write your code to build the payload. i.e. the body of your SOAP message that carries your business logic to the service
```
payload = build_om_payload_for_echo_svc(env);
```

Send the message

ret_node = axis2_svc_client_send_receive(svc_client, env, payload);

Note that from above list, only step 3 and step 4 are the additional steps that you have to take to secure a client request. Also note that in the step 3 we are giving a policy file name as a string argument to the function neethi_util_create_policy_from_file(). Here the policy_file_name is the file name for your policy configurations on the client side. If we recall the service's equivalent of this, there we added our policies to the service descriptor file but for the client side, we place them in separate file. You may find such client policy files for each and every security requirement in the scenarios available under WSFC_HOME/rampartc/samples/secpolicy.

Trying Security Samples

For this, we will use the encryption sample available with the WSF/C security module. Once you build WSFC samples, the security module is copied to the WSFC_HOME/modules/rampart directory. And the sample security service (sec_echo) is deployed under WSFC_HOME/services/sec_echo. The client sample is available under WSFC_HOME/bin/samples/rampart/client/sec_echo.

Service

And now, we have all of the basic components in place to start our experiment with policies.

First, we need to setup our service's policy to enforce encryption. In other words, our service must expect an encrypted SOAP body from it's consumers. For this we will use scenario 3 given in samples/secpolicy. Copy the file to the service location.

%cd WSFC_HOME/bin/samples/rampart/secpolicy
%cp scenario3/services.xml  WSFC_HOME/services/sec_echo/services.xml

When you open the file, you will see that there is a policy as the one given below. This means that the service needs the SOAP body to be encrypted.

<sp:EncryptedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
          <sp:Body/>
    </sp:EncryptedParts>

Also, you need to replace the correct path to your WSFC_HOME. As an example, simply replace the string to specify the sample certificate.

<rampc:Certificate>WSFC_HOME/bin/samples/rampart/keys/bhome/bob_cert.cert</rampc:Certificate>

<rampc:Certificate>/home/bob/wsfc/deploy/bin/samples/rampart/keys/bhome/bob_cert.cert</rampc:Certificate>

Client

Now the service is secure. It's time to specify the client's policies. We keep all our client's modules libraries and logs under one repository. This is by default WSFC_HOME/client_repo.

Copy the client's policy file to client's repository.

%cd WSFC_HOME/bin/samples/rampart/secpolicy
%cp scenario3/client-policy.xml WSFC_HOME/client_repo/policy.xml

Open the file and you'll see almost the same policy configurations are in the policy.xml file too. Then change the WSFC_HOME settings as mentioned before.

OK now all the bits and pieces are set. Get ready to push the button.

Run

Start the server...

%cd  WSFC_HOME/bin
%%./axis2_http_server

Run the client...

%cd  WSFC_HOME/bin/samples/rampart/client/sec_echo
%./echo http://localhost:9090/axis2/services/sec_echo/echoString WSFC_HOME/client_repo

If you see a message that reads the service invokation is successful, this means you have done everything right. If not, verify that you have gone through all of the steps once again. Moreover, you might be wondering what exactly the WSF/C security module does. To understand that you need to see the actual wire content. This is where a TCPMonitor tool comes handy. See, how to spy wire content using TCPMonitor here.

The sample shows the encryption scenario. There are twelve other scenarios shipped with the WSF/C distribution that you can try yourself.

Conclusion

This tutorial is an introduction to the security module available with the WSF/C distribution. The tutorial explains how easy it is to secure SOAP messages with very little effort. For this, we need to change certain configurations both on the client as well as the service provider.