blob: efd6ebfac3f48eba816c3c23dea8763f6a462e76 [file] [log] [blame]
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<body lang="en-US" dir="ltr">
<p style="margin-bottom: 0in">This document is intended to be a reference
manual for <a href="">Apache Rampart/C</a>.</p>
<p>For further details on Axis2/C please refer the <a href="">Apache Axis2/C manual</a></p>
<h2>Simplified Architecture</h2>
<p>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 uses <a
href="">Apache AXIOM</a> and
Axis2-Util libraries. OpenSSL is used as the crypto library in
<img src="files/rampart_simple_archi.png">
<h2>Interface with Axis2/C</h2>
<p>The interface between Rampart/C and Apache Axis2/C engine is the Rampart
module called mod_rampart. The module has two handlers, one for the inflow
and another for the outflow of the Axis2/C engine. Rampart/C directs messages
to it's other components for further security related processing using these
handlers. </p>
<p>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.</p>
<h2>Inside Rampart/C</h2>
Following is a detailed architecture diagram of Rampart/C
<p><img src="files/rampart_archi.png"></p>
<h3>Rampart Engine</h3>
<p>Rampart engine is the heart of Rampart/C. It sets security policies that
defines 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.</p>
<h3>Processors and Builders</h3>
<p>Rampart/C processes incoming SOAP message using it's processors. There are
two processors in Rampart/C.</p>
<li><strong>Security Header Processor</strong> : Processes security header
of the incoming message and make decisions upon security claims and the
security policies.</li>
<li><strong>Token Processor</strong> : Processes token claims such as
binary security token.</li>
Similar to processes, Rampart/C uses two builders that builds outgoing
<li><strong>Security Header Builder</strong> : Builds Security headers of an outgoing
message depending on security policies.</li>
<li><strong>Token Builder</strong> : Builds token claims such as binary security token.</li>
These builders and processes assemble other components such as encryption,
signature, UsernameToken together. Decisions are taken in these processes
would result in further processing of the message or throwing of a SOAP
<p>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 set of builders that builds these models. <br>
<p>Rampart/C is configured using policy assertions defined in WS-Security
Policy specification (1.1 or 1.2). These policies are defined in policy.xml files.
The client side policies are defined in a seperate policy.xml file located in the client's repository.
The service's policies are defined in the services.xml file.
<h3>Rampart utilities</h3>
<p>Rampart utilities groups different entities that cater for different
purposes. Following is a brief description of major components inside
<li><strong>Rampart context:</strong> Keeps configurations for Rampart/C.
This includes certificates, keys, passwords, policies etc.</li>
<li><strong>UsernameToken: </strong>Provides functionalities to
build/process a UsernameToken.</li>
<li><strong>TimestampToken: </strong>Provides functionalities to
build/process a TimestampToken.</li>
<li><strong>Authentication provider: </strong>The interface for
authentication modules that can be plugged into Rampart/C. This allows
users to define their own rules for processing user name / passwords.</li>
<li><strong>Credentials provider: </strong>An interface for a credentials
module to be plugged in. Users can provide custom user name/password
pairs to build user name tokens.</li>
<li><strong>Password callbacks: </strong>An interface for users to provide
password for a given user name.</li>
<p>For XML cryptographic purposes Rampart/C uses OMXMLSecurity, which is a
library written on top of Apache AXIOM. If a particular SOAP message needs to
be encrypted or signed, Rampart/C get the work done through the
OMXMLSecurity. Following are the functionalities of OMXMLSecurity.</p>
<li><strong>XML-Encryption / Decryption:</strong> This includes symmetric
and asymmetric encryptions. Usually data is encrypted using a symmetric
key (or a session key) which is again encrypted using an asymmetric
algorithm using a public key.</li>
<li><strong>XML-Signature / Verification:</strong> Allows one or more part
of an XML document to be signed using a private key. Also allows these
signed parts to be verified.</li>
<li><strong>Key management:</strong> To load X509 certificates, Private
keys etc, the Key management interface provide a series of functions.
Keys might be stored in PEM files, PKCS12 key stores or can be in string
<li><strong>Canonicalization:</strong> Provide Canonicalization (C14N)
transform support.</li>
<li><strong>Creating/Processing tokens:</strong> There are number of XML
elements that are introduced by security specifications. The token base
in OMXMLSecurity provides functionalities to create/process such
<p>Following diagram shows the architecture of OMXMLSecurity</p>
<img src="files/oxs_archi.png">
<p style="margin-bottom: 0in">Please send your feedback to the Apache Axis2/C
developer mailing list (<a
href=""></a>). Subscription
details are available on the <a
href="">Rampart site</a>.</p>