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