xdocs/docs/rampartc_manual.html - axis-axis2-c-rampart - Git at Google

 <html>
 <head>
   <title>Manual</title>
   <meta http-equiv="content-type" content="text/html; charset=UTF-8">
 </head>

 <body lang="en-US" dir="ltr">
 <h2>Preamble</h2>

 <p style="margin-bottom: 0in">This document is intended to be a reference
 manual for <a href="http://ws.apache.org/rampart/c">Apache Rampart/C</a>.</p>
 <p>For further details on Axis2/C please refer the <a href="http://ws.apache.org/axis2/c/docs/axis2c_manual.html">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="http://ws.apache.org/axis2/c/docs/om_tutorial.html">Apache AXIOM</a> and
 Axis2-Util libraries. OpenSSL is used as the crypto library in
 OMXMLSecurity.</p>
 <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>
 <ol>
   <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>
 </ol>
 Similar to processes, Rampart/C uses two builders that builds outgoing
 messages.
 <ol>
 	<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>
 </ol>
 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
 fault.

 <h3>Policy</h3>

 <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>

 <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
 utilities</p>
 <ul>
   <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>
 </ul>

 <h2>OMXMLSecurity</h2>

 <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>
 <ol>
   <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
     buffers.</li>
   <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
   elements.</li>
 </ol>
 <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="mailto:rampart-c-dev@ws.apache.org">rampart-c-dev@ws.apache.org</a>). Subscription
 details are available on the <a
 href="http://ws.apache.org/rampart/c/lists_issues.html">Rampart site</a>.</p>


 </body>
 </html>
	<html>
	<head>
	<title>Manual</title>
	<meta http-equiv="content-type" content="text/html; charset=UTF-8">
	</head>

	<body lang="en-US" dir="ltr">
	<h2>Preamble</h2>

	<p style="margin-bottom: 0in">This document is intended to be a reference
	manual for <a href="http://ws.apache.org/rampart/c">Apache Rampart/C</a>.</p>
	<p>For further details on Axis2/C please refer the <a href="http://ws.apache.org/axis2/c/docs/axis2c_manual.html">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="http://ws.apache.org/axis2/c/docs/om_tutorial.html">Apache AXIOM</a> and
	Axis2-Util libraries. OpenSSL is used as the crypto library in
	OMXMLSecurity.</p>
	<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>
	<ol>
	<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>
	</ol>
	Similar to processes, Rampart/C uses two builders that builds outgoing
	messages.
	<ol>
	<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>
	</ol>
	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
	fault.

	<h3>Policy</h3>

	<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>

	<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
	utilities</p>
	<ul>
	<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>
	</ul>

	<h2>OMXMLSecurity</h2>

	<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>
	<ol>
	<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
	buffers.</li>
	<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
	elements.</li>
	</ol>
	<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="mailto:rampart-c-dev@ws.apache.org">rampart-c-dev@ws.apache.org</a>). Subscription
	details are available on the <a
	href="http://ws.apache.org/rampart/c/lists_issues.html">Rampart site</a>.</p>


	</body>
	</html>