src/site/xdoc/migration.xml - ws-wss4j - Git at Google

 <?xml version="1.0" encoding="ISO-8859-1"?>
 <document>
 <body>
 <section name="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
 features</a> page for more information about the new functionality available in
 WSS4J 2.0.X.
 </p>
 <subsection name="Migrating to using the streaming (StAX) code">
 <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 having to read the entire request into
 memory carries performance penalties. 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).
 </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>
 <p>
 For more information on the streaming functionality available in WSS4J 2.0.0,
 please see the <a href="streaming.html">streaming documentation</a> page.
 </p>
 </subsection>

 <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
 "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.
 </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="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, 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
 can be set to sign the Assertion:
 </p>
 <ul>
 <li>boolean signAssertion - Whether to sign the assertion or not (default
 "false").</li>
 <li>String issuerKeyName - The keystore alias for signature</li>
 <li>String issuerKeyPassword - The keystore password for the alias</li>
 <li>Crypto issuerCrypto - The Crypto instance used for signature</li>
 <li>boolean sendKeyValue - Whether to send the keyvalue or the X509Certificate
 (default "false").</li>
 <li>String canonicalizationAlgorithm - The C14n algorithm to use for signature.
 </li>
 <li>String signatureAlgorithm - The Signature algorithm.</li>
 </ul>
 </subsection>
 <subsection name="Configuration tag changes">
 <p>
 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
 (WSHandlerConstants) extends this class in WSS4J 2.0.0, so there is no need to
 change any configuration code when upgrading.
 </p>
 <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
 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
 signature creation and verification.
 </p>

 <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.
 </p>
 <table name="Removed Configuration tags">
 <tr>
 <th>Tag name</th>
 <th>Tag value</th>
 <th>Tag meaning</th>
 </tr>
 <tr>
 <td>SIGN_WITH_UT_KEY</td>
 <td>UsernameTokenSignature</td>
 <td>Perform a .NET specific signature using a Username Token action. Removed
 as it was not standard compliant.</td>
 </tr>
 <tr>
 <td>PASSWORD_TYPE_STRICT</td>
 <td>passwordTypeStrict</td>
 <td>Whether to enable strict Username Token password type handling. In WSS4J
 2.0.0 this functionality can be enabled by just setting the required
 PASSWORD_TYPE.</td>
 </tr>
 <tr>
 <td>USE_DERIVED_KEY</td>
 <td>useDerivedKey</td>
 <td>Whether to use the standard UsernameToken Key Derivation algorithm. Removed
 as only the standard algorithm is used in WSS4J 2.0.0.</td>
 </tr>
 <tr>
 <td>ENC_KEY_NAME</td>
 <td>embeddedKeyName</td>
 <td>The text of the key name to be sent in the KeyInfo for encryption. Embedded
 KeyNames are not supported in WSS4J 2.0.0.</td>
 </tr>
 <tr>
 <td>ADD_UT_ELEMENTS</td>
 <td>addUTElements</td>
 <td>Additional elements to add to a Username Token, i.e. "nonce" and "created".
 See the ADD_USERNAMETOKEN_NONCE and ADD_USERNAMETOKEN_CREATED properties below.
 </td>
 </tr>
 <tr>
 <td>WSE_SECRET_KEY_LENGTH</td>
 <td>wseSecretKeyLength</td>
 <td>The length of the secret (derived) key to use for the WSE UT_SIGN
 functionality. Removed as it is not standard compliant.</td>
 </tr>
 <tr>
 <td>ENC_CALLBACK_CLASS</td>
 <td>embeddedKeyCallbackClass</td>
 <td>The CallbackHandler implementation class used to get the key associated
 with a key name. KeyName is not supported in WSS4J 2.0.0.</td>
 </tr>
 <tr>
 <td>ENC_CALLBACK_REF</td>
 <td>embeddedKeyCallbackRef</td>
 <td>The CallbackHandler implementation object used to get the key associated
 with a key name. KeyName is not supported in WSS4J 2.0.0.</td>
 </tr>

 </table>

 <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>
 <table name="New Configuration tags">
 <tr>
 <th>Tag name</th>
 <th>Tag value</th>
 <th>Tag meaning</th>
 </tr>
 <tr>
 <td>USERNAME_TOKEN_SIGNATURE</td>
 <td>UsernameTokenSignature</td>
 <td>Perform a UsernameTokenSignature action.</td>
 </tr>
 <tr>
 <td>SIGNATURE_DERIVED</td>
 <td>SignatureDerived</td>
 <td>Perform a Signature action with derived keys.</td>
 </tr>
 <tr>
 <td>ENCRYPT_DERIVED</td>
 <td>EncryptDerived</td>
 <td>Perform a Encryption action with derived keys.</td>
 </tr>
 <tr>
 <td>SIGNATURE_WITH_KERBEROS_TOKEN</td>
 <td>SignatureWithKerberosToken</td>
 <td>Perform a Signature action with a kerberos token. Only for StAX code.</td>
 </tr>
 <tr>
 <td>ENCRYPT_WITH_KERBEROS_TOKEN</td>
 <td>EncryptWithKerberosToken</td>
 <td>Perform a Encryption action with a kerberos token. Only for StAX code.</td>
 </tr>
 <tr>
 <td>KERBEROS_TOKEN</td>
 <td>KerberosToken</td>
 <td>Add a kerberos token.</td>
 </tr>
 <tr>
 <td>CUSTOM_TOKEN</td>
 <td>CustomToken</td>
 <td>Add a "Custom" token from a CallbackHandler</td>
 </tr>
 <tr>
 <td>SIG_VER_PROP_FILE</td>
 <td>signatureVerificationPropFile</td>
 <td>The path of the crypto property file to use for Signature verification.</td>
 </tr>
 <tr>
 <td>SIG_VER_PROP_REF_ID</td>
 <td>signatureVerificationPropRefId</td>
 <td>The String ID that is used to store a reference to the Crypto object or
 the Crypto Properties object for Signature verification.
 </td>
 </tr>
 <tr>
 <td>ALLOW_RSA15_KEY_TRANSPORT_ALGORITHM</td>
 <td>allowRSA15KeyTransportAlgorithm</td>
 <td>Whether to allow the RSA v1.5 Key Transport Algorithm or not. Default is
 "false".</td>
 </tr>
 <tr>
 <td>ADD_INCLUSIVE_PREFIXES</td>
 <td>addInclusivePrefixes</td>
 <td> Whether to add an InclusiveNamespaces PrefixList as a
 CanonicalizationMethod child when generating Signatures using
 WSConstants.C14N_EXCL_OMIT_COMMENTS. Default is "true".</td>
 </tr>
 <tr>
 <td>ADD_USERNAMETOKEN_NONCE</td>
 <td>addUsernameTokenNonce</td>
 <td>Whether to add a Nonce Element to a UsernameToken (for plaintext). Default
 is "false"</td>
 </tr>
 <tr>
 <td>ADD_USERNAMETOKEN_CREATED</td>
 <td>addUsernameTokenCreated</td>
 <td>Whether to add a Created Element to a UsernameToken (for plaintext).
 Default is "false"</td>
 </tr>
 <tr>
 <td>ALLOW_USERNAMETOKEN_NOPASSWORD</td>
 <td>allowUsernameTokenNoPassword</td>
 <td>Whether a UsernameToken with no password element is allowed. Default is
 "false".</td>
 </tr>
 <tr>
 <td>VALIDATE_SAML_SUBJECT_CONFIRMATION</td>
 <td>validateSamlSubjectConfirmation</td>
 <td>Whether to validate the SubjectConfirmation requirements of a received
 SAML Token (sender-vouches or holder-of-key). Default is "true".</td>
 </tr>
 <tr>
 <td>INCLUDE_SIGNATURE_TOKEN</td>
 <td>includeSignatureToken</td>
 <td>Whether to include the Signature Token in the security header as well or
 not (for IssuerSerial + Thumbprint cases). Default is "false"</td>
 </tr>
 <tr>
 <td>INCLUDE_ENCRYPTION_TOKEN</td>
 <td>includeEncryptionToken</td>
 <td>Whether to include the Encryption Token in the security header as well or
 not (for IssuerSerial, Thumbprint, SKI cases). Default is "false"</td>
 </tr>
 <tr>
 <td>ENABLE_NONCE_CACHE</td>
 <td>enableNonceCache</td>
 <td>Whether to cache UsernameToken nonces. Default is "true"</td>
 </tr>
 <tr>
 <td>ENABLE_TIMESTAMP_CACHE</td>
 <td>enableTimestampCache</td>
 <td>Whether to cache Timestamp Created Strings (these are only cached in
 conjunction with a message Signature). Default is "true"</td>
 </tr>
 <tr>
 <td>ENABLE_SAML_ONE_TIME_USE_CACHE</td>
 <td>enableSamlOneTimeUseCache</td>
 <td>Whether to cache SAML2 Token Identifiers, if the token contains a
 "OneTimeUse" Condition. Default is "true". </td>
 </tr>
 <tr>
 <td>USE_2005_12_NAMESPACE</td>
 <td>use200512Namespace</td>
 <td>Whether to use the 2005/12 namespace for SecureConveration + DerivedKeys,
 or the older namespace. The default is "true"</td>
 </tr>
 <tr>
 <td>OPTIONAL_SIGNATURE_PARTS</td>
 <td>optionalSignatureParts</td>
 <td>Parameter to define which parts of the request shall be signed, if they
 exist in the request.</td>
 </tr>
 <tr>
 <td>OPTIONAL_ENCRYPTION_PARTS</td>
 <td>optionalEncryptionParts</td>
 <td>Parameter to define which parts of the request shall be encrypted, if they
 exist in the request.</td>
 </tr>
 <tr>
 <td>ENC_MGF_ALGO</td>
 <td>encryptionMGFAlgorithm</td>
 <td>Defines which encryption mgf algorithm to use with the RSA OAEP Key
 Transport algorithm for encryption. The default is mgfsha1.</td>
 </tr>
 <tr>
 <td>VALIDATOR_MAP</td>
 <td>validatorMap</td>
 <td>A map of QName, Object (Validator) instances to be used to validate
 tokens identified by their QName.</td>
 </tr>
 <tr>
 <td>NONCE_CACHE_INSTANCE</td>
 <td>nonceCacheInstance</td>
 <td>A ReplayCache instance used to cache UsernameToken nonces. The default
 instance that is used is the EHCacheReplayCache.</td>
 </tr>
 <tr>
 <td>TIMESTAMP_CACHE_INSTANCE</td>
 <td>timestampCacheInstance</td>
 <td>A ReplayCache instance used to cache Timestamp Created Strings. The default
 instance that is used is the EHCacheReplayCache.</td>
 </tr>
 <tr>
 <td>SAML_ONE_TIME_USE_CACHE_INSTANCE</td>
 <td>samlOneTimeUseCacheInstance</td>
 <td>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.</td>
 </tr>
 <tr>
 <td>PASSWORD_ENCRYPTOR_INSTANCE</td>
 <td>passwordEncryptorInstance</td>
 <td>A PasswordEncryptor instance used to decrypt encrypted passwords in Crypto
 properties files. The default is the JasyptPasswordEncryptor.</td>
 </tr>
 <tr>
 <td>DERIVED_TOKEN_REFERENCE</td>
 <td>derivedTokenReference</td>
 <td>This controls how deriving tokens are referenced.</td>
 </tr>
 <tr>
 <td>DERIVED_TOKEN_KEY_ID</td>
 <td>derivedTokenKeyIdentifier</td>
 <td>This controls the key identifier of Derived Tokens.</td>
 </tr>
 <tr>
 <td>DERIVED_SIGNATURE_KEY_LENGTH</td>
 <td>derivedSignatureKeyLength</td>
 <td>The length to use (in bytes) when deriving a key for Signature.</td>
 </tr>
 <tr>
 <td>DERIVED_ENCRYPTION_KEY_LENGTH</td>
 <td>derivedEncryptionKeyLength</td>
 <td>The length to use (in bytes) when deriving a key for Encryption.</td>
 </tr>
 </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>

 <subsection name="RSA v1.5 Key Transport algorithm not allowed by default">
 <p>
 WSS4J supports two key transport algorithms, RSA v1.5 and RSA-OAEP. A number
 of attacks exist on RSA v1.5. Therefore, you should always use RSA-OAEP as the
 key transport algorithm. In WSS4J 2.0.0, the RSA v1.5 Key Transport algorithm
 is not allowed by default (as opposed to previous versions of WSS4J, where it
 is allowed). If you wish to allow it, then you must set the
 WSHandlerConstants.ALLOW_RSA15_KEY_TRANSPORT_ALGORITHM property to "true".
 </p>
 </subsection>

 <subsection name="InclusiveNamespaces PrefixList change">
 <p>
 In WSS4J 1.6.x, when BSP Compliance was switched off on the outbound side, it
 had the effect that an InclusiveNamespaces PrefixList was not generated as a
 CanonicalizationMethod child of a Signature Element (as required by the BSP
 specification). In WSS4J 2.0.0, this is now controlled by a separate
 configuration tag "addInclusivePrefixes", which defaults to true.
 </p>
 </subsection>

 </section>
 </body>
 </document>
	<?xml version="1.0" encoding="ISO-8859-1"?>
	<document>
	<body>
	<section name="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
	features</a> page for more information about the new functionality available in
	WSS4J 2.0.X.
	</p>
	<subsection name="Migrating to using the streaming (StAX) code">
	<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 having to read the entire request into
	memory carries performance penalties. 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).
	</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>
	<p>
	For more information on the streaming functionality available in WSS4J 2.0.0,
	please see the <a href="streaming.html">streaming documentation</a> page.
	</p>
	</subsection>

	<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
	"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.
	</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="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, 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
	can be set to sign the Assertion:
	</p>
	<ul>
	<li>boolean signAssertion - Whether to sign the assertion or not (default
	"false").</li>
	<li>String issuerKeyName - The keystore alias for signature</li>
	<li>String issuerKeyPassword - The keystore password for the alias</li>
	<li>Crypto issuerCrypto - The Crypto instance used for signature</li>
	<li>boolean sendKeyValue - Whether to send the keyvalue or the X509Certificate
	(default "false").</li>
	<li>String canonicalizationAlgorithm - The C14n algorithm to use for signature.
	</li>
	<li>String signatureAlgorithm - The Signature algorithm.</li>
	</ul>
	</subsection>
	<subsection name="Configuration tag changes">
	<p>
	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
	(WSHandlerConstants) extends this class in WSS4J 2.0.0, so there is no need to
	change any configuration code when upgrading.
	</p>
	<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
	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
	signature creation and verification.
	</p>

	<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.
	</p>
	<table name="Removed Configuration tags">
	<tr>
	<th>Tag name</th>
	<th>Tag value</th>
	<th>Tag meaning</th>
	</tr>
	<tr>
	<td>SIGN_WITH_UT_KEY</td>
	<td>UsernameTokenSignature</td>
	<td>Perform a .NET specific signature using a Username Token action. Removed
	as it was not standard compliant.</td>
	</tr>
	<tr>
	<td>PASSWORD_TYPE_STRICT</td>
	<td>passwordTypeStrict</td>
	<td>Whether to enable strict Username Token password type handling. In WSS4J
	2.0.0 this functionality can be enabled by just setting the required
	PASSWORD_TYPE.</td>
	</tr>
	<tr>
	<td>USE_DERIVED_KEY</td>
	<td>useDerivedKey</td>
	<td>Whether to use the standard UsernameToken Key Derivation algorithm. Removed
	as only the standard algorithm is used in WSS4J 2.0.0.</td>
	</tr>
	<tr>
	<td>ENC_KEY_NAME</td>
	<td>embeddedKeyName</td>
	<td>The text of the key name to be sent in the KeyInfo for encryption. Embedded
	KeyNames are not supported in WSS4J 2.0.0.</td>
	</tr>
	<tr>
	<td>ADD_UT_ELEMENTS</td>
	<td>addUTElements</td>
	<td>Additional elements to add to a Username Token, i.e. "nonce" and "created".
	See the ADD_USERNAMETOKEN_NONCE and ADD_USERNAMETOKEN_CREATED properties below.
	</td>
	</tr>
	<tr>
	<td>WSE_SECRET_KEY_LENGTH</td>
	<td>wseSecretKeyLength</td>
	<td>The length of the secret (derived) key to use for the WSE UT_SIGN
	functionality. Removed as it is not standard compliant.</td>
	</tr>
	<tr>
	<td>ENC_CALLBACK_CLASS</td>
	<td>embeddedKeyCallbackClass</td>
	<td>The CallbackHandler implementation class used to get the key associated
	with a key name. KeyName is not supported in WSS4J 2.0.0.</td>
	</tr>
	<tr>
	<td>ENC_CALLBACK_REF</td>
	<td>embeddedKeyCallbackRef</td>
	<td>The CallbackHandler implementation object used to get the key associated
	with a key name. KeyName is not supported in WSS4J 2.0.0.</td>
	</tr>

	</table>

	<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>
	<table name="New Configuration tags">
	<tr>
	<th>Tag name</th>
	<th>Tag value</th>
	<th>Tag meaning</th>
	</tr>
	<tr>
	<td>USERNAME_TOKEN_SIGNATURE</td>
	<td>UsernameTokenSignature</td>
	<td>Perform a UsernameTokenSignature action.</td>
	</tr>
	<tr>
	<td>SIGNATURE_DERIVED</td>
	<td>SignatureDerived</td>
	<td>Perform a Signature action with derived keys.</td>
	</tr>
	<tr>
	<td>ENCRYPT_DERIVED</td>
	<td>EncryptDerived</td>
	<td>Perform a Encryption action with derived keys.</td>
	</tr>
	<tr>
	<td>SIGNATURE_WITH_KERBEROS_TOKEN</td>
	<td>SignatureWithKerberosToken</td>
	<td>Perform a Signature action with a kerberos token. Only for StAX code.</td>
	</tr>
	<tr>
	<td>ENCRYPT_WITH_KERBEROS_TOKEN</td>
	<td>EncryptWithKerberosToken</td>
	<td>Perform a Encryption action with a kerberos token. Only for StAX code.</td>
	</tr>
	<tr>
	<td>KERBEROS_TOKEN</td>
	<td>KerberosToken</td>
	<td>Add a kerberos token.</td>
	</tr>
	<tr>
	<td>CUSTOM_TOKEN</td>
	<td>CustomToken</td>
	<td>Add a "Custom" token from a CallbackHandler</td>
	</tr>
	<tr>
	<td>SIG_VER_PROP_FILE</td>
	<td>signatureVerificationPropFile</td>
	<td>The path of the crypto property file to use for Signature verification.</td>
	</tr>
	<tr>
	<td>SIG_VER_PROP_REF_ID</td>
	<td>signatureVerificationPropRefId</td>
	<td>The String ID that is used to store a reference to the Crypto object or
	the Crypto Properties object for Signature verification.
	</td>
	</tr>
	<tr>
	<td>ALLOW_RSA15_KEY_TRANSPORT_ALGORITHM</td>
	<td>allowRSA15KeyTransportAlgorithm</td>
	<td>Whether to allow the RSA v1.5 Key Transport Algorithm or not. Default is
	"false".</td>
	</tr>
	<tr>
	<td>ADD_INCLUSIVE_PREFIXES</td>
	<td>addInclusivePrefixes</td>
	<td> Whether to add an InclusiveNamespaces PrefixList as a
	CanonicalizationMethod child when generating Signatures using
	WSConstants.C14N_EXCL_OMIT_COMMENTS. Default is "true".</td>
	</tr>
	<tr>
	<td>ADD_USERNAMETOKEN_NONCE</td>
	<td>addUsernameTokenNonce</td>
	<td>Whether to add a Nonce Element to a UsernameToken (for plaintext). Default
	is "false"</td>
	</tr>
	<tr>
	<td>ADD_USERNAMETOKEN_CREATED</td>
	<td>addUsernameTokenCreated</td>
	<td>Whether to add a Created Element to a UsernameToken (for plaintext).
	Default is "false"</td>
	</tr>
	<tr>
	<td>ALLOW_USERNAMETOKEN_NOPASSWORD</td>
	<td>allowUsernameTokenNoPassword</td>
	<td>Whether a UsernameToken with no password element is allowed. Default is
	"false".</td>
	</tr>
	<tr>
	<td>VALIDATE_SAML_SUBJECT_CONFIRMATION</td>
	<td>validateSamlSubjectConfirmation</td>
	<td>Whether to validate the SubjectConfirmation requirements of a received
	SAML Token (sender-vouches or holder-of-key). Default is "true".</td>
	</tr>
	<tr>
	<td>INCLUDE_SIGNATURE_TOKEN</td>
	<td>includeSignatureToken</td>
	<td>Whether to include the Signature Token in the security header as well or
	not (for IssuerSerial + Thumbprint cases). Default is "false"</td>
	</tr>
	<tr>
	<td>INCLUDE_ENCRYPTION_TOKEN</td>
	<td>includeEncryptionToken</td>
	<td>Whether to include the Encryption Token in the security header as well or
	not (for IssuerSerial, Thumbprint, SKI cases). Default is "false"</td>
	</tr>
	<tr>
	<td>ENABLE_NONCE_CACHE</td>
	<td>enableNonceCache</td>
	<td>Whether to cache UsernameToken nonces. Default is "true"</td>
	</tr>
	<tr>
	<td>ENABLE_TIMESTAMP_CACHE</td>
	<td>enableTimestampCache</td>
	<td>Whether to cache Timestamp Created Strings (these are only cached in
	conjunction with a message Signature). Default is "true"</td>
	</tr>
	<tr>
	<td>ENABLE_SAML_ONE_TIME_USE_CACHE</td>
	<td>enableSamlOneTimeUseCache</td>
	<td>Whether to cache SAML2 Token Identifiers, if the token contains a
	"OneTimeUse" Condition. Default is "true". </td>
	</tr>
	<tr>
	<td>USE_2005_12_NAMESPACE</td>
	<td>use200512Namespace</td>
	<td>Whether to use the 2005/12 namespace for SecureConveration + DerivedKeys,
	or the older namespace. The default is "true"</td>
	</tr>
	<tr>
	<td>OPTIONAL_SIGNATURE_PARTS</td>
	<td>optionalSignatureParts</td>
	<td>Parameter to define which parts of the request shall be signed, if they
	exist in the request.</td>
	</tr>
	<tr>
	<td>OPTIONAL_ENCRYPTION_PARTS</td>
	<td>optionalEncryptionParts</td>
	<td>Parameter to define which parts of the request shall be encrypted, if they
	exist in the request.</td>
	</tr>
	<tr>
	<td>ENC_MGF_ALGO</td>
	<td>encryptionMGFAlgorithm</td>
	<td>Defines which encryption mgf algorithm to use with the RSA OAEP Key
	Transport algorithm for encryption. The default is mgfsha1.</td>
	</tr>
	<tr>
	<td>VALIDATOR_MAP</td>
	<td>validatorMap</td>
	<td>A map of QName, Object (Validator) instances to be used to validate
	tokens identified by their QName.</td>
	</tr>
	<tr>
	<td>NONCE_CACHE_INSTANCE</td>
	<td>nonceCacheInstance</td>
	<td>A ReplayCache instance used to cache UsernameToken nonces. The default
	instance that is used is the EHCacheReplayCache.</td>
	</tr>
	<tr>
	<td>TIMESTAMP_CACHE_INSTANCE</td>
	<td>timestampCacheInstance</td>
	<td>A ReplayCache instance used to cache Timestamp Created Strings. The default
	instance that is used is the EHCacheReplayCache.</td>
	</tr>
	<tr>
	<td>SAML_ONE_TIME_USE_CACHE_INSTANCE</td>
	<td>samlOneTimeUseCacheInstance</td>
	<td>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.</td>
	</tr>
	<tr>
	<td>PASSWORD_ENCRYPTOR_INSTANCE</td>
	<td>passwordEncryptorInstance</td>
	<td>A PasswordEncryptor instance used to decrypt encrypted passwords in Crypto
	properties files. The default is the JasyptPasswordEncryptor.</td>
	</tr>
	<tr>
	<td>DERIVED_TOKEN_REFERENCE</td>
	<td>derivedTokenReference</td>
	<td>This controls how deriving tokens are referenced.</td>
	</tr>
	<tr>
	<td>DERIVED_TOKEN_KEY_ID</td>
	<td>derivedTokenKeyIdentifier</td>
	<td>This controls the key identifier of Derived Tokens.</td>
	</tr>
	<tr>
	<td>DERIVED_SIGNATURE_KEY_LENGTH</td>
	<td>derivedSignatureKeyLength</td>
	<td>The length to use (in bytes) when deriving a key for Signature.</td>
	</tr>
	<tr>
	<td>DERIVED_ENCRYPTION_KEY_LENGTH</td>
	<td>derivedEncryptionKeyLength</td>
	<td>The length to use (in bytes) when deriving a key for Encryption.</td>
	</tr>
	</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>

	<subsection name="RSA v1.5 Key Transport algorithm not allowed by default">
	<p>
	WSS4J supports two key transport algorithms, RSA v1.5 and RSA-OAEP. A number
	of attacks exist on RSA v1.5. Therefore, you should always use RSA-OAEP as the
	key transport algorithm. In WSS4J 2.0.0, the RSA v1.5 Key Transport algorithm
	is not allowed by default (as opposed to previous versions of WSS4J, where it
	is allowed). If you wish to allow it, then you must set the
	WSHandlerConstants.ALLOW_RSA15_KEY_TRANSPORT_ALGORITHM property to "true".
	</p>
	</subsection>

	<subsection name="InclusiveNamespaces PrefixList change">
	<p>
	In WSS4J 1.6.x, when BSP Compliance was switched off on the outbound side, it
	had the effect that an InclusiveNamespaces PrefixList was not generated as a
	CanonicalizationMethod child of a Signature Element (as required by the BSP
	specification). In WSS4J 2.0.0, this is now controlled by a separate
	configuration tag "addInclusivePrefixes", which defaults to true.
	</p>
	</subsection>

	</section>
	</body>
	</document>