## Preamble

This document is intended to be a reference manual for Apache Rampart/C.

For further details on Axis2/C please refer the Apache Axis2/C manual

## Simplified Architecture

In a very simple view, Rampart/C consists of a core module and packages related to WS-Security and WS-Security Policy. For XML-Encryption and Signature Rampart/C uses OMXMLSecurity. Both Rampart/C and OMXMLSecurity uses Apache AXIOM and Axis2-Util libraries. OpenSSL is used as the crypto library in OMXMLSecurity.

## Interface with Axis2/C

The interface between Rampart/C and Apache Axis2/C engine is the Rampart module called mod_rampart. The module has two handlers, one for the inflow and another for the outflow of the Axis2/C engine. Rampart/C directs messages to it's other components for further security related processing using these handlers.

Handlers are a way of extending capabilities of the core engine. Once the Axis2/C engine calls the invoke() method of the handler, the module can do the necessary processing over the SOAP message. Rampart/C use this mechanism to build/process security related SOAP headers.

## Inside Rampart/C

Following is a detailed architecture diagram of Rampart/C

### Rampart Engine

Rampart engine is the heart of Rampart/C. It sets security policies that defines the behavior of Rampart/C message processing. These policies are usually read from a selected policy.xml file depending on the message flow, which contains a set of policy assertions.

### Processors and Builders

Rampart/C processes incoming SOAP message using it's processors. There are two processors in Rampart/C.

1. Security Header Processor : Processes security header of the incoming message and make decisions upon security claims and the security policies.
2. Token Processor : Processes token claims such as binary security token.

Similar to processes, Rampart/C uses two builders that builds outgoing messages.

1. Security Header Builder : Builds Security headers of an outgoing message depending on security policies.
2. Token Builder : Builds token claims such as binary security token.

These builders and processes assemble other components such as encryption, signature, UsernameToken together. Decisions are taken in these processes would result in further processing of the message or throwing of a SOAP fault.

### Policy

The policy module of Rampart/C acts as the configuration module in Rampart/C. The policy module has a set of models that represents assertions. Also there are set of builders that builds these models.

Rampart/C is configured using policy assertions defined in WS-Security Policy specification (1.1 or 1.2). These policies are defined in policy.xml files. The client side policies are defined in a seperate policy.xml file located in the client's repository. The service's policies are defined in the services.xml file.

### Rampart utilities

Rampart utilities groups different entities that cater for different purposes. Following is a brief description of major components inside utilities

- Rampart context: Keeps configurations for Rampart/C. This includes certificates, keys, passwords, policies etc.
- UsernameToken: Provides functionalities to build/process a UsernameToken.
- TimestampToken: Provides functionalities to build/process a TimestampToken.
- Authentication provider: The interface for authentication modules that can be plugged into Rampart/C. This allows users to define their own rules for processing user name / passwords.
- Credentials provider: An interface for a credentials module to be plugged in. Users can provide custom user name/password pairs to build user name tokens.
- Password callbacks: An interface for users to provide password for a given user name.

## OMXMLSecurity

For XML cryptographic purposes Rampart/C uses OMXMLSecurity, which is a library written on top of Apache AXIOM. If a particular SOAP message needs to be encrypted or signed, Rampart/C get the work done through the OMXMLSecurity. Following are the functionalities of OMXMLSecurity.

1. XML-Encryption / Decryption: This includes symmetric and asymmetric encryptions. Usually data is encrypted using a symmetric key (or a session key) which is again encrypted using an asymmetric algorithm using a public key.
2. XML-Signature / Verification: Allows one or more part of an XML document to be signed using a private key. Also allows these signed parts to be verified.
3. Key management: To load X509 certificates, Private keys etc, the Key management interface provide a series of functions. Keys might be stored in PEM files, PKCS12 key stores or can be in string buffers.
4. Canonicalization: Provide Canonicalization (C14N) transform support.
5. Creating/Processing tokens: There are number of XML elements that are introduced by security specifications. The token base in OMXMLSecurity provides functionalities to create/process such elements.

Following diagram shows the architecture of OMXMLSecurity

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