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