You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ws.apache.org by co...@apache.org on 2014/02/07 12:52:14 UTC
svn commit: r1565626 [3/4] - in /webservices/website/wss4j: ./ css/ images/
images/logos/
Added: webservices/website/wss4j/package.html
URL: http://svn.apache.org/viewvc/webservices/website/wss4j/package.html?rev=1565626&view=auto
==============================================================================
--- webservices/website/wss4j/package.html (added)
+++ webservices/website/wss4j/package.html Fri Feb 7 11:52:13 2014
@@ -0,0 +1,918 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!-- Generated by Apache Maven Doxia Site Renderer 1.4 at 2014-02-07 -->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <title>Apache WSS4J - </title>
+ <style type="text/css" media="all">
+ @import url("./css/maven-base.css");
+ @import url("./css/maven-theme.css");
+ @import url("./css/site.css");
+ </style>
+ <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
+ <meta name="Date-Revision-yyyymmdd" content="20140207" />
+ <meta http-equiv="Content-Language" content="en" />
+
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="./" id="bannerLeft">
+ Apache WSS4J
+ </a>
+ <a href="http://www.apache.org" id="bannerRight">
+ <img src="http://activemq.apache.org/images/asf-logo.png" alt="$alt" />
+ </a>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+ <div class="xleft">
+ <span id="publishDate">Last Published: 2014-02-07</span>
+ | <span id="projectVersion">Version: 2.0.0-SNAPSHOT</span>
+ </div>
+ <div class="xright">
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+
+ <h5>Apache WSS4J</h5>
+ <ul>
+ <li class="none">
+ <a href="index.html" title="Home">Home</a>
+ </li>
+ <li class="none">
+ <a href="download.html" title="Download">Download</a>
+ </li>
+ <li class="none">
+ <a href="using.html" title="Using WSS4J">Using WSS4J</a>
+ </li>
+ <li class="none">
+ <a href="config.html" title="WSS4J Configuration">WSS4J Configuration</a>
+ </li>
+ <li class="none">
+ <a href="migration.html" title="WSS4J 2.0.0 Migration Guide">WSS4J 2.0.0 Migration Guide</a>
+ </li>
+ <li class="none">
+ <a href="topics.html" title="Special Topics">Special Topics</a>
+ </li>
+ <li class="none">
+ <a href="best_practice.html" title="Security Best Practices">Security Best Practices</a>
+ </li>
+ <li class="none">
+ <a href="wss4j16.html" title="WSS4J 1.6 Release Notes">WSS4J 1.6 Release Notes</a>
+ </li>
+ </ul>
+ <h5>Project Documentation</h5>
+ <ul>
+ <li class="collapsed">
+ <a href="project-info.html" title="Project Information">Project Information</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
+ </a>
+
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+
+
+<div class="section">
+<h2>Axis1 Deployment Tutorial<a name="Axis1_Deployment_Tutorial"></a></h2>
+
+<p>
+WSS4J 1.5.x Axis handlers process SOAP requests according to the OASIS Web Service
+Security (WSS) specifications.
+</p>
+<p></p>
+<p>
+The WSS4J Axis handlers <tt>WSDoAllSender</tt> and <tt>WSDoAllReceiver
+</tt> control the creation and consumption of secure SOAP requests.
+The handlers work behind the scenes and are usually transparent to Web Service
+(WS) applications. The Axis deployment descriptor files (*.wsdd) may contain all
+necessary information to control the security processing.
+</p>
+<p></p>
+<p>
+A WS application may also set properties to control the handlers
+and provide default values. If the deployment descriptor sets the same
+property (parameter) then the deployment descriptor overwrites the application
+defined property. Thus, deployment settings overwrite application settings
+to fulfill site specific requirements.
+
+</p></div>
+
+<div class="section">
+<h2>Prerequisites<a name="Prerequisites"></a></h2>
+<p>
+The WS Security Axis handlers use the WSS4J classes (Web Service Security
+for Java) to process the SOAP messages. WSS4J in turn uses the Apache XML Security
+project to handle XML Security according to XML Signature and XML Encryption.
+
+</p>
+<ul>
+
+<li><a class="externalLink" href="http://ws.apache.org/wss4j/index.html">WSS4J</a></li>
+
+<li><a class="externalLink" href="http://xml.apache.org/security/index.html">XML Security</a></li>
+</ul>
+
+The WSS4J Axis handlers require Axis V1.2 because of some problems in previous
+Axis versions. WSS4J CVS contains the latest Axis libraries.
+
+</div>
+<div class="section">
+<h2>Related Documentation<a name="Related_Documentation"></a></h2>
+<p>
+The OASIS WSS specifications define a number of features and it is possible
+to combine them in several ways. The WSS4J Axis handlers already support
+a large number of WSS features and their combinations.
+<a class="externalLink" href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss">
+Here</a> are the WSS specifications.
+
+</p></div>
+<div class="section">
+<h2>The basics - a simple example that uses<a name="The_basics_-_a_simple_example_that_uses"></a></h2>
+<p>
+This chapter gives an overview and some examples how to deploy
+the WSS4J Axis handlers and how the parameters and their values control the
+handlers. For a better understanding of this chapter the reader shall
+have a knowledge of the OASIS WSS specifications.
+</p>
+<p></p>
+<p>
+The {@link org.apache.ws.security.handler.WSHandlerConstants},
+{@link org.apache.ws.axis.security.WSDoAllSender}, and
+{@link org.apache.ws.axis.security.WSDoAllReceiver}
+provide additional and detailed documentation.
+
+</p>
+<div class="section">
+<h3>Axis deployment descriptor to insert a<a name="Axis_deployment_descriptor_to_insert_a"></a></h3>
+<p>
+The following snippet shows a general layout how to deploy a WS Axis handler
+on the client (application) side.
+</p>
+<div class="source">
+<pre>
+ <!-- define the service, use the WSDoAllSender security handler in request flow -->
+ <service name="Ping1">
+ <requestFlow>
+ <handler type="java:org.apache.ws.axis.security.WSDoAllSender" >
+ <parameter name="action" value="UsernameToken"/>
+ <parameter name="user" value="werner"/>
+ <parameter name="passwordType" value="PasswordText" />
+ <parameter name="passwordCallbackClass"
+ value="org.apache.ws.axis.oasis.PWCallback1Out"/>
+ </handler>
+ </requestFlow>
+ </service>
+</pre></div>
+
+This is the standard way to deploy an Axis handler. Axis parses the deployment
+descriptor and provides the parameters and their value to the handler. Each
+service can have its own request and response flow definition, which provides
+a very flexible set-up of the security parameters.
+
+<p></p>
+<p>
+The above setup inserts the most simple security structure into a SOAP request:
+the simple <tt>UsernameToken</tt>. This token includes a username and the
+according password. Both fields are sent in cleartext, thus it provides no
+real security.
+</p>
+<p></p>
+<p>
+
+The parameters and their meanings are:
+</p>
+<ul>
+
+<li><tt>action</tt> defines the security action. The value <tt>
+ UsernameToken</tt> directs the handler to insert this token into
+ the SOAP request.
+</li>
+
+<li><tt>user</tt> specifies the username to include in the token.
+</li>
+
+<li><tt>passwordType</tt> is a pecific parameter for the <tt>
+ UsernameToken</tt> action and defines the encoding of the passowrd.
+ <tt>PasswordText</tt> specifies to send the password in
+ plain text, <tt>PasswordDigest</tt> specifies to send the
+ password in digest mode (refer to WSS UsernameToken Profile)
+</li>
+
+<li><tt>passwordCallbackClass</tt> contains the name of a class that
+ implements a method to get the user's password. Please refer to the
+ detailed documentation in
+ {@link org.apache.ws.security.handler.WSHandlerConstants#PW_CALLBACK_CLASS}.
+ </li>
+</ul>
+The WSS4J Axis security handler interprets the parameter values and controls
+the WSS4J modules to generate the following SOAP request:
+
+<div class="source">
+<pre>
+<?xml version="1.0" encoding="UTF-8"?>
+<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+ <soapenv:Header>
+ <wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
+ soapenv:mustUnderstand="true">
+ <wsse:UsernameToken>
+ <wsse:Username>werner</wsse:Username>
+ <wsse:Password Type="wsse:PasswordText">security</wsse:Password>
+ </wsse:UsernameToken>
+ </wsse:Security>
+ </soapenv:Header>
+ <soapenv:Body>
+ <Ping xmlns="http://xmlsoap.org/Ping">
+ <text>Scenario 1 text</text>
+ <ticket xmlns:ns1="http://xmlsoap.org/Ping"
+ xsi:type="ns1:ticketType">scenario1</ticket>
+ </Ping>
+ </soapenv:Body>
+</soapenv:Envelope>
+</pre></div>
+This is a pretty print of the real SOAP message.
+
+</div>
+<div class="section">
+<h3>The password callback class<a name="The_password_callback_class"></a></h3>
+<p>
+
+The deployment descriptor contains the user name that the handler inserts into
+the <tt>UsernameToken</tt> but not the password. In general it is not a
+good idea to store sensitive information like a password in cleartext. To
+get the password the WSS4J Axis handler uses a password callback
+technique similar to the JAAS mechansim. The parameter
+<tt>passwordCallbackClass</tt> contains the classname of the callback
+class. This class must implement the
+{@link javax.security.auth.callback.CallbackHandler}
+interface. The WSS4J Axis handler gets this class,
+instantiates it, and calls the <tt>handle</tt> method when it
+needs a password. Refer also to the
+{@link org.apache.ws.security.handler.WSHandlerConstants#PW_CALLBACK_CLASS
+ parameter} documentation.
+ </p>
+<p></p>
+<p>
+ The following code snippet shows a simple password callback class:
+ </p>
+<div class="source">
+<pre>
+package org.apache.ws.axis.oasis;
+
+import java.io.IOException;
+
+import javax.security.auth.callback.Callback;
+import javax.security.auth.callback.CallbackHandler;
+import javax.security.auth.callback.UnsupportedCallbackException;
+
+import org.apache.ws.security.WSPasswordCallback;
+
+public class PWCallback implements CallbackHandler {
+
+ private static final byte[] key = {
+ (byte)0x31, (byte)0xfd, (byte)0xcb, (byte)0xda,
+ (byte)0xfb, (byte)0xcd, (byte)0x6b, (byte)0xa8,
+ (byte)0xe6, (byte)0x19, (byte)0xa7, (byte)0xbf,
+ (byte)0x51, (byte)0xf7, (byte)0xc7, (byte)0x3e,
+ (byte)0x80, (byte)0xae, (byte)0x98, (byte)0x51,
+ (byte)0xc8, (byte)0x51, (byte)0x34, (byte)0x04,
+ };
+
+ public void handle(Callback[] callbacks)
+ throws IOException, UnsupportedCallbackException {
+ for (int i = 0; i < callbacks.length; i++) {
+ if (callbacks[i] instanceof WSPasswordCallback) {
+ WSPasswordCallback pc = (WSPasswordCallback) callbacks[i];
+ /*
+ * here call a function/method to lookup the password for
+ * the given identifier (e.g. a user name or keystore alias)
+ * e.g.: pc.setPassword(passStore.getPassword(pc.getIdentfifier))
+ * for testing we supply a fixed name/fixed key here.
+ */
+ if (pc.getUsage() == WSPasswordCallback.KEY_NAME) {
+ pc.setKey(key);
+ }
+ else {
+ pc.setPassword("security");
+ }
+ } else {
+ throw new UnsupportedCallbackException(
+ callbacks[i], "Unrecognized Callback");
+ }
+ }
+ }
+}
+</pre></div>
+The Java {@link javax.security.auth.callback.CallbackHandler callback} handler
+documentation provides a detailed description of the interface and exceptions.
+
+<p></p>
+<p>
+The WSS4J library uses a specific class to get the required password or key
+informations. The <tt>WSSPasswordCallback</tt> class implements the
+{@link javax.security.auth.callback.Callback} interface according to the
+JAAS. Depending on it usage this class either carries the required password
+as a Java <tt>String </tt> or it carries the required key information
+as a Java <tt>byte[]</tt> array. Refer to
+{@link org.apache.ws.security.WSPasswordCallback} that contains a
+detailed description of the usage codes.
+</p>
+<p></p>
+<p>
+The WSS4J Axis handler or the WSS4J modules set the usage code before
+they call <tt>handle</tt> method.
+
+</p></div>
+<div class="section">
+<h3>Application sets parameters to insert in<a name="Application_sets_parameters_to_insert_in"></a></h3>
+<p>
+
+Sometimes it is not feasable or not possible to determine parameters
+and their values during deployment. In this case the application can
+set paramters during runtime. The WSS4J Axis handlers use the Axis
+<tt>setProperty</tt> method to support this feature.
+</p>
+<p></p>
+<p>
+The following code snippet shows an example how to use the dynamic setting
+of parameters and their values:
+</p>
+<div class="source">
+<pre>
+ ...
+ Service service = new Service();
+ Call call = (Call) service.createCall();
+ ...
+ call.setProperty(UsernameToken.PASSWORD_TYPE, WSConstants.PASSWORD_TEXT);
+ call.setProperty(WSHandlerConstants.USER, "werner");
+ ...
+</pre></div>
+Use this way if your application dynamically creates a <tt>call</tt>
+object. If your application uses stubs generated by Axis' <tt>WSDL2Java
+</tt> tool, the application uses the following functions:
+
+<div class="source">
+<pre>
+ ...
+ PingServiceLocator service = new PingServiceLocator();
+ ...
+ PingPort port = (PingPort) service.getPing1();
+ port._setProperty(UsernameToken.PASSWORD_TYPE, WSConstants.PASSWORD_TEXT);
+ port._setProperty(WSHandlerConstants.USER, "werner");
+ ...
+</pre></div>
+Please note that <tt>_setProperty</tt> is a Axis specific call.
+
+</div>
+<div class="section">
+<h3>The password callback object reference<a name="The_password_callback_object_reference"></a></h3>
+<p>
+
+In addition to the <a href="#pwCallBackClass">password callback class</a>
+an application may set a password callback object using the <tt>
+ setProperty()</tt> methods. Only applications (and Axis handlers that
+ preceed the WSS4J Axis handlers in a handler chain) can use this feature.
+ </p>
+<p></p>
+<p>
+ For example:
+ </p>
+<div class="source">
+<pre>
+public class Scenario1 implements CallbackHandler {
+
+ public static void main(String args[]) {
+ ...
+ PingServiceLocator service = new PingServiceLocator();
+ ...
+ PingPort port = (PingPort) service.getPing1();
+ ((org.apache.axis.client.Stub)port)._setProperty(UsernameToken.PASSWORD_TYPE, WSConstants.PASSWORD_TEXT);
+ ((org.apache.axis.client.Stub)port._setProperty(WSHandlerConstants.USER, "werner");
+ ((org.apache.axis.client.Stub)port._setProperty(WSHandlerConstants.PW_CALLBACK_REF, this);
+ ...
+ }
+
+ public void handle(Callback[] callbacks) {
+ ...
+ }
+}
+</pre></div>
+
+</div>
+<div class="section">
+<h3>Deployment of the WSS4J Axis handler<a name="Deployment_of_the_WSS4J_Axis__handler"></a></h3>
+<p>
+
+Similar to the deployment descriptor of the sending handler <tt>WSDoAllSender
+</tt> a deployment descriptor for the receiving handler exists. For the above
+example the deployment descriptor look like:
+</p>
+<div class="source">
+<pre>
+ <requestFlow>
+ <handler type="java:org.apache.ws.axis.security.WSDoAllReceiver">
+ <parameter name="passwordCallbackClass"
+ value="org.apache.ws.axis.oasis.PWCallback"/>
+ <parameter name="action" value="UsernameToken"/>
+ </handler>
+ </requestFlow>
+</pre></div>
+The receiving WSS4J Axis handler checks if the SOAP request matches the defined
+actions.
+
+</div></div>
+<div class="section">
+<h2>Combining security actions<a name="Combining_security_actions"></a></h2>
+<p>
+
+Often it is necessary to combine or concatenate several security actions, for
+example to encrypt parts of a message and sign some other parts. The WSS4J
+Axis handlers provide easy and simple methods to combine or concatenate
+security actions.
+</p>
+<p></p>
+<p>
+This chapter describes simple combinations of actions.
+
+</p>
+<div class="section">
+<h3>Combine and<a name="Combine__and"></a></h3>
+<p>
+
+The WS Interoperability specifications define this use case:
+</p>
+<ul>
+
+<li>Insert a <tt>UsernameToken</tt>, use <tt>PasswordText</tt>
+ to set the password. In addition add a timestamp and a nonce into
+ the <tt>UsernameToken</tt></li>
+
+<li>Encrypt the <tt>UsernameToken</tt> to protect the information.
+ </li>
+</ul>
+
+The Axis deplyment descriptor for this use case:
+
+<div class="source">
+<pre>
+ <requestFlow>
+ <handler type="java:org.apache.ws.axis.security.WSDoAllSender" >
+ <parameter name="action" value="UsernameToken Encrypt"/>
+ <parameter name="user" value="werner"/>
+ <parameter name="passwordCallbackClass"
+ value="org.apache.ws.axis.oasis.PWCallback"/>
+ <parameter name="passwordType" value="PasswordText" />
+ <parameter name="addUTElement" value="Nonce Created" />
+ <parameter name="encryptionPropFile" value="crypto.properties" />
+ <parameter name="encryptionKeyIdentifier" value="X509KeyIdentifier" />
+ <parameter name="encryptionUser"
+ value="16c73ab6-b892-458f-abf5-2f875f74882e" />
+ <parameter name="encryptionParts"
+ value="{Element}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd}UsernameToken" />
+ </handler>
+ </requestFlow>
+</pre></div>
+
+This descriptor contains some new parameters to control the <tt>UsernameToken
+</tt> element and its encryption. The new parameters and their meaning are:
+
+<ul>
+
+<li><tt>addUTElement</tt> - controls if the handler shall insert elements
+ into the <tt>UsernameToken</tt>. The value is a blank separated list of
+ element names to include. Only <tt>Nonce</tt> and <tt>Created</tt> are
+ supported.</li>
+
+<li><tt>encryptionPropFile</tt> - the name of a crypto property file. This
+ file contains parameters and property that control the encryption. Please refer
+ to the
+ {@link org.apache.ws.security.handler.WSHandlerConstants#ENC_PROP_FILE
+ detailed} description of the cyrpto property file.</li>
+
+<li><tt>encryptionKeyIdentifier</tt> - specifies the format in which the
+ handler inserts the encryption key into the SOAP request. Please refer
+ to the
+ {@link org.apache.ws.security.handler.WSHandlerConstants#ENC_KEY_ID
+ detailed} description.</li>
+
+<li><tt>encryptionUser</tt> - the name or identifier of the user who owns
+ the public key to encrypt the data. Usually this is the name or alias name
+ of the owner's certificate in a keystore.</li>
+
+<li><tt>encryptionParts</tt> - controls which part or parts the handler
+ of the SOAP shall encrypt. If this parameter is not defined, WSS4J encrypts
+ the whole SOAP Body in <tt>Content</tt> mode. The value of the
+ parameter in this example specifies to encrypt the element <tt>
+ UsernameToken</tt>, contained in the namespace
+ <tt>http://schemas.xmlsoap.org/ws/2002/07/secext</tt>. The encryption
+ module uses the <tt>Element</tt> mode to encrypt the element data.
+ Please refer to the
+ {@link org.apache.ws.security.handler.WSHandlerConstants#ENCRYPTION_PARTS
+ detailed} description.
+ </li>
+</ul>
+The matching receiver deployment descriptor:
+
+<div class="source">
+<pre>
+ <requestFlow>
+ <handler type="java:org.apache.ws.axis.security.WSDoAllReceiver">
+ <parameter name="passwordCallbackClass"
+ value="org.apache.ws.axis.oasis.PWCallback"/>
+ <parameter name="action" value="UsernameToken Encrypt"/>
+ <parameter name="decryptionPropFile" value="crypto.properties" />
+ </handler>
+ </requestFlow>
+</pre></div>
+The only new parameter here is the <tt>decryptionPropFile</tt>. This
+parameter defines the crypto property file at the receiver side. The value
+ of the <tt>action</tt> parameter matches the according value at the
+ sender side. The WSS4J Axis receiver checks if the SOAP request contains
+ the required security data.
+
+</div>
+<div class="section">
+<h3>Combine Signature and Encryption<a name="Combine_Signature_and_Encryption"></a></h3>
+<p>
+
+This is a very common usage of Web Service security. The WSS4J Axis handler
+provides flexible parameter settings that support several ways to use
+the Signature/Encryption combination.
+</p>
+<p></p>
+<p>
+A WSS4J Axis deployment descriptor for a simple Singature/Encryption of
+SOAP requests:
+</p>
+<div class="source">
+<pre>
+<requestFlow>
+ <handler type="java:org.apache.ws.axis.security.WSDoAllSender" >
+ <parameter name="user" value="16c73ab6-b892-458f-abf5-2f875f74882e"/>
+ <parameter name="passwordCallbackClass"
+ value="org.apache.ws.axis.oasis.PWCallback"/>
+ <parameter name="action" value="Signature Encrypt"/>
+ <parameter name="signaturePropFile" value="crypto.properties" />
+ </handler>
+</requestFlow>
+</pre></div>
+This simple deployment descriptor signs and encrypts the SOAP Body part.
+The only new parameter, <tt>signaturePropFile</tt>, specifies the
+name of the signature crypto property file to use. Because no
+<tt>encryptionPropFile</tt> is declared the handler also uses the signature
+property file to get the encryption certificate. The same holds true for
+the username. The password callback class must return a password
+to get the user's private key (the keystore is defined in the crypto
+property file) that WSS4J uses to generate the signature. The encryption
+method uses the user's public key to encrypt the dynamically generated
+session key.
+
+<p></p>
+<p>
+The <tt>action</tt> parameter defines <tt>Signature Encryption</tt>.
+Thus the handler first signs, then the encrypts the data.
+Because the deployment descriptor does not contain specific encryption or
+signature part parameters, WSS4J defaults to the data of the SOAP Body element.
+</p>
+<p></p>
+<p>
+Also all other parameters use their default setting, such as the format of the
+key identifiers, encryption modifiers, and so on. Please refer to the
+{@link org.apache.ws.security.handler.WSHandlerConstants detailed}
+documentation of the parameters.
+</p>
+<p></p>
+<p>
+If the WSS4J Axis handler shall perform encryption only, then the
+deployment descriptor must contain the encryption specific parameters. Only
+if sign <b>and</b> encryption is required the encryption method falls back to
+the signature parameters if the encryption specific parameters are not set.
+</p>
+<p></p>
+<p>
+The matching receiver deployment descriptor is also very simple:
+</p>
+<div class="source">
+<pre>
+<requestFlow>
+ <handler type="java:org.apache.ws.axis.security.WSDoAllReceiver">
+ <parameter name="passwordCallbackClass"
+ value="org.apache.ws.axis.oasis.PWCallback"/>
+ <parameter name="action" value="Signature Encrypt"/>
+ <parameter name="signaturePropFile" value="crypto.properties" />
+ </handler>
+ </requestFlow>
+</pre></div>
+To reverse the actions, just reverse the action specifiers. The WSS4J
+handler encrypts the SOAP Body first, then signs the encrypted data.
+
+</div></div>
+<div class="section">
+<h2>Signing and encrypting multiple XML elements<a name="Signing_and_encrypting_multiple_XML_elements"></a></h2>
+<p>
+
+Sometimes it is necessary to sign and/or encrypt several parts of a SOAP
+message. The deployment parameters <tt>signatureParts</tt> and
+<tt>encryptionParts</tt> control which SOAP elements to sign or
+to encrypt. Please refer to the
+{@link org.apache.ws.security.handler.WSHandlerConstants#ENCRYPTION_PARTS
+detailed} description of these parameters.
+</p>
+<p></p>
+<p>
+WSS4J signs or encrypts all declared parts using the same keys, that is
+the signature or encryption data structures directly reference the
+specified parts as described in the WSS specifications. The receiver
+automatically detects these references and verfies and decrypts the
+data parts. No special settings in the depolyment descriptor is necessary.
+
+</p></div>
+<div class="section">
+<h2>Chaining of WSS4J Axis handlers<a name="Chaining_of_WSS4J_Axis_handlers"></a></h2>
+<p>
+
+This is a very powerful feature that supports even more flexible signature and
+encryption processing such as signatures with multiple keys (overlapping
+signatures), multiple encryption algorithms, or different SOAP actor (role)
+defintions of the security headers.
+
+</p>
+<div class="section">
+<h3>Deployment at the client<a name="Deployment_at_the_client"></a></h3>
+<p>
+A deployment descriptor to chain handlers:
+</p>
+<div class="source">
+<pre>
+ <requestFlow>
+ <handler type="java:org.apache.ws.axis.security.WSDoAllSender" >
+ <parameter name="action" value="Signature NoSerialization"/>
+ <parameter name="user" value="firstUser"/>
+ <parameter name="passwordCallbackClass"
+ value="org.apache.ws.axis.oasis.PWCallback"/>
+ <parameter name="signaturePropFile" value="crypto.properties" />
+ <parameter name="signatureParts" value="{}{http://xmlsoap.org/Ping}ticket" />
+ </handler>
+ <handler type="java:org.apache.ws.axis.security.WSDoAllSender" >
+ <parameter name="action" value="Signature"/>
+ <parameter name="user" value="anotherUser"/>
+ <parameter name="passwordCallbackClass"
+ value="org.apache.ws.axis.oasis.PWCallback"/>
+ <parameter name="signaturePropFile" value="crypto.properties" />
+ </handler>
+ </requestFlow>
+</pre></div>
+Note the action specifier <tt>NoSerialization</tt> first handler.
+In a handler chain of WSS4J handlers every
+but the last handler <i>must</i> have this action specifier. This specifier
+surpresses the very last step of the handler's security processing: the
+serialization of the processed SOAP request in a XML string (document) that
+Axis sends to the reveiver. Only the last handler must perform this
+serialization.
+
+<p></p>
+<p>
+Every handler specification can have its own set of parameters that define
+the individual values for this handler instance. Thus the deployment
+descriptor can define different crypto property files, different usernames,
+and so on. In the example the first handler signs the <tt>ticket</tt>
+element and the second handler the SOAP Body (default).
+</p>
+<p></p>
+<p>
+Parameters set by the application with <tt>setProperty</tt> are valid for
+<b>all</b> handler instances in the handler
+chain (<tt>setProperty</tt> is defined on the SOAP request (call) level).
+As already decribed, deployment settings overrule application settings. Thus it
+is possible to combine various parameter specifications. A special case is the
+definition of the username. If an application sets the username and one
+handler instance in the chain does not have a <tt>user</tt> parameter
+in its deployment part, then this one handler instance uses the username set
+bey the application. After the handler copied the username from the username
+property, the handler sets the property's content to <tt>null</tt>.
+Handlers that follow in the chain cannot use this username anymore and
+must have a user (or encryption user) parameter in their deployment part.
+
+</p></div>
+<div class="section">
+<h3>Deployment at the server<a name="Deployment_at_the_server"></a></h3>
+<p>
+
+Note: Handler chaining at the receiver side is not yet fully tested.
+</p>
+<p></p>
+<p>
+Handlers at the receiver can only determine different security headers if their
+SOAP actors are different. The WSS4J handler processes each security structure
+inside one security header. Because the security structures contain most
+information to verify or decrypt the SOAP request this constraint is
+not too much of an issue.
+</p>
+<p></p>
+<p>
+Only the password call back class and the <tt>Crypto</tt> implementation
+(as defined in the crypto property file) must be able to handle all possible
+certificates, users, passwords, and keys that a security header may contain.
+The following deployment descriptor of a receiver shows this.
+</p>
+<div class="source">
+<pre>
+ <requestFlow>
+ <handler type="java:org.apache.ws.axis.security.WSDoAllReceiver">
+ <parameter name="passwordCallbackClass"
+ value="org.apache.ws.axis.oasis.PWCallback"/>
+ <parameter name="action" value="Signature Signature"/>
+ <parameter name="signaturePropFile" value="crypto.properties" />
+ </handler>
+ </requestFlow>
+</pre></div>
+The client uses two handlers in a chain, each signing a part of the SOAP
+request but with different certificates. Because the handlers do not
+specifiy a SOAP actor WSS4J puts both signatures in the security header
+of the default actor.
+To match the security actions the deployment descriptor of the receiver needs
+to contain the action declaration <tt>Signature Signature</tt>. This
+instructs the WSS4J handler to accept and verify two distinct signatures
+contained in one security header. Because the signatures use different
+certificates the <tt>Crypto</tt> implementation must be able to handle
+these certificates.
+
+<p></p>
+<p>
+Similar requirements are true for the password callback implementation if the
+sender uses handler chaining and uses different encryption parameters in the
+same security header.
+</p>
+<p></p>
+<p>
+If it is necessary to have different parameters for the distinct signature or
+decryption data then these should be put in different security headers. The
+easiest way to do this is to define different <tt>actor</tt> parameters
+for each handler in a WSS4J handler chain.
+
+</p></div></div>
+<div class="section">
+<h2>Reporting Security results to services/applications<a name="Reporting_Security_results_to_servicesapplications"></a></h2>
+<p>
+The WSS4J <tt>WSSecurityEngine</tt> processes the security elements inside
+a security header. If something goes wrong, for example a signature
+verfication fails, then the engine throws a fault. If the security engine
+could perform all operations sucessfully it returns a data structure
+that contains the results of the performed security actions. This data
+structure holds information about the performed action, the usernames or
+identifier in case the security engine performed signature or username token
+processing. Please refer to the
+{@link org.apache.ws.security.WSSecurityEngineResult result} structure.
+</p>
+<p></p>
+<p>
+The <tt>WSDoAllReceiver</tt> WSS4J handler takes this structure and
+checks if all required actions were performed. If this check fails, the
+WSS4J handler aborts the SOAP request and throws an Axis SOAP fault.
+Otherwise it creates its own data structure
+{@link org.apache.ws.axis.security.WSDoAllReceiverResult}, copies the
+security results in this structure, and adds the actor name of the
+security header. The it stores this new data structure in a vector and stores
+this vector in a specific
+{@link org.apache.ws.security.handler.WSHandlerConstants#RECV_RESULTS property}
+of the current message context. If WSS4J handlers are
+chained, then every handler in the chain adds its result to the vector. The
+vector contains the results in handler-chain order.
+</p>
+<p></p>
+<p>
+This code snippet shows how a Axis service can access the security result
+data:
+</p>
+<div class="source">
+<pre>
+ public void ping(javax.xml.rpc.holders.StringHolder text,
+ org.apache.ws.axis.oasis.ping.TicketType ticket)
+ throws java.rmi.RemoteException {
+
+ text.value = "Echo " + text.value.trim();
+
+ // get the message context first
+ MessageContext msgContext = MessageContext.getCurrentContext();
+ Message reqMsg = msgContext.getRequestMessage();
+
+ Vector results = null;
+ // get the result Vector from the property
+ if ((results =
+ (Vector) msgContext.getProperty(WSHandlerConstants.RECV_RESULTS))
+ == null) {
+ System.out.println("No security results!!");
+ }
+ System.out.println("Number of results: " + results.size());
+ for (int i = 0; i < results.size(); i++) {
+ WSHandlerResult hResult = (WSHandlerResult)results.get(i);
+ String actor = hResult.getActor();
+ Vector hResults = hResult.getResults();
+ for (int j = 0; j < hResults.size(); j++) {
+ WSSecurityEngineResult eResult = (WSSecurityEngineResult) hResults.get(j);
+ // Note: an encryption action does not have an associated principal
+ // only Signature and UsernameToken actions return a principal
+ if (eResult.getAction() != WSConstants.ENCR) {
+ System.out.println(eResult.getPrincipal().getName());
+ }
+ }
+ }
+ }
+</pre></div>
+The principal structure is either a
+{@link org.apache.ws.security.WSUsernameTokenPrincipal UsernameToken} principal
+or a {@link java.security.Principal X509Principal}. The
+princpals contain the names plus other information of the verified username
+token or signature certificate.
+
+</div>
+<div class="section">
+<h2>Some hints<a name="Some_hints"></a></h2>
+<div class="section">
+<h3>Client<a name="Client"></a></h3>
+<p>
+At the client side, the WSS4J Axis handler, as all other parts of Axis, run
+in the context of the calling application. Depending on the application,
+the callback classes may perform complex operations, even do some user
+interaction, to get the password or to access some database to get
+certificates or keys. There are no timeouts defined at the client side
+before the SOAP request is put on the wire.
+
+</p></div>
+<div class="section">
+<h3>Server<a name="Server"></a></h3>
+<p>
+On the server side the WSS4J handler run in the same context as the other part
+of the server, usually some servlet container, such as Tomcat. Also the server
+must be able to handle many requests in a short time. Thus the password
+callback as well as the <tt>Crypto</tt> implementation shall be
+as fast as possible. In general, no user interaction is possible at the
+server side to gather passwords. Also at this point of the SOAP request
+processing there are active timeouts, even if they are fairly long.
+
+</p></div>
+<div class="section">
+<h3>Bi-directional SOAP Security<a name="Bi-directional_SOAP_Security"></a></h3>
+<p>
+WSS4J fully supports bi-directional SOAP security. To enable bi-directional
+support just put <tt>WSDoAllSender</tt> on the
+<tt>responseFlow</tt> at the server and <tt>WSDoAllReceiver</tt>
+at the response flow of the client thus reversing the roles. Similar to
+the above hints, the server side part (now <tt>WSDoAllSender</tt>)
+runs in the server context and <tt>WSDoAllReceiver</tt>
+runs in the application (client) context. There are no Axis timeout
+constraints on the client side after Axis received the response
+and handed it over to the WSS4J handler.
+
+</p></div>
+<div class="section">
+<h3>Handler chaining<a name="Handler_chaining"></a></h3>
+<p>
+Usually WSS4J handlers are chained without any other handler between them in
+the chain. It is, however, possible to do so. In this case the intermediate
+handler <b>must not</b> modify the SOAP Envelope that is contained in the
+Axis message. This could (most probably will) invalidate or destroy any
+security actions done sofar. Such an intermediate handler may set some
+properties that may influence the processing of the following WSS4J handler,
+such as setting a new username, password callback class, and so on.
+
+<!-- Put @see and @since tags down here. -->
+@since WSS4J 1.0</p></div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+ Copyright © 2004-2014
+ <a href="http://www.apache.org/">The Apache Software Foundation</a>.
+ All Rights Reserved.
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
Added: webservices/website/wss4j/project-info.html
URL: http://svn.apache.org/viewvc/webservices/website/wss4j/project-info.html?rev=1565626&view=auto
==============================================================================
--- webservices/website/wss4j/project-info.html (added)
+++ webservices/website/wss4j/project-info.html Fri Feb 7 11:52:13 2014
@@ -0,0 +1,141 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!-- Generated by Apache Maven Doxia Site Renderer 1.4 at 2014-02-07 -->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <title>Apache WSS4J - Project Information</title>
+ <style type="text/css" media="all">
+ @import url("./css/maven-base.css");
+ @import url("./css/maven-theme.css");
+ @import url("./css/site.css");
+ </style>
+ <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
+ <meta name="Date-Revision-yyyymmdd" content="20140207" />
+ <meta http-equiv="Content-Language" content="en" />
+
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="./" id="bannerLeft">
+ Apache WSS4J
+ </a>
+ <a href="http://www.apache.org" id="bannerRight">
+ <img src="http://activemq.apache.org/images/asf-logo.png" alt="$alt" />
+ </a>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+ <div class="xleft">
+ <span id="publishDate">Last Published: 2014-02-07</span>
+ | <span id="projectVersion">Version: 2.0.0-SNAPSHOT</span>
+ </div>
+ <div class="xright">
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+
+ <h5>Apache WSS4J</h5>
+ <ul>
+ <li class="none">
+ <a href="index.html" title="Home">Home</a>
+ </li>
+ <li class="none">
+ <a href="download.html" title="Download">Download</a>
+ </li>
+ <li class="none">
+ <a href="using.html" title="Using WSS4J">Using WSS4J</a>
+ </li>
+ <li class="none">
+ <a href="config.html" title="WSS4J Configuration">WSS4J Configuration</a>
+ </li>
+ <li class="none">
+ <a href="migration.html" title="WSS4J 2.0.0 Migration Guide">WSS4J 2.0.0 Migration Guide</a>
+ </li>
+ <li class="none">
+ <a href="topics.html" title="Special Topics">Special Topics</a>
+ </li>
+ <li class="none">
+ <a href="best_practice.html" title="Security Best Practices">Security Best Practices</a>
+ </li>
+ <li class="none">
+ <a href="wss4j16.html" title="WSS4J 1.6 Release Notes">WSS4J 1.6 Release Notes</a>
+ </li>
+ </ul>
+ <h5>Project Documentation</h5>
+ <ul>
+ <li class="expanded">
+ <strong>Project Information</strong>
+ <ul>
+ <li class="none">
+ <a href="issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
+ </li>
+ <li class="none">
+ <a href="license.html" title="Project License">Project License</a>
+ </li>
+ <li class="none">
+ <a href="mail-lists.html" title="Mailing Lists">Mailing Lists</a>
+ </li>
+ <li class="none">
+ <a href="source-repository.html" title="Source Repository">Source Repository</a>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
+ </a>
+
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <div class="section">
+<h2>Project Information<a name="Project_Information"></a></h2>
+<p>This document provides an overview of the various documents and links that are part of this project's general information. All of this content is automatically generated by <a class="externalLink" href="http://maven.apache.org">Maven</a> on behalf of the project.</p>
+<div class="section">
+<h3>Overview<a name="Overview"></a></h3>
+<table border="0" class="bodyTable">
+<tr class="a">
+<th>Document</th>
+<th>Description</th></tr>
+<tr class="b">
+<td><a href="issue-tracking.html">Issue Tracking</a></td>
+<td>This is a link to the issue management system for this project. Issues (bugs, features, change requests) can be created and queried using this link.</td></tr>
+<tr class="a">
+<td><a href="license.html">Project License</a></td>
+<td>This is a link to the definitions of project licenses.</td></tr>
+<tr class="b">
+<td><a href="mail-lists.html">Mailing Lists</a></td>
+<td>This document provides subscription and archive information for this project's mailing lists.</td></tr>
+<tr class="a">
+<td><a href="source-repository.html">Source Repository</a></td>
+<td>This is a link to the online source repository that can be viewed via a web browser.</td></tr></table></div></div>
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+ Copyright © 2004-2014
+ <a href="http://www.apache.org/">The Apache Software Foundation</a>.
+ All Rights Reserved.
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
Added: webservices/website/wss4j/source-repository.html
URL: http://svn.apache.org/viewvc/webservices/website/wss4j/source-repository.html?rev=1565626&view=auto
==============================================================================
--- webservices/website/wss4j/source-repository.html (added)
+++ webservices/website/wss4j/source-repository.html Fri Feb 7 11:52:13 2014
@@ -0,0 +1,156 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!-- Generated by Apache Maven Doxia Site Renderer 1.4 at 2014-02-07 -->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <title>Apache WSS4J - Source Repository</title>
+ <style type="text/css" media="all">
+ @import url("./css/maven-base.css");
+ @import url("./css/maven-theme.css");
+ @import url("./css/site.css");
+ </style>
+ <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
+ <meta name="Date-Revision-yyyymmdd" content="20140207" />
+ <meta http-equiv="Content-Language" content="en" />
+
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="./" id="bannerLeft">
+ Apache WSS4J
+ </a>
+ <a href="http://www.apache.org" id="bannerRight">
+ <img src="http://activemq.apache.org/images/asf-logo.png" alt="$alt" />
+ </a>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+ <div class="xleft">
+ <span id="publishDate">Last Published: 2014-02-07</span>
+ | <span id="projectVersion">Version: 2.0.0-SNAPSHOT</span>
+ </div>
+ <div class="xright">
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+
+ <h5>Apache WSS4J</h5>
+ <ul>
+ <li class="none">
+ <a href="index.html" title="Home">Home</a>
+ </li>
+ <li class="none">
+ <a href="download.html" title="Download">Download</a>
+ </li>
+ <li class="none">
+ <a href="using.html" title="Using WSS4J">Using WSS4J</a>
+ </li>
+ <li class="none">
+ <a href="config.html" title="WSS4J Configuration">WSS4J Configuration</a>
+ </li>
+ <li class="none">
+ <a href="migration.html" title="WSS4J 2.0.0 Migration Guide">WSS4J 2.0.0 Migration Guide</a>
+ </li>
+ <li class="none">
+ <a href="topics.html" title="Special Topics">Special Topics</a>
+ </li>
+ <li class="none">
+ <a href="best_practice.html" title="Security Best Practices">Security Best Practices</a>
+ </li>
+ <li class="none">
+ <a href="wss4j16.html" title="WSS4J 1.6 Release Notes">WSS4J 1.6 Release Notes</a>
+ </li>
+ </ul>
+ <h5>Project Documentation</h5>
+ <ul>
+ <li class="expanded">
+ <a href="project-info.html" title="Project Information">Project Information</a>
+ <ul>
+ <li class="none">
+ <a href="issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
+ </li>
+ <li class="none">
+ <a href="license.html" title="Project License">Project License</a>
+ </li>
+ <li class="none">
+ <a href="mail-lists.html" title="Mailing Lists">Mailing Lists</a>
+ </li>
+ <li class="none">
+ <strong>Source Repository</strong>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
+ </a>
+
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <div class="section">
+<h2>Overview<a name="Overview"></a></h2><a name="Overview"></a>
+<p>This project uses <a class="externalLink" href="http://subversion.apache.org/">Subversion</a> to manage its source code. Instructions on Subversion use can be found at <a class="externalLink" href="http://svnbook.red-bean.com/">http://svnbook.red-bean.com/</a>.</p></div>
+<div class="section">
+<h2>Web Access<a name="Web_Access"></a></h2><a name="Web_Access"></a>
+<p>The following is a link to the online source repository.</p>
+<div class="source">
+<pre><a class="externalLink" href="http://svn.apache.org/repos/asf/webservices/wss4j/trunk">http://svn.apache.org/repos/asf/webservices/wss4j/trunk</a></pre></div></div>
+<div class="section">
+<h2>Anonymous access<a name="Anonymous_access"></a></h2><a name="Anonymous_access"></a>
+<p>The source can be checked out anonymously from SVN with this command:</p>
+<div class="source">
+<pre>$ svn checkout http://svn.apache.org/repos/asf/webservices/wss4j/trunk/ wss4j</pre></div></div>
+<div class="section">
+<h2>Developer access<a name="Developer_access"></a></h2><a name="Developer_access"></a>
+<p>Everyone can access the Subversion repository via HTTP, but Committers must checkout the Subversion repository via HTTPS.</p>
+<div class="source">
+<pre>$ svn checkout https://svn.apache.org/repos/asf/webservices/wss4j/trunk wss4j</pre></div>
+<p>To commit changes to the repository, execute the following command to commit your changes (svn will prompt you for your password)</p>
+<div class="source">
+<pre>$ svn commit --username your-username -m "A message"</pre></div></div>
+<div class="section">
+<h2>Access from behind a firewall<a name="Access_from_behind_a_firewall"></a></h2><a name="Access_from_behind_a_firewall"></a>
+<p>For those users who are stuck behind a corporate firewall which is blocking HTTP access to the Subversion repository, you can try to access it via the developer connection:</p>
+<div class="source">
+<pre>$ svn checkout https://svn.apache.org/repos/asf/webservices/wss4j/trunk wss4j</pre></div></div>
+<div class="section">
+<h2>Access through a proxy<a name="Access_through_a_proxy"></a></h2><a name="Access_through_a_proxy"></a>
+<p>The Subversion client can go through a proxy, if you configure it to do so. First, edit your "servers" configuration file to indicate which proxy to use. The file's location depends on your operating system. On Linux or Unix it is located in the directory "~/.subversion". On Windows it is in "%APPDATA%\Subversion". (Try "echo %APPDATA%", note this is a hidden directory.)</p>
+<p>There are comments in the file explaining what to do. If you don't have that file, get the latest Subversion client and run any command; this will cause the configuration directory and template files to be created.</p>
+<p>Example: Edit the 'servers' file and add something like:</p>
+<div class="source">
+<pre>[global]
+http-proxy-host = your.proxy.name
+http-proxy-port = 3128
+</pre></div></div>
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+ Copyright © 2004-2014
+ <a href="http://www.apache.org/">The Apache Software Foundation</a>.
+ All Rights Reserved.
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
Added: webservices/website/wss4j/topics.html
URL: http://svn.apache.org/viewvc/webservices/website/wss4j/topics.html?rev=1565626&view=auto
==============================================================================
--- webservices/website/wss4j/topics.html (added)
+++ webservices/website/wss4j/topics.html Fri Feb 7 11:52:13 2014
@@ -0,0 +1,402 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!-- Generated by Apache Maven Doxia Site Renderer 1.4 at 2014-02-07 -->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <title>Apache WSS4J - </title>
+ <style type="text/css" media="all">
+ @import url("./css/maven-base.css");
+ @import url("./css/maven-theme.css");
+ @import url("./css/site.css");
+ </style>
+ <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
+ <meta name="Date-Revision-yyyymmdd" content="20140207" />
+ <meta http-equiv="Content-Language" content="en" />
+
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="./" id="bannerLeft">
+ Apache WSS4J
+ </a>
+ <a href="http://www.apache.org" id="bannerRight">
+ <img src="http://activemq.apache.org/images/asf-logo.png" alt="$alt" />
+ </a>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+ <div class="xleft">
+ <span id="publishDate">Last Published: 2014-02-07</span>
+ | <span id="projectVersion">Version: 2.0.0-SNAPSHOT</span>
+ </div>
+ <div class="xright">
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+
+ <h5>Apache WSS4J</h5>
+ <ul>
+ <li class="none">
+ <a href="index.html" title="Home">Home</a>
+ </li>
+ <li class="none">
+ <a href="download.html" title="Download">Download</a>
+ </li>
+ <li class="none">
+ <a href="using.html" title="Using WSS4J">Using WSS4J</a>
+ </li>
+ <li class="none">
+ <a href="config.html" title="WSS4J Configuration">WSS4J Configuration</a>
+ </li>
+ <li class="none">
+ <a href="migration.html" title="WSS4J 2.0.0 Migration Guide">WSS4J 2.0.0 Migration Guide</a>
+ </li>
+ <li class="none">
+ <strong>Special Topics</strong>
+ </li>
+ <li class="none">
+ <a href="best_practice.html" title="Security Best Practices">Security Best Practices</a>
+ </li>
+ <li class="none">
+ <a href="wss4j16.html" title="WSS4J 1.6 Release Notes">WSS4J 1.6 Release Notes</a>
+ </li>
+ </ul>
+ <h5>Project Documentation</h5>
+ <ul>
+ <li class="collapsed">
+ <a href="project-info.html" title="Project Information">Project Information</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
+ </a>
+
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+
+
+<div class="section">
+<h2>WSS4J Special Topics<a name="WSS4J_Special_Topics"></a></h2>
+
+<p>
+This page discusses various topics regarding usage of WSS4J. See the <a class="externalLink" href="http://ws.apache.org/wss4j/using.html">Using Apache WSS4J</a> page for web stack-specific usage notes.
+</p>
+
+<div class="section">
+<h3>Crypto Interface<a name="Crypto_Interface"></a></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 class="externalLink" href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/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 class="externalLink" href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/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 class="externalLink" href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/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 class="externalLink" href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/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 class="section">
+<h3>Verifying Public Keys<a name="Verifying_Public_Keys"></a></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 class="section">
+<h3>Introducing Validators<a name="Introducing_Validators"></a></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 2.4.0. The <a class="externalLink" href="http://svn.apache.org/viewvc/cxf/trunk/rt/ws/security/src/main/java/org/apache/cxf/ws/security/trust/STSTokenValidator.java?view=markup">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 class="externalLink" href="http://svn.apache.org/viewvc/cxf/trunk/rt/ws/security/src/main/java/org/apache/cxf/ws/security/SecurityConstants.java?view=markup">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 class="section">
+<h3>Specifying elements to sign or encrypt<a name="Specifying_elements_to_sign_or_encrypt"></a></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 *all* 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 class="section">
+<h3>WSPasswordCallback identifiers<a name="WSPasswordCallback_identifiers"></a></h3>
+
+<p>The <a class="externalLink" href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/ws-security-common/src/main/java/org/apache/wss4j/common/ext/WSPasswordCallback.java?view=markup">WSPasswordCallback class</a> 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 class="section">
+<h3>UsernameToken handling in WSS4J 1.6<a name="UsernameToken_handling_in_WSS4J_1.6"></a></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 class="section">
+<h3>Support for SAML2 assertions in WSS4J 1.6<a name="Support_for_SAML2_assertions_in_WSS4J_1.6"></a></h3>
+
+
+<p>Support for SAML2 assertions has finally arrived in WSS4J, via the forthcoming 1.6 release. This has been a <a class="externalLink" 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 class="externalLink" 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 class="externalLink" 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 class="externalLink" href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/test/java/org/apache/ws/security/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 class="externalLink" href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/test/java/org/apache/ws/security/common/AbstractSAMLCallbackHandler.java?view=markup">here</a>, as well as the concrete implementations (<a class="externalLink" href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/test/java/org/apache/ws/security/common/SAML1CallbackHandler.java?view=markup">SAML 1.1</a> and <a class="externalLink" href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/test/java/org/apache/ws/security/common/SAML2CallbackHandler.java?view=markup">SAML 2</a>). As you can see, a fa
irly 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>
+<pre>
++- 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
+</pre></div>
+
+
+<p>The WSS4J 1.6 pom currently has a dependency on the Shibboleth <a class="externalLink" href="http://shibboleth.internet2.edu/downloads/maven2/">repo</a>, where the Opensaml2 artifacts live. It is planned on getting the Opensaml2 artifacts into Maven central in time for the 1.6 release - this is slightly complicated by the fact that some of the Opensaml2 dependencies are themselves not in Maven Central.
+</p>
+
+<p>One known <a class="externalLink" href="http://issues.apache.org/jira/browse/WSS-265">issue</a> is that WSS4J cannot create an Assertion which has an EncryptedKey element in the Subject. This is due to a bug in Opensaml2 which has been <a class="externalLink" href="https://bugs.internet2.edu/jira/browse/JOWS-26">fixed</a>, but not released yet.</p>
+
+<p>
+The Opensaml2 port has a large impact on existing code for *creating* 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 *do* 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 class="section">
+<h3>JSR-105 support<a name="JSR-105_support"></a></h3>
+
+<p>WSS4J 1.6 has been ported to use the <a class="externalLink" 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 class="externalLink" 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 will be <a class="externalLink" href="https://issues.apache.org/jira/browse/SANTUARIO-252">removed</a> for the 1.5 release of that library (in a few months).</p>
+
+
+<p>
+It is worth noting some changes to the main <a class="externalLink" href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/main/java/org/apache/ws/security/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 class="section">
+<h3>Basic Security Profile 1.1 compliance<a name="Basic_Security_Profile_1.1_compliance"></a></h3>
+
+
+<p>The Basic Security Profile (BSP) 1.1 <a class="externalLink" 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 class="externalLink" href="http://svn.apache.org/viewvc/webservices/wss4j/branches/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 class="externalLink" 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 <b>on </b>by default. In addition, a new <a class="externalLink" href="http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/main/java/org/apache/ws/security/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>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+ Copyright © 2004-2014
+ <a href="http://www.apache.org/">The Apache Software Foundation</a>.
+ All Rights Reserved.
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>