# 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).

## Contents

- Installing and Running on Linux
  - Using the Binary Release
  - Using the Source Release
- Installing and Running on Microsoft Windows (win32)
  - Using the Binary Release
  - Using the Source Release
- Engage Rampart/C with Axis2/C

## 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 WSFCPP_HOME environment variable pointing to the location where you have extracted Axis2/C
   - WSFCPP_HOME='/your_path_to_axis2c'
   - export WSFCPP_HOME
3. Copy modules/* to $WSFCPP_HOME/modules/
4. Copy lib/* to $WSFCPP_HOME/lib
5. Copy services/* to $WSFCPP_HOME/services/
6. Copy samples/* to $WSFCPP_HOME/samples/. This will copy callback modules etc.
7. Engage Rampart/C as specified in the section Engage Rampart/C with Axis2/C
8. Go to samples/src/rampartc/client/ and deploy the client repo

       %sh deploy_client_repo.sh

9. Go to samples/src/rampartc/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 WSFCPP_HOME environment variable pointing to the location where you want to install Axis2/C
   - WSFCPP_HOME='/your_desired_path_to_axis2c_installation'
   - export WSFCPP_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=${WSFCPP_HOME} --enable-static=no --with-axis2=${WSFCPP_HOME}/include/axis2-1.6.0
     - 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. Set the WSFCPP_HOME envirionment variable to direct to your Axis2/C Installation.

    SET WSFCPP_HOME=[your-path-to-axis2c]

3. Run the deploy_rampart.bat that could be found in the root of the rampart binary distribution.
4. Engage Rampart/C as specified in the section Engage Rampart/C with Axis2/C.
5. Go to samples/src/rampartc/secpolicy/ and try a scenario

        test_scen.bat scenarioX server-port

### 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 VSExpress 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
  - 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
- 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.)

- 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
- Then go to samples/secpolicy and try a scenario

      	test_scen.bat scenarioX server-port

## 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"/>

If you want to provide Secure Token Service (STS) functionality to a service, add the following entry to services.xml.

<module ref="rahas"/>

Then add following "Security" phase to the phase order in the inflow and outflow in the axis2.xml. Also add "Rahas" phase to inflow.

        <phaseOrder type="inflow">
            <phase name="Transport"/>
            <phase name="PreDispatch"/>
            <phase name="Dispatch"/>
            <phase name="PostDispatch"/>
            <phase name="Security" />
            <phase name="Rahas"/>
        </phaseOrder>
        <phaseOrder type="outflow">
            <phase name="MessageOut"/>
            <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.