You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fx-dev@ws.apache.org by di...@apache.org on 2005/03/09 16:09:13 UTC

cvs commit: ws-fx/wss4j/xdocs api.xml axis.xml index.xml package.xml

dims        2005/03/09 07:09:13

  Modified:    wss4j    .cvsignore maven.xml project.properties
  Added:       wss4j/xdocs api.xml axis.xml index.xml package.xml
  Log:
  Initial documentation set.
  
  - Integrate the files from Rami
  - Copy the stuff in package.html written by werner
  
  Revision  Changes    Path
  1.2       +1 -0      ws-fx/wss4j/.cvsignore
  
  Index: .cvsignore
  ===================================================================
  RCS file: /home/cvs/ws-fx/wss4j/.cvsignore,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- .cvsignore	4 Dec 2004 18:08:29 -0000	1.1
  +++ .cvsignore	9 Mar 2005 15:09:13 -0000	1.2
  @@ -3,3 +3,4 @@
   build.properties
   junit*.properties
   *.log
  +*.wsdd
  
  
  
  1.4       +6 -2      ws-fx/wss4j/maven.xml
  
  Index: maven.xml
  ===================================================================
  RCS file: /home/cvs/ws-fx/wss4j/maven.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- maven.xml	31 Aug 2004 06:21:52 -0000	1.3
  +++ maven.xml	9 Mar 2005 15:09:13 -0000	1.4
  @@ -154,5 +154,9 @@
       <postGoal name="jar">
           <ant:mkdir dir="${basedir}/target/lib"/>
       </postGoal>
  -
  +	<!--
  +    <preGoal name="xdoc:jelly-transform">
  +      <attainGoal name="html2xdoc"/>
  +    </preGoal>  
  +	-->
   </project>
  
  
  
  1.2       +2 -1      ws-fx/wss4j/project.properties
  
  Index: project.properties
  ===================================================================
  RCS file: /home/cvs/ws-fx/wss4j/project.properties,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- project.properties	13 Feb 2004 20:43:04 -0000	1.1
  +++ project.properties	9 Mar 2005 15:09:13 -0000	1.2
  @@ -6,3 +6,4 @@
   maven.xdoc.date=left
   maven.xdoc.version=${pom.currentVersion}
   maven.junit.fork=true
  +#maven.html2xdoc.enabled=true
  
  
  
  1.1                  ws-fx/wss4j/xdocs/api.xml
  
  Index: api.xml
  ===================================================================
  <?xml version="1.0" encoding="ISO-8859-1"?>
  <document><properties><title>Apache WSS4J API Overview</title></properties><body><section name="Apache WSS4J API Overview"></section><section name=""><subsection name="Contents"><ul>
    <li><a href="#API_Overview">API Overview</a><br></br>
    </li>
    <ul>
      <li><a href="#org.apache.ws.security.WSSecurityEngine">WSSecurityEngine</a></li>
      <li><a href="#org.apache.ws.security.message.WSBaseMessage">WSBaseMessage</a></li>
      <li><a href="#org.apache.ws.security.message.WSSignEnvelope">WSSignEnvelope</a>�
  (extends WSBaseMessage)</li>
      <li><a href="#org.apache.ws.security.message.WSAddTimestamp">WSAddTimestamp</a>�
  (extends WSBaseMessage)</li>
      <li><a href="#org.apache.ws.security.message.WSEncryptBody">WSEncryptBody</a>��
  (extends WSBaseMessage)</li>
      <li><a href="#org.apache.ws.security.message.WSAddUsernameToken">WSAddUsernameToken</a>
  (extends WSBaseMessage)</li>
      <li><a href="#org.apache.ws.security.message.WSSAddSAMLToken">WSSAddSAMLToken</a>
  (extends WSBaseMessage)</li>
    </ul>
    <li><a href="#Examples">Examples</a></li>
    <ul>
      <li>Sign the SOAP Body</li>
      <li>Encrypt the SOAP Body</li>
      <li>Process WSS Header and Check the Results<br></br>
      </li>
    </ul>
  </ul><br></br></subsection></section><section name=""><subsection name="API Overview"><p>WSS4J can be used as a library to provide an API for WS-Security
  processing. In this case WSS4J does not need to be used with Axis, or
  even be a part of a deployed web application. The WSS4J API can be
  invoked directly to create WS-Security headers or process them given a
  SOAP Envelope DOM Document.<br></br>
  </p><p>Following is an overview of the main classes and methods for the
  WSS4J API. Please refer to the java docs for the complete API
  documentation.<br></br>
  </p></subsection><subsection name="org.apache.ws.security.WSSecurityEngine"><table style="width: 100%; text-align: left;" border="0" cellpadding="4" cellspacing="4">
    <tbody>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Action<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Method<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle;">Get an instance of security
  engine </td>
        <td colspan="2" rowspan="1" style="vertical-align: top;">
        <pre>public static org.apache.ws.security.WSSecurityEngine getInstance()</pre>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Description<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 255, 255);">Get
  a singleton instance of security engine
  class. If you need to get an instance configured for an older spec
  (different namespaces) then use the other method which takes
  org.apache.ws.security.WSSConfig<br></br>
        </td>
      </tr>
      <tr>
        <td colspan="1" rowspan="4" style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Parameters<br></br>
        </td>
      </tr>
      <tr>
      </tr>
      <tr>
      </tr>
      <tr>
      </tr>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><span style="font-weight: bold;">Returns</span><br></br>
        </td>
        <td style="vertical-align: top; background-color: rgb(204, 255, 255);">
        <pre>org.apache.ws.security.WSSecurityEngine</pre>
        </td>
        <td style="vertical-align: top; background-color: rgb(204, 255, 255);">Processes
  WS-Security Headers in a SOAP Envelope<br></br>
        </td>
      </tr>
    </tbody>
  </table><br></br><table style="width: 100%; text-align: left;" border="0" cellpadding="4" cellspacing="4">
    <tbody>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Action<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Method<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle;">Verify WSS Headers<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top;">
        <pre>java.util.Vector <b>processSecurityHeader</b>(<br></br>    org.w3c.dom.Document doc,<br></br>    java.lang.String�actor,<br></br>    javax.security.auth.callback.CallbackHandler�cb,<br></br>    org.apache.ws.security.components.crypto.Crypto�crypto<br></br>    ) throws org.apache.ws.security.WSSecurityException</pre>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Description<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 255, 255);">Takes
  a SOAP Envelope as a W3C Document and verifies the WSS Headers.�
  This
  includes Username Token processing, Signature verification, decryption
  and timestamp verification. In the case of encrypted elements,
  decryption is performed live on the passed document, i.e., it is
  transformed into the decrypted format.<br></br>
        </td>
      </tr>
      <tr>
        <td colspan="1" rowspan="4" style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Parameters<br></br>
        </td>
        <td style="vertical-align: top; font-weight: bold;">
        <pre>doc</pre>
        </td>
        <td style="vertical-align: top;">the SOAP Envelope as W3C DOM
  Document</td>
      </tr>
      <tr>
        <td style="vertical-align: top; font-weight: bold; background-color: rgb(204, 255, 255);">actor</td>
        <td style="vertical-align: top; background-color: rgb(204, 255, 255);">the
  engine works on behalf of this actor. Refer to the SOAP specification
  about actor or role, this may be null.<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: top; font-weight: bold;">cb<br></br>
        </td>
        <td style="vertical-align: top;">a callback hander to the caller
  to resolve passwords during encryption and UsernameToken handling, this
  may be null.<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: top; font-weight: bold; background-color: rgb(204, 255, 255);">crypto<br></br>
        </td>
        <td style="vertical-align: top; background-color: rgb(204, 255, 255);">the
  object that implements the access to the keystore and the handling of
  certificates. A default implementation is included:
  org.apache.ws.security.components.crypto.Merlin<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><span style="font-weight: bold;">Returns</span><br></br>
        </td>
        <td style="vertical-align: top;">
        <pre>java.util.Vector</pre>
        </td>
        <td style="vertical-align: top;">Vector of
  org.apache.ws.security.WSSecurityEngineResult, this has the information
  resulting from the processing, such as the principal, SAML token, etc.<br></br>
        </td>
      </tr>
    </tbody>
  </table><br></br></subsection><subsection name="org.apache.ws.security.message.WSBaseMessage"><table style="width: 100%; text-align: left;" border="0" cellpadding="4" cellspacing="4">
    <tbody>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Action<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Method<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle;">Set the Signature/Encryption
  parts<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top;">
        <pre>public void setParts(java.util.Vector parts)</pre>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Description<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 255, 255);">Takes
  a vector of org.apache.ws.security.WSEncryptionPart.<br></br>
        </td>
      </tr>
      <tr>
        <td colspan="1" rowspan="2" style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Parameters<br></br>
        </td>
        <td style="vertical-align: top; font-weight: bold;">
        <pre>doc</pre>
        </td>
        <td style="vertical-align: top;">the SOAP Envelope as W3C DOM
  Document</td>
      </tr>
      <tr>
        <td style="vertical-align: top; font-weight: bold; background-color: rgb(204, 255, 255);">crypto<br></br>
        </td>
        <td style="vertical-align: top; background-color: rgb(204, 255, 255);">the
  object that implements the access to the keystore and the handling of
  certificates. A default implementation is included:
  org.apache.ws.security.components.crypto.Merlin<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><span style="font-weight: bold;">Returns</span><br></br>
        </td>
        <td style="vertical-align: top;">
        <pre>org.w3c.dom.Document</pre>
        </td>
        <td style="vertical-align: top;">the
  SOAP Envelope Signed. The signed elements depend on the signature parts
  that are specified by the WSBaseMessage.setParts(java.util.Vector
  parts) method<br></br>
        </td>
      </tr>
    </tbody>
  </table><br></br></subsection><subsection name="org.apache.ws.security.message.WSSignEnvelope
  (extends WSBaseMessage)"><table style="width: 100%; text-align: left;" border="0" cellpadding="4" cellspacing="4">
    <tbody>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Action<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Method<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle;">Signs a SOAP Envelope<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top;">
        <pre>public org.w3c.dom.Document build(<br></br>    org.w3c.dom.Document doc,<br></br>    org.apache.ws.security.components.crypto.Crypto crypto<br></br>    ) throws org.apache.ws.security.WSSecurityException</pre>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Description<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 255, 255);">Takes
  a SOAP Envelope as a W3C Document and adds WSS Signature header to it.
  The signed elements depend on the signature parts
  that are specified by the WSBaseMessage.setParts(java.util.Vector
  parts) method. By default, SOAP Body is signed </td>
      </tr>
      <tr>
        <td colspan="1" rowspan="2" style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Parameters<br></br>
        </td>
        <td style="vertical-align: top; font-weight: bold;">
        <pre>doc</pre>
        </td>
        <td style="vertical-align: top;">the SOAP Envelope as W3C DOM
  Document</td>
      </tr>
      <tr>
        <td style="vertical-align: top; font-weight: bold; background-color: rgb(204, 255, 255);">crypto<br></br>
        </td>
        <td style="vertical-align: top; background-color: rgb(204, 255, 255);">the
  object that implements the access to the keystore and the handling of
  certificates. A default implementation is included:
  org.apache.ws.security.components.crypto.Merlin<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><span style="font-weight: bold;">Returns</span><br></br>
        </td>
        <td style="vertical-align: top;">
        <pre>org.w3c.dom.Document</pre>
        </td>
        <td style="vertical-align: top;">the
  SOAP Envelope signed.<br></br>
        </td>
      </tr>
    </tbody>
  </table><br></br></subsection><subsection name="org.apache.ws.security.message.WSAddTimestamp
  (extends WSBaseMessage)"><table style="width: 100%; text-align: left;" border="0" cellpadding="4" cellspacing="4">
    <tbody>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Action<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Method<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle;">Add a Timestamp Token to a
  SOAP Envelope </td>
        <td colspan="2" rowspan="1" style="vertical-align: top;">
        <pre>public org.w3c.dom.Document <b>build</b>(<br></br>    org.w3c.dom.Document�doc,<br></br>   �int�ttl)</pre>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Description<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 255, 255);">Takes
  a SOAP Envelope as a W3C Document and adds a Timestamp header to
  it. Please refer to the WS specification 1.0. chapter 10 / appendix A.2
        <p> </p>
        <p> </p>
        </td>
      </tr>
      <tr>
        <td colspan="1" rowspan="2" style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Parameters<br></br>
        </td>
        <td style="vertical-align: top; font-weight: bold;">
        <pre>doc</pre>
        </td>
        <td style="vertical-align: top;">the SOAP Envelope as W3C DOM
  Document</td>
      </tr>
      <tr>
        <td style="vertical-align: top; font-weight: bold; background-color: rgb(204, 255, 255);">
        <pre>ttl</pre>
        </td>
        <td style="vertical-align: top; background-color: rgb(204, 255, 255);">(time
  to live) This is the time difference in seconds between the <code>Created</code>
  and the <code>Expires</code> in <code>Timestamp</code>, set to zero
  if <code>Expires</code> should not be added. </td>
      </tr>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><span style="font-weight: bold;">Returns</span><br></br>
        </td>
        <td style="vertical-align: top; background-color: rgb(255, 255, 255);">
        <pre>org.w3c.dom.Document</pre>
        </td>
        <td style="vertical-align: top; background-color: rgb(255, 255, 255);">the
  SOAP Envelope with the Timestamp added<br></br>
        </td>
      </tr>
    </tbody>
  </table><br></br></subsection><subsection name="org.apache.ws.security.message.WSEncryptBody
  (extends WSBaseMessage)"><table style="width: 100%; text-align: left;" border="0" cellpadding="4" cellspacing="4">
    <tbody>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Action<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Method<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle;">Encrypt a SOAP Envelope<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top;">
        <pre>public org.w3c.dom.Document build(<br></br>    org.w3c.dom.Document doc,<br></br>    org.apache.ws.security.components.crypto.Crypto crypto<br></br>    ) throws org.apache.ws.security.WSSecurityException</pre>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Description<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 255, 255);">Takes
  a SOAP Envelope as a W3C Document and adds WSS Encryption header to it.
  Unlike
  what the class name might imply, this can be used to encrypt elements
  in the SOAP Header, such as Username Tokens or other arbitrary
  elements. The encrypted elements depend on the signature parts
  that are specified by the WSBaseMessage.setParts(java.util.Vector
  parts) method. By default, SOAP Body is encrypted</td>
      </tr>
      <tr>
        <td colspan="1" rowspan="2" style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Parameters<br></br>
        </td>
        <td style="vertical-align: top; font-weight: bold;">
        <pre>doc</pre>
        </td>
        <td style="vertical-align: top;">the SOAP Envelope as W3C DOM
  Document</td>
      </tr>
      <tr>
        <td style="vertical-align: top; font-weight: bold; background-color: rgb(204, 255, 255);">crypto<br></br>
        </td>
        <td style="vertical-align: top; background-color: rgb(204, 255, 255);">the
  object that implements the access to the keystore and the handling of
  certificates. A default implementation is included:
  org.apache.ws.security.components.crypto.Merlin<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><span style="font-weight: bold;">Returns</span><br></br>
        </td>
        <td style="vertical-align: top;">
        <pre>org.w3c.dom.Document</pre>
        </td>
        <td style="vertical-align: top;">the
  SOAP Envelope encrypted.<br></br>
        </td>
      </tr>
    </tbody>
  </table><br></br></subsection><subsection name="org.apache.ws.security.message.WSAddUsernameToken
  (extends WSBaseMessage)"><table style="width: 100%; text-align: left;" border="0" cellpadding="4" cellspacing="4">
    <tbody>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Action<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Method<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle;">Add a Username Token to a
  SOAP Envelope<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top;">
        <pre>public org.w3c.dom.Document build(<br></br>    org.w3c.dom.Document doc,<br></br>    java.lang.String username,<br></br>    java.lang.String password)</pre>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Description<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 255, 255);">Takes
  a SOAP Envelope as a W3C Document and adds a Username Token header to
  it. Use setPasswordType(java.lang.String pwType) to choose between
  plain text passwords and digested ones. </td>
      </tr>
      <tr>
        <td colspan="1" rowspan="3" style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Parameters<br></br>
        </td>
        <td style="vertical-align: top; font-weight: bold;">
        <pre>doc</pre>
        </td>
        <td style="vertical-align: top;">the SOAP Envelope as W3C DOM
  Document</td>
      </tr>
      <tr>
        <td style="vertical-align: top; font-weight: bold; background-color: rgb(204, 255, 255);">username<br></br>
        </td>
        <td style="vertical-align: top; background-color: rgb(204, 255, 255);">the
  username to use<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: top;">password<br></br>
        </td>
        <td style="vertical-align: top;">the password to use (a plain
  text string)<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><span style="font-weight: bold;">Returns</span><br></br>
        </td>
        <td style="vertical-align: top; background-color: rgb(204, 255, 255);">
        <pre>org.w3c.dom.Document</pre>
        </td>
        <td style="vertical-align: top; background-color: rgb(204, 255, 255);">the
  SOAP Envelope with the username token header added<br></br>
        </td>
      </tr>
    </tbody>
  </table><br></br></subsection><subsection name="org.apache.ws.security.message.WSSAddSAMLToken
  (extends WSBaseMessage)"><table style="width: 100%; text-align: left;" border="0" cellpadding="4" cellspacing="4">
    <tbody>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Action<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 204, 204); font-weight: bold;">Method<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle;">Add a SAML Token to a SOAP
  Envelope </td>
        <td colspan="2" rowspan="1" style="vertical-align: top;">
        <pre>public org.w3c.dom.Document build(<br></br>    org.w3c.dom.Document doc,<br></br>   �org.opensaml.SAMLAssertion assertion)</pre>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Description<br></br>
        </td>
        <td colspan="2" rowspan="1" style="vertical-align: top; background-color: rgb(204, 255, 255);">Takes
  a SOAP Envelope as a W3C Document and adds a SAML Assertion Token
  header to
  it. Please refer to the OpenSAML documentation on how to construct SAML
  assertions.<br></br>
        </td>
      </tr>
      <tr>
        <td colspan="1" rowspan="2" style="vertical-align: middle; background-color: rgb(204, 204, 204); font-weight: bold;">Parameters<br></br>
        </td>
        <td style="vertical-align: top; font-weight: bold;">
        <pre>doc</pre>
        </td>
        <td style="vertical-align: top;">the SOAP Envelope as W3C DOM
  Document</td>
      </tr>
      <tr>
        <td style="vertical-align: top; font-weight: bold; background-color: rgb(204, 255, 255);">
        <pre>assertion</pre>
        </td>
        <td style="vertical-align: top; background-color: rgb(204, 255, 255);">the
  SAML assertion to add<br></br>
        </td>
      </tr>
      <tr>
        <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><span style="font-weight: bold;">Returns</span><br></br>
        </td>
        <td style="vertical-align: top; background-color: rgb(255, 255, 255);">
        <pre>org.w3c.dom.Document</pre>
        </td>
        <td style="vertical-align: top; background-color: rgb(255, 255, 255);">the
  SOAP Envelope with the SAML assertion header added<br></br>
        </td>
      </tr>
    </tbody>
  </table><br></br></subsection><subsection name="Examples"></subsection><subsection name="Sign the SOAP Body"><small>Document envelope = ...<br></br>
  WSSignEnvelope signer = new WSSignEnvelope();<br></br>
  Crypto crypto = CryptoFactory.getInstance("crypto.properties");<br></br>
  Vector parts = new Vector();<br></br>
  WSEncryptionPart part = new
  WSEncryptionPart(soapConstants.getBodyQName().getLocalPart(),<br></br>
  �����������������������
  � � � � � � � � �
  �� soapConstants.getEnvelopeURI(),<br></br>
  � � � � � � � � �
  ��������������������������
  "Content");<br></br>
  parts.add(part);<br></br>
  signer.setParts(parts); // this is optional since the body is signed by
  default<br></br>
  envelope = signer.build(envelope, crypto);</small><br></br></subsection><subsection name="Encrypt the SOAP Body"><small>Document envelope = ...<br></br>
  WSEncryptBody encryptor = new WSEncryptBody();<br></br>
  Crypto crypto = CryptoFactory.getInstance("crypto.properties");<br></br>
  Vector parts = new Vector();<br></br>
  WSEncryptionPart part = new
  WSEncryptionPart(soapConstants.getBodyQName().getLocalPart(),<br></br>
  �����������������������
  � � � � � � � � �
  �� soapConstants.getEnvelopeURI(),<br></br>
  � � � � � � � � �
  ��������������������������
  "Content");<br></br>
  parts.add(part);<br></br>
  encryptor.setParts(parts); </small><small>// this is optional since
  the body is encrypted by default</small><br></br><small>envelope = encryptor.build(envelope, crypto);</small><br></br></subsection><subsection name="Process WSS Header and Check the Results"><small>
  Document envelope = ...<br></br>
  WSSecurityEngine secEngine = WSSecurityEngine.getInstance();<br></br>
  Crypto crypto = CryptoFactory.getInstance("crypto.properties");<br></br>
  <code>// </code><code>javax.security.auth.callback.CallbackHandler<br></br>
  // please refer to the tests for examples of callback handlers<br></br>
  </code><code>CallbackHandler�cb = new MyCallbackHandler();</code><code></code><br></br>
  Vector results = secEngine.processSecurityHeader(envelope, null, <code>cb</code>,
  crypto);<br></br>
  for (int i = 0; i &lt; results.size(); i++) {<br></br>
  ��� WSHandlerResult hResult =
  (WSHandlerResult)results.get(i);<br></br>
  ��� String actor = hResult.getActor();<br></br>
  ��� Vector hResults = hResult.getResults();<br></br>
  ��� for (int j = 0; j &lt; hResults.size(); j++) {<br></br>
  ������� WSSecurityEngineResult
  eResult = (WSSecurityEngineResult)hResults.get(j);<br></br>
  ������� // Note: an encryption
  action does not have an associated principal<br></br>
  ��� ��� // only Signature and
  UsernameToken actions return a principal<br></br>
  ������� if (eResult.getAction() !=
  WSConstants.ENCR) {<br></br>
  �����������
  System.out.println(eResult.getPrincipal().getName());<br></br>
  ������� }<br></br>
  ��� }<br></br>
  }</small><br></br></subsection></section></body></document>
  
  
  1.1                  ws-fx/wss4j/xdocs/axis.xml
  
  Index: axis.xml
  ===================================================================
  <?xml version="1.0" encoding="ISO-8859-1"?>
  <document><properties><title>Axis Deployment Tutorial</title></properties><body><section name="Apache WSS4J"></section><section name="Axis Deployment Tutorial"></section><section name=""><subsection name="Contents"><ul>
    <li>Introduction</li>
    <li>Prerequisties</li>
    <li>Steps</li>
    <ul>
      <li>Username Token<br></br>
      </li>
    </ul>
  </ul></subsection></section><section name=""><subsection name="Introduction"><div style="margin-left: 40px;">WS4J can be used for securing web
  services deployed in virtually any application server, but it includes
  special support for Axis. WSS4J ships with handlers that can be used in
  Axis-based web
  services for an easy integration. These handlers can be added to the
  service deployment
  descriptor (wsdd file) to add a WS-Security layer to the web service.
  This is a step by step tutorial for deploying a simple service with
  Username Token.<br></br>
  </div><br></br></subsection><subsection name="Prerequisties"><div style="margin-left: 40px;"><a href="http://ws.apache.org/axis/">Axis
  1.2</a> installed and configured on a <a href="http://jakarta.apache.org/tomcat/">Tomcat Server</a>.� This
  tutorial was performed on a Linux machine with Tomcat 5.5.4/Java 1.5.0,
  however, the setup should be similar on other application servers, or
  other operating systems (like Windows) unless we stated otherwise.<br></br>
  </div></subsection><subsection name="Steps"></subsection><subsection name="��� Installing WSS4J"><div style="margin-left: 40px;">
  <ol>
    <li>Download the WSS4J binaries or build it from sources<br></br>
    </li>
    <li>Copy the contents of the WSS4J lib directory to your Axis
  WEB-INF/lib directory. Many jar files will already exist. Most of them
  will already exist there but you can just overwrite them all.</li>
    <li>You may need to restart Tomcat unless you have automatic
  deployment/class loading turned on. Check the Axis Happiness Page
  (typically at http://localhost:8080/axis), make sure that the XML
  Security (xmlsec.jar) is listed under the "Optional Components" section.</li>
  </ol>
  <h4>Creating the Service</h4>
  </div><ol>
    <ol>
      <li>This tutorial will secure the StockQuoteService which ships
  with Axis. Unless you have one already, create a deployment descriptor
  (deploy.wsdd) file with the following contents:</li>
    </ol>
  </ol><div style="margin-left: 40px;">
  <ol start="2">
    <br></br>
    <span style="color: rgb(0, 0, 153);">&lt;deployment
  xmlns="http://xml.apache.org/axis/wsdd/"
  xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"&gt;</span><br style="color: rgb(0, 0, 153);"></br>
    <span style="color: rgb(0, 0, 153);">�&lt;service
  name="stock-wss-01" provider="java:RPC" style="document"
  use="literal"&gt;</span><br style="color: rgb(0, 0, 153);"></br>
    <span style="color: rgb(0, 0, 153);">� &lt;parameter
  name="className" value="samples.stock.StockQuoteService"/&gt;</span><br style="color: rgb(0, 0, 153);"></br>
    <span style="color: rgb(0, 0, 153);">� &lt;parameter
  name="allowedMethods" value="getQuote"/&gt;</span><br style="color: rgb(0, 0, 153);"></br>
    <span style="color: rgb(0, 0, 153);">� &lt;parameter
  name="scope" value="application"/&gt;</span><br style="color: rgb(0, 0, 153);"></br>
    <span style="color: rgb(0, 0, 153);">�&lt;/service&gt;</span><br style="color: rgb(0, 0, 153);"></br>
    <span style="color: rgb(0, 0, 153);">&lt;/deployment&gt;<br></br>
    <br></br>
    </span><li>deploy the service (using AxisAdmin):</li>
  </ol>
  </div><div style="margin-left: 40px;">
  <ol>
    <span style="color: rgb(0, 0, 153);">java
  org.apache.axis.client.AdminClient
  -lhttp://localhost:8080/axis/services/AdminService deploy.wsdd<br></br>
    </span>
  </ol>
  <h4>Creating the Client</h4>
  <ol>
    <li>Use WSDL2Java to generate the client service bindings:<br></br>
      <span style="color: rgb(0, 0, 153);">java
  org.apache.axis.wsdl.WSDL2Java -o .
  -Nhttp://fox:8080/axis/services/stock-wss-01 samples.stock.client
  http://fox:8080/axis/services/stock-wss-01?wsdl</span><br></br>
      <br></br>
  A bunch of java classes will be created under samples/stock/client,
  including the StockQuoteServiceServiceLocator.<br></br>
      <br></br>
    </li>
    <li>Write a simple java client that uses the generated service
  locator. For example:<br></br>
      <br></br>
      <span style="color: rgb(0, 0, 153);">package samples.stock.client;</span><br style="color: rgb(0, 0, 153);"></br>
      <br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">import
  java.rmi.RemoteException;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">import
  javax.xml.rpc.ServiceException;</span><br style="color: rgb(0, 0, 153);"></br>
      <br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">public class
  StockServiceClient {</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">��� public
  StockServiceClient() {</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">��� }</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">��� public
  static void main(String[] args) throws ServiceException,
  RemoteException {</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�������
  if (args.length == 0) {</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�����������
  System.out.println("Usage:\njava StockServiceClient [symbol]");</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�����������
  return;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�������
  }</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�������
  StockQuoteServiceService locator = new
  StockQuoteServiceServiceLocator();</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�������
  StockQuoteService service = locator.getStockWss01();</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�������
  float quote = service.getQuote(args[0]);</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�������
  System.out.println("stock quote service returned " + args[0] + ": " +
  quote);</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">��� }</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">}</span><br></br>
      <br></br>
    </li>
    <li>run the client:<br></br>
      <span style="color: rgb(0, 0, 153);">java
  samples.stock.client.StockServiceClient IBM</span><br></br>
      <br></br>
  If all went well, you should get the result:<br></br>
      <br></br>
      <span style="color: rgb(0, 0, 153);"></span> <span style="color: rgb(0, 0, 153);">stock quote service returned IBM: 95.68</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);"><br></br>
      </span></li>
  </ol>
  </div><div style="margin-left: 40px;">
  <h3>Username Token</h3>
  <h4>Configuring the Service<br></br>
  </h4>
  <ol>
    <li>Modify the deployment descriptor you created above to look like
  this:<br></br>
      <span style="color: rgb(0, 0, 153);">&lt;deployment
  xmlns="http://xml.apache.org/axis/wsdd/"
  xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"&gt;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�&lt;service
  name="stock-wss-01" provider="java:RPC" style="document"
  use="literal"&gt;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153); font-weight: bold;">�
  &lt;requestFlow&gt;</span><br style="color: rgb(0, 0, 153); font-weight: bold;"></br>
      <span style="color: rgb(0, 0, 153); font-weight: bold;">��
  &lt;handler type="java:org.apache.ws.axis.security.WSDoAllReceiver"&gt;</span><br style="color: rgb(0, 0, 153); font-weight: bold;"></br>
      <span style="color: rgb(0, 0, 153); font-weight: bold;">���
  &lt;parameter name="passwordCallbackClass" value="PWCallback"/&gt;</span><br style="color: rgb(0, 0, 153); font-weight: bold;"></br>
      <span style="color: rgb(0, 0, 153); font-weight: bold;">���
  &lt;parameter name="action" value="UsernameToken"/&gt;</span><br style="color: rgb(0, 0, 153); font-weight: bold;"></br>
      <span style="color: rgb(0, 0, 153); font-weight: bold;"></span><span style="color: rgb(0, 0, 153); font-weight: bold;">��
  &lt;/handler&gt;</span><br style="color: rgb(0, 0, 153); font-weight: bold;"></br>
      <span style="color: rgb(0, 0, 153); font-weight: bold;">�
  &lt;/requestFlow&gt;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">� &lt;parameter
  name="className" value="samples.stock.StockQuoteService"/&gt;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">� &lt;parameter
  name="allowedMethods" value="getQuote"/&gt;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">� &lt;parameter
  name="scope" value="application"/&gt;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�&lt;/service&gt;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">&lt;/deployment&gt;<br></br>
      <br></br>
      </span>WSDoAllReceiver is an Axis handler that can be located in
  wss4j.jar. This is the standard way to deploy an Axis handler. For more
  details please refer to the Axis handler for WSS4J documentation.<br></br>
      <br></br>
    </li>
    <li>Create a class named PWCallback.java and compile it into your
  Axis WEB-INF/classes directory. In this example I used the default
  package for simplicity, but you might need to use the fully qualified
  class name (be consistent
  with the deployment descriptor).<br></br>
      <br></br>
  The following code snippet shows a simple password callback class:<br></br>
      <br></br>
      <span style="color: rgb(0, 0, 153);">import java.io.IOException;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">import
  javax.security.auth.callback.Callback;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">import
  javax.security.auth.callback.CallbackHandler;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">import
  javax.security.auth.callback.UnsupportedCallbackException;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">import
  org.apache.ws.security.WSPasswordCallback;</span><br style="color: rgb(0, 0, 153);"></br>
      <br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">public class PWCallback
  implements CallbackHandler {</span><span style="color: rgb(0, 0, 153);"></span><span style="color: rgb(0, 0, 153);"></span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">� � public void
  handle(Callback[] callbacks)</span><span style="color: rgb(0, 0, 153);">
  throws IOException, UnsupportedCallbackException {</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�������
  for (int i = 0; i &lt; callbacks.length; i++) {</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�����������
  if (callbacks[i] instanceof WSPasswordCallback) {</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">���������������
  WSPasswordCallback pc = (WSPasswordCallback)callbacks[i];<br></br>
  ���������������
  // set the password given a username<br></br>
      </span>���������������
      <span style="color: rgb(0, 0, 153);">if
  ("wss4j".equals(pc.getIdentifer())) {</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�������������������
  pc.setPassword("security");</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">���������������
  }</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);"></span><span style="color: rgb(0, 0, 153);">�����������
  } else {</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">���������������
  throw new UnsupportedCallbackException(</span><span style="color: rgb(0, 0, 153);">callbacks[i], "Unrecognized Callback");</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�����������
  }</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�������
  }</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">��� }</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">}</span><br></br>
      <span style="font-weight: bold;"></span><br></br>
      <br></br>
      <br></br>
    </li>
    <li>Redeploy the service. Your service should now be expecting a WSS
  Username Token in in the incoming requests, and clients should send the
  username "wss4j" and password "security" to get through.<br></br>
    </li>
  </ol>
  <h4>Configuring the Client</h4>
  <ol>
    <li>run the client we created again:<br></br>
      <span style="color: rgb(0, 0, 153);">java
  samples.stock.client.StockServiceClient IBM</span><br></br>
      <br></br>
  You should now get an error:<br></br>
      <br></br>
      <span style="color: rgb(0, 0, 153);">Exception in thread "main"
  AxisFault</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�faultCode:
  {http://schemas.xmlsoap.org/soap/envelope/}Server.generalException</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�faultSubcode:</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�faultString:
  WSDoAllReceiver: Request does not contain required Security header</span><br></br>
      <br></br>
  This is because your client is not configured to send a Username Token
  yet, so the service is rejecting the request.<br></br>
      <br></br>
    </li>
    <li>Create a deployment descriptor file (client_deploy.wsdd) for the
  client:<br></br>
      <br></br>
      <span style="color: rgb(0, 0, 153);">&lt;deployment
  xmlns="http://xml.apache.org/axis/wsdd/"
  xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"&gt;<br></br>
  �&lt;transport name="http"
  pivot="java:org.apache.axis.transport.http.HTTPSender"/&gt;<br></br>
  � &lt;globalConfiguration &gt;<br></br>
  �� &lt;requestFlow &gt;<br></br>
  ��� &lt;handler
  type="java:org.apache.ws.axis.security.WSDoAllSender" &gt;<br></br>
  ���� &lt;parameter name="action"
  value="UsernameToken"/&gt;<br></br>
  ���� &lt;parameter name="user" value="wss4j"/&gt;<br></br>
  ���� &lt;parameter name="passwordCallbackClass"
  value="samples.stock.client.PWCallback"/&gt;<br></br>
  ���� &lt;parameter name="passwordType"
  value="PasswordDigest"/&gt;<br></br>
  ��� &lt;/handler&gt;<br></br>
  �� &lt;/requestFlow &gt;<br></br>
  � &lt;/globalConfiguration &gt;<br></br>
  &lt;/deployment&gt;</span><span style="color: rgb(0, 0, 153);"></span><br></br>
      <br></br>
    </li>
    <li>Create the <span style="color: rgb(0, 0, 153);">samples.stock.client.PWCallback</span>
  class:<br></br>
      <br></br>
      <span style="color: rgb(0, 0, 153);">package samples.stock.client;</span><br style="color: rgb(0, 0, 153);"></br>
      <br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">import java.io.IOException;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">import
  javax.security.auth.callback.Callback;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">import
  javax.security.auth.callback.CallbackHandler;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">import
  javax.security.auth.callback.UnsupportedCallbackException;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">import
  org.apache.ws.security.WSPasswordCallback;</span><br style="color: rgb(0, 0, 153);"></br>
      <br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">/**</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�* PWCallback for the
  Client</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�*/</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">public class PWCallback
  implements CallbackHandler {</span><br style="color: rgb(0, 0, 153);"></br>
      <br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">��� /**</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">���� *
  @see
  javax.security.auth.callback.CallbackHandler#handle(javax.security.auth.callback.Callback[])</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">���� */</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">��� public void
  handle(Callback[] callbacks) throws IOException,</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�������������������
  UnsupportedCallbackException {</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�������
  for (int i = 0; i &lt; callbacks.length; i++) {</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�����������
  if (callbacks[i] instanceof WSPasswordCallback) {</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">���������������
  WSPasswordCallback pc = (WSPasswordCallback)callbacks[i];</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">���������������
  // set the password given a username</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">���������������
  if ("wss4j".equals(pc.getIdentifer())) {</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�������������������
  pc.setPassword("security");</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">���������������
  }</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�����������
  } else {</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">���������������
  throw new UnsupportedCallbackException(callbacks[i], "Unrecognized
  Callback");</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�����������
  }</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">�������
  }</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">��� }</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">}</span><br></br>
      <br></br>
    </li>
    <li>Define the system property axis.ClientConfigFile for your client:<br></br>
      <br></br>
      <span style="color: rgb(0, 0, 153);">java
  -Daxis.ClientConfigFile=client_deploy.wsdd -classpath $AXISCLASSPATH
  samples.stock.client.StockServiceClient</span><br></br>
      <br></br>
  Make sure that your classpath includes the jar files under WEB-INF/lib.<br></br>
      <br></br>
  Another way to do this is to specify the wsdd file in your
  StockServiceClient to the service locator programmatically:<br></br>
      <br></br>
      <span style="color: rgb(0, 0, 153);">...</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">import
  org.apache.axis.EngineConfiguration;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">import
  org.apache.axis.configuration.FileProvider;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">...</span><br style="color: rgb(0, 0, 153);"></br>
      <br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">EngineConfiguration config =
  new FileProvider("client_deploy.wsdd");</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">StockQuoteServiceService
  locator = new StockQuoteServiceServiceLocator(config);</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">...</span><br></br>
      <br></br>
    </li>
    <li>Run the client, you should get no errors:<br></br>
      <br></br>
      <span style="color: rgb(0, 0, 153);">stock quote service returned
  IBM: 95.7</span><br></br>
      <br></br>
  Your client is now sending a Username Token in the wsse request header
  with the username "wss4j" (see client_deploy.wsdd) and password
  "security" (see the PWCallback implementation).<br></br>
      <br></br>
  Another way to do this is to have the client application set the
  username and CallbackHandler implementation programmatically instead of
  client_deploy.wsdd:<br></br>
      <br></br>
      <span style="color: rgb(0, 0, 153);">...</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">import
  org.apache.axis.client.Stub;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">...</span><br style="color: rgb(0, 0, 153);"></br>
      <br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">Remote remote =
  locator.getPort(StockQuoteService.class);</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">Stub axisPort = (Stub)remote;</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">axisPort._setProperty(UsernameToken.PASSWORD_TYPE,
  WSConstants.PASSWORD_DIGEST);</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">axisPort._setProperty(WSHandlerConstants.USER,
  "wss4j");</span><br style="color: rgb(0, 0, 153);"></br>
      <span style="color: rgb(0, 0, 153);">axisPort._setProperty(WSHandlerConstants.PW_CALLBACK_REF,
  pwCallback);</span><br></br>
      <br></br>
  where "pwCallback" is a reference to a PWCallback implementation. See
  the Axis handler for WSS4J documentation for more details on this.<br></br>
      <br></br>
    </li>
    <li>Try modifying your client's PWCallback to return the wrong
  password, or send the wrong username. The service should reject your
  requests.</li>
  </ol>
  <br></br>
  </div><br></br><br></br><div style="margin-left: 40px;"></div></subsection></section></body></document>
  
  
  1.1                  ws-fx/wss4j/xdocs/index.xml
  
  Index: index.xml
  ===================================================================
  <?xml version="1.0" encoding="ISO-8859-1"?>
  <document><properties><title>WSS4J Documentation</title></properties><body><section name="Apache WSS4J"></section><section name=""><subsection name="Contents"><ul>
    <li><a href="#What_is_WSS4J">What is WSS4J?</a></li>
    <li><a href="#WS-Security%20Features">WS-Security Features</a></li>
    <li><a href="#WSS4J_Use_Cases">WSS4J Use Cases</a></li>
    <ul>
      <li>WSS4J API</li>
      <li>WSS4J on Axis<br></br>
      </li>
    </ul>
  </ul><br></br></subsection></section><section name=""><subsection name="What is WSS4J?"><p style="margin-left: 40px;"> 
  Apache WSS4J is an implementation of the
  OASIS Web Services Security (WS-Security) from <a href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss">OASIS
  Web Services Security TC</a>. WSS4J is a primarily a Java library that can be used to sign and verify SOAP Messages 
  with WS-Security information. WSS4J will use Apache Axis and Apache XML-Security projects and will be interoperable 
  with JAX-RPC based server/clients and .NET server/clients.
  <br></br>
  </p><p style="margin-left: 40px;">WSS4J implements<br></br>
  </p><ul style="margin-left: 40px;">
    <li><a href="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf">OASIS
  Web Serives Security: SOAP Message Security 1.0 Standard 200401, March
  2004</a></li>
    <li><a href="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0.pdf">Username
  Token profile V1.0</a></li>
    <li><a href="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0.pdf">X.509
  Token Profile V1.0</a></li>
  </ul><div style="margin-left: 40px;">WSS4J can also be configured to emulate
  previous WSS spec implementations with older namespaces, such as
  WebSphere 5.1 and WebLogic 8.1 SP2.<br></br>
  </div></subsection><subsection name="WS-Security Features"><p style="margin-left: 40px;">WSS4J can generate and process the
  following SOAP Bindings:<br></br>
  </p><ul>
    <ul>
      <li>XML Security<br></br>
      </li>
      <ul>
        <li>XML Signature</li>
      </ul>
      <ul>
        <li>XML Encryption</li>
      </ul>
      <li>Tokens</li>
      <ul>
        <li>Username
  Tokens</li>
        <li>Timestamps</li>
      </ul>
      <ul>
        <li>SAML Tokens</li>
      </ul>
    </ul>
  </ul><div style="margin-left: 40px;">WSS4J supports X.509 binary
  certificates and certificate paths.<br></br>
  <br></br>
  </div><p style="margin-left: 40px;"></p></subsection><subsection name="WSS4J Use Cases"></subsection><subsection name="WSS4J API"><p style="margin-left: 40px;">Please refer to the <a href="api.html">API
  Overview</a>
  for details.<br></br>
  <br></br>
  </p></subsection><subsection name="WSS4J on Axis"><p style="margin-left: 40px;">Please refer to the the <a href="axis.html">Axis
  Deployment Tutorial</a> for a short tutorial and <a href="package.html">Axis Deployment Examples</a> for more details.<br></br>
  </p><br></br></subsection></section></body></document>
  
  
  1.1                  ws-fx/wss4j/xdocs/package.xml
  
  Index: package.xml
  ===================================================================
  <?xml version="1.0" encoding="ISO-8859-1"?>
  <document><properties><title>Axis Deployment Examples</title></properties><body><section><p>
  
  WSS4J 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="Prerequisties"><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/ws-fx/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.PWCallback1"/&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>