Rampart/C gives an Apache Axis2/C user a deployable module that can be used to secure SOAP messages. To get the maximum out of Rampart/C, it is vital to know how its components are designed. If required, you can extend the capabilities of Rampart/C, or customize Rampart/C according to the language platform. OMXMLSecurity is the XML Security library written on top of AXIOM used by Rampart/C. Let's take a look at the architecture of Rampart/C and OMXMLSecurity.
The motivation behind the implementation of Rampart/C is to let Axis2/C users secure their SOAP messages as per the WS-Security Specification 1.0 . With a little effort in the configuration setup, Axis2/C users can fulfill their SOAP message security requirements such as confidentiality, integrity, and authentication. The WS-Security specification provides a number of mechanisms to secure SOAP messages such as Encryption, Signature, UsernameToken, and Timestamps.
Rampart configurations are based on security policy assertions as per the WS-Security Policy specification 1.1. The specification allows users to define the requirements and constraints of their Web services. For example, if the message needs to be encrypted and signed etc., Rampart/C understands such policy assertions that are defined in configuration files. A violation of such a policy would result in a SOAP fault.
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 use Apache AXIOM  and Axis2-Util libraries. OpenSSL is used as the crypto library in OMXMLSecurity.
The interface between Rampart/C and the Apache Axis2/C engine is the Rampart module called mod_rampart. The module has two handlers, one for the inflow and the other for the outflow of the Axis2/C engine. Rampart/C directs messages to its 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.
The Rampart engine is the heart of Rampart/C. It sets security policies that define 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.
Rampart/C processes incoming SOAP messages using its processors. There are two processors in Rampart/C.
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 a set of builders that builds these models.
Rampart/C is configured using policy assertions defined in the WS-Security Policy specification 1.1. These policies are defined in policy.xml files. There are two policy files for a single Rampart configuration.
Rampart Utilities groups different entities that cater for different purposes. The following is a brief description of the main components inside Utilities.
For XML cryptographic purposes, Rampart/C uses OMXMLSecurity, which is a library written on top of Apache AXIOM. If a particular SOAP message has to be encrypted or signed, Rampart/C gets the work done through the OMXMLSecurity. The functionalities of OMXMLSecurity are as follows.
The above diagram shows the essential components that form the OMXMLSecurity library.
The encryption module has been implemented in two layers to separate the XML encryption from the data encryption. XML encryption does XML related processing such as serialization/de-serialization of XML elements, building necessary XML tokens, etc,. Also it renders special support for key encryption that's required by Rampart/C. The user has to create a context in which the necessary parameters for the encryption such as the algorithm is specified. Then a suitable function is called for either encryption or decryption.
The main functionalities in the signature module are to sign a node and verify an XML digital signature. Apart from that, it helps the users to process signature nodes and their references. For signing, a user has to create a signature context. A signature context keeps information that is related to one signature step. One signature step can have multiple signature parts. (In XML signature, if you need to sign multiple parts of a message, you have to create digests of each part and group these digests into on node called
<ds:SignedInfo>, which will be the actual node that is subjected to signing). These signature parts correspond to portions of the message that need to be signed. One signature part keeps the transformations required and the digest method.
In the verification process too, the user has to create a signature context and call the verify function. This time the signature context does not need to be populated, as it is done by scanning the
The Keys Manager module provides an easy to use interface for OMXMLSecurity users to load certificates and keys. The keys manager supports keys/certificates in the following formats.
The OpenSSL library provides various routines that implement the basic cryptographic functions. The openSSL wrapper layer gives a comprehensive API, hiding the complex routines that can be used for cryptographic purposes of OMXMLSecurity. This includes,
Different transformations have to be applied to the XML signature before creating the digital signature. OMXMLSecurity allows users to set their own transformations for signature parts. A transform structure is defined for these purposes. These transformations store their input/output forms and the behavior. A transform factory is implemented for users to retrieve predefined transforms such as exclusive canonicalization. A signature part may contain more than one transformation and will be applied in the order they are set.
In order to build/process XML elements that are required for XML-Encryption and XML-Signature, a token base is implemented. This token base covers all the AXIOM specific details in the process of creating tokens. For example if it's required to create the
<ds:KeyInfo> element, simply call the
Here the parent is the node that takes KeyInfo as a child.
The utility package contains a number of utility objects that are required for major functionalities of the library. This represents string buffers, keys, certificates, various contexts, and error representation.
The error representation in OMXMLSecurity, known as "oxs_error" defines the types of errors (e.g., Encryption failure, Signature failure, Unsupported Algorithm, etc.) that can occur. Once executed, it gives the error location, and type of error with the reason for the error.
A buffer represents a storage to keep data, and expands itself if the data size exceeds the maximum limit. This is quite useful to handle binary data.
Apache Rampart/C is the security module of the Apache Axis2/C engine. It uses OMXMLSecurity as the XML-Security library. Rampart/C's feature list includes support for UsernameTokens, Timestamps, Encryption, and Digital signature as per the WS-Security specification. Its configurations are based on the WS-Security policy. In the future, it is expected to support other security related specifications such as SAML, WS-Trust and WS-Secure conversation.
 WS-Security Specification 1.0- http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf
 WS-Security Policy specification 1.1- http://specs.xmlsoap.org/ws/2005/07/securitypolicy/ws-securitypolicy.pdf
 Apache Rampart/C- http://wso2.org/projects/rampart/c
 Apache Axis2/C - http://ws.apache.org/axis2/c
 PKCS#12 - http://www.openssl.org/docs/apps/pkcs12.html