Author: coheigea
Date: Fri May 15 11:35:41 2015
New Revision: 1679544
URL: http://svn.apache.org/r1679544
Log:
Adding WSS4J 2.1.0 migration guide
Added:
webservices/wss4j/trunk/src/site/xdoc/migration/
webservices/wss4j/trunk/src/site/xdoc/migration/migration.xml
webservices/wss4j/trunk/src/site/xdoc/migration/newfeatures20.xml
- copied, changed from r1679527,
webservices/wss4j/trunk/src/site/xdoc/newfeatures20.xml
webservices/wss4j/trunk/src/site/xdoc/migration/wss4j16.xml
- copied, changed from r1679527,
webservices/wss4j/trunk/src/site/xdoc/wss4j16.xml
webservices/wss4j/trunk/src/site/xdoc/migration/wss4j20.xml
- copied, changed from r1679527,
webservices/wss4j/trunk/src/site/xdoc/migration.xml
webservices/wss4j/trunk/src/site/xdoc/migration/wss4j21.xml
Removed:
webservices/wss4j/trunk/src/site/xdoc/migration.xml
webservices/wss4j/trunk/src/site/xdoc/newfeatures20.xml
webservices/wss4j/trunk/src/site/xdoc/wss4j16.xml
Modified:
webservices/wss4j/trunk/src/site/xdoc/config.xml
webservices/wss4j/trunk/src/site/xdoc/user_guide.xml
Modified: webservices/wss4j/trunk/src/site/xdoc/config.xml
URL:
http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/site/xdoc/config.xml?rev=1679544&r1=1679543&r2=1679544&view=diff
==============================================================================
--- webservices/wss4j/trunk/src/site/xdoc/config.xml (original)
+++ webservices/wss4j/trunk/src/site/xdoc/config.xml Fri May 15 11:35:41 2015
@@ -30,7 +30,7 @@ For more information on the Crypto imple
Topics page</a>. It is possible to instantiate a Crypto implementation
directly, but it can also be loaded via a properties file. For Apache WSS4J
2.0.0 onwards, the property names ${PREFIX} below is "org.apache.wss4j.crypto".
-For Apache WSS4J 1.6.X, the property names ${PREFIX} below is
+For Apache WSS4J 1.6.x, the property names ${PREFIX} below is
"org.apache.ws.security.crypto". WSS4J 2.0.0 onwards will also accept the older
${PREFIX} value. The property values for the standard Merlin implementation
are as follows:
@@ -271,7 +271,7 @@ The configuration tags for Actions are a
<td>Add a "Custom" token from a CallbackHandler</td>
</tr>
<tr>
-<td><b>WSS4J 1.6.X only</b> SIGN_WITH_UT_KEY</td>
+<td><b>WSS4J 1.6.x only</b> SIGN_WITH_UT_KEY</td>
<td>UsernameTokenSignature</td>
<td>Perform a .NET specific signature using a Username Token action.</td>
</tr>
@@ -347,13 +347,13 @@ summarised here:
<td>The CallbackHandler implementation object used to construct SAML
Assertions.</td>
</tr>
<tr>
-<td><b>WSS4J 1.6.X only</b> ENC_CALLBACK_CLASS</td>
+<td><b>WSS4J 1.6.x only</b> ENC_CALLBACK_CLASS</td>
<td>embeddedKeyCallbackClass</td>
<td>The CallbackHandler implementation class used to get the key associated
with a key name.</td>
</tr>
<tr>
-<td><b>WSS4J 1.6.X only</b> ENC_CALLBACK_REF</td>
+<td><b>WSS4J 1.6.x only</b> ENC_CALLBACK_REF</td>
<td>embeddedKeyCallbackRef</td>
<td>The CallbackHandler implementation object used to get the key associated
with a key name.</td>
@@ -462,7 +462,7 @@ Default is "false"</td>
is "false".</td>
</tr>
<tr>
-<td><b>WSS4J 1.6.X only</b> PASSWORD_TYPE_STRICT</td>
+<td><b>WSS4J 1.6.x only</b> PASSWORD_TYPE_STRICT</td>
<td>passwordTypeStrict</td>
<td>Whether to enable strict Username Token password type handling. Default is
"false".</td>
@@ -480,7 +480,7 @@ is "false".</td>
subtree of the document. Default is "false".</td>
</tr>
<tr>
-<td><b>WSS4J 1.6.X only</b> USE_DERIVED_KEY</td>
+<td><b>WSS4J 1.6.x only</b> USE_DERIVED_KEY</td>
<td>useDerivedKey</td>
<td>Whether to use the standard UsernameToken Key Derivation algorithm.
Default is "true".</td>
@@ -605,12 +605,12 @@ parameter are as follows:
WSConstants.PW_DIGEST.</td>
</tr>
<tr>
-<td><b>WSS4J 1.6.X only</b> ENC_KEY_NAME</td>
+<td><b>WSS4J 1.6.x only</b> ENC_KEY_NAME</td>
<td>embeddedKeyName</td>
<td>The text of the key name to be sent in the KeyInfo for encryption</td>
</tr>
<tr>
-<td><b>WSS4J 1.6.X only</b> ADD_UT_ELEMENTS</td>
+<td><b>WSS4J 1.6.x only</b> ADD_UT_ELEMENTS</td>
<td>addUTElements</td>
<td>Additional elements to add to a Username Token, i.e. "nonce" and "created".
</td>
@@ -639,7 +639,7 @@ certificate.
default is: "http://www.w3.org/2001/10/xml-exc-c14n#";.</td>
</tr>
<tr>
-<td><b>WSS4J 1.6.X only</b> WSE_SECRET_KEY_LENGTH</td>
+<td><b>WSS4J 1.6.x only</b> WSE_SECRET_KEY_LENGTH</td>
<td>wseSecretKeyLength</td>
<td>The length of the secret (derived) key to use for the WSE UT_SIGN
functionality.</td>
Added: webservices/wss4j/trunk/src/site/xdoc/migration/migration.xml
URL:
http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/site/xdoc/migration/migration.xml?rev=1679544&view=auto
==============================================================================
--- webservices/wss4j/trunk/src/site/xdoc/migration/migration.xml (added)
+++ webservices/wss4j/trunk/src/site/xdoc/migration/migration.xml Fri May 15
11:35:41 2015
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<document>
+<body>
+<section name="Apache WSS4J Migration Guides">
+<p>
+Click on the links below for more information about migrating to various
+new versions of WSS4J.
+</p>
+<ul>
+<li><a href="wss4j21.html">WSS4J 2.1.0 Migration Guide</a></li>
+<li><a href="wss4j20.html">WSS4J 2.0.0 Migration Guide</a></li>
+<li><a href="newfeatures20.html">WSS4J 2.0.0 New Features</a></li>
+<li><a href="wss4j16.html">WSS4J 1.6.0 Migration Guide</a></li>
+</ul>
+</section>
+</body>
+</document>
Copied: webservices/wss4j/trunk/src/site/xdoc/migration/newfeatures20.xml (from
r1679527, webservices/wss4j/trunk/src/site/xdoc/newfeatures20.xml)
URL:
http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/site/xdoc/migration/newfeatures20.xml?p2=webservices/wss4j/trunk/src/site/xdoc/migration/newfeatures20.xml&p1=webservices/wss4j/trunk/src/site/xdoc/newfeatures20.xml&r1=1679527&r2=1679544&rev=1679544&view=diff
==============================================================================
(empty)
Copied: webservices/wss4j/trunk/src/site/xdoc/migration/wss4j16.xml (from
r1679527, webservices/wss4j/trunk/src/site/xdoc/wss4j16.xml)
URL:
http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/site/xdoc/migration/wss4j16.xml?p2=webservices/wss4j/trunk/src/site/xdoc/migration/wss4j16.xml&p1=webservices/wss4j/trunk/src/site/xdoc/wss4j16.xml&r1=1679527&r2=1679544&rev=1679544&view=diff
==============================================================================
--- webservices/wss4j/trunk/src/site/xdoc/wss4j16.xml (original)
+++ webservices/wss4j/trunk/src/site/xdoc/migration/wss4j16.xml Fri May 15
11:35:41 2015
@@ -5,7 +5,7 @@
<p>
This page describes the new features of WSS4J 1.6.0, and the things to be
aware of when upgrading from WSS4J 1.5.x. Note that WSS4J 1.6.x has now been
-replaced by WSS4J 2.0.x, please see the WSS4J 2.0.0 <a
href="migration.html">migration guide</a> for more information.
+replaced by WSS4J 2.0.x, please see the WSS4J 2.0.0 <a
href="wss4j20.html">migration guide</a> for more information.
</p>
<subsection name="New features">
<p>
Copied: webservices/wss4j/trunk/src/site/xdoc/migration/wss4j20.xml (from
r1679527, webservices/wss4j/trunk/src/site/xdoc/migration.xml)
URL:
http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/site/xdoc/migration/wss4j20.xml?p2=webservices/wss4j/trunk/src/site/xdoc/migration/wss4j20.xml&p1=webservices/wss4j/trunk/src/site/xdoc/migration.xml&r1=1679527&r2=1679544&rev=1679544&view=diff
==============================================================================
--- webservices/wss4j/trunk/src/site/xdoc/migration.xml (original)
+++ webservices/wss4j/trunk/src/site/xdoc/migration/wss4j20.xml Fri May 15
11:35:41 2015
@@ -1,12 +1,12 @@
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<body>
-<section name="WSS4J 2.0.0 Migration Guide">
+<section name="Apache WSS4J 2.0.0 Migration Guide">
<p>
-This page is a migration guide for helping Apache WSS4J 1.6.X users to migrate
-to the 2.0.X releases. Also see the <a href="newfeatures20.html">new
+This page is a migration guide for helping Apache WSS4J 1.6.x users to migrate
+to the 2.0.x releases. Also see the <a href="newfeatures20.html">new
features</a> page for more information about the new functionality available in
-WSS4J 2.0.X.
+WSS4J 2.0.x.
</p>
<subsection name="Migrating to using the streaming (StAX) code">
<p>
@@ -44,7 +44,7 @@ please see the <a href="streaming.html">
<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
+properties file. In WSS4J 1.6.x, the property names all start with
"org.apache.ws.security.crypto.*". In WSS4J 2.0.0, the new prefix is
"org.apache.wss4j.crypto.*". However, WSS4J 2.0.0 will accept the older
prefix value. No other changes are necessary for migrating Crypto properties.
@@ -85,7 +85,7 @@ signing of a SAML Assertion. In Apache W
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, and
+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>
@@ -107,7 +107,7 @@ can be set to sign the Assertion:
</subsection>
<subsection name="Configuration tag changes">
<p>
-In WSS4J 1.6.X, configuration tags were configured in the WSHandlerConstants
+In WSS4J 1.6.x, configuration tags were configured in the WSHandlerConstants
class. In WSS4J 2.0.0, both the DOM and StAX-based code largely share the
same configuration options, and so the configuration tags are defined in
<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>.
Note that the WSS4J 1.6.x configuration class
@@ -117,7 +117,7 @@ change any configuration code when upgra
<p>
The configuration tags that have been removed and added are detailed below.
The non-standard key derivation and UsernameToken Signature functionality that
-was optional in WSS4J 1.6.X has been removed. Some new actions are added for
+was optional in WSS4J 1.6.x has been removed. Some new actions are added for
the streaming code, as well as some options surrounding caching. An important
migration point is that there is now a separate configuration tag used for
verifying signatures. In WSS4J 1.6.x, there was only one tag used for both
@@ -391,7 +391,7 @@ properties files. The default is the Jas
<subsection name="Derived Key and Secure Conversation namespace change">
<p>
-In WSS4J 1.6.X, the default namespace used for Derived Key and Secure
+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
Added: webservices/wss4j/trunk/src/site/xdoc/migration/wss4j21.xml
URL:
http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/site/xdoc/migration/wss4j21.xml?rev=1679544&view=auto
==============================================================================
--- webservices/wss4j/trunk/src/site/xdoc/migration/wss4j21.xml (added)
+++ webservices/wss4j/trunk/src/site/xdoc/migration/wss4j21.xml Fri May 15
11:35:41 2015
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<document>
+<body>
+<section name="Apache WSS4J 2.1.0 Migration Guide">
+<p>
+This page is a migration guide for helping Apache WSS4J 2.0.x users to migrate
+to the 2.1.x releases.
+</p>
+
+<subsection name="JDK7 minimum requirement">
+<p>
+WSS4J 2.0.x required JDK6 as a minimum requirement. WSS4J 2.1.x requires at
+least JDK7. The Xerces and xml-api dependencies have been removed from the DOM
+code, as they are no longer required due to the JDK7 minimum requirement.
+</p>
+</subsection>
+
+<subsection name="OpenSAML 3.x migration">
+<p>
+A key dependency change in WSS4J 2.1.0 is the upgrade from OpenSAML 2.x to
+3.x (currently 3.1.0). OpenSAML 3.x contains a large number of package
+changes. Therefore if you have any OpenSAML dependencies in a CallbackHandler
+used to create SAML Assertions in WSS4J, code changes will be required.
+</p>
+<p>
+The most common OpenSAML dependency is to include a "SAMLVersion" to tell
+the SAMLCallback whether to create a SAML 2.0 or 1.1 Assertion. WSS4J 2.1
+provides an alternative way of specifying the SAML Version, via a <a
href="https://svn.apache.org/repos/asf/webservices/wss4j/trunk/ws-security-common/src/main/java/org/apache/wss4j/common/saml/bean/Version.java";>Version</a>
bean. See
+<a
href="https://svn.apache.org/repos/asf/webservices/wss4j/trunk/ws-security-dom/src/test/java/org/apache/wss4j/dom/common/SAML2CallbackHandler.java";>here</a>
for an example.
+</p>
+</subsection>
+
+<subsection name="Custom processor changes">
+<p>
+If you have a custom Processor instance to process a token in the security
+header in some custom way, you must add the WSSecurityEngineResult that is
+generated by the processing, to the WSDocInfo Object via the "addResult"
+method. Otherwise, it will not be available when security results are
+retrieved and processed.
+</p>
+</subsection>
+
+</section>
+</body>
+</document>
Modified: 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=1679544&r1=1679543&r2=1679544&view=diff
==============================================================================
--- webservices/wss4j/trunk/src/site/xdoc/user_guide.xml (original)
+++ webservices/wss4j/trunk/src/site/xdoc/user_guide.xml Fri May 15 11:35:41
2015
@@ -9,12 +9,10 @@ by WSS4J and how to configure it.
<ul>
<li><a href="what.html">What is Apache WSS4J?</a></li>
<li><a href="using.html">Using Apache WSS4J</a></li>
+<li><a href="migration/migration.html">Migration Guides</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>
