Author: coheigea Date: Wed Nov 5 16:59:05 2025 New Revision: 1929545 Log: Adding user guide
Added: webservices/website/wss4j/user_guide.html Added: webservices/website/wss4j/user_guide.html ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ webservices/website/wss4j/user_guide.html Wed Nov 5 16:59:05 2025 (r1929545) @@ -0,0 +1,1352 @@ +<!DOCTYPE html> + + +<!-- + | Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/asciidoc/user_guide.adoc at 2025-11-05 + | Rendered using Apache Maven Fluido Skin 2.0.0-M11 +--> +<html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> + <head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" /> + <meta name="date" content="2025-11-05 16:54:44 UTC" /> + <title>Apache WSS4J&#8482; User Guide – Apache WSS4J</title> + <link rel="stylesheet" href="./css/apache-maven-fluido-2.0.0-M11.min.css" /> + <link rel="stylesheet" href="./css/site.css" /> + <link rel="stylesheet" href="./css/print.css" media="print" /> + <script src="./js/apache-maven-fluido-2.0.0-M11.min.js"></script> + </head> + <body> + <div class="container-fluid container-fluid-top"> + <header> + <div id="banner"> + <div class="pull-left"><div id="bannerLeft"><h1><a href="http://ws.apache.org/wss4j";>Apache WSS4J™</a></h1></div></div> + <div class="pull-right"><div id="bannerRight"><h1><a href="http://www.apache.org";><img class="class java.lang.Object" src="http://activemq.apache.org/images/asf-logo.png"; /></a></h1></div></div> + <div class="clear"><hr/></div> + </div> + + <div id="breadcrumbs"> + <ul class="breadcrumb"> + <li id="publishDate">Last Published: 2025-10-28<span class="divider">|</span> +</li> + <li id="projectVersion">Version: 4.0.2-SNAPSHOT</li> + </ul> + </div> + </header> + <div class="row-fluid"> + <header id="leftColumn" class="span2"> + <nav class="well sidebar-nav"> + <ul class="nav nav-list"> + <li class="nav-header">Apache WSS4J</li> + <li><a href="index.html">Home</a></li> + <li><a href="download.html">Download</a></li> + <li class="active"><a>User Guide</a></li> + <li><a href="contributing.html">Contributing</a></li> + <li><a href="security_advisories.html">Security Advisories</a></li> + <li class="nav-header">Project Documentation</li> + <li><a href="project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li> + <li><a href="project-reports.html"><span class="icon-chevron-right"></span>Project Reports</a></li> + </ul> + </nav> + <div class="well sidebar-nav"> + <div id="poweredBy"> + <div class="clear"></div> + <div class="clear"></div> +<a href="https://maven.apache.org/"; class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a> + </div> + </div> + </header> + <main id="bodyColumn" class="span10"> +<h1>Apache WSS4J™ User Guide</h1> +<div> +<h2><a id="what_is_apache_wss4j"></a>What is Apache WSS4J™?</h2> +<p>In this section we describe what Apache WSS4J is and what functionality it supports. +For more information about how to use WSS4J, see the <a href="using.html">Using Apache WSS4J</a> page.</p> +<div> +<h3><a id="the_technical_answer"></a>The technical answer</h3> +<p>The technical answer is that Apache WSS4J provides a Java implementation of +the primary security standards for Web Services, namely the OASIS Web Services +Security (WS-Security) specifications from the +<a href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss";>OASIS Web Services Security TC</a>. WSS4J provides an implementation of the following +WS-Security standards:</p> +<ul> +<li><a href="http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-SOAPMessageSecurity.pdf";>SOAP Message Security 1.1</a></li> +<li><a href="http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-UsernameTokenProfile.pdf";>UsernameToken Profile 1.1</a></li> +<li><a href="http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-x509TokenProfile.pdf";>X.509Certificate Token Profile 1.1</a></li> +<li><a href="http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-SAMLTokenProfile.pdf";>SAML Token Profile 1.1</a></li> +<li><a href="http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-KerberosTokenProfile.pdf";>Kerberos Token Profile 1.1</a></li> +<li><a href="http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-SwAProfile.pdf";>SOAP Messages with Attachments Profile 1.1</a></li> +<li><a href="http://www.ws-i.org/Profiles/BasicSecurityProfile-1.1.html";>Basic Security Profile 1.1</a></li></ul></div> +<div> +<h3><a id="the_less_technical_answer"></a>The less technical answer</h3> +<p>Apache WSS4J is designed to be used with a Web Services stack such as Apache +CXF or Apache Axis to secure SOAP messages. It offers the following high +level functionality:</p> +<ul> +<li>Message Confidentiality</li> +<li>Message Integrity</li> +<li>Message Authentication</li> +<li>Message Authorization</li></ul> +<p>WSS4J uses the functionality of Apache Santuario to encrypt SOAP Messages. +Typically, the SOAP Body as well as a UsernameToken in the security header are +encrypted. WSS4J supports both Symmetric and Asymmetric encryption. Typically, +a Symmetric Key is generated and used to encrypt the SOAP Body/UsernameToken, +and then the Symmetric Key is in turn encrypted by the public key of the +recipient and included in the security header of the request.</p> +<p>WSS4J also provides the ability to ensure message integrity by applying XML +Signature to a SOAP request. Typically, the SOAP Body, Timestamp, +WS-Addressing headers, as well as any other token in the security header are +signed. Both Symmetric and Asymmetric Signature are supported. WSS4J supports +using a secret key associated with a token, such as a Kerberos Token or a key +derived from a UsernameToken, to sign (as well as to encrypt) a request.</p> +<p>As well as providing message confidentiality and integrity, WSS4J allows for +client authentication in a number of different ways. The most common way is +to include a username and password in a UsernameToken included in the security +header. The message recipient can plug in a WSS4J Validator to validate the +received credentials. Authentication is also supported via Kerberos Tokens, +SAML Assertions (when used with "HolderOfKey"), and Asymmetric Signature.</p> +<p>Finally, WSS4J supports message authorization using an RBAC approach. This can +be supported via the use-case of UsernameTokens validated using the JAAS +Validator that ships with WSS4J. This stores the JAAS Subject in the WSS4J +results list, and can be used by the web services stack to populate a security +context. Similarly, authorization can be supported using Claims extracted +from a SAML (Attribute) Assertion.</p></div></div> +<div> +<h2><a id="using_apache_wss4j"></a>Using Apache WSS4J™</h2> +<p>This page describes how to use Apache WSS4J. For information about how to +configure WSS4J, see the <a href="config.html">configuration page</a>. WSS4J +can essentially be used in three different ways. For information about using +WSS4J with a SOAP stack, see the sections on Apache CXF and Apache Rampart/Axis.</p> +<ul> +<li>Action based approach: WSS4J offers an "Action" based approach to +applying WS-Security to a SOAP request or response, in conjunction with a SOAP +stack.</li> +<li>WS-SecurityPolicy based approach: WSS4J can be configured for a SOAP +request/response via WS-SecurityPolicy, in conjunction with a SOAP Stack. +This is the recommended approach.</li> +<li>Standalone approach: WSS4J offers a low-level (DOM) API to +construct/sign/encrypt/etc. tokens directly.</li></ul> +<div> +<h3><a id="action_based_approach"></a>Action based approach</h3> +<p>The WSHandler class in WSS4J is designed to configure WSS4J to secure an +outbound SOAP request, by parsing configuration that is supplied to it via +a subclass. Typically a web services stack that uses WSS4J for WS-Security +will subclass WSHandler. An example of a subclass is the +<a href="http://cxf.apache.org/docs/ws-security.html";>WSS4JOutInterceptor</a> +in Apache CXF. The configuration tags are defined in the <a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-common/src/main/java/org/apache/wss4j/common/ConfigurationConstants.java?view=markup";>ConfigurationConstants</a> class (WSHandlerConstants in WSS4J 1.6.x). For a more detailed explanation +of the configuration tags, please refer to the <a href="config.html">configuration</a> page. The next few paragraphs will +describe the most fundamental configuration tags that are used in most +cases.</p> +<div> +<h4><a id="common_configuration_tags"></a>Common configuration tags</h4> +<p>The "Action" based approach to using Apache WSS4J involves explicitly telling +WSS4J what WS-Security functionality to perform on a request, by configuring +the stack specific WSHandler implementation with the required properties. On +the receiving side, the "actions" that are configured are matched against what +was processed in the security header, and an error is thrown if they do not +match (in some order). Typical actions include "UsernameToken, "Signature", +"Encrypt", "Timestamp, "SAMLTokenSigned", etc.</p> +<p>After specifying the action to perform on a request, the next task is typically +to specify the "user". The "user" can be either the username to insert into a +UsernameToken, or the keystore alias to use for either signature or encryption. +If you are configuring more than one of these actions, the "signatureUser" and +"encryptionUser" configuration tags override the more general "user" tag. The +next task is often to specify a CallbackHandler implementation to use to +retrieve passwords. On the sending side, this is used to retrieve a password +to insert into a UsernameToken and to decrypt a private key from a keystore +for Signature. On the receiving side, it is used to retrieve a password to +validate a received UsernameToken, and to decrypt a private key from a +keystore to use for decryption.</p> +<p>The next task is to specify a Crypto implementation if you are using Signature +or Encryption. See the <a href="configuration.html">configuration</a> page for +more information on the Crypto interface. Typically, it is configured in a +Crypto properties file, which specifies the Crypto implementation to use, as +well as the keystore location, default alias/password, etc. For signature, the +path of this properties file can be referred to by the tag "signaturePropFile" +and "encryptionPropFile" for outbound request, and +"signatureVerificationPropFile" and "decryptionPropFile" for inbound requests". +How signing keys/certificates are referenced from a Signature can be +controlled via the "signatureKeyIdentifier" configuration tag. This defaults +to "IssuerSerial", but could be "DirectReference", "Thumbprint", etc. The +"encryptionKeyIdentifier" tag performs the same function for encryption.</p> +<p>Finally, the Elements to sign or encrypt can be specified by the +"signatureParts" and "encryptionParts" configuration tags. Both default to the +SOAP Body. The value of signatureParts/encryptionParts is a list of semi-colon +separated values that identify the elements to sign/encrypt. The value is of +the format of an encryption mode specifier, and a namespace URI, each inside a +pair of curly brackets, and then the local name of the Element. For example, +"{Content}{http://example.org/paymentv2}CreditCard;";. The encryption modifier +can be either "Content" or "Element" and only applies to encryption.</p> +<p>Here are some sample configuration values for various actions, as taken from +some CXF system tests. The constructor of the +WSS4JOutInterceptor/WSS4JInIntereptor interceptors in CXF takes a map of +String/Object pairs which correspond to the key/value pairs given in the tables +below. See the CXF configuration <a href="https://github.com/apache/cxf/blob/master/systests/ws-security/src/test/resources/org/apache/cxf/systest/ws/action/client.xml";>file</a> for more information.</p></div> +<div> +<h4><a id="sample_outbound_usernametoken_configuration"></a>Sample Outbound UsernameToken configuration</h4> +<ul> +<li><strong>Key</strong> - <strong>Value</strong></li> +<li>action - UsernameToken</li> +<li>user - Alice</li> +<li>passwordCallbackClass - <a href="https://github.com/apache/cxf/blob/master/systests/ws-security/src/test/java/org/apache/cxf/systest/ws/common/UTPasswordCallback.java";>org.apache.cxf.systest.ws.common.UTPasswordCallback</a></li></ul></div> +<div> +<h4><a id="sample_outbound_signaturetimestamp_configuration"></a>Sample Outbound Signature/Timestamp configuration</h4> +<ul> +<li><strong>Key</strong> - <strong>Value</strong></li> +<li>action - Signature Timestamp</li> +<li>signatureUser - alice</li> +<li>passwordCallbackClass - <a href="https://github.com/apache/cxf/blob/master/systests/ws-security/src/test/java/org/apache/cxf/systest/ws/common/KeystorePasswordCallback.java";>org.apache.cxf.systest.ws.common.KeystorePasswordCallback</a></li> +<li>signaturePropFile - <a href="https://github.com/apache/cxf/blob/master/systests/ws-security/src/test/resources/alice.properties";>alice.properties</a></li> +<li>signatureKeyIdentifier - DirectReference</li> +<li>signatureParts - {}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp;{}{http://schemas.xmlsoap.org/soap/envelope/}Body;</li></ul></div></div> +<div> +<h3><a id="ws_securitypolicy_based_approach"></a>WS-SecurityPolicy based approach</h3> +<p>The recommended way of applying WS-Security to your web services is to use +WS-SecurityPolicy. The WS-SecurityPolicy specification defines a set of +WS-Policy expressions that can be used to define the security requirements of +a web service. Typically one or more policies are attached to the WSDL of a +service, which conveys the security requirements of the service to the client. +A WS-SecurityPolicy aware stack such as Apache CXF or Apache Axis/Rampart can +parse the policies and configure WSS4J appropriately. This greatly simplifies +things for the user, who then only has to supply some basic information about +which users, CallbackHandlers, Crypto property files, etc. to use.</p> +<p>For more information on using WS-SecurityPolicy with WSS4J, please see CXF’s +WS-SecurityPolicy page, or go to the SOAP stack sections below: +<a href="http://cxf.apache.org/docs/ws-securitypolicy.html";>CXF WS-SecurityPolicy configuration</a></p></div> +<div> +<h3><a id="standalone_approach"></a>Standalone approach</h3> +<p>Apache WSS4J provides a set of APIs to implement WS-Security functionality on +a SOAP message. It is possible to use these APIs directly in a standalone +manner, although it is far more common to use either the "Action" or +WS-SecurityPolicy based approaches. This functionality is only available for +the DOM code. The best way of finding out how to do this is to take a look at +the test sources. For example:</p> +<ul> +<li><a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/UsernameTokenTest.java?view=markup";>Username Token Test</a></li> +<li><a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/EncryptionTest.java?view=markup";>Encryption Test</a></li> +<li><a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/SignatureTest.java?view=markup";>Signature Test</a></li> +<li><a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/TimestampTest.java?view=markup";>Timestamp Test</a></li> +<li><a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/saml/SamlTokenTest.java?view=markup";>SAML Token Test</a></li></ul></div> +<div> +<h3><a id="soap_stacks"></a>SOAP Stacks</h3> +<div> +<h4><a id="apache_cxf"></a>Apache CXF</h4> +<p><a href="http://cxf.apache.org";>Apache CXF</a> is an open-source web services +stack. CXF uses WSS4J to perform the core WS-Security functionality, and +provides extended security functionality based around the WS-SecurityPolicy, +WS-SecureConversation and WS-Trust specifications. More information:</p> +<ul> +<li><a href="http://cxf.apache.org/docs/ws-security.html";>CXF WS-Security configuration</a></li> +<li><a href="http://cxf.apache.org/docs/ws-secureconversation.html";>CXF WS-SecureConversation configuration</a></li> +<li><a href="http://cxf.apache.org/docs/ws-securitypolicy.html";>CXF WS-SecurityPolicy configuration</a></li> +<li><a href="http://cxf.apache.org/docs/ws-trust.html";>CXF WS-Trust configuration</a></li> +<li><a href="http://cxf.apache.org/resources-and-articles.html";>CXF Security articles</a></li></ul></div> +<div> +<h4><a id="apache_rampartaxis"></a>Apache Rampart/Axis</h4> +<p><a href="http://axis.apache.org/axis2/java/rampart/";>Apache Rampart</a> is the +security module for the Axis2 web services stack. Rampart uses WSS4J to +perform the core WS-Security functionality, and provides extended security +functionality based around the WS-SecurityPolicy, WS-SecureConversation and +WS-Trust specifications. Note that support for Apache Axis1 via the WSS4J +1.5.x series of releases is no longer supported. More information:</p> +<ul> +<li><a href="http://axis.apache.org/axis2/java/rampart/developer-guide.html";>Rampart developer guide</a></li> +<li><a href="http://axis.apache.org/axis2/java/rampart/samples.html";>Rampart samples</a></li> +<li><a href="http://axis.apache.org/axis2/java/rampart/rampartconfig-guide.html";>Rampart configuration guide</a></li> +<li><a href="http://axis.apache.org/axis2/java/rampart/articles.html";>Rampart articles</a></li></ul></div></div></div> +<div> +<h2><a id="apache_wss4j_migration_guides"></a>Apache WSS4J Migration Guides</h2> +<p>Information about migrating to various new versions of WSS4J is provided in this section.</p> +<div> +<h3><a id="apache_wss4j_2_2_0_migration_guide"></a>Apache WSS4J 2.2.0 Migration Guide</h3> +<p>This section is a migration guide for helping Apache WSS4J 2.1.x users to migrate +to the 2.2.x releases.</p> +<div> +<h4><a id="jdk8_minimum_requirement"></a>JDK8 minimum requirement</h4> +<p>WSS4J 2.1.x required JDK7 as a minimum requirement. WSS4J 2.2.x requires at +least JDK8.</p></div> +<div> +<h4><a id="base64_changes"></a>Base64 changes</h4> +<p>In WSS4J 2.1.x, the Base64 implementation that ships with the JDK +(java.util.Base64) is used, instead of the Base64 implementation that ships +with Apache Santuario. It is unlikely, but this may have an impact on users +who are parsing messages with Base64 implementations that depend on specific +CR or LF characters, as the Santuario and Java Base64 implementations differ +slightly. Both the Apache Santuario and Java Base64 implementations can +correctly decode the messages created with Apache WSS4J 2.2.x.</p></div> +<div> +<h4><a id="kerberos_changes"></a>Kerberos changes</h4> +<p>There are some changes with regards to Kerberos in WSS4J 2.1.x. The +KerberosClientAction and KerberosServiceAction classes are removed. Instead +use KerberosClientExceptionAction and KerberosServiceExceptionAction in the +same package. The KerberosTokenDecoderImpl is removed as we can now get access +to the secret key via the JDK APIs. As a consequence, the ws-security-common +module no longer has a dependency on Apache Directory.</p></div></div> +<div> +<h3><a id="apache_wss4j_2_1_0_migration_guide"></a>Apache WSS4J 2.1.0 Migration Guide</h3> +<p>This section is a migration guide for helping Apache WSS4J 2.0.x users to migrate +to the 2.1.x releases.</p> +<div> +<h4><a id="jdk7_minimum_requirement"></a>JDK7 minimum requirement</h4> +<p>WSS4J 2.0.x required JDK6 as a minimum requirement. WSS4J 2.1.x requires at +least JDK7. The Xerces and xml-api dependencies have been removed from the DOM +code, as they are no longer required due to the JDK7 minimum requirement.</p></div> +<div> +<h4><a id="opensaml_3_x_migration"></a>OpenSAML 3.x migration</h4> +<p>A key dependency change in WSS4J 2.1.0 is the upgrade from OpenSAML 2.x to +3.x (currently 3.1.0). OpenSAML 3.x contains a large number of package +changes. Therefore if you have any OpenSAML dependencies in a CallbackHandler +used to create SAML Assertions in WSS4J, code changes will be required.</p> +<p>The most common OpenSAML dependency is to include a "SAMLVersion" to tell +the SAMLCallback whether to create a SAML 2.0 or 1.1 Assertion. WSS4J 2.1 +provides an alternative way of specifying the SAML Version, via a <a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-common/src/main/java/org/apache/wss4j/common/saml/bean/Version.java";>Version</a> bean. See +<a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/common/SAML2CallbackHandler.java";>here</a> for an example.</p></div> +<div> +<h4><a id="custom_processor_changes"></a>Custom processor changes</h4> +<p>If you have a custom Processor instance to process a token in the security +header in some custom way, you must add the WSSecurityEngineResult that is +generated by the processing, to the WSDocInfo Object via the "addResult" +method. Otherwise, it will not be available when security results are +retrieved and processed.</p></div></div> +<div> +<h3><a id="apache_wss4j_2_0_0_migration_guide"></a>Apache WSS4J 2.0.0 Migration Guide</h3> +<p>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 <a href="newfeatures20.html">new +features</a> page for more information about the new functionality available in +WSS4J 2.0.x.</p> +<div> +<h4><a id="migrating_to_using_the_streaming_stax_code"></a>Migrating to using the streaming (StAX) code</h4> +<p>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).</p> +<p>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:</p> +<ul> +<li>"org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor" to +"org.apache.cxf.ws.security.wss4j.WSS4JStaxOutInterceptor".</li> +<li>"org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor" to +"org.apache.cxf.ws.security.wss4j.WSS4JStaxInInterceptor".</li></ul> +<p>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".</p> +<p>For more information on the streaming functionality available in WSS4J 2.0.0, +please see the <a href="streaming.html">streaming documentation</a> page.</p></div> +<div> +<h4><a id="cryptocallbackhandler_changes"></a>Crypto/CallbackHandler changes</h4> +<p>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.</p> +<p>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:</p> +<ul> +<li>signatureVerificationPropFile - The path of the crypto property file to +use for Signature verification.</li> +<li>signatureVerificationPropRefId - The key that holds a reference to the +object holding complete information about the signature verification Crypto +implementation.</li></ul> +<p>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.</p></div> +<div> +<h4><a id="saml_assertion_changes"></a>SAML Assertion changes</h4> +<p>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".</p> +<p>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.</p> +<p>The SAMLCallback Object contains the additional properties in WSS4J 2.0.0 that +can be set to sign the Assertion:</p> +<ul> +<li>boolean signAssertion - Whether to sign the assertion or not (default "false").</li> +<li>String issuerKeyName - The keystore alias for signature</li> +<li>String issuerKeyPassword - The keystore password for the alias</li> +<li>Crypto issuerCrypto - The Crypto instance used for signature</li> +<li>boolean sendKeyValue - Whether to send the keyvalue or the X509Certificate +(default "false").</li> +<li>String canonicalizationAlgorithm - The C14n algorithm to use for signature.</li> +<li>String signatureAlgorithm - The Signature algorithm.</li></ul></div> +<div> +<h4><a id="configuration_tag_changes"></a>Configuration tag changes</h4> +<p>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 +<a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-common/src/main/java/org/apache/wss4j/common/ConfigurationConstants.java?view=markup";>ConfigurationConstants</a>. 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.</p> +<p>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.</p> +<div> +<h5><a id="removed_configuration_tags_in_wss4j_2_0_0"></a>Removed Configuration tags in WSS4J 2.0.0</h5> +<p>This section details the Configuration tags that are no longer present in +WSS4J 2.0.0.</p> +<ul> +<li>SIGN_WITH_UT_KEY (UsernameTokenSignature) - Perform a .NET specific signature using a Username Token action. Removed +as it was not standard compliant.</li> +<li>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.</li> +<li>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.</li> +<li>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.</li> +<li>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.</li> +<li>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.</li> +<li>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.</li> +<li>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.</li></ul></div> +<div> +<h5><a id="new_configuration_tags_in_wss4j_2_0_0"></a>New Configuration tags in WSS4J 2.0.0</h5> +<p>This section details the new Configuration tags in WSS4J 2.0.0.</p> +<ul> +<li>USERNAME_TOKEN_SIGNATURE (UsernameTokenSignature) - Perform a UsernameTokenSignature action.</li> +<li>SIGNATURE_DERIVED (SignatureDerived) - Perform a Signature action with derived keys.</li> +<li>ENCRYPT_DERIVED (EncryptDerived) - Perform a Encryption action with derived keys.</li> +<li>SIGNATURE_WITH_KERBEROS_TOKEN (SignatureWithKerberosToken) - Perform a Signature action with a kerberos token. Only for StAX code.</li> +<li>ENCRYPT_WITH_KERBEROS_TOKEN (EncryptWithKerberosToken) - Perform a Encryption action with a kerberos token. Only for StAX code.</li> +<li>KERBEROS_TOKEN (KerberosToken) - Add a kerberos token.</li> +<li>CUSTOM_TOKEN (CustomToken) - Add a "Custom" token from a CallbackHandler</li> +<li>SIG_VER_PROP_FILE (signatureVerificationPropFile) - The path of the crypto property file to use for Signature verification.</li> +<li>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.</li> +<li>ALLOW_RSA15_KEY_TRANSPORT_ALGORITHM (allowRSA15KeyTransportAlgorithm) - Whether to allow the RSA v1.5 Key Transport Algorithm or not. Default is +"false".</li> +<li>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".</li> +<li>ADD_USERNAMETOKEN_NONCE (addUsernameTokenNonce) - Whether to add a Nonce Element to a UsernameToken (for plaintext). Default +is "false"</li> +<li>ADD_USERNAMETOKEN_CREATED (addUsernameTokenCreated) - Whether to add a Created Element to a UsernameToken (for plaintext). +Default is "false"</li> +<li>ALLOW_USERNAMETOKEN_NOPASSWORD (allowUsernameTokenNoPassword) - Whether a UsernameToken with no password element is allowed. Default is +"false".</li> +<li>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".</li> +<li>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"</li> +<li>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"</li> +<li>ENABLE_NONCE_CACHE (enableNonceCache) - Whether to cache UsernameToken nonces. Default is "true"</li> +<li>ENABLE_TIMESTAMP_CACHE (enableTimestampCache) - Whether to cache Timestamp Created Strings (these are only cached in +conjunction with a message Signature). Default is "true"</li> +<li>ENABLE_SAML_ONE_TIME_USE_CACHE (enableSamlOneTimeUseCache) - Whether to cache SAML2 Token Identifiers, if the token contains a +"OneTimeUse" Condition. Default is "true".</li> +<li>USE_2005_12_NAMESPACE (use200512Namespace) - Whether to use the 2005/12 namespace for SecureConveration + DerivedKeys, +or the older namespace. The default is "true"</li> +<li>OPTIONAL_SIGNATURE_PARTS (optionalSignatureParts) - Parameter to define which parts of the request shall be signed, if they +exist in the request.</li> +<li>OPTIONAL_ENCRYPTION_PARTS (optionalEncryptionParts) - Parameter to define which parts of the request shall be encrypted, if they +exist in the request.</li> +<li>ENC_MGF_ALGO (encryptionMGFAlgorithm) - Defines which encryption mgf algorithm to use with the RSA OAEP Key +Transport algorithm for encryption. The default is mgfsha1.</li> +<li>VALIDATOR_MAP (validatorMap) - A map of QName, Object (Validator) instances to be used to validate +tokens identified by their QName.</li> +<li>NONCE_CACHE_INSTANCE (nonceCacheInstance) - A ReplayCache instance used to cache UsernameToken nonces. The default +instance that is used is the EHCacheReplayCache.</li> +<li>TIMESTAMP_CACHE_INSTANCE (timestampCacheInstance) - A ReplayCache instance used to cache Timestamp Created Strings. The default +instance that is used is the EHCacheReplayCache.</li> +<li>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.</li> +<li>PASSWORD_ENCRYPTOR_INSTANCE (passwordEncryptorInstance) - A PasswordEncryptor instance used to decrypt encrypted passwords in Crypto +properties files. The default is the JasyptPasswordEncryptor.</li> +<li>DERIVED_TOKEN_REFERENCE (derivedTokenReference) - This controls how deriving tokens are referenced.</li> +<li>DERIVED_TOKEN_KEY_ID (derivedTokenKeyIdentifier) - This controls the key identifier of Derived Tokens.</li> +<li>DERIVED_SIGNATURE_KEY_LENGTH (derivedSignatureKeyLength) - The length to use (in bytes) when deriving a key for Signature.</li> +<li>DERIVED_ENCRYPTION_KEY_LENGTH (derivedEncryptionKeyLength) - The length to use (in bytes) when deriving a key for Encryption.</li></ul></div></div> +<div> +<h4><a id="derived_key_and_secure_conversation_namespace_change"></a>Derived Key and Secure Conversation namespace change</h4> +<p>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".</p></div> +<div> +<h4><a id="caching_changes"></a>Caching changes</h4> +<p>WSS4J 2.0.0 uses three EhCache-based caches by default for the following +scenarios, to prevent replay attacks:</p> +<ul> +<li>UsernameToken nonces</li> +<li>Signed Timestamps</li> +<li>SAML 2.0 OneTimeUse Assertions</li></ul> +<p>If you are seeing a error about "replay attacks" after upgrade, then you may +need to disable a particular cache.</p></div> +<div> +<h4><a id="rsa_v1_5_key_transport_algorithm_not_allowed_by_default"></a>RSA v1.5 Key Transport algorithm not allowed by default</h4> +<p>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".</p></div> +<div> +<h4><a id="inclusivenamespaces_prefixlist_change"></a>InclusiveNamespaces PrefixList change</h4> +<p>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.</p></div></div> +<div> +<h3><a id="new_features_available_in_apache_wss4j_2_0_0"></a>New features available in Apache WSS4J 2.0.0</h3> +<div> +<h4><a id="overview_of_new_features"></a>Overview of new features</h4> +<p>Apache WSS4J 2.0.0 delivers the following major new features:</p> +<ul> +<li>Support for a streaming (StAX) based WS-Security implementation that +covers all of the main specifications.</li> +<li>A WS-SecurityPolicy model that can be shared between both DOM + StAX +implementations.</li> +<li>Support for "real-time" WS-SecurityPolicy validation for the StAX +implementation.</li> +<li>Support for the SOAP with Attachments (SWA) Profile 1.1 specification.</li> +<li>Support for caching based on EhCache.</li> +<li>Support for encrypting passwords in Crypto properties files using Jasypt.</li></ul></div> +<div> +<h4><a id="streaming_stax_based_ws_security_implementation"></a>Streaming (StAX) based WS-Security implementation</h4> +<p>WSS4J 2.0.0 introduces a new streaming (StAX) based WS-Security implementation. +Please see the dedicated <a href="streaming.html">page</a> for more information.</p></div> +<div> +<h4><a id="ws_securitypolicy_support"></a>WS-SecurityPolicy support</h4> +<p>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.</p> +<p>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.</p></div> +<div> +<h4><a id="support_for_signing_and_encrypting_message_attachments"></a>Support for signing and encrypting message attachments</h4> +<p>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 <a href="attachments.html">page</a> for more +information.</p></div> +<div> +<h4><a id="replay_attack_detection_using_ehcache"></a>Replay Attack detection using EhCache</h4> +<p>In WSS4J 1.6.x, a "ReplayCache" interface was introduced to cache tokens to +guard against replay attacks for the following scenarios:</p> +<ul> +<li>Signed Timestamps</li> +<li>UsernameToken nonces</li> +<li>SAML OneTimeUse Assertions</li></ul> +<p>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:</p> +<ul> +<li>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.</li> +<li>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".</li> +<li>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.</li> +<li>ConfigurationConstants.ENABLE_NONCE_CACHE ("enableNonceCache"): Whether to +cache UsernameToken nonces. The default value is "true".</li> +<li>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.</li> +<li>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".</li></ul></div> +<div> +<h4><a id="encrypting_passwords_in_crypto_property_files"></a>Encrypting passwords in Crypto property files</h4> +<p>A typical example of the contents of a Crypto properties file (for Signature +creation) is as follows:</p> +<ul> +<li>org.apache.wss4j.crypto.provider=org.apache.wss4j.common.crypto.Merlin</li> +<li>org.apache.wss4j.crypto.merlin.keystore.type=jks</li> +<li>org.apache.wss4j.crypto.merlin.keystore.password=security</li> +<li>org.apache.wss4j.crypto.merlin.keystore.alias=wss40</li> +<li>org.apache.wss4j.crypto.merlin.keystore.file=keys/wss40.jks</li></ul> +<p>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".</p> +<p>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").</p></div> +<div> +<h4><a id="miscellaneous_new_features"></a>Miscellaneous new features</h4> +<p>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.</p> +<p>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.</p> +<p>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.</p> +<p>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").</p></div></div> +<div> +<h3><a id="apache_wss4j_1_6_0_migration_guide"></a>Apache WSS4J 1.6.0 Migration Guide</h3> +<p>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 <a href="wss4j20.html">migration guide</a> for more information.</p> +<div> +<h4><a id="new_features"></a>New features</h4> +<p>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 +<a href="https://issues.apache.org/jira/browse/WSS/fixforversion/12313718";>list of JIRAs</a> +that have been fixed in WSS4J 1.6.</p> +<ul> +<li><a href="http://coheigea.blogspot.com/2011/03/wss4j-16-jsr-105-support.html";>JSR-105 support</a>: +WSS4J 1.6 has been ported to use the JSR 105 API for XML Digital Signature.</li> +<li><a href="http://coheigea.blogspot.com/2011/02/support-for-saml2-assertions-in-wss4j.html";>SAML2 support</a>: WSS4J 1.6 includes full support for creating, manipulating and parsing SAML2 +assertions, via the Opensaml2 library.</li> +<li>Performance work: A general code-rewrite has been done with a focus on improving performance, +e.g. the <a href="http://coheigea.blogspot.com/2011/01/wss4j-16-actionprocessor-loading-change.html";>changes</a> that have been made to processor loading.</li> +<li><a href="http://coheigea.blogspot.com/2011/03/wss4j-16-basic-security-profile-11.html";>Basic Security Profile 1.1 compliance</a>: WSS4J 1.6 provides support for the BSP 1.1 specification.</li> +<li>JDK 1.5 port: The JDK 1.4 requirement of WSS4J 1.5.x has been dropped as part of this work.</li> +<li><a href="http://coheigea.blogspot.com/2011/01/wss4j-16-crypto-property-change.html";>Support for Crypto trust-stores</a>: WSS4J 1.6 separates the concept of keystore and truststores for +Crypto implementations.</li> +<li><a href="http://coheigea.blogspot.com/2011/04/wss4j-16-introducing-validators.html";>New Validator interface</a>: WSS4J 1.6 moves all validation of security tokens into a new Validator +interface, which allows for custom validation of specific tokens.</li> +<li>Support for the Kerberos Token Profile (in WSS4J 1.6.2 and 1.6.3).</li></ul></div> +<div> +<h4><a id="upgrade_notes"></a>Upgrade notes</h4> +<p>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.</p> +<ul> +<li>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.</li> +<li>A number of changes have been made to the Crypto interface. See +<a href="http://coheigea.blogspot.com/2011/01/wss4j-16-crypto-property-change.html";>here</a>, +<a href="http://coheigea.blogspot.com/2011/02/wss4j-16-changes-to-crypto-interface.html";>here</a> +and <a href="http://coheigea.blogspot.com/2011/02/wss4j-16-change-to-publickey-validation.html";>here</a> +for an indepth explanation. In a nutshell, these changes are: +<ol style="list-style-type: decimal;"> +<li>The BouncyCastle crypto implementation has been removed (replaced by Merlin)</li> +<li>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.</li> +<li>The CA certs are now <b>not</b> loaded by default.</li> +<li>PublicKeys (from KeyValues) are now not handled by a PublicKeyCallback, but by the Crypto implementation +directly.</li></ol></li> +<li>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, <strong>all</strong> DOM Elements that match the stored +localname/namespace will be processed. See the +<a href="http://ws.apache.org/wss4j/topics.html#Specifying_elements_to_sign_or_encrypt";>Special Topics page</a> +for more information.</li> +<li>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 +<a href="http://coheigea.blogspot.com/2011/02/support-for-saml2-assertions-in-wss4j.html";>here</a> for +more information on this. Some changes to be aware of are: +<ol style="list-style-type: decimal;"> +<li>The way of creating SAML assertions via a properties file has completely changed. For example, see +<a href="xref-test/org/apache/ws/security/saml/SamlTokenTest.html">SAML Token Test</a>.</li> +<li>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.</li> +<li>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 <strong>do</strong> have an enveloped +signature are saved as a "WSConstants.ST_SIGNED" action.</li> +<li>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.</li></ol></li> +<li>The way that UsernameTokens are processed has been changed. See +<a href="http://coheigea.blogspot.com/2011/02/usernametoken-processing-changes-in.html";>here</a> for +more information. Some important changes are: +<ol style="list-style-type: decimal;"> +<li>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.</li> +<li>The custom password type case defaults to the same behaviour as the plaintext case, assuming +wssConfig.getHandleCustomPasswordTypes() returns true.</li> +<li>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.</li></ol></li> +<li>Some changes have been made to the WSPasswordCallback identifiers, used to obtain passwords for various +actions. For more information see +<a href="http://coheigea.blogspot.com/2011/02/wspasswordcallback-changes-in-wss4j-16.html";>here</a>. In +a nutshell, these changes consist of: +<ol style="list-style-type: decimal;"> +<li>The WSPasswordCallback KEY_NAME, USERNAME_TOKEN_UNKNOWN and WSPasswordCallback.ENCRYPTED_KEY_TOKEN +identifiers have been removed.</li> +<li>CUSTOM_TOKEN is not longer used in the processors to get a secret key.</li> +<li>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.</li></ol></li> +<li>Timestamp validation and signature trust verification is not done by the WSHandler implementation +any more, but is performed when the security header is processed.</li></ul></div></div></div> +<div> +<h2><a id="wss4j_configuration"></a>WSS4J configuration</h2> +<p>This section describes how to use configure Apache WSS4J. This page only applies +to WSS4J 2.x, and 1.6.x, a lot of the properties have changed since WSS4J 1.5.x.</p> +<div> +<h3><a id="crypto_properties"></a>Crypto properties</h3> +<p>Apache WSS4J uses the Crypto interface to get keys and certificates for +encryption/decryption and for signature creation/verification. WSS4J ships +with three implementations:</p> +<ul> +<li><a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-common/src/main/java/org/apache/wss4j/common/crypto/Merlin.java?view=markup";> +Merlin</a>: The standard implementation, based around two JDK keystores for +key/cert retrieval, and trust verification.</li> +<li><a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-common/src/main/java/org/apache/wss4j/common/crypto/CertificateStore.java?view=markup";> +CertificateStore</a>: Holds an array of X509 Certificates. Can only be used +for encryption and signature verification.</li> +<li><a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-common/src/main/java/org/apache/wss4j/common/crypto/MerlinDevice.java?view=markup";> +MerlinDevice</a>: Based on Merlin, allows loading of keystores using a null +InputStream - for example on a smart-card device.</li></ul> +<p>For more information on the Crypto implementations see the +<a href="http://ws.apache.org/wss4j/topics.html#Crypto_Interface";>Special +Topics page</a>. It is possible to instantiate a Crypto implementation +directly, but it can also be loaded via a properties file. For Apache WSS4J +2.0.0 onwards, the property names ${PREFIX} below is "org.apache.wss4j.crypto". +For Apache WSS4J 1.6.x, the property names ${PREFIX} below is +"org.apache.ws.security.crypto". WSS4J 2.0.0 onwards will also accept the older +${PREFIX} value. The property values for the standard Merlin implementation +are as follows:</p> +<div> +<h4><a id="general_properties"></a>General properties</h4> +<ul> +<li>${PREFIX}.provider - WSS4J specific provider used to create Crypto instances. Defaults to +"org.apache.wss4j.common.crypto.Merlin".</li> +<li>${PREFIX}.merlin.x509crl.file - The location of an (X509) CRL file to use.</li></ul></div> +<div> +<h4><a id="merlin_keystore_properties"></a>Merlin Keystore Properties</h4> +<ul> +<li>${PREFIX}.merlin.keystore.provider - The provider used to load keystores. Defaults to installed provider.</li> +<li>${PREFIX}.merlin.cert.provider - The provider used to load certificates. Defaults to keystore provider.</li> +<li>${PREFIX}.merlin.keystore.file - The location of the keystore</li> +<li>${PREFIX}.merlin.keystore.password - The password used to load the keystore. Default value is "security".</li> +<li>${PREFIX}.merlin.keystore.type - Type of keystore. Defaults to: java.security.KeyStore.getDefaultType())</li> +<li>${PREFIX}.merlin.keystore.alias - The default keystore alias to use, if none is specified.</li> +<li>${PREFIX}.merlin.keystore.private.password - The default password used to load the private key.</li> +<li><strong>WSS4J 2.3.0/2.2.6</strong> ${PREFIX}.merlin.keystore.private.caching - Whether to enable caching when loading private keys or not. The default is true for WSS4J 2.3.0 and false for WSS4J 2.2.6. There is a significant performance gain for PKCS12 keys when caching is enabled.</li></ul></div> +<div> +<h4><a id="merlin_truststore_properties"></a>Merlin TrustStore properties</h4> +<ul> +<li>${PREFIX}.merlin.load.cacerts - Whether or not to load the CA certs in ${java.home}/lib/security/cacerts (default is false)</li> +<li>${PREFIX}.merlin.truststore.file - The location of the truststore</li> +<li>${PREFIX}.merlin.truststore.password - The truststore password. Defaults to "changeit".</li> +<li>${PREFIX}.merlin.truststore.type - The truststore type. Defaults to: java.security.KeyStore.getDefaultType().</li> +<li>${PREFIX}.merlin.truststore.provider - <strong>WSS4J 2.1.5</strong> The provider used to load truststores. By default it’s the same as the keystore provider. Set to an empty value to force use of the JRE’s default provider.</li></ul></div></div> +<div> +<h3><a id="saml_properties"></a>SAML properties</h3> +<p><strong>WSS4J 1.6.x only</strong> 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.</p> +<p>WSS4J 1.6.x ships with a default "SAMLIssuerImpl" implementation. It is +possible to instantiate a SAMLIssuer implementation directly, but it can also +be loaded via a properties file. The property values are as follows:</p> +<div> +<h4><a id="samlissuer_properties"></a>SAMLIssuer properties</h4> +<ul> +<li>org.apache.ws.security.saml.issuerClass - The SAML Issuer implementation (defaults to "org.apache.ws.security.saml.SAMLIssuerImpl").</li> +<li>org.apache.ws.security.saml.issuer.cryptoProp.file - The crypto properties file corresponding to the issuer crypto instance, if the assertion is to +be signed.</li> +<li>org.apache.ws.security.saml.issuer.key.name - The KeyStore alias for the issuer key.</li> +<li>org.apache.ws.security.saml.issuer.key.password - The KeyStore password for the issuer key.</li> +<li>org.apache.ws.security.saml.issuer - The issuer name</li> +<li>org.apache.ws.security.saml.issuer.sendKeyValue - Whether to send the key value or the X509Certificate. Default is "false".</li> +<li>org.apache.ws.security.saml.issuer.signAssertion - Whether the SAMLIssuer implementation will sign the assertion or not. Default is +"false".</li> +<li>org.apache.ws.security.saml.callback - The name of the SAML CallbackHandler implementation used to populate the SAML Assertion.</li></ul></div></div> +<div> +<h3><a id="configuration_tags"></a>Configuration tags</h3> +<p>Apache WSS4J provides a set of configuration tags that can be used to configure +both the DOM-based and StAX-based (WSS4J 2.0.0 onwards) outbound and inbound +processing. As both DOM and StAX code are very similar, both approaches share +a set of common configuration tags given in <a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-common/src/main/java/org/apache/wss4j/common/ConfigurationConstants.java?view=markup";>ConfigurationConstants</a>. 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.</p> +<p>The configuration tags for Actions are as follows:</p> +<div> +<h4><a id="action_configuration_tags"></a>Action configuration tags</h4> +<ul> +<li>ACTION (action) - The action to perform, e.g. ConfigurationConstants.TIMESTAMP</li> +<li>NO_SECURITY (NoSecurity) - Do not perform any action, do nothing. Only applies to DOM code.</li> +<li><strong>WSS4J 2.0.0</strong> USERNAME_TOKEN_SIGNATURE (UsernameTokenSignature) - Perform a UsernameTokenSignature action.</li> +<li>USERNAME_TOKEN (UsernameToken) - Perform a UsernameToken action.</li> +<li>USERNAME_TOKEN_NO_PASSWORD (UsernameTokenNoPassword) - Used on the receiving side to specify a UsernameToken with no password</li> +<li>SAML_TOKEN_UNSIGNED (SAMLTokenUnsigned) - Perform an unsigned SAML Token action.</li> +<li>SAML_TOKEN_SIGNED (SAMLTokenSigned) - Perform a signed SAML Token action.</li> +<li>SIGNATURE (Signature) - Perform a signature action.</li> +<li><strong>WSS4J 2.3.0</strong> ENCRYPTION (Encryption) - Perform an encryption action. +Note that for previous releases, this configuration tag was called ENCRYPT (Encrypt).</li> +<li>TIMESTAMP (Timestamp) - Perform a Timestamp action.</li> +<li><strong>WSS4J 2.0.0</strong> SIGNATURE_DERIVED (SignatureDerived) - Perform a Signature action with derived keys.</li> +<li><strong>WSS4J 2.3.0</strong> ENCRYPTION_DERIVED (EncryptionDerived) - Perform a Encryption action with derived keys. +Note that for releases from 2.0.0 → 2.2.x, this configuration tag was called ENCRYPT_DERIVED (EncryptDerived).</li> +<li><strong>WSS4J 2.0.0</strong> SIGNATURE_WITH_KERBEROS_TOKEN (SignatureWithKerberosToken) - Perform a Signature action with a kerberos token. Only for StAX code.</li> +<li><strong>WSS4J 2.3.0</strong> ENCRYPTION_WITH_KERBEROS_TOKEN (EncryptionWithKerberosToken) - Perform a Encryption action with a kerberos token. Only for StAX code. +Note that for releases from 2.0.0 → 2.2.x, this configuration tag was called ENCRYPT_WITH_KERBEROS_TOKEN (EncryptWithKerberosToken).</li> +<li><strong>WSS4J 2.0.0</strong> KERBEROS_TOKEN (KerberosToken) - Add a kerberos token. Only for StAX code.</li> +<li><strong>WSS4J 2.0.0</strong> CUSTOM_TOKEN (CustomToken) - Add a "Custom" token from a CallbackHandler</li> +<li><strong>WSS4J 1.6.x only</strong> SIGN_WITH_UT_KEY (UsernameTokenSignature) - Perform a .NET specific signature using a Username Token action.</li></ul></div> +<div> +<h4><a id="wshandler_user_configuration_tags"></a>WSHandler User configuration tags</h4> +<p>The configuration tags for WSHandler user properties are as follows:</p> +<ul> +<li>ACTOR ("actor") - The actor or role name of the wsse:Security header.</li> +<li>USER ("user") - The user’s name. Consult the Javadoc for an explanation of this property.</li> +<li>ENCRYPTION_USER ("encryptionUser") - The user’s name for encryption. Consult the Javadoc for an explanation of +this property.</li> +<li>SIGNATURE_USER ("signatureUser") - The user’s name for signature. Consult the Javadoc for an explanation of +this property.</li> +<li>USE_REQ_SIG_CERT ("useReqSigCert") - A special value for ENCRYPTION_USER. Consult the Javadoc for an +explanation of this property.</li></ul></div> +<div> +<h4><a id="callback_class_and_property_file_configuration_tags"></a>Callback class and Property File configuration tags</h4> +<p>The configuration tags for callback class and property file configuration are +summarised here:</p> +<ul> +<li>PW_CALLBACK_CLASS (passwordCallbackClass) - The CallbackHandler implementation class used to obtain passwords.</li> +<li>PW_CALLBACK_REF (passwordCallbackRef) - The CallbackHandler implementation object used to obtain passwords.</li> +<li>SAML_CALLBACK_CLASS (samlCallbackClass) - The CallbackHandler implementation class used to construct SAML Assertions.</li> +<li>SAML_CALLBACK_REF (samlCallbackRef) - The CallbackHandler implementation object used to construct SAML Assertions.</li> +<li><strong>WSS4J 1.6.x only</strong> ENC_CALLBACK_CLASS (embeddedKeyCallbackClass) - The CallbackHandler implementation class used to get the key associated +with a key name.</li> +<li><strong>WSS4J 1.6.x only</strong> ENC_CALLBACK_REF (embeddedKeyCallbackRef) - The CallbackHandler implementation object used to get the key associated +with a key name.</li> +<li>SIG_PROP_FILE (signaturePropFile) - The path of the crypto property file to use for Signature.</li> +<li>SIG_PROP_REF_ID (signaturePropRefId) - The String ID that is used to store a reference to the Crypto object or +the Crypto Properties object for Signature.</li> +<li><strong>WSS4J 2.0.0</strong> SIG_VER_PROP_FILE (signatureVerificationPropFile) - The path of the crypto property file to use for Signature verification.</li> +<li><strong>WSS4J 2.0.0</strong> 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.</li> +<li>DEC_PROP_FILE (decryptionPropFile) - The path of the crypto property file to use for Decryption.</li> +<li>DEC_PROP_REF_ID (decryptionPropRefId) - The String ID that is used to store a reference to the Crypto object or +the Crypto Properties object for decryption.</li> +<li>ENC_PROP_FILE (encryptionPropFile) - The path of the crypto property file to use for encryption.</li> +<li>ENC_PROP_REF_ID (encryptionPropRefId) - The String ID that is used to store a reference to the Crypto object or +the Crypto Properties object for encryption.</li> +<li>SAML_PROP_FILE (samlPropFile) - The path of the property file to use for creating SAML Assertions.</li></ul></div> +<div> +<h4><a id="boolean_configuration_tags"></a>Boolean configuration tags</h4> +<p>The configuration tags for properties that are configured via a boolean +parameter (i.e. "true" or "false") are as follows:</p> +<ul> +<li>ENABLE_SIGNATURE_CONFIRMATION (enableSignatureConfirmation) - Whether to enable signature confirmation or not. Default is "false".</li> +<li>MUST_UNDERSTAND (mustUnderstand) - Set the outbound MustUnderstand flag or not. Default is "true".</li> +<li>IS_BSP_COMPLIANT (isBSPCompliant) - Whether or not to ensure compliance with the BSP 1.1 spec. Default is +"true".</li> +<li><strong>WSS4J 2.0.0</strong> 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".</li> +<li><strong>WSS4J 2.0.0</strong> ADD_USERNAMETOKEN_NONCE (addUsernameTokenNonce) - Whether to add a Nonce Element to a UsernameToken (for plaintext). Default +is "false"</li> +<li><strong>WSS4J 2.0.0</strong> ADD_USERNAMETOKEN_CREATED (addUsernameTokenCreated) - Whether to add a Created Element to a UsernameToken (for plaintext). +Default is "false"</li> +<li>HANDLE_CUSTOM_PASSWORD_TYPES (handleCustomPasswordTypes) - Whether to allow non-standard password types in a UsernameToken. Default +is "false".</li> +<li><strong>WSS4J 1.6.x only</strong> PASSWORD_TYPE_STRICT (passwordTypeStrict) - Whether to enable strict Username Token password type handling. Default is +"false".</li> +<li><strong>WSS4J 2.0.0</strong> ALLOW_USERNAMETOKEN_NOPASSWORD (allowUsernameTokenNoPassword) - Whether a UsernameToken with no password element is allowed. Default is +"false".</li> +<li>REQUIRE_SIGNED_ENCRYPTED_DATA_ELEMENTS (requireSignedEncryptedDataElements) - Whether the engine needs to enforce EncryptedData elements are in a signed +subtree of the document. Default is "false".</li> +<li><strong>WSS4J 1.6.x only</strong> USE_DERIVED_KEY (useDerivedKey) - Whether to use the standard UsernameToken Key Derivation algorithm. +Default is "true".</li> +<li>ALLOW_NAMESPACE_QUALIFIED_PASSWORD_TYPES (allowNamespaceQualifiedPasswordTypes) - Whether (wsse) namespace qualified password types are accepted when +processing UsernameTokens. Default is "false".</li> +<li>ENABLE_REVOCATION (enableRevocation) - Whether to enable Certificate Revocation List (CRL) checking when +verifying trust in a certificate. Default is "false".</li> +<li>USE_ENCODED_PASSWORDS (useEncodedPasswords) - Set whether to treat passwords as binary values for Username Tokens. +Default is "false". DOM code only.</li> +<li>USE_SINGLE_CERTIFICATE (useSingleCertificate) - Whether to use a single certificate or a whole certificate chain to +construct a BinarySecurityToken. Default is "true".</li> +<li>USE_DERIVED_KEY_FOR_MAC (useDerivedKeyForMAC) - Whether to use the Username Token derived key for a MAC. Default is +"true".</li> +<li>TIMESTAMP_PRECISION (precisionInMilliseconds) - Set whether outbound timestamps have precision in milliseconds. Default is +"true".</li> +<li>TIMESTAMP_STRICT (timestampStrict) - Set whether to enable strict Timestamp handling, i.e. throw an exception if +the current receiver time is past the Expires time of the Timestamp. Default +is "true".</li> +<li><strong>WSS4J 2.0.4/2.1.0</strong> REQUIRE_TIMESTAMP_EXPIRES (requireTimestampExpires) - Set the value of this parameter to true to require that a Timestamp must +have an "Expires" Element. The default is "false".</li> +<li>ENC_SYM_ENC_KEY (encryptSymmetricEncryptionKey) - Set whether to encrypt the symmetric encryption key or not. Default is +"true".</li> +<li><strong>WSS4J 2.0.0</strong> ALLOW_RSA15_KEY_TRANSPORT_ALGORITHM (allowRSA15KeyTransportAlgorithm) - Whether to allow the RSA v1.5 Key Transport Algorithm or not. Default is +"false".</li> +<li><strong>WSS4J 2.0.0</strong> 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".</li> +<li><strong>WSS4J 2.0.0</strong> INCLUDE_SIGNATURE_TOKEN (includeSignatureToken) - Whether to include the Signature Token in the security header as well or +not (for IssuerSerial, Thumbprint, SKI cases). Default is "false"</li> +<li><strong>WSS4J 2.0.0</strong> 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"</li> +<li><strong>WSS4J 2.0.0</strong> USE_2005_12_NAMESPACE (use200512Namespace) - Whether to use the 2005/12 namespace for SecureConveration + DerivedKeys, +or the older namespace. The default is "true"</li> +<li><strong>WSS4J 2.1.2/2.0.5</strong> GET_SECRET_KEY_FROM_CALLBACK_HANDLER (getSecretKeyFromCallbackHandler) - Whether to get a secret key from a CallbackHandler or not for encryption +only. The default is false. If set to true WSS4J attempts to get the secret +key from the CallbackHandler instead of generating a random key internally.</li> +<li><strong>WSS4J 2.1.2/2.0.5</strong> STORE_BYTES_IN_ATTACHMENT (storeBytesInAttachment) - Whether to store bytes (CipherData or BinarySecurityToken) in an +attachment. The default is false, meaning that bytes are BASE-64 encoded and +"inlined" in the message. Setting this to true is more efficient, as it means +that the BASE-64 encoding step can be skipped. For this to work, a +CallbackHandler must be set on RequestData that can handle attachments.</li> +<li><strong>WSS4J 2.1.2/2.0.5</strong> EXPAND_XOP_INCLUDE_FOR_SIGNATURE (expandXOPIncludeForSignature) - (Deprecated in 2.2.0). Whether to expand xop:Include Elements encountered when verifying a +Signature. The default is true, meaning that the relevant attachment bytes are +BASE-64 encoded and inserted into the Element. This ensures that the actual +bytes are signed, and not just the reference.</li> +<li><strong>WSS4J 2.2.0</strong> EXPAND_XOP_INCLUDE (expandXOPInclude) - Whether to search for and expand xop:Include Elements for encryption and +signature (on the outbound side) or for signature verification (on the inbound +side). The default is false on the outbound side and true on the inbound side. +What this means on the inbound side, is that the relevant attachment bytes are +BASE-64 encoded and inserted into the Element. This ensures that the actual +bytes are signed, and not just the reference.</li></ul></div> +<div> +<h4><a id="non_boolean_configuration_tags"></a>Non-boolean configuration tags</h4> +<p>The configuration tags for properties that are configured via a non-boolean +parameter are as follows:</p> +<ul> +<li>PASSWORD_TYPE (passwordType) - The encoding of the password for a Username Token. The default is +WSConstants.PW_DIGEST.</li> +<li><strong>WSS4J 1.6.x only</strong> ENC_KEY_NAME (embeddedKeyName) - The text of the key name to be sent in the KeyInfo for encryption</li> +<li><strong>WSS4J 1.6.x only</strong> ADD_UT_ELEMENTS (addUTElements) - Additional elements to add to a Username Token, i.e. "nonce" and "created".</li> +<li>SIG_KEY_ID (signatureKeyIdentifier) - The key identifier type to use for signature. The default is "IssuerSerial".</li> +<li>SIG_ALGO (signatureAlgorithm) - The signature algorithm to use. The default is set by the data in the +certificate.</li> +<li>SIG_DIGEST_ALGO (signatureDigestAlgorithm) - The signature digest algorithm to use. The default is SHA-1.</li> +<li>SIG_C14N_ALGO (signatureC14nAlgorithm) - Defines which signature c14n (canonicalization) algorithm to use. The +default is: "http://www.w3.org/2001/10/xml-exc-c14n#";.</li> +<li><strong>WSS4J 1.6.x only</strong> WSE_SECRET_KEY_LENGTH (wseSecretKeyLength) - The length of the secret (derived) key to use for the WSE UT_SIGN +functionality.</li> +<li>SIGNATURE_PARTS (signatureParts) - Parameter to define which parts of the request shall be signed. The SOAP +body is signed by default.</li> +<li><strong>WSS4J 2.0.0</strong> OPTIONAL_SIGNATURE_PARTS (optionalSignatureParts) - Parameter to define which parts of the request shall be signed, if they +exist in the request.</li> +<li>DERIVED_KEY_ITERATIONS (derivedKeyIterations) - The number of iterations to use when deriving a key from a Username Token. +The default is 1000.</li> +<li>ENC_KEY_ID (encryptionKeyIdentifier) - The key identifier type to use for encryption. The default is +"IssuerSerial".</li> +<li>ENC_SYM_ALGO (encryptionSymAlgorithm) - The symmetric encryption algorithm to use. The default is AES-128.</li> +<li>ENC_KEY_TRANSPORT (encryptionKeyTransportAlgorithm) - The algorithm to use to encrypt the generated symmetric key. The default is RSA-OAEP.</li> +<li>ENC_DIGEST_ALGO (encryptionDigestAlgorithm) - The encryption digest algorithm to use with the RSA-OAEP key transport +algorithm. The default is SHA-1.</li> +<li>ENCRYPTION_PARTS (encryptionParts) - Parameter to define which parts of the request shall be encrypted. The +SOAP body is encrypted in "Content" mode by default.</li> +<li><strong>WSS4J 2.0.0</strong> OPTIONAL_ENCRYPTION_PARTS (optionalEncryptionParts) - Parameter to define which parts of the request shall be encrypted, if they +exist in the request.</li> +<li><strong>WSS4J 2.0.0</strong> ENC_MGF_ALGO (encryptionMGFAlgorithm) - Defines which encryption mgf algorithm to use with the RSA OAEP Key +Transport algorithm for encryption. The default is mgfsha1.</li> +<li>TTL_TIMESTAMP (timeToLive) - The time difference between creation and expiry time in seconds in the WSS +Timestamp. The default is "300".</li> +<li>TTL_FUTURE_TIMESTAMP (futureTimeToLive) - The time in seconds in the future within which the Created time of an +incoming Timestamp is valid. The default is "60".</li> +<li>TTL_USERNAMETOKEN (utTimeToLive) - The time difference between creation and expiry time in seconds in the WSS +UsernameToken created element. The default is "300".</li> +<li>TTL_FUTURE_USERNAMETOKEN (utFutureTimeToLive) - The time in seconds in the future within which the Created time of an +incoming UsernameToken is valid. The default is "60".</li> +<li>SIG_SUBJECT_CERT_CONSTRAINTS (sigSubjectCertConstraints) - A String (separated by the value specified for SIG_CERT_CONSTRAINTS_SEPARATOR) +of regular expressions which will be applied to +the subject DN of the certificate used for signature validation, after trust +verification of the certificate chain associated with the certificate.</li> +<li>SIG_ISSUER_CERT_CONSTRAINTS (sigIssuerCertConstraints) - A String (separated by the value specified for SIG_CERT_CONSTRAINTS_SEPARATOR) +of regular expressions which will be applied to +the issuer DN of the certificate used for signature validation, after trust +verification of the certificate chain associated with the certificate.</li> +<li><strong>WSS4J 2.2.3</strong> SIG_CERT_CONSTRAINTS_SEPARATOR (sigCertConstraintsSeparator) - The separator that is used to parse certificate constraints configured in the +SIG_SUBJECT_CERT_CONSTRAINTS and SIG_ISSUER_CERT_CONSTRAINTS configuration tags. The default is ",".</li> +<li><strong>WSS4J 2.0.0</strong> VALIDATOR_MAP (validatorMap) - A map of QName, Object (Validator) instances to be used to validate +tokens identified by their QName.</li> +<li><strong>WSS4J 2.0.0</strong> NONCE_CACHE_INSTANCE (nonceCacheInstance) - A ReplayCache instance used to cache UsernameToken nonces. The default +instance that is used is the EHCacheReplayCache.</li> +<li><strong>WSS4J 2.0.0</strong> TIMESTAMP_CACHE_INSTANCE (timestampCacheInstance) - A ReplayCache instance used to cache Timestamp Created Strings. The default +instance that is used is the EHCacheReplayCache.</li> +<li><strong>WSS4J 2.0.0</strong> 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.</li> +<li><strong>WSS4J 2.0.0</strong> PASSWORD_ENCRYPTOR_INSTANCE (passwordEncryptorInstance) - A PasswordEncryptor instance used to decrypt encrypted passwords in Crypto +properties files. The default is the JasyptPasswordEncryptor.</li> +<li><strong>WSS4J 2.0.0</strong> DERIVED_TOKEN_REFERENCE (derivedTokenReference) - This controls how deriving tokens are referenced.</li> +<li><strong>WSS4J 2.0.0</strong> DERIVED_TOKEN_KEY_ID (derivedTokenKeyIdentifier) - This controls the key identifier of Derived Tokens.</li> +<li><strong>WSS4J 2.0.0</strong> DERIVED_SIGNATURE_KEY_LENGTH (derivedSignatureKeyLength) - The length to use (in bytes) when deriving a key for Signature.</li> +<li><strong>WSS4J 2.0.0</strong> DERIVED_ENCRYPTION_KEY_LENGTH (derivedEncryptionKeyLength) - The length to use (in bytes) when deriving a key for Encryption.</li></ul></div> +<div> +<h4><a id="keyidentifier_values"></a>KeyIdentifier values</h4> +<p>The configuration values for setting the KeyIdentifiers for signature or +encryption are shown below. For an in depth explanation +with examples, see this blog <a href="http://coheigea.blogspot.com/2013/03/signature-and-encryption-key.html";>entry</a>.</p> +<ul> +<li>DirectReference</li> +<li>IssuerSerial</li> +<li>X509KeyIdentifier</li> +<li>SKIKeyIdentifier</li> +<li>EmbeddedKeyName</li> +<li>Thumbprint</li> +<li>EncryptedKeySHA1</li> +<li>KeyValue</li> +<li><strong>WSS4J 2.0.0</strong> KerberosSHA1</li></ul></div></div></div> +<div> +<h2><a id="streaming_stax_ws_security_support_in_apache_wss4j_2_0_0"></a>Streaming (StAX) WS-Security support in Apache WSS4J™ 2.0.0</h2> +<div> +<h3><a id="overview_of_new_features_2"></a>Overview of new features</h3> +<p>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 suffers from having to read the entire +XML tree into memory. For large SOAP requests this can have a detrimental +impact on performance. In addition, for web services stacks such as Apache CXF +which are streaming-based, it carries an additional performance penalty of +having to explicitly convert the request stream to a DOM Element.</p> +<p>The new StAX-based WS-Security implementation does not read the request into +memory, and hence uses far less memory for large requests. It is also more +performant in certain circumstances. 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). It does not offer the low-level API available in the DOM +code to individually construct various WS-Security tokens, but instead must be +used by specifying various actions to perform.</p> +<p>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:</p> +<ul> +<li>"org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor" to +"org.apache.cxf.ws.security.wss4j.WSS4JStaxOutInterceptor".</li> +<li>"org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor" to +"org.apache.cxf.ws.security.wss4j.WSS4JStaxInInterceptor".</li></ul> +<p>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".</p></div> +<div> +<h3><a id="limitations_of_the_streaming_ws_security_implementation"></a>Limitations of the streaming WS-Security implementation</h3> +<p>The new streaming implementation in WSS4J 2.0.0 meets the vast majority of the +most common use-cases. However, it does not support everything that the DOM +implementation supports. The limitations are:</p> +<ul> +<li>XPath evaluation is not supported apart from certain simple expressions. +XPath evaluations are used with WS-SecurityPolicy RequiredElements, +SignedElements, (Content)EncryptedElements. XPath expressions that point +directly to the element are supported, e.g. /soap:Envelope/soap:Header/wsa:To. +See WSS-445.</li> +<li>WS-SecurityPolicy "Strict" Layout validation is not enforced. This includes +enforcing whether a Timestamp is first or last. See WSS-444.</li> +<li>A SymmetricBinding policy with a ProtectTokens assertion is not supported. +See WSS-456.</li> +<li>The combination of EncryptBeforeSigning + EncryptSignature policies are not +supported. See WSS-464.</li> +<li>Deriving keys from Username Tokens (Endorsing Username Tokens) are not +supported.</li> +<li>Endorsing tokens don’t work with Symmetric + Asymmetric binding on the +client side, unless the endorsing token is a SAML or IssuedToken.</li> +<li>Derived Endorsing Tokens are not supported on the client side.</li></ul></div></div> +<div> +<h2><a id="securing_message_attachments"></a>Securing message attachments</h2> +<p>WSS4J 2.0.0 introduces support for signing and encrypting SOAP message +attachments, via the the SOAP with Attachments (SWA) Profile 1.1 specification. +There is no support in WSS4J 1.6.x for signing or encrypting message +attachments. Attachments can be signed and encrypted in WSS4J via either the +"action"-based approach or via WS-SecurityPolicy, as covered in the sections +below.</p> +<p>The message attachment streams must be supplied to WSS4J for +signature/encryption via a CallbackHandler approach. An +AttachmentRequestCallback Object is used to retrieve either a particular +Attachment (on the receiving side), or all attachments (on the sending side). +The user must implement a CallbackHandler that sets a list of Attachments +matching this request on the Callback. Correspondingly, there is also a +AttachmentResponseCallback, which represents the secured/processed Attachment.</p> +<p>The good news is that if you are using Apache CXF then all of this is taken +care of automatically by a CallbackHandler that retrieves and sets CXF message +attachments. Therefore if you are using CXF then you can sign/encrypt message +attachments just by setting the configuration detailed in the next couple of +sections.</p> +<div> +<h3><a id="securing_message_attachments_via_the_action_approach"></a>Securing message attachments via the action approach</h3> +<p>With the "action" approach to using WSS4J, the user specifies the parts to +sign or encrypt via the following configuration tags:</p> +<ul> +<li>ConfigurationConstants.SIGNATURE_PARTS ("signatureParts")</li> +<li>ConfigurationConstants.ENCRYPTION_PARTS ("encryptionParts")</li></ul> +<p>The value of these tags is a String in a special format that looks something +like "{Content}{http://example.org/paymentv2}CreditCard"; +({modifier}{namespace}localname). In WSS4J 2.0.0, it is possible to +sign/encrypt all of the attachments by specifying the following as part of +signatureParts/encryptionParts: "{}cid:Attachments;". Note that this signs or +encrypts all of the attachments, it is not possible to only sign/encrypt +individual attachments.</p></div> +<div> +<h3><a id="securing_message_attachments_via_ws_securitypolicy"></a>Securing message attachments via WS-SecurityPolicy</h3> +<p>An easier way to use WSS4J is in conjunction with a web services stack such as +Apache CXF and a WS-SecurityPolicy-based policy. It is possible to sign/encrypt +all attachments by adding a "sp:Attachments" policy as a child of either a +"sp:SignedParts" or "sp:EncryptedParts" policy. In addition, the +"sp:Attachments" policy for SignedParts only has two optional child policies +called "sp13:ContentSignatureTransform" and +"sp13:AttachmentCompleteSignatureTransform", which dictate whether the +attachment headers are included or not in the Signature.</p></div></div> +<div> +<h2><a id="wss4j_special_topics"></a>WSS4J Special Topics</h2> +<p>This section discusses various topics regarding usage of WSS4J. See the <a href="using.html">Using Apache WSS4J</a> page for web stack-specific usage notes.</p> +<div> +<h3><a id="crypto_interface"></a>Crypto Interface</h3> +<p>WSS4J uses the Crypto interface to provide a pluggable way of retrieving and converting certificates, verifying trust on certificates etc. Three implementations are provided out of the box by WSS4J:</p> +<ul> +<li><a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-common/src/main/java/org/apache/wss4j/common/crypto/Merlin.java?view=markup";>Merlin</a>: The standard implementation, based around two JDK keystores for key/cert retrieval, and trust verification.</li> +<li><a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-common/src/main/java/org/apache/wss4j/common/crypto/CertificateStore.java?view=markup";>CertificateStore</a>: Holds an array of X509 Certificates. Can only be used for encryption and signature verification.</li> +<li><a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-common/src/main/java/org/apache/wss4j/common/crypto/MerlinDevice.java?view=markup";>MerlinDevice</a>: Based on Merlin, allows loading of keystores using a null InputStream - for example on a smart-card device.</li></ul> +<p>Typically, a Crypto implementation is loaded and configured via a Crypto properties file. This tells WSS4J what Crypto implementation to load, as well as implementation-specific properties such as a keystore location, password, default alias to use, etc. A typical example of the contents of a Crypto properties file for Signature creation is as <a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/resources/wss40.properties?view=markup";>follows</a>:</p> +<ul> +<li>org.apache.wss4j.crypto.provider=org.apache.wss4j.common.crypto.Merlin</li> +<li>org.apache.wss4j.crypto.merlin.keystore.type=jks</li> +<li>org.apache.wss4j.crypto.merlin.keystore.password=security</li> +<li>org.apache.wss4j.crypto.merlin.keystore.alias=wss40</li> +<li>org.apache.wss4j.crypto.merlin.keystore.file=keys/wss40.jks</li></ul> +<p>Note that in WSS4J 2.0.0 the "org.apache.ws.security.crypto" prefix used previously is now "org.apache.wss4j.crypto", however both prefixes are accepted by the code. For WSS4J 1.6.X and 1.5.X, you must use the "org.apache.ws.security.crypto" prefix.</p></div> +<div> +<h3><a id="verifying_public_keys"></a>Verifying Public Keys</h3> +<p>In WSS4J 1.5.x, trust validation of public keys involved construction of a PublicKeyCallback instance, passing it the PublicKey object, and invoking the CallbackHandler. It then called a "isVerified" method on the Callback to check to see whether the CallbackHandler had verified the PublicKey or not. The CallbackHandler implementation needed to call the "verifyTrust" method on the PublicKeyCallback, passing in a KeyStore object. This method iterates through each Certificate in the KeyStore, and checks to see whether the PublicKeys match.</p> +<p>In WSS4J 1.6.x, trust validation of public keys was moved from a WSS4J 1.5’s PublicKeyCallback instance to the Crypto interface, where the argument is now a PublicKey object. In this way, validation is done using the same interface as for trust validation for Certificates, and the end-user has no need to consider the special-case of verifying public keys in the CallbackHandler, as it is taken care of internally by WSS4J.</p></div> +<div> +<h3><a id="introducing_validators"></a>Introducing Validators</h3> +<p>WSS4J 1.6 introduces the concept of a Validator, for validating credentials that have been processed by a Processor instance.</p> +<p>An inbound security header is processed by WSS4J by iterating through each child element of the header, and by calling the appropriate Processor implementation to deal with each element. In WSS4J 1.5.x, some processors perform validation on the received token (e.g. UsernameTokens), whereas others store the processing results for later verification by third-party WS-Handler implementations (e.g. Timestamp verification, Certificate trust verification). There are some problems with this approach:</p> +<ul> +<li>It is not consistent, some processors perform validation, others do not.</li> +<li>There is a potential security hole, in that it is assumed third-party code will know to validate the credentials that the WSS4J processors do not validate.</li> +<li>WSS4J will continue to process the rest of the security header even if the Timestamp is invalid, or the certificate non-trusted, which could lead to denial-of-service attacks.</li> +<li>There is no separation of concerns between processing the token and validating the token. If you want to change how the token is validated, you must replace the processor instance.</li></ul> +<p>WSS4J 1.6 has moved Timestamp verification and certificate trust validation back into the processing of the security header, thus solving the first three points above. The fourth point is met by the new concept of Validators, as well as some changes to the way Processors and CallbackHandler implementations are used in WSS4J 1.6.</p> +<p>In WSS4J 1.5.x, CallbackHandler implementations are used in different ways by different processors, sometimes they are expected to verify a password (as for processing UsernameTokens), and other times they are expected to supply a password (as for decryption). In WSS4J 1.6, CallbackHandler implementations are only expected to supply a password (if it exists) to the processors. The Processor implementations do not perform any validation of the security token, instead they package up the processed token, along with any (password) information extracted from the CallbackHandler, and hand it off to a Validator implementation for Validation.</p> +<p>The Processor implementations get the specific Validator implementation to use via the RequestData parameter, which in turn asks a WSSConfig object for the Validator implementation. If the Validator is null, then no Validation is performed on the received token. The Processor then stores the received token as normal. WSS4J 1.6 comes with several default Validators, which are:</p> +<ul> +<li>NoOpValidator: Does no processing of the credential</li> +<li>TimestampValidator: Validates a Timestamp</li> +<li>UsernameTokenValidator: Validates a UsernameToken</li> +<li>SignatureTrustValidator: Verifies trust in a signature</li> +<li>SamlAssertionValidator: Checks some HOK requirements on a SAML Assertion, and verifies trust on the (enveloped) signature.</li></ul> +<p>There are some additional WSSecurityEngineResult constants that pertain to the Validator implementations:</p> +<ul> +<li>TAG_VALIDATED_TOKEN: Indicates that the token corresponding to this result has been validated by a Validator implementation. Some of the processors do not have a default Validator implementation.</li> +<li>TAG_TRANSFORMED_TOKEN: A Validator implementation may transform a credential (into a SAML Assertion) as a result of Validation. This tag holds a reference to an AssertionWrapper instance, that represents a transformed version of the validated credential.</li></ul> +<p>To validate an inbound UsernameToken in some custom way, simply associate the NoOpValidator with the UsernameToken QName in the WSSConfig of the RequestData object used to supply context information to the processors. After WSS4J has finished processing the security header, then extract the WSSecurityEngineResult instance corresponding to the WSConstants.UT action, and perform some custom validation on the token.</p> +<p>To validate plaintext passwords against a directory store, rather than have the CallbackHandler set the password: Simply @Override the verifyPlaintextPassword(UsernameToken usernameToken) method in the validator. By simply plugging in a validator on the UsernameTokenProcessor (such as the NoOpValidator), it is possible to do any kind of custom validation (or none at all) on the token.</p> +<p>An example of how to add a custom Validator implementation is the STSTokenValidator in CXF. The <a href="https://github.com/apache/cxf/blob/master/rt/ws/security/src/main/java/org/apache/cxf/ws/security/trust/STSTokenValidator.java";>STSTokenValidator</a> tries to validate a received SAML Assertion locally, and if that fails, it dispatches it to a Security Token Service (STS) via the WS-Trust interface for validation. It also supports validating a UsernameToken and BinarySecurityToken in the same manner. The <a href="https://github.com/apache/cxf/blob/master/rt/ws/security/src/main/java/org/apache/cxf/ws/security/SecurityConstants.java";>SecurityConstants</a> class defines some configuration tags for specifying a custom validator for inbound SAML1, SAML2, UsernameToken, BinarySecurityToken, Signature and Timestamps. The STSTokenValidator can be configured by associating it with the appropriate configuration tag.</p></div> +<div> +<h3><a id="specifying_elements_to_sign_or_encrypt"></a>Specifying elements to sign or encrypt</h3> +<p>The signature and encryption creation code in WSS4J uses the WSEncryptionPart class to find DOM elements to sign and encrypt. There are a number of minor changes to how elements are located from a WSEncryptionPart in WSS4J 1.6:</p> +<ol style="list-style-type: decimal;"> +<li>WSEncryptionPart now stores an optional DOM element, which will be used as the element to sign/encrypt if it is non-null.</li> +<li>Failing this, it finds the SOAP body and compares the wsu:Id with the stored Id, or if there is no stored Id in WSEncryptionPart, it checks the stored localname/namespace.</li> +<li>Failing this, if the stored Id in WSEncryptionPart is not null, it tries to find the first element in the SOAP envelope that has a matching wsu:Id.</li> +<li>If the stored Id is null, it tries to find <strong>all</strong> DOM Elements that match the stored localname/namespace.</li></ol> +<p>WSEncryptionPart is intended to refer to a single Element for encryption/signature. However, as a localname/namespace is not necessarily unique, point 4 will return all matching Elements. An important implication of the order of the steps given above, is that client code should set the DOM element on the WSEncryptionPart if it is accessible, and if not, it should set the wsu:Id. Otherwise, a localname/namespace (which is not referring to the SOAP Body) will result in a traversal of the DOM tree.</p> +<p>The DOM element(s) that is(are) found are stored for retrieval, so that we don’t need to traverse the SOAP envelope multiple times, when e.g. doing an STR Transform, or for element location in the XML Security code.</p></div> +<div> +<h3><a id="wspasswordcallback_identifiers"></a>WSPasswordCallback identifiers</h3> +<p>The hhttps://github.com/apache/ws-wss4j/tree/master/ws-security-common/src/main/java/org/apache/wss4j/common/ext/WSPasswordCallback.java?view=markup[WSPasswordCallback class] defines a set of integers which correspond to usage instructions for the CallbackHandler. In WSS4J 1.6, the following WSPasswordCallback identifiers are used:</p> +<ul> +<li>WSPasswordCallback.DECRYPT - DECRYPT usage is used when the calling code needs a password to get the private key of this identifier (alias) from a keystore. This is only used for the inbound case of decrypting a session (symmetric) key, and not for the case of getting a private key to sign the message. The CallbackHandler must set the password via the setPassword(String) method.</li> +<li>WSPasswordCallback.USERNAME_TOKEN - USERNAME_TOKEN usage is used to obtain a password for either creating a Username Token (whether plaintext or digest), or for validating it. It is also used for the case of deriving a key from a Username Token. The CallbackHandler must set the password via the setPassword(String) method.</li> +<li>WSPasswordCallback.SIGNATURE - SIGNATURE usage is used on the outbound side only, to get a password to get the private key of this identifier (alias) from a keystore. The CallbackHandler must set the password via the setPassword(String) method.</li> +<li>WSPasswordCallback.SECURITY_CONTEXT_TOKEN - SECURITY_CONTEXT_TOKEN usage is for the case of when we want the CallbackHandler to supply the key associated with a SecurityContextToken. The CallbackHandler must set the key via the setKey(byte[]) method.</li> +<li>WSPasswordCallback.CUSTOM_TOKEN - CUSTOM_TOKEN usage is used for the case that we want the CallbackHandler to supply a token as a DOM Element. For example, this is used for the case of a reference to a SAML Assertion or Security Context Token that is not in the message. The CallbackHandler must set the token via the setCustomToken(Element) method.</li> +<li>WSPasswordCallback.SECRET_KEY - SECRET_KEY usage is used for the case that we want to obtain a secret key for encryption or signature on the outbound side, or for decryption or verification on the inbound side. The CallbackHandler must set the key via the setKey(byte[]) method.</li></ul> +<p>In WSS4J 2.0, the following additional WSPasswordCallback identifier is:</p> +<ul> +<li>WSPasswordCallback.PASSWORD_ENCRYPTOR_PASSWORD - PASSWORD_ENCRYPTOR_PASSWORD usage is used to return the password used with a PasswordEncryptor implementation to decrypt encrypted passwords stored in Crypto properties files</li></ul></div> +<div> +<h3><a id="usernametoken_handling_in_wss4j_1_6"></a>UsernameToken handling in WSS4J 1.6</h3> +<p>The CallbackHandler interface receives and requires the following information when handling UsernameTokens:</p> +<ul> +<li>For both digest and plaintext cases, the CallbackHandler is given the username, password type and an identifier of WSPasswordCallback.USERNAME_TOKEN. It must set the password on the callback, and the validator does the comparison.</li> +<li>The custom password type case defaults to the same behaviour as the plaintext case, assuming wssConfig.getHandleCustomPasswordTypes() returns true.</li> +<li>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.</li></ul></div> +<div> +<h3><a id="support_for_saml2_assertions_in_wss4j_1_6"></a>Support for SAML2 assertions in WSS4J 1.6</h3> +<p>Support for SAML2 assertions has finally arrived in WSS4J, via the forthcoming 1.6 release. This has been a <a href="http://issues.apache.org/jira/browse/WSS-146";>long-standing</a> feature request. WSS4J 1.5.x only supports SAML 1.1 assertions via the deprecated <a href="https://spaces.internet2.edu/display/OpenSAML/OS1Status";>Opensaml1</a>, and it supports them in a very limited manner, namely:</p> +<ul> +<li>It only supports the creation of Authentication statements.</li> +<li>Processing essentially involves saving the assertions, it did not support validating enveloped signatures, or trust on the signatures, etc.</li></ul> +<p>Several patches were submitted to <a href="http://issues.apache.org/jira/browse/WSS-146";>WSS-146</a> to upgrade WSS4J to use Opensaml2. SAML2 support in WSS4J 1.6 consists of:</p> +<ul> +<li>Support for creating signed/unsigned SAML 1.1/2.0 assertions, containing authentication, authorization, attribute statements etc.</li> +<li>This extensibility is achieved by letting the user implement a CallbackHandler instance.</li> +<li>The SAMLTokenProcessor can now process any type of assertion, verify an enveloped signature on it, and verify trust on the signature. It also verifies some holder-of-key requirements, e.g. that the Subject contains a KeyInfo element, and that the assertion is signed and trusted etc.</li></ul> +<p>WSS4J 1.6 contains an <a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/saml/";>extensive set of tests</a> for both creating and processing different type of assertions. To illustrate the flexibility and simplicity of the CallbackHandler approach for constructing assertions, take a look at an abstract CallbackHandler <a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/common/AbstractSAMLCallbackHandler.java?view=markup";>here</a>, as well as the concrete implementations (<a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/common/SAML1CallbackHandler.java?view=markup";>SAML 1.1</a> and <a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/common/SAML2CallbackHandler.java?view=markup";>SAML 2</a>). As you can see, a fairly small amount of code can create a large variety of assertions.</p> +<p>Opensaml2 has a very large set of dependencies, but through some judicious pom exclusions, as well replacing the Opensaml DefaultBootstrap code to avoid loading velocity, the following dependencies are introduced in WSS4J via Opensaml (snippet from mvn dependency):</p><div class="source"><pre class="prettyprint"><code>+- org.opensaml:opensaml:jar:2.4.1:compile + | \- org.opensaml:openws:jar:1.4.1:compile + | \- org.opensaml:xmltooling:jar:1.3.1:compile + | +- org.slf4j:slf4j-api:jar:1.6.1:compile + | \- joda-time:joda-time:jar:1.6.2:compile</code></pre></div> +<p>The Opensaml2 port has a large impact on existing code for <strong>creating</strong> assertions, however it is thought that very few people used that code. It has a minimal impact on existing code for processing assertions, with several caveats:</p> +<ul> +<li>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</li> +<li>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 <strong>do</strong> have an enveloped signature are saved as a "WSConstants.ST_SIGNED" action.</li> +<li>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.</li></ul></div> +<div> +<h3><a id="jsr_105_support"></a>JSR-105 support</h3> +<p>WSS4J 1.6 has been ported to use the <a href="http://jcp.org/en/jsr/detail?id=105";>JSR 105</a> API for XML Digital Signature. Previously, WSS4J 1.5.x used the custom API of the Apache <a href="http://santuario.apache.org/";>Santuario</a> XML Security for Java library to create and process XML Digital Signatures.</p> +<p>WSS4J 1.6 has a minimum requirement of JDK 1.5 (note that WSS4J 1.5.x supports JDK 1.4). As JDK 1.5 does not contain an implementation of JSR 105, this means that XML Digital Signature is done via the JSR 105 implementation of Apache Santuario. However, when JDK 1.6+ is used, WSS4J 1.6 uses the JDK implementation of JSR 105 for signature creation and verification. You can override this by endorsing the Santuario jar.</p> +<p>The Apache Santuario XML Security jar is still required for the JDK 1.6 case, as there are compile-time dependencies in WSS4J for encryption/decryption, as well as for some algorithm parsing, and resource resolver stuff. One downside to the Santuario jar, is its dependence on Xalan for a small subset of operations. This dependency is <a href="https://issues.apache.org/jira/browse/SANTUARIO-252";>removed</a> for the 1.5 release of that library.</p> +<p>It is worth noting some changes to the main <a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/main/java/org/apache/wss4j/dom/message/WSSecSignature.java?view=markup";>class</a> used in WSS4J for signature creation as a result of the JSR-105 port. In WSS4J 1.5.x, after the signature certs and list of references to sign had been configured, the "computeSignature" method was called to compute the signature. The DOM element corresponding to the signature was independent of the pre-existing security header, and could be extracted later and inserted into the security header.</p> +<p>In WSS4J 1.6, you must tell "computeSignature" where to insert the signature element. A boolean "prepend" argument allows you to configure whether to prepend the generated Signature element to the security header, or whether to append it. If prepend is true, then an optional siblingElement argument can be used to prepend the signature element before this sibling element. Once computeSignature has been called, you have no control over where the signature element is inserted into the security header.</p></div> +<div> +<h3><a id="basic_security_profile_1_1_compliance"></a>Basic Security Profile 1.1 compliance</h3> +<p>The Basic Security Profile (BSP) 1.1 <a href="http://www.ws-i.org/Profiles/BasicSecurityProfile-1.1.html";>specification</a> provides an industry-standard way of making sure that different WS-Security stacks can communicate with each other, by clarifying and narrowing the scope of the various WS-Security standards. WSS4J 1.5.x does not implement the BSP in any meaningful way. The <a href="https://github.com/apache/ws-wss4j/tree/1_5_x-fixes/src/org/apache/ws/security/WSSConfig.java?view=markup";>WSSConfig</a> class supports a "isWsiBSPCompliant" method (default is false), which will enable the generation of an InclusivePrefix list for signature generation, something that is mandated by the BSP spec.</p> +<p>WSS4J 1.6 provides <a href="https://issues.apache.org/jira/browse/WSS-256";>support</a> for the BSP 1.1 specification, in so far as it pertains to the core WS-Security specifications that WSS4J supports. The enforcing of BSP compliance for inbound messages is controlled by the WSSConfig class, as per WSS4J 1.5.x. An important change is that BSP compliance is now turned <strong>on</strong> by default. In addition, a new <a href="https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/main/java/org/apache/wss4j/dom/handler/WSHandlerConstants.java?view=markup";>WSHandlerConstants</a> configuration parameter has been added so that BSP compliance can be controlled via a WSHandler implementation.</p></div></div> +<div> +<h2><a id="security_best_practices"></a>Security Best Practices</h2> +<p>This section describes a number of steps which should be taken to ensure that security best +practices are followed and enforced.</p> +<div> +<h3><a id="upgrade_to_wss4j_2_3_x_or_2_2_x"></a>Upgrade to WSS4J 2.3.x or 2.2.x</h3> +<p>The 1.5.x and 1.6.x series of releases of WSS4J are deprecated. You should switch to +either 2.3.x or the latest 2.2.x release as a matter of priority, as these +branches contain up to date security fixes.</p></div> +<div> +<h3><a id="upgrade_to_the_latest_minor_release_as_soon_as_possible"></a>Upgrade to the latest minor release as soon as possible</h3> +<p>You should always upgrade to the latest minor release in a timely manner, in order to pick up +security fixes.</p></div> +<div> +<h3><a id="use_ws_securitypolicy_to_enforce_security_requirements"></a>Use WS-SecurityPolicy to enforce security requirements</h3> +<p>WSS4J can be used with a web services stack such as Apache CXF or Apache Axis in one of two +ways: either by specifying security actions directly, or via WS-SecurityPolicy. +WS-SecurityPolicy is a much richer way of specifying security constraints when processing +messages, and gives you more <strong>automatic</strong> protection against various attacks then when +configuring via security actions. See for example, this blog +<a href="http://coheigea.blogspot.ie/2012/10/xml-signature-wrapping-attacks-on-web.html";>post</a> +on XML signature wrapping attacks. Therefore, you should always try to use WSS4J with a +WS-SecurityPolicy requirement.</p></div> +<div> +<h3><a id="use_rsa_oaep_for_the_key_transport_algorithm"></a>Use RSA-OAEP for the Key Transport Algorithm</h3> +<p>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, and enforce this decision. For WS-SecurityPolicy, +this means to avoid using any AlgorithmSuite that ends with "Rsa15" (e.g. +"Basic128Rsa15").</p> +<p>For the "Action" based approach, there are different ways of enforcing that +RSA v1.5 cannot be used for key transport depending on the version of WSS4J. +From WSS4J 2.0.0, it is not allowed by default and no action is required. If you +wish to allow it, then you must set the +WSHandlerConstants.ALLOW_RSA15_KEY_TRANSPORT_ALGORITHM property to "true". For +WSS4J 1.6.x, the RSA v1.5 key transport algorithm is allowed by default. In +this case, you should explicitly configure WSHandlerConstants.ENC_KEY_TRANSPORT +("encryptionKeyTransportAlgorithm") to be +"http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p";. This latter point requires +the web services stack to set this property on the Request (it is known that +Apache CXF does this).</p></div> +<div> +<h3><a id="avoid_using_a_cbc_symmetric_encryption_algorithm"></a>Avoid using a cbc Symmetric Encryption Algorithm</h3> +<p>There are some attacks that exploit the "cbc" mode of a Symmetric Encryption Algorithm. +WSS4J has support for "gcm" mode algorithms as well. This can be specified via +WSHandlerConstants.ENC_SYM_ALGO ("encryptionSymAlgorithm"), for example to +"http://www.w3.org/2009/xmlenc11#aes128-gcm";.</p></div> +<div> +<h3><a id="use_subject_dn_regular_expressions_with_chain_trust"></a>Use Subject DN regular expressions with chain trust</h3> +<p>WSS4J 1.6.7 introduced the ability to specify regular expressions on the Subject DN of a +certificate used for signature validation. It is important to add this constraint when you +are supporting "chain trust", which is where you are establishing trust in a certificate +based on the fact that the Issuer of the certificate is in your trust store. Otherwise, any +certificate of this issuer will pass trust validation. See +<a href="http://coheigea.blogspot.ie/2012/08/subject-dn-certificate-constraint.html";>here</a> +for more information.</p></div> +<div> +<h3><a id="specify_signature_algorithm_on_receiving_side"></a>Specify signature algorithm on receiving side</h3> +<p>When not using WS-SecurityPolicy (see point above about favouring the WS-SecurityPolicy +approach), you should specify a signature algorithm to use on the receiving side. This +can be done via WSHandlerConstants.SIG_ALGO ("signatureAlgorithm"). Setting this property +to (e.g.) "http://www.w3.org/2000/09/xmldsig#rsa-sha1"; will ensure that the signature +algorithm allowed is RSA-SHA1 and not (e.g.) HMAC-SHA1. This latter point requires the +web services stack to set this property on the Request (it is known that Apache CXF does +this). See also the previous point about setting the key encryption transport algorithm.</p></div></div> +<div> +<h2><a id="further_resources"></a>Further Resources</h2> +<p>This section lists some further resources that describe how to use WSS4J in more +detail.</p> +<div> +<h3><a id="wss4j_2_0_0_articles"></a>WSS4J 2.0.0 articles</h3> +<ul> +<li><a href="http://coheigea.blogspot.ie/2014/01/apache-wss4j-200-part-i.html";>WSS4J 2.0.0 overview</a></li></ul></div> +<div> +<h3><a id="wss4j_1_6_x_articles"></a>WSS4J 1.6.x articles</h3> +<ul> +<li><a href="http://coheigea.blogspot.ie/2011/01/wss4j-16-crypto-property-change.html";>Crypto property changes in WSS4J 1.6.x</a></li> +<li><a href="http://coheigea.blogspot.ie/2011/02/support-for-saml2-assertions-in-wss4j.html";>Support for SAML 2.0 in WSS4J 1.6.x</a></li> +<li><a href="http://coheigea.blogspot.ie/2011/02/usernametoken-processing-changes-in.html";>UsernameToken processing changes in WSS4J 1.6.x</a></li> +<li><a href="http://coheigea.blogspot.ie/2011/02/wspasswordcallback-changes-in-wss4j-16.html";>WSPasswordCallback changes in WSS4J 1.6.x</a></li> +<li><a href="http://coheigea.blogspot.ie/2011/02/wss4j-16-specifying-elements-to-sign-or.html";>Specifying elements to sign or encrypt</a></li> +<li><a href="http://coheigea.blogspot.ie/2011/03/wss4j-16-basic-security-profile-11.html";>Basic Security Profile 1.1 compliance</a></li> +<li><a href="http://coheigea.blogspot.ie/2011/03/wss4j-16-saml-property-changes.html";>SAML property changes</a></li> +<li><a href="http://coheigea.blogspot.ie/2011/04/wss4j-16-introducing-validators.html";>WSS4J Validators</a></li> +<li><a href="http://coheigea.blogspot.ie/2011/05/crl-support-in-wss4j-161.html";>CRL support in WSS4J 1.6.1</a></li> +<li><a href="http://coheigea.blogspot.ie/2011/08/saml-token-creation-in-apache-wss4j-16.html";>Creating SAML Tokens</a></li> +<li><a href="http://coheigea.blogspot.ie/2013/03/signature-and-encryption-key.html";>Signature and Encryption Key Identifiers in Apache WSS4J</a></li></ul></div></div> </main> + </div> + </div> + <hr/> + <footer> + <div class="container-fluid"> + <div class="row-fluid"> +Apache WSS4J, WSS4J, Apache, the Apache feather logo are trademarks of The Apache Software Foundation. + All other marks mentioned may be trademarks or registered trademarks of their respective owners. + </div> + </div> + </footer> + </body> +</html>
![http://activemq.apache.org/images/asf-logo.png"](http://activemq.apache.org/images/asf-logo.png"){kind=link}