Axis deployment descriptor to insert a

The following snippet shows a general layout how to deploy a WS Axis handler on the client (application) side.

 <!-- 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>

The above setup inserts the most simple security structure into a SOAP request: the simple UsernameToken. This token includes a username and the according password. Both fields are sent in cleartext, thus it provides no real security.

The parameters and their meanings are:

• action defines the security action. The value UsernameToken directs the handler to insert this token into the SOAP request.
• user specifies the username to include in the token.
• passwordType is a pecific parameter for the UsernameToken action and defines the encoding of the passowrd. PasswordText specifies to send the password in plain text, PasswordDigest specifies to send the password in digest mode (refer to WSS UsernameToken Profile)
• passwordCallbackClass 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}.

<?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>

The password callback class

The deployment descriptor contains the user name that the handler inserts into the UsernameToken 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 passwordCallbackClass 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 handle method when it needs a password. Refer also to the {@link org.apache.ws.security.handler.WSHandlerConstants#PW_CALLBACK_CLASS parameter} documentation.

The following code snippet shows a simple password callback class:

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");
      }
    }
  }
}

The WSS4J library uses a specific class to get the required password or key informations. The WSSPasswordCallback 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 String or it carries the required key information as a Java byte[] array. Refer to {@link org.apache.ws.security.WSPasswordCallback} that contains a detailed description of the usage codes.

The WSS4J Axis handler or the WSS4J modules set the usage code before they call handle method.

Application sets parameters to insert in

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 setProperty method to support this feature.

The following code snippet shows an example how to use the dynamic setting of parameters and their values:

   ...
 Service service = new Service();
 Call call = (Call) service.createCall();
   ...  
 call.setProperty(UsernameToken.PASSWORD_TYPE, WSConstants.PASSWORD_TEXT);
 call.setProperty(WSHandlerConstants.USER, "werner");
   ...

    ...
 PingServiceLocator service = new PingServiceLocator();
    ...
 PingPort port = (PingPort) service.getPing1();
 port._setProperty(UsernameToken.PASSWORD_TYPE, WSConstants.PASSWORD_TEXT);
 port._setProperty(WSHandlerConstants.USER, "werner");
    ...

The password callback object reference

In addition to the password callback class an application may set a password callback object using the setProperty() methods. Only applications (and Axis handlers that preceed the WSS4J Axis handlers in a handler chain) can use this feature.

For example:

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

Deployment of the WSS4J Axis handler

Similar to the deployment descriptor of the sending handler WSDoAllSender a deployment descriptor for the receiving handler exists. For the above example the deployment descriptor look like:

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

Combine and

The WS Interoperability specifications define this use case:

• Insert a UsernameToken, use PasswordText to set the password. In addition add a timestamp and a nonce into the UsernameToken
• Encrypt the UsernameToken to protect the information.

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

• addUTElement - controls if the handler shall insert elements into the UsernameToken. The value is a blank separated list of element names to include. Only Nonce and Created are supported.
• encryptionPropFile - 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.
• encryptionKeyIdentifier - 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.
• encryptionUser - 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.
• encryptionParts - 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 Content mode. The value of the parameter in this example specifies to encrypt the element UsernameToken, contained in the namespace http://schemas.xmlsoap.org/ws/2002/07/secext. The encryption module uses the Element mode to encrypt the element data. Please refer to the {@link org.apache.ws.security.handler.WSHandlerConstants#ENCRYPTION_PARTS detailed} description.

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

Combine Signature and Encryption

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.

A WSS4J Axis deployment descriptor for a simple Singature/Encryption of SOAP requests:

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

The action parameter defines Signature Encryption. 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.

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.

If the WSS4J Axis handler shall perform encryption only, then the deployment descriptor must contain the encryption specific parameters. Only if sign and encryption is required the encryption method falls back to the signature parameters if the encryption specific parameters are not set.

The matching receiver deployment descriptor is also very simple:

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

Deployment at the client

A deployment descriptor to chain handlers:

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

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 ticket element and the second handler the SOAP Body (default).

Parameters set by the application with setProperty are valid for all handler instances in the handler chain (setProperty 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 user 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 null. Handlers that follow in the chain cannot use this username anymore and must have a user (or encryption user) parameter in their deployment part.

Deployment at the server

Note: Handler chaining at the receiver side is not yet fully tested.

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.

Only the password call back class and the Crypto 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.

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

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.

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 actor parameters for each handler in a WSS4J handler chain.

Client

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.

Server

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

Bi-directional SOAP Security

WSS4J fully supports bi-directional SOAP security. To enable bi-directional support just put WSDoAllSender on the responseFlow at the server and WSDoAllReceiver at the response flow of the client thus reversing the roles. Similar to the above hints, the server side part (now WSDoAllSender) runs in the server context and WSDoAllReceiver 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.

Handler chaining

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 must not 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. @since WSS4J 1.0