You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by ru...@apache.org on 2006/05/05 11:47:00 UTC
svn commit: r400032 - in
/webservices/axis2/trunk/java/xdocs/modules/rampart: ./ 1_0/ 1_0/sec-conf/
Author: ruchithf
Date: Fri May 5 02:46:58 2006
New Revision: 400032
URL: http://svn.apache.org/viewcvs?rev=400032&view=rev
Log:
Created the rampart docs
Added:
webservices/axis2/trunk/java/xdocs/modules/rampart/
webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/
webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/
webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/in-sample.png (with props)
webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/in.action.xsd
webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/out-action.xsd
webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/out-sample.png (with props)
webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/out-sample2.png (with props)
webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/security-module.html
Added: webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/in-sample.png
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/in-sample.png?rev=400032&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/in-sample.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/in.action.xsd
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/in.action.xsd?rev=400032&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/in.action.xsd (added)
+++ webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/in.action.xsd Fri May 5 02:46:58 2006
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
+ <xs:element name="action">
+ <xs:annotation>
+ <xs:documentation>Inflow security 'action' configuration</xs:documentation>
+ </xs:annotation>
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="items" type="xs:string"/>
+ <xs:element name="passwordCallbackClass" type="xs:string" minOccurs="0"/>
+ <xs:element name="signaturePropFile" type="xs:string" minOccurs="0"/>
+ <xs:element name="decryptionPropFile" type="xs:string" minOccurs="0"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+</xs:schema>
Added: webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/out-action.xsd
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/out-action.xsd?rev=400032&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/out-action.xsd (added)
+++ webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/out-action.xsd Fri May 5 02:46:58 2006
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
+ <xs:element name="action">
+ <xs:annotation>
+ <xs:documentation>Outflow security 'action' configuration</xs:documentation>
+ </xs:annotation>
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="items" type="xs:string"/>
+ <xs:element name="user" type="xs:string"/>
+ <xs:element name="passwordCallbackClass" type="xs:string" minOccurs="0"/>
+ <xs:element name="signaturePropFile" type="xs:string" minOccurs="0"/>
+ <xs:element name="encryptionPropFile" type="xs:string" minOccurs="0"/>
+ <xs:element name="encryptionPropFile" type="xs:string" minOccurs="0"/>
+ <xs:element name="signatureKeyIdentifier" type="xs:string" minOccurs="0"/>
+ <xs:element name="encryptionKeyIdentifier" type="xs:string" minOccurs="0"/>
+ <xs:element name="encryptionUser" type="xs:string" minOccurs="0"/>
+ <xs:element name="signatureParts" type="xs:string" minOccurs="0"/>
+ <xs:element name="encryptionParts" type="xs:string" minOccurs="0"/>
+ <xs:element name="optimizeParts" type="xs:string" minOccurs="0"/>
+ <xs:element name="encryptionSymAlgorithm" type="xs:string" minOccurs="0"/>
+ <xs:element name="EmbeddedKeyCallbackClass" type="xs:string" minOccurs="0"/>
+ <xs:element name="encryptionKeyTransportAlgorithm" type="xs:string" minOccurs="0"/>
+ <xs:element name="EmbeddedKeyName" type="xs:string" minOccurs="0"/>
+ <xs:element name="timeToLive" type="xs:string" minOccurs="0"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+</xs:schema>
Added: webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/out-sample.png
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/out-sample.png?rev=400032&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/out-sample.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/out-sample2.png
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/out-sample2.png?rev=400032&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/sec-conf/out-sample2.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/security-module.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/security-module.html?rev=400032&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/security-module.html (added)
+++ webservices/axis2/trunk/java/xdocs/modules/rampart/1_0/security-module.html Fri May 5 02:46:58 2006
@@ -0,0 +1,250 @@
+<!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, 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">
+ <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, 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>