Axis2 comes with a module based on Apache WSS4J [1] to provide WS-Security features, called "Rampart". This document explains how to engage and configure Rampart module.
Since rampart module inserts handlers in the system specific security phase, it must be engaged globally. These handlers can be configured using WS-SecurityPolicy[2] and Rampart specific policy assertions. Rampart-1.0 used two axis2 parameters for configuration and these are still supported in the 1.1 release as well.
The rampart-1.1 release is available here.
First it should be engaged by inserting the following in the axis2.xml file.
<module ref="rampart"/>
The web admin interface can be used when Axis2 is deployed in a servlet container such as Apache Tomcat.
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.
Rampart uses the standard WS-SecurityPolicy[2] assertions and also defines its own assertions to be able capture the configuration information that is not provided in WS-SecurityPolicy.
The Rampart specific assertion's xsd can be found here .
The ramp:RampartConfig assertion must be available as a one of the top level assertions of the policy as shown here.
To configure the service one will simply have to add the policy element into the sevices.xml file. A sample service.xml file is available here.
On the client side, a policy object should be created and loaded into options. Creating the policy object can be done using a "policy.xml" file as follows.
//Creating the object
StAXOMBuilder builder = new StAXOMBuilder(pathToPolicyfile);
Policy clientPolicy = PolicyEngine.getPolicy(builder.getDocumentElement());
//setting the object
Options options = new Options();
options.setProperty(RampartMessageData.KEY_RAMPART_POLICY, clientPolicy);
Rampart module uses two parameters:
The configuration that can go in each of these parameters are described below:
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 here.
An outflow configuration to add a timestamp, sign and encrypt the message once, is shown in Example 1 and Example 2 shows how to sign the message twice by chaining the outflow handler (using two 'action' elements)
Following is a description of the elements that can go in an 'action' element of the OutflowSecurity parameter
| Parameter | Description | Example |
| items | Security actions for the inflow | Add a Timestamp, Sign the SOAP body and Encrypt the SOAP body <items> Timestamp Signature Encrypt</items> |
| user | The user's name | Set alias of the key to be used to sign <user> bob</user> |
| passwordCallbackClass | Callback class used to provide the password required to create the UsernameToken or to sign the message | <passwordCallbackClass> org.apache.axis2.security.PWCallback</passwordCallbackClass> |
| signaturePropFile | property file used to get the signature parameters such as crypto provider, keystore and its password | Set example.properties file as the signature property file <signaturePropFile> example.properties</signaturePropFile> |
| signatureKeyIdentifier | Key identifier to be used in referring the key in the signature | Use the serial number of the certificate <signatureKeyIdentifier> IssuerSerial</signatureKeyIdentifier> |
| encryptionKeyIdentifier | Key identifier to be used in referring the key in encryption | Use the serial number of the certificate <encryptionKeyIdentifier>IssuerSerial</encryptionKeyIdentifier> |
| encryptionUser | The user's name for encryption. | <encryptionUser>alice</encryptionUser> |
| encryptionSymAlgorithm | Symmetric algorithm to be used for encryption | Use AES-128 <encryptionSymAlgorithm> http://www.w3.org/2001/04/xmlenc#aes128-cbc</encryptionSymAlgorithm> |
| encryptionKeyTransportAlgorithm | Key encryption algorithm | Use RSA-OAEP <parameter name="encryptionSymAlgorithm"> http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p</parameter> |
| signatureParts | Sign multiple parts in the SOAP message | Sign Foo and Bar elements qualified by "http://app.ns/ns" <signatureParts> {Element}{http://app.ns/ns}Foo;{Element}{http://app.ns/ns}Bar </signatureParts> |
| optimizeParts | MTOM Optimize the elements specified by the XPath query | Optimize the CipherValue <optimizeParts> //xenc:EncryptedData/xenc:CipherData/xenc:CipherValue </optimizeParts> |
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. Example 3 shows the configuration to decrypt, verify signature and validate timestamp.
| Parameter | Description | Example |
| items | Security actions for the inflow | first the incoming message should be decrypted and then the
signatures should be verified and should be checked for the
availability of the Timestamp <items> Timestamp Signature Encrypt</items> |
| passwordCallbackClass | Callback class used to obtain password for decryption and UsernameToken verification | <passwordCallbackClass> org.apache.axis2.security.PWCallback</passwordCallbackClass> |
| signaturePropFile | Property file used for signature verification | <signaturePropFile> sig.properties</signaturePropFile> |
| decryptionPropFile | Property file used for decryption | <decryptionPropFile> dec.properties</decryptionPropFile> |
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
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
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).
