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