| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia at 30 Jul 2017 |
| | Rendered using Apache Maven Fluido Skin 1.4 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <meta name="Date-Revision-yyyymmdd" content="20170730" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| <title>Apache Rampart – </title> |
| <link rel="stylesheet" href="./css/apache-maven-fluido-1.4.min.css" /> |
| <link rel="stylesheet" href="./css/site.css" /> |
| <link rel="stylesheet" href="./css/print.css" media="print" /> |
| |
| |
| <script type="text/javascript" src="./js/apache-maven-fluido-1.4.min.js"></script> |
| |
| |
| </head> |
| <body class="topBarDisabled"> |
| |
| |
| |
| <div class="container-fluid"> |
| <div id="banner"> |
| <div class="pull-left"> |
| <div id="bannerLeft"> |
| <img src="images/apache-rampart-logo.jpg" /> |
| </div> |
| </div> |
| <div class="pull-right"> <a href="http://www.apache.org" id="bannerRight"> |
| <img src="http://www.apache.org/images/asf_logo_wide.png" /> |
| </a> |
| </div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| |
| |
| <li id="publishDate">Last Published: 30 Jul 2017 |
| <span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 1.7.1 |
| </li> |
| |
| |
| |
| |
| |
| <li class="pull-right"> |
| <a href="../core/" title="Apache Axis2/Java"> |
| Apache Axis2/Java</a> |
| </li> |
| |
| </ul> |
| </div> |
| |
| |
| <div class="row-fluid"> |
| <div id="leftColumn" class="span2"> |
| <div class="well sidebar-nav"> |
| |
| |
| <ul class="nav nav-list"> |
| <li class="nav-header">Apache Rampart</li> |
| |
| <li> |
| |
| <a href="index.html" title="Home"> |
| <span class="none"></span> |
| Home</a> |
| </li> |
| |
| <li> |
| |
| <a href="javascript:void(0)" title="Downloads"> |
| <span class="icon-chevron-down"></span> |
| Downloads</a> |
| <ul class="nav nav-list"> |
| |
| <li> |
| |
| <a href="download.html" title="Releases"> |
| <span class="none"></span> |
| Releases</a> |
| </li> |
| |
| <li> |
| |
| <a href="svn.html" title="Source Code"> |
| <span class="none"></span> |
| Source Code</a> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| |
| <a href="javascript:void(0)" title="Release Notes"> |
| <span class="icon-chevron-down"></span> |
| Release Notes</a> |
| <ul class="nav nav-list"> |
| |
| <li> |
| |
| <a href="release-notes/1.6.1.html" title="1.6.1"> |
| <span class="none"></span> |
| 1.6.1</a> |
| </li> |
| |
| <li> |
| |
| <a href="release-notes/1.6.2.html" title="1.6.2"> |
| <span class="none"></span> |
| 1.6.2</a> |
| </li> |
| |
| <li> |
| |
| <a href="release-notes/1.6.3.html" title="1.6.3"> |
| <span class="none"></span> |
| 1.6.3</a> |
| </li> |
| |
| <li> |
| |
| <a href="release-notes/1.6.4.html" title="1.6.4"> |
| <span class="none"></span> |
| 1.6.4</a> |
| </li> |
| |
| <li> |
| |
| <a href="release-notes/1.7.0.html" title="1.7.0"> |
| <span class="none"></span> |
| 1.7.0</a> |
| </li> |
| |
| <li> |
| |
| <a href="release-notes/1.7.1.html" title="1.7.1"> |
| <span class="none"></span> |
| 1.7.1</a> |
| </li> |
| </ul> |
| </li> |
| <li class="nav-header">Documentation</li> |
| |
| <li> |
| |
| <a href="quick-start.html" title="Getting Started"> |
| <span class="none"></span> |
| Getting Started</a> |
| </li> |
| |
| <li> |
| |
| <a href="samples.html" title="Samples"> |
| <span class="none"></span> |
| Samples</a> |
| </li> |
| |
| <li> |
| |
| <a href="http://wiki.apache.org/ws/FrontPage/Rampart/FAQ" class="externalLink" title="FAQ"> |
| <span class="none"></span> |
| FAQ</a> |
| </li> |
| |
| <li> |
| |
| <a href="rampartconfig-guide.html" title="Rampart Configuration"> |
| <span class="none"></span> |
| Rampart Configuration</a> |
| </li> |
| |
| <li> |
| |
| <a href="setting-up-sts.html" title="STS Configuration"> |
| <span class="none"></span> |
| STS Configuration</a> |
| </li> |
| |
| <li class="active"> |
| |
| <a href="#"><span class="none"></span>Developer Guide</a> |
| </li> |
| |
| <li> |
| |
| <a href="siteHowTo.html" title="Build the Site"> |
| <span class="none"></span> |
| Build the Site</a> |
| </li> |
| <li class="nav-header">Resources</li> |
| |
| <li> |
| |
| <a href="articles.html" title="Articles"> |
| <span class="none"></span> |
| Articles</a> |
| </li> |
| |
| <li> |
| |
| <a href="specifications.html" title="Specifications"> |
| <span class="none"></span> |
| Specifications</a> |
| </li> |
| |
| <li> |
| |
| <a href="apidocs/index.html" title="Online Javadocs"> |
| <span class="none"></span> |
| Online Javadocs</a> |
| </li> |
| <li class="nav-header">Project Information</li> |
| |
| <li> |
| |
| <a href="team-list.html" title="Project Team"> |
| <span class="none"></span> |
| Project Team</a> |
| </li> |
| |
| <li> |
| |
| <a href="http://issues.apache.org/jira/browse/Rampart" class="externalLink" title="Issue Tracking"> |
| <span class="none"></span> |
| Issue Tracking</a> |
| </li> |
| |
| <li> |
| |
| <a href="mail-lists.html" title="Mailing Lists"> |
| <span class="none"></span> |
| Mailing Lists</a> |
| </li> |
| |
| <li> |
| |
| <a href="http://svn.apache.org/viewvc/axis/axis2/java/rampart/" class="externalLink" title="Source Code"> |
| <span class="none"></span> |
| Source Code</a> |
| </li> |
| |
| <li> |
| |
| <a href="http://www.apache.org/licenses/" class="externalLink" title="License"> |
| <span class="none"></span> |
| License</a> |
| </li> |
| |
| <li> |
| |
| <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"> |
| <span class="none"></span> |
| Sponsorship</a> |
| </li> |
| |
| <li> |
| |
| <a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"> |
| <span class="none"></span> |
| Thanks</a> |
| </li> |
| |
| <li> |
| |
| <a href="http://www.apache.org/security/" class="externalLink" title="Security"> |
| <span class="none"></span> |
| Security</a> |
| </li> |
| </ul> |
| |
| |
| |
| <hr /> |
| |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /> |
| </a> |
| </div> |
| </div> |
| </div> |
| |
| |
| <div id="bodyColumn" class="span10" > |
| |
| <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> |
| |
| <hr/> |
| |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p >Copyright © 2005–2017 |
| <a href="http://www.apache.org">Apache Software Foundation</a>. |
| All rights reserved. |
| |
| </p> |
| </div> |
| |
| |
| </div> |
| </footer> |
| </body> |
| </html> |