Google Git
Sign in
apache / axis-site / f7bdbce8f5178add02522fdbf11ca5350d8eef03 / . / axis2 / java / rampart-staging / developer-guide.html
blob: 4b6620ab21ab62c9f5ee796e5ce825be87ae483b [file] [log] [blame]
<!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 &#x2013; </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
&quot;modules&quot; 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 -
&quot;org.apache.rampart.handler.RampartReciever&quot; and
&quot;org.apache.rampart.handler.RampartSender&quot; 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 &quot;RampartReciver&quot; 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>&quot;RampartSender&quot; 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 &quot;DOM&quot; for parsing and
generating XML, while Axis2 uses &quot;AXIOM&quot; as the object model. This was
resolved by using a new object model named &quot;DOOM&quot;. 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
&quot;org.apache.rampart.policy.RampartPolicyData&quot;, which contains security policy
in the manner required by &quot;RampartEngine&quot; and &quot;MessageBuilder&quot;.</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 &quot;Neethi&quot;, which is the Apache implementation of WS Policy
specification. For each policy assertion introduced in the WS-Security
Policy, there is an &quot;Assertion Builder&quot; and an &quot;Assertion Model&quot; 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 &quot;Jar file Service Provider Mechanism&quot;. 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 &quot;Policy&quot;
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 &copy; 2005&#x2013;2017
<a href="http://www.apache.org">Apache Software Foundation</a>.
All rights reserved.
</p>
</div>
</div>
</footer>
</body>
</html>