src/site/asciidoc/wss4j16.adoc - ws-wss4j - Git at Google

 //
 // Licensed to the Apache Software Foundation (ASF) under one
 // or more contributor license agreements.  See the NOTICE file
 // distributed with this work for additional information
 // regarding copyright ownership.  The ASF licenses this file
 // to you under the Apache License, Version 2.0 (the
 // "License"); you may not use this file except in compliance
 // with the License.  You may obtain a copy of the License at
 //
 //   http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing,
 // software distributed under the License is distributed on an
 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 // KIND, either express or implied.  See the License for the
 // specific language governing permissions and limitations
 // under the License.
 //

 === Apache WSS4J 1.6.0 Migration Guide

 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 link:wss4j20.html[migration guide] for more information.

 ==== New features

 This section describes the main new features that have been implemented in
 WSS4J 1.6. For more information on the changes, please click on the links. You
 can also review the
 https://issues.apache.org/jira/browse/WSS/fixforversion/12313718[list of JIRAs]
 that have been fixed in WSS4J 1.6.

  * http://coheigea.blogspot.com/2011/03/wss4j-16-jsr-105-support.html[JSR-105 support]:
 WSS4J 1.6 has been ported to use the JSR 105 API for XML Digital Signature.
  * http://coheigea.blogspot.com/2011/02/support-for-saml2-assertions-in-wss4j.html[SAML2 support]: WSS4J 1.6 includes full support for creating, manipulating and parsing SAML2
 assertions, via the Opensaml2 library.
  * Performance work: A general code-rewrite has been done with a focus on improving performance,
 e.g. the http://coheigea.blogspot.com/2011/01/wss4j-16-actionprocessor-loading-change.html[changes] that have been made to processor loading.
  * http://coheigea.blogspot.com/2011/03/wss4j-16-basic-security-profile-11.html[Basic Security Profile 1.1 compliance]: WSS4J 1.6 provides support for the BSP 1.1 specification.
  * JDK 1.5 port: The JDK 1.4 requirement of WSS4J 1.5.x has been dropped as part of this work.
  * http://coheigea.blogspot.com/2011/01/wss4j-16-crypto-property-change.html[Support for Crypto trust-stores]: WSS4J 1.6 separates the concept of keystore and truststores for
 Crypto implementations.
  * http://coheigea.blogspot.com/2011/04/wss4j-16-introducing-validators.html[New Validator interface]: WSS4J 1.6 moves all validation of security tokens into a new Validator
 interface, which allows for custom validation of specific tokens.
  * Support for the Kerberos Token Profile (in WSS4J 1.6.2 and 1.6.3).

 ==== Upgrade notes
 This section describes the changes that have been made in WSS4J 1.6 that will impact on an existing
 user of WSS4J 1.5.x. Although WSS4J 1.6 is not 100% backwards compatible with 1.5.x, a general goal for
 the release was to restrict the API changes to those that were strictly necessary.

  * All Axis1 dependencies have been removed. Any user wishing to use WSS4J with Axis1 must use the
 WSS4J 1.5.x library. As Axis1 has been replaced by Axis2, this is unlikely to be an issue.
  * A number of changes have been made to the Crypto interface. See
 http://coheigea.blogspot.com/2011/01/wss4j-16-crypto-property-change.html[here],
 http://coheigea.blogspot.com/2011/02/wss4j-16-changes-to-crypto-interface.html[here]
 and http://coheigea.blogspot.com/2011/02/wss4j-16-change-to-publickey-validation.html[here]
 for an indepth explanation. In a nutshell, these changes are:
   . The BouncyCastle crypto implementation has been removed (replaced by Merlin)
   . A new set of Merlin "truststore" configuration tags have been added. The behaviour of the old Merlin
 configuration tags will work exactly the same way in WSS4J 1.6.
   . The CA certs are now <b>not</b> loaded by default.
   . PublicKeys (from KeyValues) are now not handled by a PublicKeyCallback, but by the Crypto implementation
 directly.
  * If the WSEncryptionPart used to point to an element for signature or encryption does not either store
 the element directly, or store the wsu:Id, *all* DOM Elements that match the stored
 localname/namespace will be processed. See the
 http://ws.apache.org/wss4j/topics.html#Specifying_elements_to_sign_or_encrypt[Special Topics page]
 for more information.
  * WSS4J 1.5.x used Opensaml1 to provide extremely limited support for SAML 1 assertions. WSS4J 1.6 has
 been upgraded to Opensaml2, and provides far more comprehensive support for SAML. See
 http://coheigea.blogspot.com/2011/02/support-for-saml2-assertions-in-wss4j.html[here] for
 more information on this. Some changes to be aware of are:
   . The way of creating SAML assertions via a properties file has completely changed. For example, see
 link:xref-test/org/apache/ws/security/saml/SamlTokenTest.html[SAML Token Test].
   . 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.
   . 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.
   . 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.
  * The way that UsernameTokens are processed has been changed. See
 http://coheigea.blogspot.com/2011/02/usernametoken-processing-changes-in.html[here] for
 more information. Some important changes are:
   . The plaintext password case has exactly the same behaviour as the digest case. The identifier is now
 WSPasswordCallback.USERNAME_TOKEN and not WSPasswordCallback.USERNAME_TOKEN_UNKNOWN, and the
 CallbackHandler does not do any authentication, but must set the password on the callback.
   . The custom password type case defaults to the same behaviour as the plaintext case, assuming
 wssConfig.getHandleCustomPasswordTypes() returns true.
   . 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.
  * Some changes have been made to the WSPasswordCallback identifiers, used to obtain passwords for various
 actions. For more information see
 http://coheigea.blogspot.com/2011/02/wspasswordcallback-changes-in-wss4j-16.html[here]. In
 a nutshell, these changes consist of:
   . The WSPasswordCallback KEY_NAME, USERNAME_TOKEN_UNKNOWN and WSPasswordCallback.ENCRYPTED_KEY_TOKEN
 identifiers have been removed.
   . CUSTOM_TOKEN is not longer used in the processors to get a secret key.
   . SECRET_KEY is a new identifier for finding secret keys. It replaces the occasionally incorrect use of
 CUSTOM_TOKEN, as well as KEY_NAME and ENCRYPTED_KEY_TOKEN.
  * Timestamp validation and signature trust verification is not done by the WSHandler implementation
 any more, but is performed when the security header is processed.
	//
	// Licensed to the Apache Software Foundation (ASF) under one
	// or more contributor license agreements. See the NOTICE file
	// distributed with this work for additional information
	// regarding copyright ownership. The ASF licenses this file
	// to you under the Apache License, Version 2.0 (the
	// "License"); you may not use this file except in compliance
	// with the License. You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing,
	// software distributed under the License is distributed on an
	// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	// KIND, either express or implied. See the License for the
	// specific language governing permissions and limitations
	// under the License.
	//

	=== Apache WSS4J 1.6.0 Migration Guide

	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 link:wss4j20.html[migration guide] for more information.

	==== New features

	This section describes the main new features that have been implemented in
	WSS4J 1.6. For more information on the changes, please click on the links. You
	can also review the
	https://issues.apache.org/jira/browse/WSS/fixforversion/12313718[list of JIRAs]
	that have been fixed in WSS4J 1.6.

	* http://coheigea.blogspot.com/2011/03/wss4j-16-jsr-105-support.html[JSR-105 support]:
	WSS4J 1.6 has been ported to use the JSR 105 API for XML Digital Signature.
	* http://coheigea.blogspot.com/2011/02/support-for-saml2-assertions-in-wss4j.html[SAML2 support]: WSS4J 1.6 includes full support for creating, manipulating and parsing SAML2
	assertions, via the Opensaml2 library.
	* Performance work: A general code-rewrite has been done with a focus on improving performance,
	e.g. the http://coheigea.blogspot.com/2011/01/wss4j-16-actionprocessor-loading-change.html[changes] that have been made to processor loading.
	* http://coheigea.blogspot.com/2011/03/wss4j-16-basic-security-profile-11.html[Basic Security Profile 1.1 compliance]: WSS4J 1.6 provides support for the BSP 1.1 specification.
	* JDK 1.5 port: The JDK 1.4 requirement of WSS4J 1.5.x has been dropped as part of this work.
	* http://coheigea.blogspot.com/2011/01/wss4j-16-crypto-property-change.html[Support for Crypto trust-stores]: WSS4J 1.6 separates the concept of keystore and truststores for
	Crypto implementations.
	* http://coheigea.blogspot.com/2011/04/wss4j-16-introducing-validators.html[New Validator interface]: WSS4J 1.6 moves all validation of security tokens into a new Validator
	interface, which allows for custom validation of specific tokens.
	* Support for the Kerberos Token Profile (in WSS4J 1.6.2 and 1.6.3).

	==== Upgrade notes
	This section describes the changes that have been made in WSS4J 1.6 that will impact on an existing
	user of WSS4J 1.5.x. Although WSS4J 1.6 is not 100% backwards compatible with 1.5.x, a general goal for
	the release was to restrict the API changes to those that were strictly necessary.

	* All Axis1 dependencies have been removed. Any user wishing to use WSS4J with Axis1 must use the
	WSS4J 1.5.x library. As Axis1 has been replaced by Axis2, this is unlikely to be an issue.
	* A number of changes have been made to the Crypto interface. See
	http://coheigea.blogspot.com/2011/01/wss4j-16-crypto-property-change.html[here],
	http://coheigea.blogspot.com/2011/02/wss4j-16-changes-to-crypto-interface.html[here]
	and http://coheigea.blogspot.com/2011/02/wss4j-16-change-to-publickey-validation.html[here]
	for an indepth explanation. In a nutshell, these changes are:
	. The BouncyCastle crypto implementation has been removed (replaced by Merlin)
	. A new set of Merlin "truststore" configuration tags have been added. The behaviour of the old Merlin
	configuration tags will work exactly the same way in WSS4J 1.6.
	. The CA certs are now <b>not</b> loaded by default.
	. PublicKeys (from KeyValues) are now not handled by a PublicKeyCallback, but by the Crypto implementation
	directly.
	* If the WSEncryptionPart used to point to an element for signature or encryption does not either store
	the element directly, or store the wsu:Id, all DOM Elements that match the stored
	localname/namespace will be processed. See the
	http://ws.apache.org/wss4j/topics.html#Specifying_elements_to_sign_or_encrypt[Special Topics page]
	for more information.
	* WSS4J 1.5.x used Opensaml1 to provide extremely limited support for SAML 1 assertions. WSS4J 1.6 has
	been upgraded to Opensaml2, and provides far more comprehensive support for SAML. See
	http://coheigea.blogspot.com/2011/02/support-for-saml2-assertions-in-wss4j.html[here] for
	more information on this. Some changes to be aware of are:
	. The way of creating SAML assertions via a properties file has completely changed. For example, see
	link:xref-test/org/apache/ws/security/saml/SamlTokenTest.html[SAML Token Test].
	. 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.
	. 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.
	. 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.
	* The way that UsernameTokens are processed has been changed. See
	http://coheigea.blogspot.com/2011/02/usernametoken-processing-changes-in.html[here] for
	more information. Some important changes are:
	. The plaintext password case has exactly the same behaviour as the digest case. The identifier is now
	WSPasswordCallback.USERNAME_TOKEN and not WSPasswordCallback.USERNAME_TOKEN_UNKNOWN, and the
	CallbackHandler does not do any authentication, but must set the password on the callback.
	. The custom password type case defaults to the same behaviour as the plaintext case, assuming
	wssConfig.getHandleCustomPasswordTypes() returns true.
	. 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.
	* Some changes have been made to the WSPasswordCallback identifiers, used to obtain passwords for various
	actions. For more information see
	http://coheigea.blogspot.com/2011/02/wspasswordcallback-changes-in-wss4j-16.html[here]. In
	a nutshell, these changes consist of:
	. The WSPasswordCallback KEY_NAME, USERNAME_TOKEN_UNKNOWN and WSPasswordCallback.ENCRYPTED_KEY_TOKEN
	identifiers have been removed.
	. CUSTOM_TOKEN is not longer used in the processors to get a secret key.
	. SECRET_KEY is a new identifier for finding secret keys. It replaces the occasionally incorrect use of
	CUSTOM_TOKEN, as well as KEY_NAME and ENCRYPTED_KEY_TOKEN.
	* Timestamp validation and signature trust verification is not done by the WSHandler implementation
	any more, but is performed when the security header is processed.