xdocs/modules/rampart/1_0/security-module.html - axis-axis2-java-rampart - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html>
 <head>
   <meta http-equiv="content-type" content="">
   <title>Rampart : WS-Security module for Axis2</title>
 </head>

 <body>
 <h1>Securing SOAP Messages with WSS4J</h1>

 <p><em>-For Axis2 Version 1.0</em></p>

 <p>Axis2 comes with a module based on WSS4J [1] to provide WS-Security
 features, called "rampart". This document explains how to engage and
 configure rampart module.</p>

 <h2>Content</h2>
 <ul>
   <li><a href="#intro">Introduction</a></li>
   <li><a href="#outflowsecurity">OutflowSecurity Parameter</a></li>
   <li><a href="#inflowsecurity">InflowSecurity Parameter</a></li>
   <li><a href="#references">References</a></li>
   <li><a href="#examples">Examples</a></li>
 </ul>
 <a name="intro"></a>

 <h2>Introduction</h2>

 <p>Since rampart module inserts handlers in the system specific pre-dispatch
 phase, it must be engaged globally. But it is possible to activate rampart
 module for the inflow or the outflow when required by the service or the
 clients.</p>

 <p>The rampart module (rampart.mar) is available with the Axis2 release.</p>

 <p>First it should be engaged by inserting the following in the axis2.xml
 file.</p>
 <source><pre>    &lt;module ref="rampart"/&gt;</pre>
 </source>
 <p>The web admin interface can be used when Axis2 is deployed in a servlet
 container such as Apache Tomcat.</p>

 <p>At the server it is possible to provide security on a per service basis.
 The configuration parameters should be set in the service.xml file of the
 service. The client side config parameters should be set in the axis2.xml of
 the client's Axis2 repository.</p>

 <p>Aegis module uses two parameters:</p>
 <ul>
   <li>OutflowSecurity</li>
   <li>InflowSecurity</li>
 </ul>
 The configuration that can go in each of these parameters are described
 below: <a name="outflowsecurity"></a>

 <h2>OutflowSecurity Parameter</h2>
 This parameter is used to configure the outflow security handler. The outflow
 handler can be invoked more than once in the outflow one can provide
 configuration for each of these invocations. The 'action' element describes
 one of these configurations. Therefore the 'OutflowSecurity' parameter can
 contain more than one 'action' elements. The schema of this 'action' element
 is available <a href="sec-conf/out-action.xsd">here</a>.

 <p>An outflow configuration to add a timestamp, sign and encrypt the message
 once, is shown in<a href="#ex1"> Example 1</a> and <a href="#ex1"> Example
 2</a> shows how to sign the message twice by chaining the outflow handler
 (using two 'action' elements)</p>

 <p>Following is a description of the elements that can go in an 'action'
 element of the OutflowSecurity parameter</p>
 <br>


 <table border="1">
   <tbody>
     <tr>
       <td><b>Parameter</b></td>
       <td><b>Description</b></td>
       <td><b>Example</b></td>
     </tr>
     <tr>
       <td>items</td>
       <td>Security actions for the inflow</td>
       <td>Add a Timestamp, Sign the SOAP body and Encrypt the SOAP body <br>
         &lt;items&gt; Timestamp Signature Encrypt&lt;/items&gt;</td>
     </tr>
     <tr>
       <td>user</td>
       <td>The user's name</td>
       <td>Set alias of the key to be used to sign<br>
         &lt;user&gt; bob&lt;/user&gt;</td>
     </tr>
     <tr>
       <td>passwordCallbackClass</td>
       <td>Callback class used to provide the password required to create the
         UsernameToken or to sign the message</td>
       <td>&lt;passwordCallbackClass&gt;
         org.apache.axis2.security.PWCallback&lt;/passwordCallbackClass&gt;</td>
     </tr>
     <tr>
       <td>signaturePropFile</td>
       <td>property file used to get the signature parameters such as crypto
         provider, keystore and its password</td>
       <td>Set example.properties file as the signature property file<br>
         &lt;signaturePropFile&gt;
       example.properties&lt;/signaturePropFile&gt;</td>
     </tr>
     <tr>
       <td>signatureKeyIdentifier</td>
       <td>Key identifier to be used in referring the key in the signature</td>
       <td>Use the serial number of the certificate<br>
         &lt;signatureKeyIdentifier&gt;
         IssuerSerial&lt;/signatureKeyIdentifier&gt;</td>
     </tr>
     <tr>
       <td>encryptionKeyIdentifier</td>
       <td>Key identifier to be used in referring the key in encryption</td>
       <td>Use the serial number of the certificate <br>
         &lt;encryptionKeyIdentifier&gt;IssuerSerial&lt;/encryptionKeyIdentifier&gt;</td>
     </tr>
     <tr>
       <td>encryptionUser</td>
       <td>The user's name for encryption.</td>
       <td><br>
         &lt;encryptionUser&gt;alice&lt;/encryptionUser&gt;</td>
     </tr>
     <tr>
       <td>encryptionSymAlgorithm</td>
       <td>Symmetric algorithm to be used for encryption</td>
       <td>Use AES-128<br>
         &lt;encryptionSymAlgorithm&gt;
         http://www.w3.org/2001/04/xmlenc#aes128-cbc&lt;/encryptionSymAlgorithm&gt;</td>
     </tr>
     <tr>
       <td>encryptionKeyTransportAlgorithm</td>
       <td>Key encryption algorithm</td>
       <td>Use RSA-OAEP<br>
         &lt;parameter name="encryptionSymAlgorithm"&gt;
         http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p&lt;/parameter&gt;</td>
     </tr>
     <tr>
       <td>signatureParts</td>
       <td>Sign multiple parts in the SOAP message</td>
       <td>Sign Foo and Bar elements qualified by "http://app.ns/ns"<br>
         &lt;signatureParts&gt;
         {Element}{http://app.ns/ns}Foo;{Element}{http://app.ns/ns}Bar
         &lt;/signatureParts&gt;</td>
     </tr>
     <tr>
       <td>optimizeParts</td>
       <td>MTOM Optimize the elements specified by the XPath query</td>
       <td>Optimize the CipherValue<br>
         &lt;optimizeParts&gt;
         //xenc:EncryptedData/xenc:CipherData/xenc:CipherValue
         &lt;/optimizeParts&gt;</td>
     </tr>
   </tbody>
 </table>
 <a name="inflowsecurity"></a>

 <h2>InflowSecurity Parameter</h2>

 <p>This parameter is used to configure the inflow security handler. The
 'action' element is used to encapsulate the configuration elements here as
 well. The schema of the 'action' element is available here. <a
 href="#ex3">Example 3</a> shows the configuration to decrypt, verify
 signature and validate timestamp.</p>

 <table border="1">
   <tbody>
     <tr>
       <td><b>Parameter</b></td>
       <td><b>Description</b></td>
       <td><b>Example</b></td>
     </tr>
     <tr>
       <td>items</td>
       <td>Security actions for the inflow</td>
       <td>first the incoming message should be decrypted and then the
         signatures should be verified and should be checked for the
         availability of the Timestamp <br>
         &lt;items&gt; Timestamp Signature Encrypt&lt;/items&gt;</td>
     </tr>
     <tr>
       <td>passwordCallbackClass</td>
       <td>Callback class used to obtain password for decryption and
         UsernameToken verification</td>
       <td><br>
         &lt;passwordCallbackClass&gt;
         org.apache.axis2.security.PWCallback&lt;/passwordCallbackClass&gt;</td>
     </tr>
     <tr>
       <td>signaturePropFile</td>
       <td>Property file used for signature verification</td>
       <td><br>
         &lt;signaturePropFile&gt;
       sig.properties&lt;/signaturePropFile&gt;</td>
     </tr>
     <tr>
       <td>decryptionPropFile</td>
       <td>Property file used for decryption</td>
       <td><br>
         &lt;decryptionPropFile&gt;
       dec.properties&lt;/decryptionPropFile&gt;</td>
     </tr>
   </tbody>
 </table>
 <br>


 <p>Please note that the '.properties' files used in properties such as
 OutSignaturePropFile are the same property files that are using in the WSS4J
 project. Following shows the properties defined in a sample property file</p>
 <source><pre>        org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
         org.apache.ws.security.crypto.merlin.keystore.type=pkcs12
         org.apache.ws.security.crypto.merlin.keystore.password=security
         org.apache.ws.security.crypto.merlin.keystore.alias=16c73ab6-b892-458f-abf5-2f875f74882e
         org.apache.ws.security.crypto.merlin.alias.password=security
         org.apache.ws.security.crypto.merlin.file=keys/x509.PFX.MSFT
     </pre>
 </source>org.apache.ws.security.crypto.provider defines the implementation of
 the org.apache.ws.security.components.crypto.Crypto interface to provide the
 crypto information required by WSS4J. The other properties defined are the
 configuration properties used by the implementation class
 (org.apache.ws.security.components.crypto.Merlin). <a name="ref"></a> <a
 name="references"></a>

 <h2>References</h2>

 <p>1. <a href="http://ws.apache.org/wss4j">Apache WSS4J -Home</a></p>
 <a name="examples"></a>

 <h2>Examples</h2>

 <p id="ex1">Example 1: An outflow configuration to add a timestamp, sign and
 encrypt the message once</p>

 <p><img alt="" src="sec-conf/out-sample.png"></p>

 <p id="ex2">Example 2: An outflow configuration to sign the message twice and
 add a timestamp</p>

 <p><img alt="" src="sec-conf/out-sample2.png"></p>

 <p id="ex3">Example 3: An inflow configuration to decrypt, verify signature
 and validate timestamp</p>

 <p><img alt="" src="sec-conf/in-sample.png"></p>
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html>
	<head>
	<meta http-equiv="content-type" content="">
	<title>Rampart : WS-Security module for Axis2</title>
	</head>

	<body>
	<h1>Securing SOAP Messages with WSS4J</h1>

	<p><em>-For Axis2 Version 1.0</em></p>

	<p>Axis2 comes with a module based on WSS4J [1] to provide WS-Security
	features, called "rampart". This document explains how to engage and
	configure rampart module.</p>

	<h2>Content</h2>
	<ul>
	<li><a href="#intro">Introduction</a></li>
	<li><a href="#outflowsecurity">OutflowSecurity Parameter</a></li>
	<li><a href="#inflowsecurity">InflowSecurity Parameter</a></li>
	<li><a href="#references">References</a></li>
	<li><a href="#examples">Examples</a></li>
	</ul>
	<a name="intro"></a>

	<h2>Introduction</h2>

	<p>Since rampart module inserts handlers in the system specific pre-dispatch
	phase, it must be engaged globally. But it is possible to activate rampart
	module for the inflow or the outflow when required by the service or the
	clients.</p>

	<p>The rampart module (rampart.mar) is available with the Axis2 release.</p>

	<p>First it should be engaged by inserting the following in the axis2.xml
	file.</p>
	<source><pre> <module ref="rampart"/></pre>
	</source>
	<p>The web admin interface can be used when Axis2 is deployed in a servlet
	container such as Apache Tomcat.</p>

	<p>At the server it is possible to provide security on a per service basis.
	The configuration parameters should be set in the service.xml file of the
	service. The client side config parameters should be set in the axis2.xml of
	the client's Axis2 repository.</p>

	<p>Aegis module uses two parameters:</p>
	<ul>
	<li>OutflowSecurity</li>
	<li>InflowSecurity</li>
	</ul>
	The configuration that can go in each of these parameters are described
	below: <a name="outflowsecurity"></a>

	<h2>OutflowSecurity Parameter</h2>
	This parameter is used to configure the outflow security handler. The outflow
	handler can be invoked more than once in the outflow one can provide
	configuration for each of these invocations. The 'action' element describes
	one of these configurations. Therefore the 'OutflowSecurity' parameter can
	contain more than one 'action' elements. The schema of this 'action' element
	is available <a href="sec-conf/out-action.xsd">here</a>.

	<p>An outflow configuration to add a timestamp, sign and encrypt the message
	once, is shown in<a href="#ex1"> Example 1</a> and <a href="#ex1"> Example
	2</a> shows how to sign the message twice by chaining the outflow handler
	(using two 'action' elements)</p>

	<p>Following is a description of the elements that can go in an 'action'
	element of the OutflowSecurity parameter</p>
	<br>


	<table border="1">
	<tbody>
	<tr>
	<td><b>Parameter</b></td>
	<td><b>Description</b></td>
	<td><b>Example</b></td>
	</tr>
	<tr>
	<td>items</td>
	<td>Security actions for the inflow</td>
	<td>Add a Timestamp, Sign the SOAP body and Encrypt the SOAP body <br>
	<items> Timestamp Signature Encrypt</items></td>
	</tr>
	<tr>
	<td>user</td>
	<td>The user's name</td>
	<td>Set alias of the key to be used to sign<br>
	<user> bob</user></td>
	</tr>
	<tr>
	<td>passwordCallbackClass</td>
	<td>Callback class used to provide the password required to create the
	UsernameToken or to sign the message</td>
	<td><passwordCallbackClass>
	org.apache.axis2.security.PWCallback</passwordCallbackClass></td>
	</tr>
	<tr>
	<td>signaturePropFile</td>
	<td>property file used to get the signature parameters such as crypto
	provider, keystore and its password</td>
	<td>Set example.properties file as the signature property file<br>
	<signaturePropFile>
	example.properties</signaturePropFile></td>
	</tr>
	<tr>
	<td>signatureKeyIdentifier</td>
	<td>Key identifier to be used in referring the key in the signature</td>
	<td>Use the serial number of the certificate<br>
	<signatureKeyIdentifier>
	IssuerSerial</signatureKeyIdentifier></td>
	</tr>
	<tr>
	<td>encryptionKeyIdentifier</td>
	<td>Key identifier to be used in referring the key in encryption</td>
	<td>Use the serial number of the certificate <br>
	<encryptionKeyIdentifier>IssuerSerial</encryptionKeyIdentifier></td>
	</tr>
	<tr>
	<td>encryptionUser</td>
	<td>The user's name for encryption.</td>
	<td><br>
	<encryptionUser>alice</encryptionUser></td>
	</tr>
	<tr>
	<td>encryptionSymAlgorithm</td>
	<td>Symmetric algorithm to be used for encryption</td>
	<td>Use AES-128<br>
	<encryptionSymAlgorithm>
	http://www.w3.org/2001/04/xmlenc#aes128-cbc</encryptionSymAlgorithm></td>
	</tr>
	<tr>
	<td>encryptionKeyTransportAlgorithm</td>
	<td>Key encryption algorithm</td>
	<td>Use RSA-OAEP<br>
	<parameter name="encryptionSymAlgorithm">
	http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p</parameter></td>
	</tr>
	<tr>
	<td>signatureParts</td>
	<td>Sign multiple parts in the SOAP message</td>
	<td>Sign Foo and Bar elements qualified by "http://app.ns/ns"<br>
	<signatureParts>
	{Element}{http://app.ns/ns}Foo;{Element}{http://app.ns/ns}Bar
	</signatureParts></td>
	</tr>
	<tr>
	<td>optimizeParts</td>
	<td>MTOM Optimize the elements specified by the XPath query</td>
	<td>Optimize the CipherValue<br>
	<optimizeParts>
	//xenc:EncryptedData/xenc:CipherData/xenc:CipherValue
	</optimizeParts></td>
	</tr>
	</tbody>
	</table>
	<a name="inflowsecurity"></a>

	<h2>InflowSecurity Parameter</h2>

	<p>This parameter is used to configure the inflow security handler. The
	'action' element is used to encapsulate the configuration elements here as
	well. The schema of the 'action' element is available here. <a
	href="#ex3">Example 3</a> shows the configuration to decrypt, verify
	signature and validate timestamp.</p>

	<table border="1">
	<tbody>
	<tr>
	<td><b>Parameter</b></td>
	<td><b>Description</b></td>
	<td><b>Example</b></td>
	</tr>
	<tr>
	<td>items</td>
	<td>Security actions for the inflow</td>
	<td>first the incoming message should be decrypted and then the
	signatures should be verified and should be checked for the
	availability of the Timestamp <br>
	<items> Timestamp Signature Encrypt</items></td>
	</tr>
	<tr>
	<td>passwordCallbackClass</td>
	<td>Callback class used to obtain password for decryption and
	UsernameToken verification</td>
	<td><br>
	<passwordCallbackClass>
	org.apache.axis2.security.PWCallback</passwordCallbackClass></td>
	</tr>
	<tr>
	<td>signaturePropFile</td>
	<td>Property file used for signature verification</td>
	<td><br>
	<signaturePropFile>
	sig.properties</signaturePropFile></td>
	</tr>
	<tr>
	<td>decryptionPropFile</td>
	<td>Property file used for decryption</td>
	<td><br>
	<decryptionPropFile>
	dec.properties</decryptionPropFile></td>
	</tr>
	</tbody>
	</table>
	<br>


	<p>Please note that the '.properties' files used in properties such as
	OutSignaturePropFile are the same property files that are using in the WSS4J
	project. Following shows the properties defined in a sample property file</p>
	<source><pre> org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
	org.apache.ws.security.crypto.merlin.keystore.type=pkcs12
	org.apache.ws.security.crypto.merlin.keystore.password=security
	org.apache.ws.security.crypto.merlin.keystore.alias=16c73ab6-b892-458f-abf5-2f875f74882e
	org.apache.ws.security.crypto.merlin.alias.password=security
	org.apache.ws.security.crypto.merlin.file=keys/x509.PFX.MSFT
	</pre>
	</source>org.apache.ws.security.crypto.provider defines the implementation of
	the org.apache.ws.security.components.crypto.Crypto interface to provide the
	crypto information required by WSS4J. The other properties defined are the
	configuration properties used by the implementation class
	(org.apache.ws.security.components.crypto.Merlin). <a name="ref"></a> <a
	name="references"></a>

	<h2>References</h2>

	<p>1. <a href="http://ws.apache.org/wss4j">Apache WSS4J -Home</a></p>
	<a name="examples"></a>

	<h2>Examples</h2>

	<p id="ex1">Example 1: An outflow configuration to add a timestamp, sign and
	encrypt the message once</p>

	<p><img alt="" src="sec-conf/out-sample.png"></p>

	<p id="ex2">Example 2: An outflow configuration to sign the message twice and
	add a timestamp</p>

	<p><img alt="" src="sec-conf/out-sample2.png"></p>

	<p id="ex3">Example 3: An inflow configuration to decrypt, verify signature
	and validate timestamp</p>

	<p><img alt="" src="sec-conf/in-sample.png"></p>
	</body>
	</html>