<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<document>
<body>
<section name="Axis1 Deployment Tutorial">
<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 <code>WSDoAllSender</code> and <code>WSDoAllReceiver
</code> 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></section>
<section name="Prerequisites"><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. 

<ul>
  <li><a href="http://ws.apache.org/wss4j/index.html">WSS4J</a></li>
  <li><a 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. 

</p></section><section name="Related Documentation"><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 href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss">
Here</a> are the WSS specifications.

</p></section><section name="The basics - a simple example that uses"><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><subsection name="Axis deployment descriptor to insert a"><p>
The following snippet shows a general layout how to deploy a WS Axis handler
on the client (application) side.
<source>
 &lt;!-- define the service, use the WSDoAllSender security handler in request flow --&gt;
 &lt;service name="Ping1"&gt;
  &lt;requestFlow&gt;
   &lt;handler type="java:org.apache.ws.axis.security.WSDoAllSender" &gt;
    &lt;parameter name="action" value="UsernameToken"/&gt;
    &lt;parameter name="user" value="werner"/&gt;
    &lt;parameter name="passwordType" value="PasswordText" /&gt;
    &lt;parameter name="passwordCallbackClass" 
      value="org.apache.ws.axis.oasis.PWCallback1Out"/&gt;
   &lt;/handler&gt;
  &lt;/requestFlow&gt;
  &lt;/service&gt;
</source>

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><p>
The above setup inserts the most simple security structure into a SOAP request: 
the simple <code>UsernameToken</code>. 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:
<ul>
<li><code>action</code> defines the security action. The value <code>
    UsernameToken</code> directs the handler to insert this token into
    the SOAP request.
</li>
<li><code>user</code> specifies the username to include in the token.
</li>
<li><code>passwordType</code> is a pecific parameter for the <code>
    UsernameToken</code> action and defines the encoding of the passowrd.
    <code>PasswordText</code> specifies to send the password in
    plain text, <code>PasswordDigest</code> specifies to send the
    password in digest mode (refer to WSS UsernameToken Profile)
</li>
<li><code>passwordCallbackClass</code> 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:
<source>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;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"&gt;
  &lt;soapenv:Header&gt;
    &lt;wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext" 
      soapenv:mustUnderstand="true"&gt;
      &lt;wsse:UsernameToken&gt;
        &lt;wsse:Username&gt;werner&lt;/wsse:Username&gt;
        &lt;wsse:Password Type="wsse:PasswordText"&gt;security&lt;/wsse:Password&gt;
      &lt;/wsse:UsernameToken&gt;
    &lt;/wsse:Security&gt;
  &lt;/soapenv:Header&gt;
  &lt;soapenv:Body&gt;
    &lt;Ping xmlns="http://xmlsoap.org/Ping"&gt;
      &lt;text&gt;Scenario 1 text&lt;/text&gt;
      &lt;ticket xmlns:ns1="http://xmlsoap.org/Ping" 
        xsi:type="ns1:ticketType"&gt;scenario1&lt;/ticket&gt;
    &lt;/Ping&gt;
  &lt;/soapenv:Body&gt;
&lt;/soapenv:Envelope&gt;
</source>
This is a pretty print of the real SOAP message.

</p></subsection><subsection name="The password callback class"><p>

The deployment descriptor contains the user name that the handler inserts into
the <code>UsernameToken</code> 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 
<code>passwordCallbackClass</code> 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 <code>handle</code> 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:
 <source>
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 &lt; 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");
      }
    }
  }
}
</source>
The Java {@link javax.security.auth.callback.CallbackHandler callback} handler
documentation provides a detailed description of the interface and exceptions.
</p><p></p><p>
The WSS4J library uses a specific class to get the required password or key
informations. The <code>WSSPasswordCallback</code> 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 <code>String </code> or it carries the required key information 
as a Java <code>byte[]</code> 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 <code>handle</code> method. 

</p></subsection><subsection name="Application sets parameters to insert in"><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
<code>setProperty</code> 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:
<source>
   ...
 Service service = new Service();
 Call call = (Call) service.createCall();
   ...  
 call.setProperty(UsernameToken.PASSWORD_TYPE, WSConstants.PASSWORD_TEXT);
 call.setProperty(WSHandlerConstants.USER, "werner");
   ...
</source>
Use this way if your application dynamically creates a <code>call</code>
object. If your application uses stubs generated by Axis' <code>WSDL2Java
</code> tool, the application uses the following functions:
<source>
    ...
 PingServiceLocator service = new PingServiceLocator();
    ...
 PingPort port = (PingPort) service.getPing1();
 port._setProperty(UsernameToken.PASSWORD_TYPE, WSConstants.PASSWORD_TEXT);
 port._setProperty(WSHandlerConstants.USER, "werner");
    ...
</source>
Please note that <code>_setProperty</code> is a Axis specific call.

</p></subsection><subsection name="The password callback object reference"><p>

In addition to the <a href="#pwCallBackClass">password callback class</a>
an application may set a password callback object using the <code>
  setProperty()</code> 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:
  <source>
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) {
    ...
  }
}
</source>

</p></subsection><subsection name="Deployment of the WSS4J Axis  handler"><p>

Similar to the deployment descriptor of the sending handler <code>WSDoAllSender
</code> a deployment descriptor for the receiving handler exists. For the above
example the deployment descriptor look like:
<source>
  &lt;requestFlow&gt;
   &lt;handler type="java:org.apache.ws.axis.security.WSDoAllReceiver"&gt;
    &lt;parameter name="passwordCallbackClass" 
      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
    &lt;parameter name="action" value="UsernameToken"/&gt;
   &lt;/handler&gt;
  &lt;/requestFlow&gt;
</source>
The receiving WSS4J Axis handler checks if the SOAP request matches the defined
actions.

</p></subsection></section><section name="Combining security actions"><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><subsection name="Combine  and"><p>

The WS Interoperability specifications define this use case: 
<ul>
  <li>Insert a <code>UsernameToken</code>, use <code>PasswordText</code>
    to set the password. In addition add a timestamp and a nonce into
    the <code>UsernameToken</code></li>
  <li>Encrypt the <code>UsernameToken</code> to protect the information.
    </li>
</ul>

The Axis deplyment descriptor for this use case:
<source>
  &lt;requestFlow&gt;
   &lt;handler type="java:org.apache.ws.axis.security.WSDoAllSender" &gt;
    &lt;parameter name="action" value="UsernameToken Encrypt"/&gt;
    &lt;parameter name="user" value="werner"/&gt;
    &lt;parameter name="passwordCallbackClass" 
      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
    &lt;parameter name="passwordType" value="PasswordText" /&gt;
    &lt;parameter name="addUTElement" value="Nonce Created" /&gt;
    &lt;parameter name="encryptionPropFile" value="crypto.properties" /&gt;
    &lt;parameter name="encryptionKeyIdentifier" value="X509KeyIdentifier" /&gt;
    &lt;parameter name="encryptionUser" 
      value="16c73ab6-b892-458f-abf5-2f875f74882e" /&gt;
    &lt;parameter name="encryptionParts" 
      value="{Element}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd}UsernameToken" /&gt;  
   &lt;/handler&gt;
  &lt;/requestFlow&gt;  
</source>

This descriptor contains some new parameters to control the <code>UsernameToken
</code> element and its encryption. The new parameters and their meaning are:
<ul>
  <li><code>addUTElement</code> - controls if the handler shall insert elements
    into the <code>UsernameToken</code>. The value is a blank separated list of
    element names to include. Only <code>Nonce</code> and <code>Created</code> are
    supported.</li>
  <li><code>encryptionPropFile</code> - 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><code>encryptionKeyIdentifier</code> - 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><code>encryptionUser</code> - 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><code>encryptionParts</code> - 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 <code>Content</code> mode. The value of the
    parameter in this example specifies to encrypt the element <code>
    UsernameToken</code>, contained in the namespace
    <code>http://schemas.xmlsoap.org/ws/2002/07/secext</code>. The encryption
    module uses the <code>Element</code> 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:
<source>
  &lt;requestFlow&gt;
   &lt;handler type="java:org.apache.ws.axis.security.WSDoAllReceiver"&gt;
    &lt;parameter name="passwordCallbackClass" 
      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
    &lt;parameter name="action" value="UsernameToken Encrypt"/&gt;
    &lt;parameter name="decryptionPropFile" value="crypto.properties" /&gt;
   &lt;/handler&gt;
  &lt;/requestFlow&gt;
</source>
The only new parameter here is the <code>decryptionPropFile</code>. This
parameter defines the crypto property file at the receiver side. The value
  of the <code>action</code> parameter matches the according value at the
  sender side. The WSS4J Axis receiver checks if the SOAP request contains
  the required security data.

</p></subsection><subsection name="Combine Signature and Encryption"><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:
<source>
&lt;requestFlow&gt;
  &lt;handler type="java:org.apache.ws.axis.security.WSDoAllSender" &gt;
    &lt;parameter name="user" value="16c73ab6-b892-458f-abf5-2f875f74882e"/&gt;
    &lt;parameter name="passwordCallbackClass" 
      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
    &lt;parameter name="action" value="Signature Encrypt"/&gt;
    &lt;parameter name="signaturePropFile" value="crypto.properties" /&gt;
  &lt;/handler&gt;
&lt;/requestFlow&gt;
</source>
This simple deployment descriptor signs and encrypts the SOAP Body part.
The only new parameter, <code>signaturePropFile</code>, specifies the
name of the signature crypto property file to use. Because no 
<code>encryptionPropFile</code> 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><p>
The <code>action</code> parameter defines <code>Signature Encryption</code>.
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:
<source>
&lt;requestFlow&gt;
  &lt;handler type="java:org.apache.ws.axis.security.WSDoAllReceiver"&gt;
    &lt;parameter name="passwordCallbackClass" 
      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
    &lt;parameter name="action" value="Signature Encrypt"/&gt;
    &lt;parameter name="signaturePropFile" value="crypto.properties" /&gt;
  &lt;/handler&gt;
 &lt;/requestFlow&gt;	
</source>
To reverse the actions, just reverse the action specifiers. The WSS4J
handler encrypts the SOAP Body first, then signs the encrypted data.

</p></subsection></section><section name="Signing and encrypting multiple XML elements"><p>

Sometimes it is necessary to sign and/or encrypt several parts of a SOAP
message. The deployment parameters <code>signatureParts</code> and 
<code>encryptionParts</code> 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></section><section name="Chaining of WSS4J Axis handlers"><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><subsection name="Deployment at the client"><p>
A deployment descriptor to chain handlers:
<source>
  &lt;requestFlow&gt;
   &lt;handler type="java:org.apache.ws.axis.security.WSDoAllSender" &gt;
    &lt;parameter name="action" value="Signature NoSerialization"/&gt;
    &lt;parameter name="user" value="firstUser"/&gt;
    &lt;parameter name="passwordCallbackClass" 
      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
    &lt;parameter name="signaturePropFile" value="crypto.properties" /&gt;
    &lt;parameter name="signatureParts" value="{}{http://xmlsoap.org/Ping}ticket" /&gt;    
   &lt;/handler&gt;
   &lt;handler type="java:org.apache.ws.axis.security.WSDoAllSender" &gt;
    &lt;parameter name="action" value="Signature"/&gt;
    &lt;parameter name="user" value="anotherUser"/&gt;
    &lt;parameter name="passwordCallbackClass" 
      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
    &lt;parameter name="signaturePropFile" value="crypto.properties" /&gt;
   &lt;/handler&gt;  
  &lt;/requestFlow&gt;
</source>
Note the action specifier <code>NoSerialization</code> 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><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 <code>ticket</code>
element and the second handler the SOAP Body (default).
</p><p></p><p>
Parameters set by the application with <code>setProperty</code> are valid for 
<b>all</b> handler instances in the handler
chain (<code>setProperty</code> 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 <code>user</code> 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 <code>null</code>. 
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></subsection><subsection name="Deployment at the server"><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 <code>Crypto</code> 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.
<source>
  &lt;requestFlow&gt;
   &lt;handler type="java:org.apache.ws.axis.security.WSDoAllReceiver"&gt;
    &lt;parameter name="passwordCallbackClass" 
      value="org.apache.ws.axis.oasis.PWCallback"/&gt;
    &lt;parameter name="action" value="Signature Signature"/&gt;
    &lt;parameter name="signaturePropFile" value="crypto.properties" /&gt;
   &lt;/handler&gt;
  &lt;/requestFlow&gt;
</source>
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 <code>Signature Signature</code>. This 
instructs the WSS4J handler to accept and verify two distinct signatures 
contained in one security header. Because the signatures use different 
certificates the <code>Crypto</code> implementation must be able to handle
these certificates.
</p><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 <code>actor</code> parameters
for each handler in a WSS4J handler chain.
 
</p></subsection></section><section name="Reporting Security results to services/applications"><p>
The WSS4J <code>WSSecurityEngine</code> 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 <code>WSDoAllReceiver</code> 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:
<source>
    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 &lt; results.size(); i++) {
            WSHandlerResult hResult = (WSHandlerResult)results.get(i);
            String actor = hResult.getActor();
            Vector hResults = hResult.getResults();
            for (int j = 0; j &lt; 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());
                }
            }
        }
    }
</source>
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.
 
</p></section><section name="Some hints"><subsection name="Client"><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></subsection><subsection name="Server"><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 <code>Crypto</code> 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></subsection><subsection name="Bi-directional SOAP Security"><p>
WSS4J fully supports bi-directional SOAP security. To enable bi-directional
support just put <code>WSDoAllSender</code> on the 
<code>responseFlow</code> at the server and <code>WSDoAllReceiver</code>
at the response flow of the client thus reversing the roles. Similar to
the above hints, the server side part (now <code>WSDoAllSender</code>)
runs in the server context and <code>WSDoAllReceiver</code>
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></subsection><subsection name="Handler chaining"><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></subsection>
</section>
</body>
</document>