//
// 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 2.0.0 Migration Guide

This section is a migration guide for helping Apache WSS4J 1.6.x users to migrate
to the 2.0.x releases. Also see the link:newfeatures20.html[new
features] page for more information about the new functionality available in
WSS4J 2.0.x.

==== Migrating to using the streaming (StAX) code

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

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:

 * "org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor" to
"org.apache.cxf.ws.security.wss4j.WSS4JStaxOutInterceptor".
 * "org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor" to
"org.apache.cxf.ws.security.wss4j.WSS4JStaxInInterceptor".

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

For more information on the streaming functionality available in WSS4J 2.0.0, 
please see the link:streaming.html[streaming documentation] page.

==== Crypto/CallbackHandler changes

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.

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:

 * signatureVerificationPropFile - The path of the crypto property file to
use for Signature verification.
 * signatureVerificationPropRefId - The key that holds a reference to the
object holding complete information about the signature verification Crypto
implementation.

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.

==== SAML Assertion changes

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

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. 

The SAMLCallback Object contains the additional properties in WSS4J 2.0.0 that
can be set to sign the Assertion:

 * boolean signAssertion - Whether to sign the assertion or not (default "false").
 * String issuerKeyName - The keystore alias for signature
 * String issuerKeyPassword - The keystore password for the alias
 * Crypto issuerCrypto - The Crypto instance used for signature
 * boolean sendKeyValue - Whether to send the keyvalue or the X509Certificate
(default "false").
 * String canonicalizationAlgorithm - The C14n algorithm to use for signature.
 * String signatureAlgorithm - The Signature algorithm.

==== Configuration tag changes

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
https://github.com/apache/ws-wss4j/tree/master/ws-security-common/src/main/java/org/apache/wss4j/common/ConfigurationConstants.java?view=markup[ConfigurationConstants]. 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.

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.

===== Removed Configuration tags in WSS4J 2.0.0

This section details the Configuration tags that are no longer present in
WSS4J 2.0.0.

 * SIGN_WITH_UT_KEY (UsernameTokenSignature) - Perform a .NET specific signature using a Username Token action. Removed
as it was not standard compliant.
 * PASSWORD_TYPE_STRICT (passwordTypeStrict) - 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.
 * USE_DERIVED_KEY (useDerivedKey) - Whether to use the standard UsernameToken Key Derivation algorithm. Removed
as only the standard algorithm is used in WSS4J 2.0.0.
 * ENC_KEY_NAME (embeddedKeyName) - The text of the key name to be sent in the KeyInfo for encryption. Embedded
KeyNames are not supported in WSS4J 2.0.0.
 * ADD_UT_ELEMENTS (addUTElements) - Additional elements to add to a Username Token, i.e. "nonce" and "created".
See the ADD_USERNAMETOKEN_NONCE and ADD_USERNAMETOKEN_CREATED properties below.
 * WSE_SECRET_KEY_LENGTH (wseSecretKeyLength) - The length of the secret (derived) key to use for the WSE UT_SIGN
functionality. Removed as it is not standard compliant.
 * ENC_CALLBACK_CLASS (embeddedKeyCallbackClass) - The CallbackHandler implementation class used to get the key associated
with a key name. KeyName is not supported in WSS4J 2.0.0.
 * ENC_CALLBACK_REF (embeddedKeyCallbackRef) -The CallbackHandler implementation object used to get the key associated
with a key name. KeyName is not supported in WSS4J 2.0.0.

===== New Configuration tags in WSS4J 2.0.0

This section details the new Configuration tags in WSS4J 2.0.0.

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

==== Derived Key and Secure Conversation namespace change

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

==== Caching changes

WSS4J 2.0.0 uses three EhCache-based caches by default for the following
scenarios, to prevent replay attacks:

 * UsernameToken nonces
 * Signed Timestamps
 * SAML 2.0 OneTimeUse Assertions

If you are seeing a error about "replay attacks" after upgrade, then you may
need to disable a particular cache.

==== RSA v1.5 Key Transport algorithm not allowed by default

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

==== InclusiveNamespaces PrefixList change

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.