| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html><title>The Security Module</title> |
| |
| <body> |
| <h1>Securing SOAP Messages with WSS4J</h1> |
| |
| <p>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.</p> |
| |
| <p>The security module (security.mar) is available in the axis2.war but it is not engaged by |
| default.</p> |
| |
| <p>First it should be engaged by inserting the following in the axis2.xml file.</p> |
| <source><pre> |
| <module ref="security"/> |
| </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>The security 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: |
| |
| <h3>OutflowSecurity parameter</h3> |
| |
| 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, sing 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"> |
| <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> |
| </table> |
| <br/> |
| |
| <h3>InflowSecurity parameter</h3> |
| |
| <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"> |
| <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> |
| </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). |
| |
| <p><b>References</b></p> |
| |
| <p>1. <a href="http://ws.apache.org/wss4j">Apache WSS4J</a></p> |
| <br/> |
| |
| <p><b>Examples</b></p> |
| |
| <p id="ex1">Example 1: An outflow configuration to add a timestamp, sing 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> |