Apache Rampart/C Installation Guide

This document guides you on how to install Rampart/C.

You must have OpenSSL 0.9.8 (or above) installed in you system.

This release comes in two forms, source and binary. This document covers both forms.

Please send your feedback to the developer mailing list: rampart-c-dev@ws.apache.org (Subscription details are available on the Rampart/C site.

1. Installing and Running on Linux

This can be done using binary or source distributions. (Download the two distributions)

1.1. Installing the Binary Distribution

The following steps have to be followed to install and run the Rampart/C binary distribution on Linux :

  1. Extract the binary tar package to a folder.
  2. Set the AXIS2C_HOME environment variable pointing to the location where you have extracted Axis2/C
    • AXIS2C_HOME='/your_path_to_axis2c'
    • export AXIS2C_HOME
  3. Copy modules/rampart to $AXIS2C_HOME/modules
  4. Copy lib/* to $AXIS2C_HOME/lib
  5. Copy bin/samples/server/sec_echo to $AXIS2C_HOME/services/
  6. Copy bin/samples/* to $AXIS2C_HOME/bin/samples/rampart. This will copy callback modules etc
  7. Engage Rampart/C as specified in the section Engage Rampart/C with Axis2/C
  8. Go to bin/samples/client/sec_echo/ and deploy the client repo
    %sh deploy_client_repo.sh
  9. Go to bin/samples/secpolicy/ and try a scenario
     %sh test_scen.sh scenarioX server-port

1.2. Installing the Source Distribution

The following steps have to be followed to install and run Rampart/C using the source distribution on Linux :

  1. Extract the source tar package to a folder.
  2. Set the AXIS2C_HOME environment variable pointing to the location where you want to install Axis2/C
    • AXIS2C_HOME='/your_desired_path_to_axis2c_installation'
    • export AXIS2C_HOME
  3. Then go to the folder where you extracted the source.
  4. Build the source
    • This can be done using the following command sequence, in the directory where you have extracted the source:
      • ./configure --prefix=${AXIS2C_HOME} --enable-static=no --with-axis2=${AXIS2C_HOME}/include/axis2-1.2
      • make
      • make install
    • Please run "./configure --help" in the samples folder for more information on the configure options.
  5. Engage Rampart/C as specified in the section Engage Rampart/C with Axis2/C
  6. If you need to try samples,first you need to build them. Go to samples and run the script build.sh
    	%sh build.sh
    	
  7. Then go to samples/secpolicy and try a scenario
    	%sh test_scen.sh scenarioX server-port
    	

2. Installing and Running on Microsoft Windows

This too can be done using binary or source distributions. (Download the two distributions.)

2. 1. Installing the Binary Distribution

  1. Extract the binary distribution to a folder of your choice. (example: C:\rampartc).
  2. Copy modules\rampart to %AXIS2C_HOME%\modules.
  3. Engage Rampart/C as specified in the section Engage Rampart/C with Axis2/C.
  4. Copy samples\server\sec_echo to %AXIS2C_HOME%\services
  5. Start the axis2_http_server and run the echo client in the samples\client\sec_echo to consume the secured service.

2. 2. Installing Source Distribution

2.2.1. Requirements

  • The makefile shipped with this version needs Microsoft Visual Studio Compiler (cl) and the nmake build tool.
  • (Note: You can download the Microsoft VSExpress2005 edition and Platform SDK from the Microsoft Web site. You will need to add the path to the Platform SDK Include and Lib folders to the makefile)

2.2.2. Compiling the Source

The following steps will take you through the source compilation.

  • Extract the source distribution to a folder of your choice. (Example: C:\rampartc)
  • Edit the configure.in file to specify the Axis2/C repository path and the OpenSSL installation path
  • Open a DOS shell
  • cd C:\rampartc\build\win32
  • to access .Net tools, run
    • C:\rampartc\build\win32\> vcvars32.bat

    (Note: You may have to set the PATH environment variable to vcvars32.bat if MS Windows gives an error indicating that it cannot find this batch file. This file is located in <your MS Visual Studio install Directory>\VC\bin directory.)

  • Set the patameters in the configure.in
    • AXIS2_BIN_DIR = path/to/where/you/have/installed/axis2
    • OPENSSL_BIN_DIR = path/to/where/you/have/installed/openssl
    • DEBUG = 1 if enabled, 0 otherwise
  • To build the system and create the binary files in a directory named deploy under the build directory,
    • C:\rampartc\build\win32>nmake install
  • Engage Rampart/C as specified in the section Engage Rampart/C with Axis2/C
  • Start the axis2_http_server and run the echo client in the samples/client/sec_echo to consume the secured service

Engage Rampart/C with axis2/C

You can engage Rampart/C in global level or in service level.

Just add the following entry either to axis2.xml(gloabl level) or in services.xml(service level) corresponding to the service you want to secure.

   
   <module ref="rampart"/>


Also you need to add follwoing phase under <phaseOrder type="outflow">

   <phaseOrder type="outflow">
        <!-- Other Phases-->
        <phase name="Security"/>
   </phaseOrder>

Apart from that you must define security policies for the client and the server.



CLIENT SIDE:

In the client side just drop a policy.xml file to the same location(client-repo) where you have the axis2.xml.



SERVER SIDE:

Add WS-Security Policy assertions to the services.xml.

NOTE: Please find sample security policy files that are located under samples/secpolicy

You may go through each and every scenario and see how Rampart/C is configured using the policy assertions available in respective policy files.

For each scenario there are two files

  1. client-policy.xml : Defines what the security configurations are for the client using security policies
  2. services.xml : Defines what the security configurations are for a particular service using security policies

NOTE: If you have changed a client's policy file, make sure that you change the corresponding policy assertions in the services.xml file as well, and vise versa.

NOTE: To try out samples, use the client available under samples/client/sec_echo

Usage: echo [address] [client_repo]