| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- Generated by Apache Maven Doxia Site Renderer 1.6 at 10 Dec 2015 --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| <title>Apache Rampart – </title> |
| <style type="text/css" media="all"> |
| @import url("./css/maven-base.css"); |
| @import url("./css/maven-theme.css"); |
| @import url("./css/site.css"); |
| </style> |
| <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" /> |
| <meta name="Date-Revision-yyyymmdd" content="20151210" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| |
| </head> |
| <body class="composite"> |
| <div id="banner"> |
| <a href="images/apache-rampart-logo.jpg" id="bannerLeft"> |
| Apache Rampart |
| </a> |
| <a href="http://www.apache.org" id="bannerRight"> |
| <img src="http://www.apache.org/images/asf_logo_wide.png" alt="$alt" /> |
| </a> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="breadcrumbs"> |
| |
| |
| <div class="xleft"> |
| <span id="publishDate">Last Published: 10 Dec 2015</span> |
| | <span id="projectVersion">Version: 1.6.3</span> |
| </div> |
| <div class="xright"> <a href="../core/" title="Apache Axis2/Java">Apache Axis2/Java</a> |
| |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="leftColumn"> |
| <div id="navcolumn"> |
| |
| |
| <h5>Apache Rampart</h5> |
| <ul> |
| <li class="none"> |
| <a href="index.html" title="Home">Home</a> |
| </li> |
| <li class="expanded"> |
| <a href="javascript:void(0)" title="Downloads">Downloads</a> |
| <ul> |
| <li class="none"> |
| <a href="download.html" title="Releases">Releases</a> |
| </li> |
| <li class="none"> |
| <a href="svn.html" title="Source Code">Source Code</a> |
| </li> |
| </ul> |
| </li> |
| <li class="expanded"> |
| <a href="javascript:void(0)" title="Release Notes">Release Notes</a> |
| <ul> |
| <li class="none"> |
| <a href="release-notes/1.6.1.html" title="1.6.1">1.6.1</a> |
| </li> |
| <li class="none"> |
| <a href="release-notes/1.6.2.html" title="1.6.2">1.6.2</a> |
| </li> |
| <li class="none"> |
| <a href="release-notes/1.6.3.html" title="1.6.3">1.6.3</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| <h5>Documentation</h5> |
| <ul> |
| <li class="none"> |
| <a href="quick-start.html" title="Getting Started">Getting Started</a> |
| </li> |
| <li class="none"> |
| <a href="samples.html" title="Samples">Samples</a> |
| </li> |
| <li class="none"> |
| <a href="http://wiki.apache.org/ws/FrontPage/Rampart/FAQ" class="externalLink" title="FAQ">FAQ</a> |
| </li> |
| <li class="none"> |
| <a href="rampartconfig-guide.html" title="Rampart Configuration">Rampart Configuration</a> |
| </li> |
| <li class="none"> |
| <a href="setting-up-sts.html" title="STS Configuration">STS Configuration</a> |
| </li> |
| <li class="none"> |
| <strong>Developer Guide</strong> |
| </li> |
| <li class="none"> |
| <a href="siteHowTo.html" title="Build the Site">Build the Site</a> |
| </li> |
| </ul> |
| <h5>Resources</h5> |
| <ul> |
| <li class="none"> |
| <a href="articles.html" title="Articles">Articles</a> |
| </li> |
| <li class="none"> |
| <a href="specifications.html" title="Specifications">Specifications</a> |
| </li> |
| <li class="none"> |
| <a href="apidocs/index.html" title="Online Javadocs">Online Javadocs</a> |
| </li> |
| </ul> |
| <h5>Project Information</h5> |
| <ul> |
| <li class="none"> |
| <a href="team-list.html" title="Project Team">Project Team</a> |
| </li> |
| <li class="none"> |
| <a href="http://issues.apache.org/jira/browse/Rampart" class="externalLink" title="Issue Tracking">Issue Tracking</a> |
| </li> |
| <li class="none"> |
| <a href="mail-lists.html" title="Mailing Lists">Mailing Lists</a> |
| </li> |
| <li class="none"> |
| <a href="http://svn.apache.org/viewvc/axis/axis2/java/rampart/" class="externalLink" title="Source Code">Source Code</a> |
| </li> |
| <li class="none"> |
| <a href="http://www.apache.org/licenses/" class="externalLink" title="License">License</a> |
| </li> |
| <li class="none"> |
| <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship">Sponsorship</a> |
| </li> |
| <li class="none"> |
| <a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks">Thanks</a> |
| </li> |
| <li class="none"> |
| <a href="http://www.apache.org/security/" class="externalLink" title="Security">Security</a> |
| </li> |
| </ul> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /> |
| </a> |
| |
| |
| </div> |
| </div> |
| <div id="bodyColumn"> |
| <div id="contentBox"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| |
| |
| <h1>Apache Rampart Developer Guide</h1> |
| |
| <div class="section"> |
| <h2><a name="Getting_Involved_in_Rampart"></a>Getting Involved in Rampart</h2> |
| |
| |
| <div class="section"> |
| <h3><a name="Introduction"></a>Introduction</h3> |
| |
| Components of Rampart |
| |
| <ul> |
| |
| <li>Rampart Core</li> |
| |
| <li>Rampart Policy</li> |
| |
| <li>Rampart Trust</li> |
| </ul> |
| |
| |
| <p></p> |
| <img src="images/security-stack.jpg" alt="Rampart Components and WS-Security Stack" title="Rampart Components and WS-Security Stack" align="middle" /> |
| |
| |
| <p><b><i>Figure 1 : Rampart Components and WS-Security |
| Stack</i></b></p> |
| |
| </div> |
| <div class="section"> |
| <h3><a name="Building_Rampart"></a>Building Rampart</h3> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li>Install maven2. Refer to the <a class="externalLink" href="http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html">Installation |
| guide</a>.</li> |
| |
| <li>Install SVN on your machine. (The Rampart repository uses SVN.) Please |
| read the ASF <a class="externalLink" href="http://www.apache.org/dev/version-control.html">Source Code |
| Repositories page.</a></li> |
| |
| <li>Download the source code. |
| |
| <ul> |
| |
| <li>Anon Checkout <a class="externalLink" href="http://svn.apache.org/repos/asf/axis/axis2/java/rampart/trunk/">http://svn.apache.org/repos/asf/axis/axis2/java/rampart/trunk/</a></li> |
| |
| <li>Committers <a class="externalLink" href="https://svn.apache.org/repos/asf/axis/axis2/java/rampart/trunk/">https://svn.apache.org/repos/asf/axis/axis2/java/rampart/trunk/</a></li> |
| </ul> |
| </li> |
| |
| <li>The Rampart project has 8 modules under it. They are: |
| |
| <ul> |
| |
| <li>rampart-policy contains security policy assertions.</li> |
| |
| <li>rampart-core has core components that process and enforce |
| security.</li> |
| |
| <li>rampart-trust contains trust components.</li> |
| |
| <li>rampart-mar builds the rampart.mar that is deployed in the |
| "modules" directory of the Axis2 repository.</li> |
| |
| <li>rampart-trust-mar builds the rahas.mar that adds WS-Trust into |
| Axis2.</li> |
| |
| <li>rampart-test has a set of unit test cases.</li> |
| |
| <li>integration-test has functional tests.</li> |
| |
| <li>rampart-samples consist of samples provided with the |
| distribution.</li> |
| </ul> |
| </li> |
| |
| <li>Build by typing <tt>$mvn clean install</tt></li> |
| </ol> |
| |
| |
| <p>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.</p> |
| |
| </div> |
| <div class="section"> |
| <h3><a name="Rampart_in_Axis2"></a>Rampart in Axis2</h3> |
| |
| |
| <p>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.</p> |
| |
| |
| <p></p> |
| <img src="images/rampart-handlers.jpg" alt="DOOM" title="Rampart in Axis2" align="middle" /> |
| |
| |
| <p><b><i>Figure 2 : Rampart in Axis2</i></b></p> |
| |
| |
| <p>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.</p> |
| |
| |
| <p>"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.</p> |
| |
| </div> |
| <div class="section"> |
| <h3><a name="Rampart_WSS4J_and_DOOM"></a>Rampart, WSS4J, and DOOM</h3> |
| |
| |
| <p>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 <a class="externalLink" href="http://www.w3.org/TR/xmlenc-core/">XML |
| Encryption</a> and <a class="externalLink" href="http://www.w3.org/TR/xmldsig-core/">XML Digital |
| Signature</a> 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 <a class="externalLink" href="http://santuario.apache.org/Java/index.html">xmlsec |
| libraries</a> for XML Encryption and XML Digital Signature.</p> |
| |
| |
| <p>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.</p> |
| |
| |
| <p>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.</p> |
| |
| </div> |
| <div class="section"> |
| <h3><a name="Rampart_Core"></a>Rampart Core</h3> |
| |
| |
| <p>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,</p> |
| |
| <ul> |
| |
| <li>org.apache.rampart.RampartEngine</li> |
| |
| <li>org.apache.rampart.MessageBuilder</li> |
| </ul> |
| |
| |
| <p><b>SOAP Message Inflow</b></p> |
| |
| |
| <p>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.</p> |
| <img src="images/rampart-engine.jpg" alt="Rampart Engine" title="Rampart Engine" align="middle" /> |
| |
| |
| <p><b><i>Figure 3: Control flow in RampartEngine</i></b></p> |
| |
| |
| <p><b>Note</b>: RampartMessageData stores |
| "org.apache.rampart.policy.RampartPolicyData", which contains security policy |
| in the manner required by "RampartEngine" and "MessageBuilder".</p> |
| |
| |
| <p><b>SOAP Message Outflow</b></p> |
| |
| |
| <p>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.</p> |
| <img src="images/message-builder.jpg" alt="Message Builder" title="Message Builder" align="middle" /> |
| |
| |
| <p><b><i>Figure 4: Control flow in MessageBuilder</i></b></p> |
| |
| </div> |
| <div class="section"> |
| <h3><a name="Rampart_Policy"></a>Rampart Policy</h3> |
| |
| |
| <p>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.</p> |
| |
| |
| <p>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.</p> |
| |
| |
| <p>The RampartPolicyBuilder creates a RampartPolicyData given a "Policy" |
| object created using the Rampart-policy and Neethi frameworks.</p> |
| |
| </div> |
| <div class="section"> |
| <h3><a name="Rampart_Trust"></a>Rampart Trust</h3> |
| |
| |
| <p>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.</p> |
| <img src="images/rampart-trust.jpg" alt="Rampart Trust" title="Rampart Trust" align="middle" /> |
| |
| |
| <p><b><i>Figure 5: Control flow in Rampart Trust</i></b></p> |
| |
| |
| <p></p> |
| |
| |
| <p></p> |
| |
| |
| <p></p> |
| </div> |
| </html> |
| </div> |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| <div id="footer"> |
| <div class="xright"> |
| Copyright © 2005–2015 |
| <a href="http://www.apache.org">Apache Software Foundation</a>. |
| All rights reserved. |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| </body> |
| </html> |