svn commit: r1566629 - in /webservices/wss4j/site/src/site/xdoc: config.xml migration.xml

[co...@apache.org]

Author: coheigea
Date: Mon Feb 10 14:11:07 2014
New Revision: 1566629

URL: http://svn.apache.org/r1566629
Log:
Updating migration guide

Modified:
    webservices/wss4j/site/src/site/xdoc/config.xml
    webservices/wss4j/site/src/site/xdoc/migration.xml

Modified: webservices/wss4j/site/src/site/xdoc/config.xml
URL: http://svn.apache.org/viewvc/webservices/wss4j/site/src/site/xdoc/config.xml?rev=1566629&r1=1566628&r2=1566629&view=diff
==============================================================================
--- webservices/wss4j/site/src/site/xdoc/config.xml (original)
+++ webservices/wss4j/site/src/site/xdoc/config.xml Mon Feb 10 14:11:07 2014
@@ -753,7 +753,7 @@ properties files. The default is the Jas
 <tr>
 <td><b>WSS4J 2.0.0</b> DERIVED_TOKEN_REFERENCE</td>
 <td>derivedTokenReference</td>
-<td>This controls how deriving tokens are referenced. Only used by StAX code.</td>
+<td>This controls how deriving tokens are referenced.</td>
 </tr>
 <tr>
 <td><b>WSS4J 2.0.0</b> DERIVED_TOKEN_KEY_ID</td>

Modified: webservices/wss4j/site/src/site/xdoc/migration.xml
URL: http://svn.apache.org/viewvc/webservices/wss4j/site/src/site/xdoc/migration.xml?rev=1566629&r1=1566628&r2=1566629&view=diff
==============================================================================
--- webservices/wss4j/site/src/site/xdoc/migration.xml (original)
+++ webservices/wss4j/site/src/site/xdoc/migration.xml Mon Feb 10 14:11:07 2014
@@ -6,7 +6,7 @@
 This page is a migration guide for helping Apache WSS4J 1.6.X users to migrate
 to the 2.0.X releases.
 </p>
-<subsection name="Crypto properties changes">
+<subsection name="Crypto/CallbackHandler changes">
 <p>
 Typically, a user configures Signature and Encryption keys via a Crypto
 properties file. In WSS4J 1.6.X, the property names all start with 
@@ -14,15 +14,44 @@ properties file. In WSS4J 1.6.X, the pro
 "org.apache.wss4j.crypto.*". However, WSS4J 2.0.0 will accept the older
 prefix value. No other changes are necessary for migrating Crypto properties.
 </p>
+<p>
+In WSS4J 1.6.x, it was only possible to specify a Crypto implementation for
+both Signature Creation + Verification. In WSS4J 2.0.0, there is now a
+separate Signature Verification Crypto instance, that can be configured via
+the following configuration tags:
+</p>
+<ul>
+<li>signatureVerificationPropFile - The path of the crypto property file to
+use for Signature verification.</li>
+<li>signatureVerificationPropRefId - The key that holds a reference to the
+object holding complete information about the signature verification Crypto
+implementation.</li>
+</ul>
+<p>
+In WSS4J, you need to define a CallbackHandler to supply a password to a
+WSPasswordCallback Object when dealing with UsernameTokens, or to unlock
+private keys for Signature creation, etc. In WSS4J 2.0.0, the functionality is
+exactly the same, except that the package of the WSPasswordCallback Object has
+changed from "org.apache.ws.security" to "org.apache.wss4j.common.ext". Any
+CallbackHandler implementation will need to be updated to use the new package.
+</p>
 </subsection>
-<subsection name="Changes to how SAML Assertions are signed">
+<subsection name="SAML Assertion changes">
+<p>
+A CallbackHandler implementation is required to create a SAML Assertion, by
+populating various beans. Similar to the WSPasswordCallback package change,
+there are also some package changes for SAML. The base package for the
+SAMLCallback class, and of the various "bean" classes, has changed from
+"org.apache.ws.security.saml.ext" to "org.apache.wss4j.common.saml". 
+</p>
 <p>
 Apache WSS4J 1.6.x uses the SAMLIssuer interface to configure the creation and
 signing of a SAML Assertion. In Apache WSS4J 2.0.0, the SAMLIssuer
 functionality has been moved to the SAMLCallback, so that the CallbackHandler
 used to create a SAML Assertion is responsible for all of the signing
 configuration as well. Therefore, the properties file that is used in
-WSS4J 1.6.X to sign a SAML Assertion is no longer used in WSS4J 2.0.0.
+WSS4J 1.6.X to sign a SAML Assertion is no longer used in WSS4J 2.0.0, and
+the "samlPropFile" and "samlPropRefId" configuration tags have been removed. 
 </p>
 <p>
 The SAMLCallback Object contains the additional properties in WSS4J 2.0.0 that
@@ -60,7 +89,7 @@ verifying signatures. In WSS4J 1.6.x, th
 signature creation and verification.
 </p>
 
-<subsection name="Removed Configuration tags in WSS4J 2.0.0">
+<h3><p>Removed Configuration tags in WSS4J 2.0.0</p></h3>
 <p>
 This section details the Configuration tags that are no longer present in
 WSS4J 2.0.0.
@@ -110,9 +139,8 @@ See the ADD_USERNAMETOKEN_NONCE and ADD_
 functionality. Removed as it is not standard compliant.</td>
 </tr>
 </table>
-</subsection>
 
-<subsection name="New Configuration tags in WSS4J 2.0.0">
+<h3><p>New Configuration tags in WSS4J 2.0.0</p></h3>
 <p>
 This section details the new Configuration tags in WSS4J 2.0.0.
 </p>
@@ -301,6 +329,31 @@ properties files. The default is the Jas
 </table>
 </subsection>
 
+<subsection name="Derived Key and Secure Conversation namespace change">
+<p>
+In WSS4J 1.6.X, the default namespace used for Derived Key and Secure
+Conversation was the older "http://schemas.xmlsoap.org/ws/2005/02/sc"
+namespace. In WSS4J 2.0.0, the default namespace is now
+"http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512". To switch
+back to use the older namespace, you can set the new configuration property
+"USE_2005_12_NAMESPACE" to "false".
+</p>
+</subsection>
+
+<subsection name="Caching changes">
+<p>
+WSS4J 2.0.0 uses three EhCache-based caches by default for the following
+scenarios, to prevent replay attacks:
+</p>
+<ul>
+<li>UsernameToken nonces</li>
+<li>Signed Timestamps</li>
+<li>SAML 2.0 OneTimeUse Assertions</li>
+</ul>
+<p>
+If you are seeing a error about "replay attacks" after upgrade, then you may
+need to disable a particular cache.
+</p>
 </subsection>
 
 </section>