| <!-- |
| ~ Licensed to the Apache Software Foundation (ASF) under one |
| ~ or more contributor license agreements. See the NOTICE file |
| ~ distributed with this work for additional information |
| ~ regarding copyright ownership. The ASF licenses this file |
| ~ to you under the Apache License, Version 2.0 (the |
| ~ "License"); you may not use this file except in compliance |
| ~ with the License. You may obtain a copy of the License at |
| ~ |
| ~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~ |
| ~ Unless required by applicable law or agreed to in writing, |
| ~ software distributed under the License is distributed on an |
| ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~ KIND, either express or implied. See the License for the |
| ~ specific language governing permissions and limitations |
| ~ under the License. |
| --> |
| |
| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="content-type" content=""/> |
| <link href="../../../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" /> |
| <title>Rampart : WS-Security module for Axis2</title> |
| </head> |
| |
| <body> |
| <h1>Securing SOAP Messages with Rampart</h1> |
| |
| <p>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.</p> |
| |
| <h2>Content</h2> |
| <ul> |
| <li><a href="#intro">Introduction</a></li> |
| <li><a href="#1_1_config">Rampart-1.1 Configuration</a> |
| <ul> |
| <li><a href="#1_1_assetions">Rampart Specific Assertions</a></li> |
| <li><a href="#1_1_service_config">Service Configration</a></li> |
| <li><a href="#1_1_client_config">Client Confiuration</a></li> |
| </ul></li> |
| <li><a href="#1_0_config">Rampart-1.0 Configuration</a> |
| <ul> |
| <li><a href="#outflowsecurity">OutflowSecurity Parameter</a></li> |
| <li><a href="#inflowsecurity">InflowSecurity Parameter</a></li> |
| </ul></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 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.</p> |
| |
| <p>The rampart-1.1 release is available |
| <a href="http://www.apache.org/dyn/closer.cgi/ws/rampart/1_1">here</a>.</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> |
| <a id="1_1_config"></a> |
| <h2>Rampart-1.1 Configuration</h2> |
| <a id="1_1_assetions"></a> |
| <h3>Rampart Specific Assertions</h3> |
| |
| <p>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.</p> |
| <p>The Rampart specific assertion's xsd can be found <a href="sec-conf/rampart-config.xsd">here |
| </a>.</p> |
| |
| <p>The <strong>ramp:RampartConfig</strong> assertion must be available as a one of the top |
| level assertions of the policy as shown <a href="sec-conf/sample-policy.xml">here</a>.</p> |
| <a id="1_1_service_config"></a> |
| <h3>Service Configration</h3> |
| |
| 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 |
| <a href="sec-conf/sample-services.xml">here</a>. |
| <a id="1_1_client_config"></a> |
| <h3>Client Confiuration</h3> |
| <p>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.</p> |
| |
| <pre> |
| //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); |
| </pre> |
| <a id="1_0_config"></a> |
| <h2>Rampart-1.0 Configuration</h2> |
| |
| <p>Rampart module uses two parameters:</p> |
| <ul> |
| <li><a href="outflowsecurity">OutflowSecurity</a></li> |
| <li><a href="inflowsecurity">InflowSecurity</a></li> |
| </ul> |
| The configuration that can go in each of these parameters are described |
| below: <a name="outflowsecurity"></a> |
| |
| <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, 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> |
| |
| <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"> |
| <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> |
| <p>2. <a href="http://specs.xmlsoap.org/ws/2005/07/securitypolicy/ws-securitypolicy.pdf">ws-securitypolicy.pdf</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> |
