Apache Rampart Developer Guide
Getting Involved in Rampart
Introduction
Components of Rampart- Rampart Core
- Rampart Policy
- Rampart Trust
Figure 1 : Rampart Components and WS-Security Stack
Building Rampart
- Install maven2. Refer to the Installation guide.
- Install SVN on your machine. (The Rampart repository uses SVN.) Please read the ASF Source Code Repositories page.
- Download the source code.
- The Rampart project has 8 modules under it. They are:
- rampart-policy contains security policy assertions.
- rampart-core has core components that process and enforce security.
- rampart-trust contains trust components.
- rampart-mar builds the rampart.mar that is deployed in the "modules" directory of the Axis2 repository.
- rampart-trust-mar builds the rahas.mar that adds WS-Trust into Axis2.
- rampart-test has a set of unit test cases.
- integration-test has functional tests.
- rampart-samples consist of samples provided with the distribution.
- Build by typing $mvn clean install
When deploying rampart.mar and rampart-trust.mar in the Axis2 repository, you may notice that they do not contain any dependencies. Therefore all the dependencies must be in the classpath.
Rampart in Axis2
Rampart is deployed as a module in Axis2, in the security phase. The security phase is right after the transport phase. The Rampart module introduces a couple of handlers - "org.apache.rampart.handler.RampartReciever" and "org.apache.rampart.handler.RampartSender" to the security phase.
Figure 2 : Rampart in Axis2
The "RampartReciver" handler intercepts the incoming message. Then Rampart validates the security of the incoming message, and checks whether it is in-line with the specified security policy. All security actions such as decryption of the message, validating the digital signature, validating the timestamp, and authenticating the user happens inside the Rampart module.
"RampartSender" is the last handler in the outflow. The outgoing message is intercepted by this handler and Rampart takes the security actions. For example SOAP message can be encrypted, digitally signed, and security tokens are included according to the security policy.
Rampart, WSS4J, and DOOM
Rampart uses WSS4J for securing SOAP messages. WSS4J is an Apache project which implements the WS-Security specification. SOAP messages are signed and encrypted according to the XML Encryption and XML Digital Signature specifications, but the WS-Security specification introduces an additional set of rules. Therefore WSS4J ensures that SOAP messages are singed according to all the rules defined in the specifications. WSS4J uses Apache's xmlsec libraries for XML Encryption and XML Digital Signature.
Rather than re-inventing the wheel, it was decided to use WSS4J for SOAP message security in Rampart but there was a fundamental problem. WSS4J and all the incorporating XML security libraries use "DOM" for parsing and generating XML, while Axis2 uses "AXIOM" as the object model. This was resolved by using a new object model named "DOOM". DOOM is both AXIOM and DOM implementations. Therefore you can manipulate/access a DOOM object structure through DOM interfaces and AXIOM interfaces.
When Rampart is engaged and configured, the incoming SOAP messages are converted to DOOM. Since DOOM implements the DOM interface it is possible for WSS4J to process messages. After performing the security validations, before flushing the message down the message inflow, the DOOM SOAP message is converted back to OM. At the outgoing flow, the message is converted to DOOM and then the security functions are performed using WSS4J.
Rampart Core
Rampart core drives security enforcement and validation on SOAP messages. It binds all components together to create the final product. The important components of Rampart core are,
- org.apache.rampart.RampartEngine
- org.apache.rampart.MessageBuilder
SOAP Message Inflow
Incoming messages are intercepted by RampartReciver and handed over to the RampartEngine. RampartEngine is responsible for handling validation of security in the incoming SOAP message.
Figure 3: Control flow in RampartEngine
Note: RampartMessageData stores "org.apache.rampart.policy.RampartPolicyData", which contains security policy in the manner required by "RampartEngine" and "MessageBuilder".
SOAP Message Outflow
Outgoing messages are intercepted by RampartSender and handed over to org.apache.rampart.RampartMessageBuilder. It is responsible for enforcing security on an outgoing SOAP message.
Figure 4: Control flow in MessageBuilder
Rampart Policy
WS - Security Policy is an extension of WS-Policy specification. Corresponding to this, the implementation of the security policy in Rampart is based on "Neethi", which is the Apache implementation of WS Policy specification. For each policy assertion introduced in the WS-Security Policy, there is an "Assertion Builder" and an "Assertion Model" defined in Rampart-policy.
Apache Neethi is a highly extensible framework. When reading a security policy file, these builders and models in Rampart Policy are picked up by the Neethi framework using the "Jar file Service Provider Mechanism". All Rampart builders are listed in the META-INF/services/org.apache.neethi.builders.AssertionBuilder file. When adding a new Policy assertion it requires only a builder, assertion model, and an entry in the file.
The RampartPolicyBuilder creates a RampartPolicyData given a "Policy" object created using the Rampart-policy and Neethi frameworks.
Rampart Trust
Rampart Trust implements the WS-Trust specification, which can be used in-conjunction with the Rampart Core and Rampart Policy modules. Rampart Trust defines a framework that can be used to issue, cancel, renew, and validate tokens, i.e., it defines a set of interfaces that must be implemented by different token issuing parties. Basically, Rampart Trust provides the functionality needed to host a STS - Security Token Service.
Figure 5: Control flow in Rampart Trust