ws-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cohei...@apache.org
Subject svn commit: r1574036 [2/3] - in /webservices/wss4j/trunk: ./ src/ src/site/ src/site/xdoc/
Date Tue, 04 Mar 2014 11:31:33 GMT
Added: webservices/wss4j/trunk/src/site/xdoc/newfeatures20.xml
URL: http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/site/xdoc/newfeatures20.xml?rev=1574036&view=auto
==============================================================================
--- webservices/wss4j/trunk/src/site/xdoc/newfeatures20.xml (added)
+++ webservices/wss4j/trunk/src/site/xdoc/newfeatures20.xml Tue Mar  4 11:31:32 2014
@@ -0,0 +1,186 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<document>
+<body>
+<section name="New features available in Apache WSS4J 2.0.0">
+
+<subsection name="Overview of new features">
+<p>
+Apache WSS4J 2.0.0 delivers the following major new features:
+</p>
+<ul>
+<li>Support for a streaming (StAX) based WS-Security implementation that
+covers all of the main specifications.</li>
+<li>A WS-SecurityPolicy model that can be shared between both DOM + StAX
+implementations.</li>
+<li>Support for "real-time" WS-SecurityPolicy validation for the StAX
+implementation.</li>
+<li>Support for the SOAP with Attachments (SWA) Profile 1.1 specification.</li>
+<li>Support for caching based on EhCache.</li>
+<li>Support for encrypting passwords in Crypto properties files using Jasypt.
+</li>
+</ul>
+</subsection>
+
+<subsection name="Streaming (StAX) based WS-Security implementation">
+<p>
+WSS4J 2.0.0 introduces a new streaming (StAX) based WS-Security implementation.
+Please see the dedicated <a href="streaming.html">page</a> for more
+information.
+</p>
+</subsection>
+
+<subsection name="WS-SecurityPolicy support">
+<p>
+WSS4J 2.0.0 introduces a new WS-SecurityPolicy model as part of the
+"wss4j-policy" module. This model can be shared between both the DOM and StAX
+WS-Security implementations. Web service stacks such as Apache CXF and 
+Apache Axis/Rampart that use WSS4J for WS-Security no longer need to maintain
+their own model. In this way any bug fixes to the model will get picked up
+by all web service stacks that rely on WSS4J.
+</p>
+<p>
+In addition to the new WS-SecurityPolicy model, a significant new feature of
+WSS4J 2.0.0 is that the new streaming WS-Security implementation has the
+ability to perform "real-time" validation of a request against the set of
+applicable WS-SecurityPolicy policies. The DOM-based code in WSS4J does not
+have any concept of WS-SecurityPolicy, but instead processes an inbound 
+request, and relies on the web service stack to compare the results against
+the applicable policies. The advantage of the streaming approach in WSS4J
+2.0.0 is that bogus requests can be rejected quicker, which may help to avoid
+DoS based scenarios.
+</p>
+</subsection>
+
+<subsection name="Support for signing and encrypting message attachments">
+<p>
+WSS4J 2.0.0 introduces support for signing and encrypting SOAP message
+attachments, via the the SOAP with Attachments (SWA) Profile 1.1 specification.
+Please see the dedicated <a href="attachments.html">page</a> for more
+information.
+</p>
+</subsection>
+
+
+<subsection name="Replay Attack detection using EhCache">
+<p>
+In WSS4J 1.6.x, a "ReplayCache" interface was introduced to cache tokens to
+guard against replay attacks for the following scenarios:
+</p>
+<ul>
+<li>Signed Timestamps</li>
+<li>UsernameToken nonces</li>
+<li>SAML OneTimeUse Assertions</li>
+</ul>
+<p>
+However, replay attack detection was not "switched on" by default in WSS4J
+1.6.x. In WSS4J 2.0.x, replay attack detection is enabled by default using
+an implementation of the "ReplayCache" interface based on EhCache. The 
+following configuration tags can be used to configure caching:
+</p>
+<ul>
+<li>ConfigurationConstants.TIMESTAMP_CACHE_INSTANCE ("timestampCacheInstance"):
+This holds a reference to a ReplayCache instance used to cache Timestamp
+Created Strings. The default instance that is used is the EHCacheReplayCache.
+</li>
+<li>ConfigurationConstants.ENABLE_TIMESTAMP_CACHE ("enableTimestampCache"):
+Whether to cache Timestamp Created Strings (these are only cached in
+conjunction with a message Signature). The default value is "true".</li>
+<li>ConfigurationConstants.NONCE_CACHE_INSTANCE ("nonceCacheInstance"): This
+holds a reference to a ReplayCache instance used to cache UsernameToken
+nonces. The default instance that is used is the EHCacheReplayCache.</li>
+<li>ConfigurationConstants.ENABLE_NONCE_CACHE ("enableNonceCache"): Whether to
+cache UsernameToken nonces. The default value is "true".</li>
+<li>ConfigurationConstants. SAML_ONE_TIME_USE_CACHE_INSTANCE
+("samlOneTimeUseCacheInstance"): This holds a reference to a ReplayCache
+instance used to cache SAML2 Token Identifier Strings (if the token contains a
+OneTimeUse Condition). The default instance that is used is the
+EHCacheReplayCache.</li>
+<li>ConfigurationConstants.ENABLE_SAML_ONE_TIME_USE_CACHE
+("enableSamlOneTimeUseCache"):  Whether to cache SAML2 Token Identifiers, if
+the token contains a "OneTimeUse" Condition. The default value is "true".</li>
+</ul>
+</subsection>
+
+<subsection name="Encrypting passwords in Crypto property files">
+<p>
+A typical example of the contents of a Crypto properties file (for Signature
+creation) is as follows:
+</p>
+<ul>
+<li>org.apache.wss4j.crypto.provider=org.apache.wss4j.common.crypto.Merlin</li>
+<li>org.apache.wss4j.crypto.merlin.keystore.type=jks</li>
+<li>org.apache.wss4j.crypto.merlin.keystore.password=security</li>
+<li>org.apache.wss4j.crypto.merlin.keystore.alias=wss40</li>
+<li>org.apache.wss4j.crypto.merlin.keystore.file=keys/wss40.jks</li>
+</ul>
+<p>
+Note that the password used to load the keystore is in cleartext. One of the
+new features of Apache WSS4J 2.0.0 is the ability to instead store a (BASE-64
+encoded) encrypted version of the keystore password in the Crypto properties
+file. A new PasswordEncryptor interface is defined to allow for the
+encryption/decryption of passwords. A default implementation is now provided
+based on Jasypt called JasyptPasswordEncryptor, which uses
+"PBEWithMD5AndTripleDES".
+</p>
+<p>
+The WSPasswordCallback class has an additional "usage" called
+WSPasswordCallback.PASSWORD_ENCRYPTOR_PASSWORD, which is used to return the
+master password for use with the PasswordEncryptor implementation. When WSS4J
+is loading a Crypto implementation via a properties file, and it encounters a
+password encrypted in the format "ENC(encoded encrypted password)", it queries
+a CallbackHandler for a password via this WSPasswordCallback usage tag. It is
+possible to pass a custom PasswordEncryptor implementation to WSS4J via the
+new configuration tag ConfigurationConstants.PASSWORD_ENCRYPTOR_INSTANCE
+("passwordEncryptorInstance").
+</p>
+
+</subsection>
+
+<subsection name="Miscellaneous new features">
+<p>
+Support was added in WSS4J 1.6.x to obtain a Kerberos ticket from a KDC (Key
+Distribution Center) and include it in the security header of a request, as 
+well as to process the received token. However, there was no built-in way to
+extract the secret key from the ticket to secure the request. Instead it was
+up to the user to plug in a custom "KerberosTokenDecoder" implementation to
+support this behaviour. In WSS4J 2.0.0, a default KerberosTokenDecoder
+implementation is provided, and so WSS4J now supports signing/encrypting using
+Kerberos tokens by default.
+</p>
+<p>
+A new "CustomToken" Action is defined in WSS4J 2.0.0. If this action is
+defined, a token (DOM Element) will be retrieved from a CallbackHandler via
+WSPasswordCallback.Usage.CUSTOM_TOKEN and written out as is in the security
+header. This provides for an easy way to write out tokens that have been
+retrieved out of band. Another related new feature is the ability to associate
+an action with a particular set of keys/algorithms. This means that it is now
+possible to configure two different Signature actions, that use different
+keys/algorithms.
+</p>
+<p>
+Support for enforcing the Basic Security Profile (BSP) 1.1 specification was
+added in WSS4J 1.6.x. In WSS4J 2.0.0, it is possible to disable individual
+BSP Rules for a non-compliant request, instead of having to disable BSP
+enforcement altogether as for WSS4J 1.6.x. The RequestData class has a
+setIgnoredBSPRules method, that takes a list of BSPRule Objects as an argument.
+The BSPRule class contains a complete list of Basic Security Profile rules
+that are enforced in WSS4J.
+</p>
+<p>
+WSS4J 2.0.0 now enforces the SubjectConfirmation requirements of an inbound
+SAML Token, instead of leaving it to the web services stack. For
+sender-vouches, a Signature must be present that covers both the SOAP Body and
+the SAML Assertion. For holder-of-key, a Signature must be present that signs
+some part of the SOAP request using the key information contained in the SAML
+Subject. Note that a Signature can be either a message or transport level
+Signature (i.e. using TLS is acceptable). A new configuration tag is defined
+that allows the user to switch off this validation if required
+(ConfigurationConstants.VALIDATE_SAML_SUBJECT_CONFIRMATION  -
+"validateSamlSubjectConfirmation").
+</p>
+
+</subsection>
+
+</section>            
+</body>
+</document>

Added: webservices/wss4j/trunk/src/site/xdoc/package.xml
URL: http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/site/xdoc/package.xml?rev=1574036&view=auto
==============================================================================
--- webservices/wss4j/trunk/src/site/xdoc/package.xml (added)
+++ webservices/wss4j/trunk/src/site/xdoc/package.xml Tue Mar  4 11:31:32 2014
@@ -0,0 +1,654 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<document>
+<body>
+<section name="Axis1 Deployment Tutorial">
+<p>
+WSS4J 1.5.x Axis handlers process SOAP requests according to the OASIS Web Service 
+Security (WSS) specifications.
+</p><p></p><p>
+The WSS4J Axis handlers <code>WSDoAllSender</code> and <code>WSDoAllReceiver
+</code> control the creation and consumption of secure SOAP requests.
+The handlers work behind the scenes and are usually transparent to Web Service
+(WS) applications. The Axis deployment descriptor files (*.wsdd) may contain all
+necessary information to control the security processing.
+</p><p></p><p>
+A WS application may also set properties to control the handlers
+and provide default values. If the deployment descriptor sets the same 
+property (parameter) then the deployment descriptor overwrites the application
+defined property.  Thus, deployment settings overwrite application settings 
+to fulfill site specific requirements.
+
+</p></section>
+<section name="Prerequisites"><p>
+The WS Security Axis handlers use the WSS4J classes (Web Service Security 
+for Java) to process the SOAP messages. WSS4J in turn uses the Apache XML Security 
+project to handle XML Security according to XML Signature and XML Encryption. 
+
+<ul>
+  <li><a href="http://ws.apache.org/wss4j/index.html">WSS4J</a></li>
+  <li><a href="http://xml.apache.org/security/index.html">XML Security</a></li>
+</ul>
+
+The WSS4J Axis handlers require Axis V1.2 because of some problems in previous
+Axis versions. WSS4J CVS contains the latest Axis libraries. 
+
+</p></section><section name="Related Documentation"><p>
+The OASIS WSS specifications define a number of features and it is possible 
+to combine them in several ways. The WSS4J Axis handlers already support 
+a large number of WSS features and their combinations. 
+<a href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss">
+Here</a> are the WSS specifications.
+
+</p></section><section name="The basics - a simple example that uses"><p>
+This chapter gives an overview and some examples how to deploy 
+the WSS4J Axis handlers and how the parameters and their values control the
+handlers. For a better understanding of this chapter the reader shall 
+have a knowledge of the OASIS WSS specifications.
+</p><p></p><p>
+The {@link org.apache.ws.security.handler.WSHandlerConstants}, 
+{@link org.apache.ws.axis.security.WSDoAllSender}, and 
+{@link org.apache.ws.axis.security.WSDoAllReceiver}
+provide additional and detailed documentation.
+
+</p><subsection name="Axis deployment descriptor to insert a"><p>
+The following snippet shows a general layout how to deploy a WS Axis handler
+on the client (application) side.
+<source>
+ &lt;!-- define the service, use the WSDoAllSender security handler in request flow --&gt;
+ &lt;service name="Ping1"&gt;
+  &lt;requestFlow&gt;
+   &lt;handler type="java:org.apache.ws.axis.security.WSDoAllSender" &gt;
+    &lt;parameter name="action" value="UsernameToken"/&gt;
+    &lt;parameter name="user" value="werner"/&gt;
+    &lt;parameter name="passwordType" value="PasswordText" /&gt;
+    &lt;parameter name="passwordCallbackClass" 
+      value="org.apache.ws.axis.oasis.PWCallback1Out"/&gt;
+   &lt;/handler&gt;
+  &lt;/requestFlow&gt;
+  &lt;/service&gt;
+</source>
+
+This is the standard way to deploy an Axis handler. Axis parses the deployment
+descriptor and provides the parameters and their value to the handler. Each
+service can have its own request and response flow definition, which provides
+a very flexible set-up of the security parameters.
+</p><p></p><p>
+The above setup inserts the most simple security structure into a SOAP request: 
+the simple <code>UsernameToken</code>. This token includes a username and the 
+according password. Both fields are sent in cleartext, thus it provides no 
+real security.
+</p><p></p><p>
+
+The parameters and their meanings are:
+<ul>
+<li><code>action</code> defines the security action. The value <code>
+    UsernameToken</code> directs the handler to insert this token into
+    the SOAP request.
+</li>
+<li><code>user</code> specifies the username to include in the token.
+</li>
+<li><code>passwordType</code> is a pecific parameter for the <code>
+    UsernameToken</code> action and defines the encoding of the passowrd.
+    <code>PasswordText</code> specifies to send the password in
+    plain text, <code>PasswordDigest</code> specifies to send the
+    password in digest mode (refer to WSS UsernameToken Profile)
+</li>
+<li><code>passwordCallbackClass</code> contains the name of a class that
+    implements a method to get the user's password. Please refer to the
+    detailed documentation in 
+    {@link org.apache.ws.security.handler.WSHandlerConstants#PW_CALLBACK_CLASS}.
+    </li>
+</ul>
+The WSS4J Axis security handler interprets the parameter values and controls
+the WSS4J modules to generate the following SOAP request:
+<source>
+&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
+  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;
+  &lt;soapenv:Header&gt;
+    &lt;wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext" 
+      soapenv:mustUnderstand="true"&gt;
+      &lt;wsse:UsernameToken&gt;
+        &lt;wsse:Username&gt;werner&lt;/wsse:Username&gt;
+        &lt;wsse:Password Type="wsse:PasswordText"&gt;security&lt;/wsse:Password&gt;
+      &lt;/wsse:UsernameToken&gt;
+    &lt;/wsse:Security&gt;
+  &lt;/soapenv:Header&gt;
+  &lt;soapenv:Body&gt;
+    &lt;Ping xmlns="http://xmlsoap.org/Ping"&gt;
+      &lt;text&gt;Scenario 1 text&lt;/text&gt;
+      &lt;ticket xmlns:ns1="http://xmlsoap.org/Ping" 
+        xsi:type="ns1:ticketType"&gt;scenario1&lt;/ticket&gt;
+    &lt;/Ping&gt;
+  &lt;/soapenv:Body&gt;
+&lt;/soapenv:Envelope&gt;
+</source>
+This is a pretty print of the real SOAP message.
+
+</p></subsection><subsection name="The password callback class"><p>
+
+The deployment descriptor contains the user name that the handler inserts into
+the <code>UsernameToken</code> but not the password. In general it is not a
+good idea to store sensitive information like a password in cleartext. To
+get the password the WSS4J Axis handler uses a password callback
+technique similar to the JAAS mechansim. The parameter 
+<code>passwordCallbackClass</code> contains the classname of the callback
+class. This class must implement the
+{@link javax.security.auth.callback.CallbackHandler}
+interface. The WSS4J Axis handler gets this class,
+instantiates it, and calls the <code>handle</code> method when it
+needs a password. Refer also to the 
+{@link org.apache.ws.security.handler.WSHandlerConstants#PW_CALLBACK_CLASS
+ parameter} documentation.
+ </p><p></p><p>
+ The following code snippet shows a simple password callback class:
+ <source>
+package org.apache.ws.axis.oasis;
+
+import java.io.IOException;
+
+import javax.security.auth.callback.Callback;
+import javax.security.auth.callback.CallbackHandler;
+import javax.security.auth.callback.UnsupportedCallbackException;
+
+import org.apache.ws.security.WSPasswordCallback;
+
+public class PWCallback implements CallbackHandler {
+
+  private static final byte[] key = {
+    (byte)0x31, (byte)0xfd, (byte)0xcb, (byte)0xda,
+    (byte)0xfb, (byte)0xcd, (byte)0x6b, (byte)0xa8,
+    (byte)0xe6, (byte)0x19, (byte)0xa7, (byte)0xbf,
+    (byte)0x51, (byte)0xf7, (byte)0xc7, (byte)0x3e,
+    (byte)0x80, (byte)0xae, (byte)0x98, (byte)0x51,
+    (byte)0xc8, (byte)0x51, (byte)0x34, (byte)0x04,
+  };
+	
+  public void handle(Callback[] callbacks)
+    throws IOException, UnsupportedCallbackException {
+    for (int i = 0; i &lt; callbacks.length; i++) {
+      if (callbacks[i] instanceof WSPasswordCallback) {
+        WSPasswordCallback pc = (WSPasswordCallback) callbacks[i];
+        /*
+         * here call a function/method to lookup the password for
+         * the given identifier (e.g. a user name or keystore alias)
+         * e.g.: pc.setPassword(passStore.getPassword(pc.getIdentfifier))
+         * for testing we supply a fixed name/fixed key here.
+         */
+        if (pc.getUsage() == WSPasswordCallback.KEY_NAME) {
+          pc.setKey(key);
+        }
+        else {
+          pc.setPassword("security");
+        }
+      } else {
+        throw new UnsupportedCallbackException(
+          callbacks[i], "Unrecognized Callback");
+      }
+    }
+  }
+}
+</source>
+The Java {@link javax.security.auth.callback.CallbackHandler callback} handler
+documentation provides a detailed description of the interface and exceptions.
+</p><p></p><p>
+The WSS4J library uses a specific class to get the required password or key
+informations. The <code>WSSPasswordCallback</code> class implements the
+{@link javax.security.auth.callback.Callback} interface according to the
+JAAS. Depending on it usage this class either carries the required password
+as a Java <code>String </code> or it carries the required key information 
+as a Java <code>byte[]</code> array. Refer to
+{@link org.apache.ws.security.WSPasswordCallback} that contains a
+detailed description of the usage codes.
+</p><p></p><p>
+The WSS4J Axis handler or the WSS4J modules set the usage code before
+they call <code>handle</code> method. 
+
+</p></subsection><subsection name="Application sets parameters to insert in"><p>
+
+Sometimes it is not feasable or not possible to determine parameters
+and their values during deployment. In this case the application can
+set paramters during runtime. The WSS4J Axis handlers use the Axis
+<code>setProperty</code> method to support this feature.
+</p><p></p><p>
+The following code snippet shows an example how to use the dynamic setting
+of parameters and their values:
+<source>
+   ...
+ Service service = new Service();
+ Call call = (Call) service.createCall();
+   ...  
+ call.setProperty(UsernameToken.PASSWORD_TYPE, WSConstants.PASSWORD_TEXT);
+ call.setProperty(WSHandlerConstants.USER, "werner");
+   ...
+</source>
+Use this way if your application dynamically creates a <code>call</code>
+object. If your application uses stubs generated by Axis' <code>WSDL2Java
+</code> tool, the application uses the following functions:
+<source>
+    ...
+ PingServiceLocator service = new PingServiceLocator();
+    ...
+ PingPort port = (PingPort) service.getPing1();
+ port._setProperty(UsernameToken.PASSWORD_TYPE, WSConstants.PASSWORD_TEXT);
+ port._setProperty(WSHandlerConstants.USER, "werner");
+    ...
+</source>
+Please note that <code>_setProperty</code> is a Axis specific call.
+
+</p></subsection><subsection name="The password callback object reference"><p>
+
+In addition to the <a href="#pwCallBackClass">password callback class</a>
+an application may set a password callback object using the <code>
+  setProperty()</code> methods. Only applications (and Axis handlers that
+  preceed the WSS4J Axis handlers in a handler chain) can use this feature.
+  </p><p></p><p>
+  For example:
+  <source>
+public class Scenario1 implements CallbackHandler {
+
+  public static void main(String args[]) {
+    ...
+    PingServiceLocator service = new PingServiceLocator();
+    ...
+    PingPort port = (PingPort) service.getPing1();
+    ((org.apache.axis.client.Stub)port)._setProperty(UsernameToken.PASSWORD_TYPE, WSConstants.PASSWORD_TEXT);
+    ((org.apache.axis.client.Stub)port._setProperty(WSHandlerConstants.USER, "werner");
+    ((org.apache.axis.client.Stub)port._setProperty(WSHandlerConstants.PW_CALLBACK_REF, this);
+    ...
+  }
+
+  public void handle(Callback[] callbacks) {
+    ...
+  }
+}
+</source>
+
+</p></subsection><subsection name="Deployment of the WSS4J Axis  handler"><p>
+
+Similar to the deployment descriptor of the sending handler <code>WSDoAllSender
+</code> a deployment descriptor for the receiving handler exists. For the above
+example the deployment descriptor look like:
+<source>
+  &lt;requestFlow&gt;
+   &lt;handler type="java:org.apache.ws.axis.security.WSDoAllReceiver"&gt;
+    &lt;parameter name="passwordCallbackClass" 
+      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
+    &lt;parameter name="action" value="UsernameToken"/&gt;
+   &lt;/handler&gt;
+  &lt;/requestFlow&gt;
+</source>
+The receiving WSS4J Axis handler checks if the SOAP request matches the defined
+actions.
+
+</p></subsection></section><section name="Combining security actions"><p>
+
+Often it is necessary to combine or concatenate several security actions, for 
+example to encrypt parts of a message and sign some other parts. The WSS4J 
+Axis handlers provide easy and simple methods to combine or concatenate
+security actions. 
+</p><p></p><p>
+This chapter describes simple combinations of actions.
+
+</p><subsection name="Combine  and"><p>
+
+The WS Interoperability specifications define this use case: 
+<ul>
+  <li>Insert a <code>UsernameToken</code>, use <code>PasswordText</code>
+    to set the password. In addition add a timestamp and a nonce into
+    the <code>UsernameToken</code></li>
+  <li>Encrypt the <code>UsernameToken</code> to protect the information.
+    </li>
+</ul>
+
+The Axis deplyment descriptor for this use case:
+<source>
+  &lt;requestFlow&gt;
+   &lt;handler type="java:org.apache.ws.axis.security.WSDoAllSender" &gt;
+    &lt;parameter name="action" value="UsernameToken Encrypt"/&gt;
+    &lt;parameter name="user" value="werner"/&gt;
+    &lt;parameter name="passwordCallbackClass" 
+      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
+    &lt;parameter name="passwordType" value="PasswordText" /&gt;
+    &lt;parameter name="addUTElement" value="Nonce Created" /&gt;
+    &lt;parameter name="encryptionPropFile" value="crypto.properties" /&gt;
+    &lt;parameter name="encryptionKeyIdentifier" value="X509KeyIdentifier" /&gt;
+    &lt;parameter name="encryptionUser" 
+      value="16c73ab6-b892-458f-abf5-2f875f74882e" /&gt;
+    &lt;parameter name="encryptionParts" 
+      value="{Element}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd}UsernameToken" /&gt;  
+   &lt;/handler&gt;
+  &lt;/requestFlow&gt;  
+</source>
+
+This descriptor contains some new parameters to control the <code>UsernameToken
+</code> element and its encryption. The new parameters and their meaning are:
+<ul>
+  <li><code>addUTElement</code> - controls if the handler shall insert elements
+    into the <code>UsernameToken</code>. The value is a blank separated list of
+    element names to include. Only <code>Nonce</code> and <code>Created</code> are
+    supported.</li>
+  <li><code>encryptionPropFile</code> - the name of a crypto property file. This
+    file contains parameters and property that control the encryption. Please refer
+    to the
+    {@link org.apache.ws.security.handler.WSHandlerConstants#ENC_PROP_FILE 
+    detailed} description of the cyrpto property file.</li>
+  <li><code>encryptionKeyIdentifier</code> - specifies the format in which the 
+    handler inserts the encryption key into the SOAP request. Please refer
+    to the 
+    {@link org.apache.ws.security.handler.WSHandlerConstants#ENC_KEY_ID 
+    detailed} description.</li>
+  <li><code>encryptionUser</code> - the name or identifier of the user who owns
+    the public key to encrypt the data. Usually this is the name or alias name
+    of the owner's certificate in a keystore.</li>
+  <li><code>encryptionParts</code> - controls which part or parts the handler
+    of the SOAP shall encrypt. If this parameter is not defined, WSS4J encrypts
+    the whole SOAP Body in <code>Content</code> mode. The value of the
+    parameter in this example specifies to encrypt the element <code>
+    UsernameToken</code>, contained in the namespace
+    <code>http://schemas.xmlsoap.org/ws/2002/07/secext</code>. The encryption
+    module uses the <code>Element</code> mode to encrypt the element data.
+    Please refer to the
+    {@link org.apache.ws.security.handler.WSHandlerConstants#ENCRYPTION_PARTS 
+    detailed} description.
+    </li>
+</ul>
+The matching receiver deployment descriptor:
+<source>
+  &lt;requestFlow&gt;
+   &lt;handler type="java:org.apache.ws.axis.security.WSDoAllReceiver"&gt;
+    &lt;parameter name="passwordCallbackClass" 
+      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
+    &lt;parameter name="action" value="UsernameToken Encrypt"/&gt;
+    &lt;parameter name="decryptionPropFile" value="crypto.properties" /&gt;
+   &lt;/handler&gt;
+  &lt;/requestFlow&gt;
+</source>
+The only new parameter here is the <code>decryptionPropFile</code>. This
+parameter defines the crypto property file at the receiver side. The value
+  of the <code>action</code> parameter matches the according value at the
+  sender side. The WSS4J Axis receiver checks if the SOAP request contains
+  the required security data.
+
+</p></subsection><subsection name="Combine Signature and Encryption"><p>
+
+This is a very common usage of Web Service security. The WSS4J Axis handler
+provides flexible parameter settings that support several ways to use
+the Signature/Encryption combination.
+</p><p></p><p>
+A WSS4J Axis deployment descriptor for a simple Singature/Encryption of
+SOAP requests:
+<source>
+&lt;requestFlow&gt;
+  &lt;handler type="java:org.apache.ws.axis.security.WSDoAllSender" &gt;
+    &lt;parameter name="user" value="16c73ab6-b892-458f-abf5-2f875f74882e"/&gt;
+    &lt;parameter name="passwordCallbackClass" 
+      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
+    &lt;parameter name="action" value="Signature Encrypt"/&gt;
+    &lt;parameter name="signaturePropFile" value="crypto.properties" /&gt;
+  &lt;/handler&gt;
+&lt;/requestFlow&gt;
+</source>
+This simple deployment descriptor signs and encrypts the SOAP Body part.
+The only new parameter, <code>signaturePropFile</code>, specifies the
+name of the signature crypto property file to use. Because no 
+<code>encryptionPropFile</code> is declared the handler also uses the signature
+property file to get the encryption certificate. The same holds true for
+the username. The password callback class must return a password
+to get the user's private key (the keystore is defined in the crypto
+property file) that WSS4J uses to generate the signature. The encryption
+method uses the user's public key to encrypt the dynamically generated
+session key.
+</p><p></p><p>
+The <code>action</code> parameter defines <code>Signature Encryption</code>.
+Thus the handler first signs, then the encrypts the data.
+Because the deployment descriptor does not contain specific encryption or 
+signature part parameters, WSS4J defaults to the data of the SOAP Body element.
+</p><p></p><p>
+Also all other parameters use their default setting, such as the format of the
+key identifiers, encryption modifiers, and so on. Please refer to the
+{@link org.apache.ws.security.handler.WSHandlerConstants detailed}
+documentation of the parameters.
+</p><p></p><p>
+If the WSS4J Axis handler shall perform encryption only, then the
+deployment descriptor must contain the encryption specific parameters. Only
+if sign <b>and</b> encryption is required the encryption method falls back to
+the signature parameters if the encryption specific parameters are not set.
+</p><p></p><p>
+The matching receiver deployment descriptor is also very simple:
+<source>
+&lt;requestFlow&gt;
+  &lt;handler type="java:org.apache.ws.axis.security.WSDoAllReceiver"&gt;
+    &lt;parameter name="passwordCallbackClass" 
+      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
+    &lt;parameter name="action" value="Signature Encrypt"/&gt;
+    &lt;parameter name="signaturePropFile" value="crypto.properties" /&gt;
+  &lt;/handler&gt;
+ &lt;/requestFlow&gt;	
+</source>
+To reverse the actions, just reverse the action specifiers. The WSS4J
+handler encrypts the SOAP Body first, then signs the encrypted data.
+
+</p></subsection></section><section name="Signing and encrypting multiple XML elements"><p>
+
+Sometimes it is necessary to sign and/or encrypt several parts of a SOAP
+message. The deployment parameters <code>signatureParts</code> and 
+<code>encryptionParts</code> control which SOAP elements to sign or
+to encrypt. Please refer to the
+{@link org.apache.ws.security.handler.WSHandlerConstants#ENCRYPTION_PARTS 
+detailed} description of these parameters.
+</p><p></p><p>
+WSS4J signs or encrypts all declared parts using the same keys, that is 
+the signature or encryption data structures directly reference the 
+specified parts as described in the WSS specifications. The receiver
+automatically detects these references and verfies and decrypts the
+data parts. No special settings in the depolyment descriptor is necessary.
+
+</p></section><section name="Chaining of WSS4J Axis handlers"><p>
+
+This is a very powerful feature that supports even more flexible signature and
+encryption processing such as signatures with multiple keys (overlapping
+signatures), multiple encryption algorithms, or different SOAP actor (role)
+defintions of the security headers.
+
+</p><subsection name="Deployment at the client"><p>
+A deployment descriptor to chain handlers:
+<source>
+  &lt;requestFlow&gt;
+   &lt;handler type="java:org.apache.ws.axis.security.WSDoAllSender" &gt;
+    &lt;parameter name="action" value="Signature NoSerialization"/&gt;
+    &lt;parameter name="user" value="firstUser"/&gt;
+    &lt;parameter name="passwordCallbackClass" 
+      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
+    &lt;parameter name="signaturePropFile" value="crypto.properties" /&gt;
+    &lt;parameter name="signatureParts" value="{}{http://xmlsoap.org/Ping}ticket" /&gt;    
+   &lt;/handler&gt;
+   &lt;handler type="java:org.apache.ws.axis.security.WSDoAllSender" &gt;
+    &lt;parameter name="action" value="Signature"/&gt;
+    &lt;parameter name="user" value="anotherUser"/&gt;
+    &lt;parameter name="passwordCallbackClass" 
+      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
+    &lt;parameter name="signaturePropFile" value="crypto.properties" /&gt;
+   &lt;/handler&gt;  
+  &lt;/requestFlow&gt;
+</source>
+Note the action specifier <code>NoSerialization</code> first handler. 
+In a handler chain of WSS4J handlers every
+but the last handler <i>must</i> have this action specifier. This specifier
+surpresses the very last step of the handler's security processing: the 
+serialization of the processed SOAP request in a XML string (document) that 
+Axis sends to the reveiver. Only the last handler must perform this 
+serialization.
+</p><p></p><p>
+Every handler specification can have its own set of parameters that define
+the individual values for this handler instance. Thus the deployment
+descriptor can define different crypto property files, different usernames,
+and so on. In the example the first handler signs the <code>ticket</code>
+element and the second handler the SOAP Body (default).
+</p><p></p><p>
+Parameters set by the application with <code>setProperty</code> are valid for 
+<b>all</b> handler instances in the handler
+chain (<code>setProperty</code> is defined on the SOAP request (call) level).
+As already decribed, deployment settings overrule application settings. Thus it
+is possible to combine various parameter specifications. A special case is the
+definition of the username. If an application sets the username and one
+handler instance in the chain does not have a <code>user</code> parameter 
+in its deployment part, then this one handler instance uses the username set
+bey the application. After the handler copied the username from the username
+property, the handler sets the property's content to <code>null</code>. 
+Handlers that follow in the chain cannot use this username anymore and 
+must have a user (or encryption user) parameter in their deployment part.
+
+</p></subsection><subsection name="Deployment at the server"><p>
+
+Note: Handler chaining at the receiver side is not yet fully tested.
+</p><p></p><p>
+Handlers at the receiver can only determine different security headers if their
+SOAP actors are different. The WSS4J handler processes each security structure
+inside one security header. Because the security structures contain most
+information to verify or decrypt the SOAP request this constraint is
+not too much of an issue.
+</p><p></p><p>
+Only the password call back class and the <code>Crypto</code> implementation
+(as defined in the crypto property file) must be able to handle all possible 
+certificates, users, passwords, and keys that a security header may contain.
+The following deployment descriptor of a receiver shows this.
+<source>
+  &lt;requestFlow&gt;
+   &lt;handler type="java:org.apache.ws.axis.security.WSDoAllReceiver"&gt;
+    &lt;parameter name="passwordCallbackClass" 
+      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
+    &lt;parameter name="action" value="Signature Signature"/&gt;
+    &lt;parameter name="signaturePropFile" value="crypto.properties" /&gt;
+   &lt;/handler&gt;
+  &lt;/requestFlow&gt;
+</source>
+The client uses two handlers in a chain, each signing a part of the SOAP 
+request but with different certificates. Because the handlers do not 
+specifiy a SOAP actor WSS4J puts both signatures in the security header
+of the default actor. 
+To match the security actions the deployment descriptor of the receiver needs 
+to contain the action declaration <code>Signature Signature</code>. This 
+instructs the WSS4J handler to accept and verify two distinct signatures 
+contained in one security header. Because the signatures use different 
+certificates the <code>Crypto</code> implementation must be able to handle
+these certificates.
+</p><p></p><p>
+Similar requirements are true for the password callback implementation if the
+sender uses handler chaining and uses different encryption parameters in the
+same security header.
+</p><p></p><p>
+If it is necessary to have different parameters for the distinct signature or
+decryption data then these should be put in different security headers. The 
+easiest way to do this is to define different <code>actor</code> parameters
+for each handler in a WSS4J handler chain.
+ 
+</p></subsection></section><section name="Reporting Security results to services/applications"><p>
+The WSS4J <code>WSSecurityEngine</code> processes the security elements inside
+a security header. If something goes wrong, for example a signature 
+verfication fails, then the engine throws a fault. If the security engine
+could perform all operations sucessfully it returns a data structure
+that contains the results of the performed security actions. This data
+structure holds information about the performed action, the usernames or
+identifier in case the security engine performed signature or username token
+processing. Please refer to the
+{@link org.apache.ws.security.WSSecurityEngineResult result} structure.
+</p><p></p><p>
+The <code>WSDoAllReceiver</code> WSS4J handler takes this structure and
+checks if all required actions were performed. If this check fails, the
+WSS4J handler aborts the SOAP request and throws an Axis SOAP fault.
+Otherwise it creates its own data structure 
+{@link org.apache.ws.axis.security.WSDoAllReceiverResult}, copies the
+security results in this structure, and adds the actor name of the
+security header. The it stores this new data structure in a vector and stores
+this vector in a specific 
+{@link org.apache.ws.security.handler.WSHandlerConstants#RECV_RESULTS property} 
+of the current message context. If WSS4J handlers are
+chained, then every handler in the chain adds its result to the vector. The
+vector contains the results in handler-chain order.
+</p><p></p><p>
+This code snippet shows how a Axis service can access the security result
+data:
+<source>
+    public void ping(javax.xml.rpc.holders.StringHolder text,
+        org.apache.ws.axis.oasis.ping.TicketType ticket)
+        throws java.rmi.RemoteException {
+
+        text.value = "Echo " + text.value.trim();
+		
+        // get the message context first
+        MessageContext msgContext = MessageContext.getCurrentContext();
+        Message reqMsg = msgContext.getRequestMessage();
+
+        Vector results = null;
+        // get the result Vector from the property
+        if ((results =
+            (Vector) msgContext.getProperty(WSHandlerConstants.RECV_RESULTS))
+             == null) {
+            System.out.println("No security results!!");
+        }
+        System.out.println("Number of results: " + results.size());
+        for (int i = 0; i &lt; results.size(); i++) {
+            WSHandlerResult hResult = (WSHandlerResult)results.get(i);
+            String actor = hResult.getActor();
+            Vector hResults = hResult.getResults();
+            for (int j = 0; j &lt; hResults.size(); j++) {
+              	WSSecurityEngineResult eResult = (WSSecurityEngineResult) hResults.get(j);
+                // Note: an encryption action does not have an associated principal
+    	        // only Signature and UsernameToken actions return a principal
+                if (eResult.getAction() != WSConstants.ENCR) {
+                    System.out.println(eResult.getPrincipal().getName());
+                }
+            }
+        }
+    }
+</source>
+The principal structure is either a 
+{@link org.apache.ws.security.WSUsernameTokenPrincipal UsernameToken} principal 
+or a {@link java.security.Principal X509Principal}. The 
+princpals contain the names plus other information of the verified username
+token or signature certificate.
+ 
+</p></section><section name="Some hints"><subsection name="Client"><p>
+At the client side, the WSS4J Axis handler, as all other parts of Axis, run
+in the context of the calling application. Depending on the application,
+the callback classes may perform complex operations, even do some user 
+interaction, to get the password or to access some database to get 
+certificates or keys. There are no timeouts defined at the client side 
+before the SOAP request is put on the wire.
+
+</p></subsection><subsection name="Server"><p>
+On the server side the WSS4J handler run in the same context as the other part
+of the server, usually some servlet container, such as Tomcat. Also the server
+must be able to handle many requests in a short time. Thus the password 
+callback as well as the <code>Crypto</code> implementation shall be
+as fast as possible. In general, no user interaction is possible at the
+server side to gather passwords. Also at this point of the SOAP request
+processing there are active timeouts, even if they are fairly long.
+
+</p></subsection><subsection name="Bi-directional SOAP Security"><p>
+WSS4J fully supports bi-directional SOAP security. To enable bi-directional
+support just put <code>WSDoAllSender</code> on the 
+<code>responseFlow</code> at the server and <code>WSDoAllReceiver</code>
+at the response flow of the client thus reversing the roles. Similar to
+the above hints, the server side part (now <code>WSDoAllSender</code>)
+runs in the server context and <code>WSDoAllReceiver</code>
+runs in the application (client) context. There are no Axis timeout
+constraints on the client side after Axis received the response 
+and handed it over to the WSS4J handler.
+
+</p></subsection><subsection name="Handler chaining"><p>
+Usually WSS4J handlers are chained without any other handler between them in
+the chain. It is, however, possible to do so. In this case the intermediate
+handler <b>must not</b> modify the SOAP Envelope that is contained in the
+Axis message. This could (most probably will) invalidate or destroy any 
+security actions done sofar. Such an intermediate handler may set some 
+properties that may influence the processing of the following WSS4J handler, 
+such as setting a new username, password callback class, and so on.
+
+<!-- Put @see and @since tags down here. -->
+@since WSS4J 1.0</p></subsection>
+</section>
+</body>
+</document>
\ No newline at end of file

Added: webservices/wss4j/trunk/src/site/xdoc/resources.xml
URL: http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/site/xdoc/resources.xml?rev=1574036&view=auto
==============================================================================
--- webservices/wss4j/trunk/src/site/xdoc/resources.xml (added)
+++ webservices/wss4j/trunk/src/site/xdoc/resources.xml Tue Mar  4 11:31:32 2014
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<document>
+<body>
+<section name="Further Resources">
+<p>
+This page lists some further resources that describe how to use WSS4J in more
+detail.
+</p>
+<subsection name="WSS4J 2.0.0 articles">
+<ul>
+<li><a href="http://coheigea.blogspot.ie/2014/01/apache-wss4j-200-part-i.html">WSS4J 2.0.0 overview</a></li>
+</ul>
+</subsection>
+
+<subsection name="WSS4J 1.6.x articles">
+<ul>
+<li><a href="http://coheigea.blogspot.ie/2011/01/wss4j-16-crypto-property-change.html">Crypto property changes in WSS4J 1.6.x</a></li>
+<li><a href="http://coheigea.blogspot.ie/2011/02/support-for-saml2-assertions-in-wss4j.html">Support for SAML 2.0 in WSS4J 1.6.x</a></li>
+<li><a href="http://coheigea.blogspot.ie/2011/02/usernametoken-processing-changes-in.html">UsernameToken processing changes in WSS4J 1.6.x</a></li>
+<li><a href="http://coheigea.blogspot.ie/2011/02/wspasswordcallback-changes-in-wss4j-16.html">WSPasswordCallback changes in WSS4J 1.6.x</a></li>
+<li><a href="http://coheigea.blogspot.ie/2011/02/wss4j-16-specifying-elements-to-sign-or.html">Specifying elements to sign or encrypt</a></li>
+<li><a href="http://coheigea.blogspot.ie/2011/03/wss4j-16-basic-security-profile-11.html">Basic Security Profile 1.1 compliance</a></li>
+<li><a href="http://coheigea.blogspot.ie/2011/03/wss4j-16-saml-property-changes.html">SAML property changes</a></li>
+<li><a href="http://coheigea.blogspot.ie/2011/04/wss4j-16-introducing-validators.html">WSS4J Validators</a></li>
+<li><a href="http://coheigea.blogspot.ie/2011/05/crl-support-in-wss4j-161.html">CRL support in WSS4J 1.6.1</a></li>
+<li><a href="http://coheigea.blogspot.ie/2011/08/saml-token-creation-in-apache-wss4j-16.html">Creating SAML Tokens</a></li>
+<li><a href="http://coheigea.blogspot.ie/2013/03/signature-and-encryption-key.html">Signature and Encryption Key Identifiers in Apache WSS4J</a></li>
+</ul>
+</subsection>
+
+</section>            
+</body>
+</document>

Added: webservices/wss4j/trunk/src/site/xdoc/streaming.xml
URL: http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/site/xdoc/streaming.xml?rev=1574036&view=auto
==============================================================================
--- webservices/wss4j/trunk/src/site/xdoc/streaming.xml (added)
+++ webservices/wss4j/trunk/src/site/xdoc/streaming.xml Tue Mar  4 11:31:32 2014
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<document>
+<body>
+<section name="Streaming (StAX) WS-Security support in Apache WSS4J 2.0.0">
+
+<subsection name="Overview of new features">
+<p>
+WSS4J 2.0.0 introduces a streaming (StAX-based) WS-Security implementation to
+complement the existing DOM-based implementation. The DOM-based implementation
+is quite performant and flexible, but suffers from having to read the entire
+XML tree into memory. For large SOAP requests this can have a detrimental
+impact on performance. In addition, for web services stacks such as Apache CXF
+which are streaming-based, it carries an additional performance penalty of
+having to explicitly convert the request stream to a DOM Element.
+</p>
+<p>
+The new StAX-based WS-Security implementation does not read the request into
+memory, and hence uses far less memory for large requests. It is also more
+performant in certain circumstances. The StAX-based code offers largely the
+same functionality as that available as part of the DOM code, and is
+configured in mostly the same way (via configuration tags that are shared
+between both stacks). It does not offer the low-level API available in the DOM
+code to individually construct various WS-Security tokens, but instead must be
+used by specifying various actions to perform.
+</p>
+<p>
+As of the time of writing, Apache CXF is the only web services stack to 
+integrate the new WS-Security streaming functionality. To switch to use the
+streaming code for the manual "Action" based approach, simply change the
+outbound and inbound interceptors as follows:
+</p>
+<ul>
+<li>"org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor" to
+"org.apache.cxf.ws.security.wss4j.WSS4JStaxOutInterceptor".</li>
+<li>"org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor" to
+"org.apache.cxf.ws.security.wss4j.WSS4JStaxInInterceptor".</li>
+</ul>
+<p>
+For the WS-SecurityPolicy based approach of configuring WS-Security, simply
+set the JAX-WS property SecurityConstants.ENABLE_STREAMING_SECURITY
+("ws-security.enable.streaming") to "true".
+</p>
+</subsection>
+
+</section>            
+</body>
+</document>

Added: webservices/wss4j/trunk/src/site/xdoc/topics.xml
URL: http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/site/xdoc/topics.xml?rev=1574036&view=auto
==============================================================================
--- webservices/wss4j/trunk/src/site/xdoc/topics.xml (added)
+++ webservices/wss4j/trunk/src/site/xdoc/topics.xml Tue Mar  4 11:31:32 2014
@@ -0,0 +1,188 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<document>
+<body>
+<section name="WSS4J Special Topics">
+<p>
+This page discusses various topics regarding usage of WSS4J.  See the <a href="http://ws.apache.org/wss4j/using.html">Using Apache WSS4J</a> page for web stack-specific usage notes.
+</p>
+<subsection name="Crypto Interface">
+<p>
+WSS4J uses the Crypto interface to provide a pluggable way of retrieving and converting certificates, verifying trust on certificates etc. Three implementations are provided out of the box by WSS4J:
+</p>
+<ul>
+<li><a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/ws-security-common/src/main/java/org/apache/wss4j/common/crypto/Merlin.java?view=markup">Merlin</a>: The standard implementation, based around two JDK keystores for key/cert retrieval, and trust verification.</li>
+<li><a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/ws-security-common/src/main/java/org/apache/wss4j/common/crypto/CertificateStore.java?view=markup">CertificateStore</a>: Holds an array of X509 Certificates. Can only be used for encryption and signature verification.</li>
+<li><a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/ws-security-common/src/main/java/org/apache/wss4j/common/crypto/MerlinDevice.java?view=markup">MerlinDevice</a>: Based on Merlin, allows loading of keystores using a null InputStream - for example on a smart-card device.</li>
+</ul>
+<p>
+Typically, a Crypto implementation is loaded and configured via a Crypto properties file. This tells WSS4J what Crypto implementation to load, as well as implementation-specific properties such as a keystore location, password, default alias to use, etc. A typical example of the contents of a Crypto properties file for Signature creation is as <a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/ws-security-dom/src/test/resources/wss40.properties?view=markup">follows</a>:
+</p>
+<ul>
+<li>org.apache.wss4j.crypto.provider=org.apache.wss4j.common.crypto.Merlin</li>
+<li>org.apache.wss4j.crypto.merlin.keystore.type=jks</li>
+<li>org.apache.wss4j.crypto.merlin.keystore.password=security</li>
+<li>org.apache.wss4j.crypto.merlin.keystore.alias=wss40</li>
+<li>org.apache.wss4j.crypto.merlin.keystore.file=keys/wss40.jks</li>
+</ul>
+<p>
+Note that in WSS4J 2.0.0 the "org.apache.ws.security.crypto" prefix used previously is now "org.apache.wss4j.crypto", however both prefixes are accepted by the code. For WSS4J 1.6.X and 1.5.X, you must use the "org.apache.ws.security.crypto" prefix.
+</p>
+</subsection>
+
+<subsection name="Verifying Public Keys">
+<p>In WSS4J 1.5.x, trust validation of public keys involved construction of a PublicKeyCallback instance, passing it the PublicKey object, and invoking the CallbackHandler. It then called a "isVerified" method on the Callback to check to see whether the CallbackHandler had verified the PublicKey or not. The CallbackHandler implementation needed to call the "verifyTrust" method on the PublicKeyCallback, passing in a KeyStore object. This method iterates through each Certificate in the KeyStore, and checks to see whether the PublicKeys match.</p>
+
+<p>In WSS4J 1.6.x, trust validation of public keys was moved from a WSS4J 1.5's PublicKeyCallback instance to the Crypto interface, where the argument is now a PublicKey object. In this way, validation is done using the same interface as for trust validation for Certificates, and the end-user has no need to consider the special-case of verifying public keys in the CallbackHandler, as it is taken care of internally by WSS4J.</p>
+</subsection>
+
+
+<subsection name="Introducing Validators">
+<p>WSS4J 1.6 introduces the concept of a Validator, for validating credentials that have been processed by a Processor instance.</p>
+
+<p>An inbound security header is processed by WSS4J by iterating through each child element of the header, and by calling the appropriate Processor implementation to deal with each element. In WSS4J 1.5.x, some processors perform validation on the received token (e.g. UsernameTokens), whereas others store the processing results for later verification by third-party WS-Handler implementations (e.g. Timestamp verification, Certificate trust verification). There are some problems with this approach:</p>
+
+<ul>
+<li>It is not consistent, some processors perform validation, others do not.</li>
+<li>There is a potential security hole, in that it is assumed third-party code will know to validate the credentials that the WSS4J processors do not validate.</li>
+<li>WSS4J will continue to process the rest of the security header even if the Timestamp is invalid, or the certificate non-trusted, which could lead to denial-of-service attacks.</li>
+<li>There is no separation of concerns between processing the token and validating the token. If you want to change how the token is validated, you must replace the processor instance.</li>
+</ul>
+
+<p>WSS4J 1.6 has moved Timestamp verification and certificate trust validation back into the processing of the security header, thus solving the first three points above. The fourth point is met by the new concept of Validators, as well as some changes to the way Processors and CallbackHandler implementations are used in WSS4J 1.6.</p>
+
+<p>In WSS4J 1.5.x, CallbackHandler implementations are used in different ways by different processors, sometimes they are expected to verify a password (as for processing UsernameTokens), and other times they are expected to supply a password (as for decryption). In WSS4J 1.6, CallbackHandler implementations are only expected to supply a password (if it exists) to the processors. The Processor implementations do not perform any validation of the security token, instead they package up the processed token, along with any (password) information extracted from the CallbackHandler, and hand it off to a Validator implementation for Validation.</p>
+
+<p>The Processor implementations get the specific Validator implementation to use via the RequestData parameter, which in turn asks a WSSConfig object for the Validator implementation. If the Validator is null, then no Validation is performed on the received token. The Processor then stores the received token as normal. WSS4J 1.6 comes with several default Validators, which are:</p>
+
+<ul>
+<li>NoOpValidator: Does no processing of the credential</li>
+<li>TimestampValidator: Validates a Timestamp</li>
+<li>UsernameTokenValidator: Validates a UsernameToken</li>
+<li>SignatureTrustValidator: Verifies trust in a signature</li>
+<li>SamlAssertionValidator: Checks some HOK requirements on a SAML Assertion, and verifies trust on the (enveloped) signature.</li>
+</ul>
+
+<p>There are some additional WSSecurityEngineResult constants that pertain to the Validator implementations:</p>
+
+<ul>
+<li>TAG_VALIDATED_TOKEN: Indicates that the token corresponding to this result has been validated by a Validator implementation. Some of the processors do not have a default Validator implementation.</li>
+<li>TAG_TRANSFORMED_TOKEN: A Validator implementation may transform a credential (into a SAML Assertion) as a result of Validation. This tag holds a reference to an AssertionWrapper instance, that represents a transformed version of the validated credential.</li>
+</ul>
+
+<p>To validate an inbound UsernameToken in some custom way, simply associate the NoOpValidator with the UsernameToken QName in the WSSConfig of the RequestData object used to supply context information to the processors. After WSS4J has finished processing the security header, then extract the WSSecurityEngineResult instance corresponding to the WSConstants.UT action, and perform some custom validation on the token.</p>
+
+<p>To validate plaintext passwords against a directory store, rather than have the CallbackHandler set the password:  Simply @Override the verifyPlaintextPassword(UsernameToken usernameToken) method in the validator. By simply plugging in a validator on the UsernameTokenProcessor (such as the NoOpValidator), it is possible to do any kind of custom validation (or none at all) on the token.</p>
+
+<p>An example of how to add a custom Validator implementation is the STSTokenValidator in CXF 2.4.0. The <a href="http://svn.apache.org/viewvc/cxf/trunk/rt/ws/security/src/main/java/org/apache/cxf/ws/security/trust/STSTokenValidator.java?view=markup">STSTokenValidator</a> tries to validate a received SAML Assertion locally, and if that fails, it dispatches it to a Security Token Service (STS) via the WS-Trust interface for validation. It also supports validating a UsernameToken and BinarySecurityToken in the same manner. The <a href="http://svn.apache.org/viewvc/cxf/trunk/rt/ws/security/src/main/java/org/apache/cxf/ws/security/SecurityConstants.java?view=markup">SecurityConstants</a> class defines some configuration tags for specifying a custom validator for inbound SAML1, SAML2, UsernameToken, BinarySecurityToken, Signature and Timestamps. The STSTokenValidator can be configured by associating it with the appropriate configuration tag.</p>
+
+</subsection>
+
+<subsection name="Specifying elements to sign or encrypt">
+<p>The signature and encryption creation code in WSS4J uses the WSEncryptionPart class to find DOM elements to sign and encrypt. There are a number of minor changes to how elements are located from a WSEncryptionPart in WSS4J 1.6:</p>
+
+<ol>
+<li>WSEncryptionPart now stores an optional DOM element, which will be used as the element to sign/encrypt if it is non-null.</li>
+<li>Failing this, it finds the SOAP body and compares the wsu:Id with the stored Id, or if there is no stored Id in WSEncryptionPart, it checks the stored localname/namespace.</li>
+<li>Failing this, if the stored Id in WSEncryptionPart is not null, it tries to find the first element in the SOAP envelope that has a matching wsu:Id.</li>
+<li>If the stored Id is null, it tries to find *all* DOM Elements that match the stored localname/namespace.</li>
+</ol>
+
+<p>WSEncryptionPart is intended to refer to a single Element for encryption/signature. However, as a localname/namespace is not necessarily unique, point 4 will return all matching Elements. An important implication of the order of the steps given above, is that client code should set the DOM element on the WSEncryptionPart if it is accessible, and if not, it should set the wsu:Id. Otherwise, a localname/namespace (which is not referring to the SOAP Body) will result in a traversal of the DOM tree.</p>
+
+<p>The DOM element(s) that is(are) found are stored for retrieval, so that we don't need to traverse the SOAP envelope multiple times, when e.g. doing an STR Transform, or for element location in the XML Security code.</p>
+</subsection>
+
+<subsection name="WSPasswordCallback identifiers">
+<p>The <a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/ws-security-common/src/main/java/org/apache/wss4j/common/ext/WSPasswordCallback.java?view=markup">WSPasswordCallback class</a> defines a set of integers which correspond to usage instructions for the CallbackHandler.  In WSS4J 1.6, the following WSPasswordCallback identifiers are used:</p>
+
+<ul>
+<li>WSPasswordCallback.DECRYPT - DECRYPT usage is used when the calling code needs a password to get the private key of this identifier (alias) from a keystore. This is only used for the inbound case of decrypting a session (symmetric) key, and not for the case of getting a private key to sign the message. The CallbackHandler must set the password via the setPassword(String) method.</li>
+<li>WSPasswordCallback.USERNAME_TOKEN - USERNAME_TOKEN usage is used to obtain a password for either creating a Username Token (whether plaintext or digest), or for validating it. It is also used for the case of deriving a key from a Username Token. The CallbackHandler must set the password via the setPassword(String) method.</li>
+<li>WSPasswordCallback.SIGNATURE - SIGNATURE usage is used on the outbound side only, to get a password to get the private key of this identifier (alias) from a keystore. The CallbackHandler must set the password via the setPassword(String) method.</li>
+<li>WSPasswordCallback.SECURITY_CONTEXT_TOKEN - SECURITY_CONTEXT_TOKEN usage is for the case of when we want the CallbackHandler to supply the key associated with a SecurityContextToken. The CallbackHandler must set the key via the setKey(byte[]) method.</li>
+<li>WSPasswordCallback.CUSTOM_TOKEN - CUSTOM_TOKEN usage is used for the case that we want the CallbackHandler to supply a token as a DOM Element. For example, this is used for the case of a reference to a SAML Assertion or Security Context Token that is not in the message. The CallbackHandler must set the token via the setCustomToken(Element) method.</li>
+<li>WSPasswordCallback.SECRET_KEY - SECRET_KEY usage is used for the case that we want to obtain a secret key for encryption or signature on the outbound side, or for decryption or verification on the inbound side. The CallbackHandler must set the key via the setKey(byte[]) method.</li>
+</ul>
+<p>
+In WSS4J 2.0, the following additional WSPasswordCallback identifier is:
+</p>
+<ul>
+<li>WSPasswordCallback.PASSWORD_ENCRYPTOR_PASSWORD - PASSWORD_ENCRYPTOR_PASSWORD usage is used to return the password used with a PasswordEncryptor implementation to decrypt encrypted passwords stored in Crypto properties files</li>
+</ul>
+
+</subsection>
+
+<subsection name="UsernameToken handling in WSS4J 1.6">
+
+<p>The CallbackHandler interface receives and requires the following information when handling UsernameTokens:</p>
+
+<ul>
+<li>For both digest and plaintext cases, the CallbackHandler is given the username, password type and an identifier of WSPasswordCallback.USERNAME_TOKEN. It must set the password on the callback, and the validator does the comparison.</li>
+<li>The custom password type case defaults to the same behaviour as the plaintext case, assuming wssConfig.getHandleCustomPasswordTypes() returns true.</li>
+<li>For the case of a username token with no password element, the default behaviour is simply to ignore it, and to store it as a new result of type WSConstants.UT_NOPASSWORD.</li>
+</ul>
+
+</subsection>
+
+<subsection name="Support for SAML2 assertions in WSS4J 1.6">
+
+<p>Support for SAML2 assertions has finally arrived in WSS4J, via the forthcoming 1.6 release. This has been a <a href="http://issues.apache.org/jira/browse/WSS-146">long-standing</a> feature request. WSS4J 1.5.x only supports SAML 1.1 assertions via the deprecated <a href="https://spaces.internet2.edu/display/OpenSAML/OS1Status">Opensaml1</a>, and it supports them in a very limited manner, namely:</p>
+
+<ul><li>It only supports the creation of Authentication statements.</li>
+
+<li>Processing essentially involves saving the assertions, it did not support validating enveloped signatures, or trust on the signatures, etc.</li>
+</ul>
+<p>Several patches were submitted to <a href="http://issues.apache.org/jira/browse/WSS-146">WSS-146</a> to upgrade WSS4J to use Opensaml2. SAML2 support in WSS4J 1.6 consists of:</p>
+<ul><li>Support for creating signed/unsigned SAML 1.1/2.0 assertions, containing authentication, authorization, attribute statements etc.</li>
+<li> This extensibility is achieved by letting the user implement a CallbackHandler instance.</li>
+<li>The SAMLTokenProcessor can now process any type of assertion, verify an enveloped signature on it, and verify trust on the signature. It also verifies some holder-of-key requirements, e.g. that the Subject contains a KeyInfo element, and that the assertion is signed and trusted etc.</li>
+</ul>
+
+<p>WSS4J 1.6 contains an <a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/test/java/org/apache/ws/security/saml/">extensive set of tests</a> for both creating and processing different type of assertions. To illustrate the flexibility and simplicity of the CallbackHandler approach for constructing assertions, take a look at an abstract CallbackHandler <a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/test/java/org/apache/ws/security/common/AbstractSAMLCallbackHandler.java?view=markup">here</a>, as well as the concrete implementations (<a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/test/java/org/apache/ws/security/common/SAML1CallbackHandler.java?view=markup">SAML 1.1</a> and <a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/test/java/org/apache/ws/security/common/SAML2CallbackHandler.java?view=markup">SAML 2</a>). As you can see, a fairly small amount of code can create a large variety of assertions.</p>
+
+<p>Opensaml2 has a very large set of dependencies, but through some judicious pom exclusions, as well replacing the Opensaml DefaultBootstrap code to avoid loading velocity, the following dependencies are introduced in WSS4J via Opensaml (snippet from mvn dependency):</p>
+
+<pre>
++- org.opensaml:opensaml:jar:2.4.1:compile
+ |  \- org.opensaml:openws:jar:1.4.1:compile
+ |     \- org.opensaml:xmltooling:jar:1.3.1:compile
+ |        +- org.slf4j:slf4j-api:jar:1.6.1:compile
+ |        \- joda-time:joda-time:jar:1.6.2:compile
+</pre>
+
+<p>The WSS4J 1.6 pom currently has a dependency on the Shibboleth <a href="http://shibboleth.internet2.edu/downloads/maven2/">repo</a>, where the Opensaml2 artifacts live. It is planned on getting the Opensaml2 artifacts into Maven central in time for the 1.6 release - this is slightly complicated by the fact that some of the Opensaml2 dependencies are themselves not in Maven Central.
+</p>
+<p>One known <a href="http://issues.apache.org/jira/browse/WSS-265">issue</a> is that WSS4J cannot create an Assertion which has an EncryptedKey element in the Subject. This is due to a bug in Opensaml2 which has been <a href="https://bugs.internet2.edu/jira/browse/JOWS-26">fixed</a>, but not released yet.</p>
+<p>
+The Opensaml2 port has a large impact on existing code for *creating* assertions, however it is thought that very few people used that code. It has a minimal impact on existing code for processing assertions, with several caveats:</p>
+
+<ul><li>WSS4J 1.5.x ignored (enveloped) signatures on SAML (1.1) assertions - this is no longer the case, so deployments which do not set the correct keystore/truststore config for dealing with signature verification will fail</li>
+<li> The SAMLTokenProcessor no longer saves all tokens as an "WSConstants.ST_UNSIGNED" action. It saves tokens that do not have an enveloped signature as this action, and token which *do* have an enveloped signature are saved as a "WSConstants.ST_SIGNED" action.</li>
+<li>The object that is saved as part of the action above has changed, from an Opensaml1 specific Assertion object, to an AssertionWrapper instance, which is a WSS4J specific object which encapsulates an Assertion, as well as some information corresponding to signature verification, etc.</li>
+</ul>
+</subsection>
+
+<subsection name="JSR-105 support">
+<p>WSS4J 1.6 has been ported to use the <a href="http://jcp.org/en/jsr/detail?id=105">JSR 105</a>  API for XML Digital Signature. Previously, WSS4J 1.5.x used the custom API of the Apache <a href="http://santuario.apache.org/">Santuario</a> XML Security for Java library to create and process XML Digital Signatures.</p>
+<p>
+WSS4J 1.6 has a minimum requirement of JDK 1.5 (note that WSS4J 1.5.x supports JDK 1.4). As JDK 1.5 does not contain an implementation of JSR 105, this means that XML Digital Signature is done via the JSR 105 implementation of Apache Santuario. However, when JDK 1.6+ is used, WSS4J 1.6 uses the JDK implementation of JSR 105 for signature creation and verification. You can override this by endorsing the Santuario jar.</p>
+<p>
+The Apache Santuario XML Security jar is still required for the JDK 1.6 case, as there are compile-time dependencies in WSS4J for encryption/decryption, as well as for some algorithm parsing, and resource resolver stuff. One downside to the Santuario jar, is its dependence on Xalan for a small subset of operations. This dependency will be <a href="https://issues.apache.org/jira/browse/SANTUARIO-252">removed</a> for the 1.5 release of that library (in a few months).</p>
+
+<p>
+It is worth noting some changes to the main <a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/main/java/org/apache/ws/security/message/WSSecSignature.java?view=markup">class</a> used in WSS4J for signature creation as a result of the JSR-105 port. In WSS4J 1.5.x, after the signature certs and list of references to sign had been configured, the "computeSignature" method was called to compute the signature. The DOM element corresponding to the signature was independent of the pre-existing security header, and could be extracted later and inserted into the security header.</p>
+<p>
+In WSS4J 1.6, you must tell "computeSignature" where to insert the signature element. A boolean "prepend" argument allows you to configure whether to prepend the generated Signature element to the security header, or whether to append it. If prepend is true, then an optional siblingElement argument can be used to prepend the signature element before this sibling element. Once computeSignature has been called, you have no control over where the signature element is inserted into the security header.</p>
+</subsection>
+
+<subsection name="Basic Security Profile 1.1 compliance">
+
+<p>The Basic Security Profile (BSP) 1.1 <a href="http://www.ws-i.org/Profiles/BasicSecurityProfile-1.1.html">specification</a> provides an industry-standard way of making sure that different WS-Security stacks can communicate with each other, by clarifying and narrowing the scope of the various WS-Security standards. WSS4J 1.5.x does not implement the BSP in any meaningful way. The <a href="http://svn.apache.org/viewvc/webservices/wss4j/branches/1_5_x-fixes/src/org/apache/ws/security/WSSConfig.java?view=markup">WSSConfig</a> class supports a "isWsiBSPCompliant" method (default is false), which will enable the generation of an InclusivePrefix list for signature generation, something that is mandated by the BSP spec.</p>
+<p>
+WSS4J 1.6 provides <a href="https://issues.apache.org/jira/browse/WSS-256">support</a> for the BSP 1.1 specification, in so far as it pertains to the core WS-Security specifications that WSS4J supports. The enforcing of BSP compliance for inbound messages is controlled by the WSSConfig class, as per WSS4J 1.5.x. An important change is that BSP compliance is now turned <b>on </b>by default. In addition, a new <a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/main/java/org/apache/ws/security/handler/WSHandlerConstants.java?view=markup">WSHandlerConstants</a> configuration parameter has been added so that BSP compliance can be controlled via a WSHandler implementation.</p>
+
+</subsection>
+
+</section>            
+</body>
+</document>

Added: webservices/wss4j/trunk/src/site/xdoc/user_guide.xml
URL: http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/site/xdoc/user_guide.xml?rev=1574036&view=auto
==============================================================================
--- webservices/wss4j/trunk/src/site/xdoc/user_guide.xml (added)
+++ webservices/wss4j/trunk/src/site/xdoc/user_guide.xml Tue Mar  4 11:31:32 2014
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<document>
+<body>
+<section name="Apache WSS4J User's Guide">
+<p>
+Click on the links below for more information about the functionality offered
+by WSS4J and how to configure it.
+</p>
+<ul>
+<li><a href="using.html">Using Apache WSS4J</a></li>
+<li><a href="config.html">WSS4J Configuration</a></li>
+<li><a href="newfeatures20.html">WSS4J 2.0.0 New Features</a></li>
+<li><a href="streaming.html">Streaming WS-Security support</a></li>
+<li><a href="attachments.html">Securing message attachments</a></li>
+<li><a href="migration.html">WSS4J 2.0.0 Migration Guide</a></li>
+<li><a href="wss4j16.html">WSS4J 1.6.0 Migration Guide</a></li>
+<li><a href="topics.html">Special Topics</a></li>
+<li><a href="best_practice.html">Security Best Practices</a></li>
+<li><a href="resources.html">Further Resources</a></li>
+</ul>
+</section>            
+</body>
+</document>

Added: webservices/wss4j/trunk/src/site/xdoc/using.xml
URL: http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/site/xdoc/using.xml?rev=1574036&view=auto
==============================================================================
--- webservices/wss4j/trunk/src/site/xdoc/using.xml (added)
+++ webservices/wss4j/trunk/src/site/xdoc/using.xml Tue Mar  4 11:31:32 2014
@@ -0,0 +1,259 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<document>
+<body>
+<section name="Using Apache WSS4J">
+<p>
+This page describes how to use Apache WSS4J. For information about how to
+configure WSS4J, see the <a href="config.html">configuration page</a>. WSS4J
+can essentially be used in three different ways. For information about using
+WSS4J with a SOAP stack, see the sections on Apache CXF and Apache Rampart/Axis.
+</p>
+<ul>
+<li>Action based approach: WSS4J offers an "Action" based approach to
+applying WS-Security to a SOAP request or response, in conjunction with a SOAP
+stack.</li>
+<li>WS-SecurityPolicy based approach: WSS4J can be configured for a SOAP
+request/response via WS-SecurityPolicy, in conjunction with a SOAP Stack. 
+This is the recommended approach.</li>
+<li>Standalone approach: WSS4J offers a low-level (DOM) API to
+construct/sign/encrypt/etc. tokens directly.</li>
+</ul>
+
+<subsection name="Action based approach">
+<p>
+The WSHandler class in WSS4J is designed to configure WSS4J to secure an
+outbound SOAP request, by parsing configuration that is supplied to it via
+a subclass. Typically a web services stack that uses WSS4J for WS-Security
+will subclass WSHandler. An example of a subclass is the
+<a href="http://cxf.apache.org/docs/ws-security.html">WSS4JOutInterceptor</a>
+in Apache CXF. The configuration tags are defined in the <a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/ws-security-common/src/main/java/org/apache/wss4j/common/ConfigurationConstants.java?view=markup">ConfigurationConstants</a> class (WSHandlerConstants in WSS4J 1.6.x). For a more detailed explanation
+of the configuration tags, please refer to the
+<a href="config.html">configuration</a> page. The next few paragraphs will
+describe the most fundamental configuration tags that are used in most
+cases.
+</p>
+
+<h3><p>Common configuration tags</p></h3>
+<p>
+The "Action" based approach to using Apache WSS4J involves explicitly telling
+WSS4J what WS-Security functionality to perform on a request, by configuring
+the stack specific WSHandler implementation with the required properties. On
+the receiving side, the "actions" that are configured are matched against what
+was processed in the security header, and an error is thrown if they do not
+match (in some order). Typical actions include "UsernameToken, "Signature",
+"Encrypt", "Timestamp, "SAMLTokenSigned", etc. 
+</p>
+<p>
+After specifying the action to perform on a request, the next task is typically
+to specify the "user". The "user" can be either the username to insert into a
+UsernameToken, or the keystore alias to use for either signature or encryption.
+If you are configuring more than one of these actions, the "signatureUser" and
+"encryptionUser" configuration tags override the more general "user" tag. The
+next task is often to specify a CallbackHandler implementation to use to
+retrieve passwords. On the sending side, this is used to retrieve a password
+to insert into a UsernameToken and to decrypt a private key from a keystore
+for Signature. On the receiving side, it is used to retrieve a password to
+validate a received UsernameToken, and to decrypt a private key from a
+keystore to use for decryption.  
+</p>
+<p>
+The next task is to specify a Crypto implementation if you are using Signature
+or Encryption. See the <a href="configuration.html">configuration</a> page for
+more information on the Crypto interface. Typically, it is configured in a 
+Crypto properties file, which specifies the Crypto implementation to use, as
+well as the keystore location, default alias/password, etc. For signature, the
+path of this properties file can be referred to by the tag "signaturePropFile"
+and "encryptionPropFile" for outbound request, and
+"signatureVerificationPropFile" and "decryptionPropFile" for inbound requests".
+How signing keys/certificates are referenced from a Signature can be 
+controlled via the "signatureKeyIdentifier" configuration tag. This defaults
+to "IssuerSerial", but could be "DirectReference", "Thumbprint", etc. The
+"encryptionKeyIdentifier" tag performs the same function for encryption.
+</p>
+<p>
+Finally, the Elements to sign or encrypt can be specified by the
+"signatureParts" and "encryptionParts" configuration tags. Both default to the
+SOAP Body. The value of signatureParts/encryptionParts is a list of semi-colon
+separated values that identify the elements to sign/encrypt. The value is of
+the format of an encryption mode specifier, and a namespace URI, each inside a
+pair of curly brackets, and then the local name of the Element. For example,
+"{Content}{http://example.org/paymentv2}CreditCard;". The encryption modifier
+can be either "Content" or "Element" and only applies to encryption.
+</p>
+<p>
+Here are some sample configuration values for various actions, as taken from
+some CXF system tests. The constructor of the
+WSS4JOutInterceptor/WSS4JInIntereptor interceptors in CXF takes a map of 
+String/Object pairs which correspond to the key/value pairs given in the tables
+below. See the CXF configuration <a href="https://git-wip-us.apache.org/repos/asf?p=cxf.git;a=blob_plain;f=systests/ws-security/src/test/resources/org/apache/cxf/systest/ws/action/client.xml;hb=HEAD">file</a> for more information.
+</p>
+
+<h3><p>Sample Outbound UsernameToken configuration</p></h3>
+
+<table name="UsernameToken configuration">
+<tr>
+<th>Key</th>
+<th>Value</th>
+</tr>
+<tr>
+<td>action</td>
+<td>UsernameToken</td>
+</tr>
+<tr>
+<td>user</td>
+<td>Alice</td>
+</tr>
+<tr>
+<td>passwordCallbackClass</td>
+<td><a href="https://git-wip-us.apache.org/repos/asf?p=cxf.git;a=blob_plain;f=systests/ws-security/src/test/java/org/apache/cxf/systest/ws/common/UTPasswordCallback.java;hb=HEAD">org.apache.cxf.systest.ws.common.UTPasswordCallback</a></td>
+</tr>
+</table>
+
+<h3><p>Sample Outbound Signature/Timestamp configuration</p></h3>
+
+<table name="Signature configuration">
+<tr>
+<th>Key</th>
+<th>Value</th>
+</tr>
+<tr>
+<td>action</td>
+<td>Signature Timestamp</td>
+</tr>
+<tr>
+<td>signatureUser</td>
+<td>alice</td>
+</tr>
+<tr>
+<td>passwordCallbackClass</td>
+<td><a href="https://git-wip-us.apache.org/repos/asf?p=cxf.git;a=blob_plain;f=systests/ws-security/src/test/java/org/apache/cxf/systest/ws/common/KeystorePasswordCallback.java;hb=HEAD">org.apache.cxf.systest.ws.common.KeystorePasswordCallback</a></td>
+</tr>
+<tr>
+<td>signaturePropFile</td>
+<td><a href="https://git-wip-us.apache.org/repos/asf?p=cxf.git;a=blob_plain;f=systests/ws-security/src/test/resources/alice.properties;hb=HEAD">alice.properties</a></td>
+</tr>
+<tr>
+<td>signatureKeyIdentifier</td>
+<td>DirectReference</td>
+</tr>
+<tr>
+<td>signatureParts</td>
+<td>{}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp;{}{http://schemas.xmlsoap.org/soap/envelope/}Body;</td>
+</tr>
+</table>
+
+</subsection>
+
+<subsection name="WS-SecurityPolicy based approach">
+<p>
+The recommended way of applying WS-Security to your web services is to use
+WS-SecurityPolicy. The WS-SecurityPolicy specification defines a set of
+WS-Policy expressions that can be used to define the security requirements of
+a web service. Typically one or more policies are attached to the WSDL of a
+service, which conveys the security requirements of the service to the client.
+A WS-SecurityPolicy aware stack such as Apache CXF or Apache Axis/Rampart can
+parse the policies and configure WSS4J appropriately. This greatly simplifies
+things for the user, who then only has to supply some basic information about
+which users, CallbackHandlers, Crypto property files, etc. to use.
+</p>
+<p>
+For more information on using WS-SecurityPolicy with WSS4J, please see CXF's
+WS-SecurityPolicy page, or go to the SOAP stack sections below:
+<a href="http://cxf.apache.org/docs/ws-securitypolicy.html">CXF
+WS-SecurityPolicy configuration</a>
+</p>
+
+</subsection>
+
+<subsection name="Standalone approach">
+<p>
+Apache WSS4J provides a set of APIs to implement WS-Security functionality on
+a SOAP message. It is possible to use these APIs directly in a standalone
+manner, although it is far more common to use either the "Action" or
+WS-SecurityPolicy based approaches. This functionality is only available for
+the DOM code. The best way of finding out how to do this is to take a look at
+the test sources. For example: 
+</p>
+<ul>
+<li>
+<a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/UsernameTokenTest.java?view=markup">Username Token Test</a>
+</li>
+<li>
+<a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/EncryptionTest.java?view=markup">Encryption Test</a>
+</li>
+<li>
+<a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/SignatureTest.java?view=markup">Signature Test</a>
+</li>
+<li>
+<a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/TimestampTest.java?view=markup">Timestamp Test</a>
+</li>
+<li>
+<a href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/ws-security-dom/src/test/java/org/apache/wss4j/dom/saml/SamlTokenTest.java?view=markup">SAML Token Test</a>
+</li>
+</ul>
+</subsection>
+
+<subsection name="SOAP Stacks">
+
+<h3><p>Apache CXF</p></h3>
+<p>
+<a href="http://cxf.apache.org">Apache CXF</a> is an open-source web services
+stack. CXF uses WSS4J to perform the core WS-Security functionality, and
+provides extended security functionality based around the WS-SecurityPolicy,
+WS-SecureConversation and WS-Trust specifications. More information:
+</p>
+<ul>
+<li>
+<a href="http://cxf.apache.org/docs/ws-security.html">CXF WS-Security
+configuration</a>
+</li>
+<li>
+<a href="http://cxf.apache.org/docs/ws-secureconversation.html">CXF
+WS-SecureConversation configuration</a>
+</li>
+<li>
+<a href="http://cxf.apache.org/docs/ws-securitypolicy.html">CXF
+WS-SecurityPolicy configuration</a>
+</li>
+<li>
+<a href="http://cxf.apache.org/docs/ws-trust.html">CXF WS-Trust
+configuration</a>
+</li>
+<li>
+<a href="http://cxf.apache.org/resources-and-articles.html">CXF Security
+articles</a>
+</li>
+</ul>
+
+<h3><p>Apache Rampart/Axis</p></h3>
+<p>
+<a href="http://axis.apache.org/axis2/java/rampart/">Apache Rampart</a> is the
+security module for the Axis2 web services stack. Rampart uses WSS4J to
+perform the core WS-Security functionality, and provides extended security
+functionality based around the WS-SecurityPolicy, WS-SecureConversation and
+WS-Trust specifications. Note that support for Apache Axis1 via the WSS4J
+1.5.x series of releases is no longer supported. More information:
+</p>
+<ul>
+<li>
+<a href="http://axis.apache.org/axis2/java/rampart/developer-guide.html">
+Rampart developer guide</a>
+</li>
+<li>
+<a href="http://axis.apache.org/axis2/java/rampart/samples.html">Rampart
+samples</a>
+</li>
+<li>
+<a href="http://axis.apache.org/axis2/java/rampart/rampartconfig-guide.html">
+Rampart configuration guide</a>
+</li>
+<li>
+<a href="http://axis.apache.org/axis2/java/rampart/articles.html">Rampart
+articles</a>
+</li>
+</ul>
+</subsection>
+
+</section>            
+</body>
+</document>



Mime
View raw message