Securing SOAP Messages with WSS4J

Axis2 comes with a module based on WSS4J [1] to provide WS-Security features. This section explains how to engage and configure the security module. Since the security module inserts handlers in the system specific pre-dispatch phase, it must be engaged globally. But it is possible to activate the security module for the inflow or the outflow when required by the service or the clients.

The security module (security.mar) is available in the axis2.war but it is not engaged by default.

First it should be engaged by inserting the following in the axis2.xml file.

    <module ref="security"/>

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.

The security module uses two parameters:

  • OutflowSecurity
  • InflowSecurity

The configuration that can go in each of these parameters are described below:

OutflowSecurity parameter

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



ParameterDescriptionExample
itemsSecurity actions for the inflowAdd a Timestamp, Sign the SOAP body and Encrypt the SOAP body

<items> Timestamp Signature Encrypt</items>
userThe user's nameSet alias of the key to be used to sign

<user> bob</user>
passwordCallbackClassCallback class used to provide the password required to create the UsernameToken or to sign the message<passwordCallbackClass> org.apache.axis2.security.PWCallback</passwordCallbackClass>
signaturePropFileproperty file used to get the signature parameters such as crypto provider, keystore and its passwordSet example.properties file as the signature property file

<signaturePropFile> example.properties</signaturePropFile>
signatureKeyIdentifierKey identifier to be used in referring the key in the signatureUse the serial number of the certificate

<signatureKeyIdentifier> IssuerSerial</signatureKeyIdentifier>
encryptionKeyIdentifierKey identifier to be used in referring the key in encryptionUse the serial number of the certificate

<encryptionKeyIdentifier>IssuerSerial</encryptionKeyIdentifier>
encryptionUserThe user's name for encryption.

<encryptionUser>alice</encryptionUser>
encryptionSymAlgorithmSymmetric algorithm to be used for encryptionUse AES-128

<encryptionSymAlgorithm> http://www.w3.org/2001/04/xmlenc#aes128-cbc</encryptionSymAlgorithm>
encryptionKeyTransportAlgorithmKey encryption algorithmUse RSA-OAEP

<parameter name="encryptionSymAlgorithm"> http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p</parameter>
signaturePartsSign multiple parts in the SOAP messageSign Foo and Bar elements qualified by "http://app.ns/ns"

<signatureParts> {Element}{http://app.ns/ns}Foo;{Element}{http://app.ns/ns}Bar </signatureParts>
optimizePartsMTOM Optimize the elements specified by the XPath queryOptimize the CipherValue

<optimizeParts> //xenc:EncryptedData/xenc:CipherData/xenc:CipherValue </optimizeParts>


InflowSecurity parameter

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.

ParameterDescriptionExample
itemsSecurity actions for the inflowfirst 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>
passwordCallbackClassCallback class used to obtain password for decryption and UsernameToken verification

<passwordCallbackClass> org.apache.axis2.security.PWCallback</passwordCallbackClass>
signaturePropFileProperty file used for signature verification

<signaturePropFile> sig.properties</signaturePropFile>
decryptionPropFileProperty 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).

References

1. Apache WSS4J



Examples

Example 1: An outflow configuration to add a timestamp, sing and encrypt the message once

Example 2: An outflow configuration to sign the message twice and add a timestamp

Example 3: An inflow configuration to decrypt, verify signature and validate timestamp