src/site/asciidoc/newfeatures20.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.
 //

 === New features available in Apache WSS4J 2.0.0

 ==== Overview of new features

 Apache WSS4J 2.0.0 delivers the following major new features:

  * Support for a streaming (StAX) based WS-Security implementation that
 covers all of the main specifications.
  * A WS-SecurityPolicy model that can be shared between both DOM + StAX
 implementations.
  * Support for "real-time" WS-SecurityPolicy validation for the StAX
 implementation.
  * Support for the SOAP with Attachments (SWA) Profile 1.1 specification.
  * Support for caching based on EhCache.
  * Support for encrypting passwords in Crypto properties files using Jasypt.

 ==== Streaming (StAX) based WS-Security implementation

 WSS4J 2.0.0 introduces a new streaming (StAX) based WS-Security implementation.
 Please see the dedicated link:streaming.html[page] for more information.

 ==== WS-SecurityPolicy support

 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.

 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.

 ==== Support for signing and encrypting message attachments

 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 link:attachments.html[page] for more
 information.

 ==== Replay Attack detection using EhCache

 In WSS4J 1.6.x, a "ReplayCache" interface was introduced to cache tokens to
 guard against replay attacks for the following scenarios:

  * Signed Timestamps
  * UsernameToken nonces
  * SAML OneTimeUse Assertions

 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:

  * 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.
  * 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".
  * 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.
  * ConfigurationConstants.ENABLE_NONCE_CACHE ("enableNonceCache"): Whether to
 cache UsernameToken nonces. The default value is "true".
  * 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.
  * 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".

 ==== Encrypting passwords in Crypto property files

 A typical example of the contents of a Crypto properties file (for Signature
 creation) is as follows:

  * org.apache.wss4j.crypto.provider=org.apache.wss4j.common.crypto.Merlin
  * org.apache.wss4j.crypto.merlin.keystore.type=jks
  * org.apache.wss4j.crypto.merlin.keystore.password=security
  * org.apache.wss4j.crypto.merlin.keystore.alias=wss40
  * org.apache.wss4j.crypto.merlin.keystore.file=keys/wss40.jks

 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".

 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").

 ==== Miscellaneous new features

 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.

 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.

 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.

 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").
	//
	// 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.
	//

	=== New features available in Apache WSS4J 2.0.0

	==== Overview of new features

	Apache WSS4J 2.0.0 delivers the following major new features:

	* Support for a streaming (StAX) based WS-Security implementation that
	covers all of the main specifications.
	* A WS-SecurityPolicy model that can be shared between both DOM + StAX
	implementations.
	* Support for "real-time" WS-SecurityPolicy validation for the StAX
	implementation.
	* Support for the SOAP with Attachments (SWA) Profile 1.1 specification.
	* Support for caching based on EhCache.
	* Support for encrypting passwords in Crypto properties files using Jasypt.

	==== Streaming (StAX) based WS-Security implementation

	WSS4J 2.0.0 introduces a new streaming (StAX) based WS-Security implementation.
	Please see the dedicated link:streaming.html[page] for more information.

	==== WS-SecurityPolicy support

	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.

	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.

	==== Support for signing and encrypting message attachments

	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 link:attachments.html[page] for more
	information.

	==== Replay Attack detection using EhCache

	In WSS4J 1.6.x, a "ReplayCache" interface was introduced to cache tokens to
	guard against replay attacks for the following scenarios:

	* Signed Timestamps
	* UsernameToken nonces
	* SAML OneTimeUse Assertions

	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:

	* 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.
	* 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".
	* 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.
	* ConfigurationConstants.ENABLE_NONCE_CACHE ("enableNonceCache"): Whether to
	cache UsernameToken nonces. The default value is "true".
	* 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.
	* 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".

	==== Encrypting passwords in Crypto property files

	A typical example of the contents of a Crypto properties file (for Signature
	creation) is as follows:

	* org.apache.wss4j.crypto.provider=org.apache.wss4j.common.crypto.Merlin
	* org.apache.wss4j.crypto.merlin.keystore.type=jks
	* org.apache.wss4j.crypto.merlin.keystore.password=security
	* org.apache.wss4j.crypto.merlin.keystore.alias=wss40
	* org.apache.wss4j.crypto.merlin.keystore.file=keys/wss40.jks

	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".

	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").

	==== Miscellaneous new features

	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.

	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.

	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.

	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").