<!-- <!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  -->
<html>
<head>
  <title>Web Service Security classes for message creation</title>
<!--

  @(#)Web Service Security classes for message creation 

/*
 * Copyright  2003-2004 The Apache Software Foundation.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 */
-->
</head>
<body bgcolor="white">

The package provides classes to create messages that are compliant to the
OASIS Web Service Security specifications.
<p/>
The OASIS WSS specifications define a number of features and it is possible 
to combine them in several ways. The WSS4J classes 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/>
Currently this package contains two sets of classes that provide the same 
or similar functionality. 
<ul>
  <li>The old classes, named WSAdd*, WSEncryptBody, WSSignEnvelope, WSBaseMessage.
  The usage of these classes is depreciated.</li>
  <li>The new, refactored classes. Their names start with the prefix <e>WSSec</e>.
</ul>

<h3>How to use the WSSec* classes</h3>
The new refactored classes follow the same usage pattern. 
<ol type="1">
  <li>Create an object for the required security element, for example a 
  <code>WSSecSignature</code>.
  </li>
  <li>Set the required fields using setter methods, for example user name, signature
  algorithm, etc.
  </li>
  <li>After the fields are set call <code>prepare(...)</code>. This initializes the internal
  structures, gets the required data like X509 tokens, etc.
  </li>
  <li>After preparation you may do security element specific functions, for example add
  data refernces that should be included in the signature. You can also add the element to
  the <code>WSSecHeader</code> at this time (adding to the security header can be done at any
  time after <code>prepare(...)</code>). See the documentation of the various classes what is
  available.
  </li>
</ol>
In contrast to the old classes the handling of the security header is not longer
implicitly performed. To provide better flexibilty the class <code>WSSecHeader</code>
deals with the security header.
<p/>
The new structure of the classes provide a much more flxible handling of the actions
performed by the classes. This enhanced flexibility enables a precise control of
the placement of security elements in the security header and a much better control
which elements to sign or to encrypt.
<p/>
This code snippet shows how to setup a Signature element:
<pre>
        /*
         * Explicit security header handling. The WSSecHeader object
         * remains the same for all elements that shall go into this
         * security header. Thus you usually need to created one
         * WSSecHeader object only.
         */
        WSSecHeader secHeader = new WSSecHeader();
        secHeader.insertSecurityHeader(doc);


        WSSecSignature builder = new WSSecSignature();

        builder.setUserInfo("username", "password");
        builder.setKeyIdentifierType(WSConstants.ISSUER_SERIAL);

        Document doc = getSOAPEnvelope();

		builder.prepare(doc, crypto, secHeader);

		/*
		 * Set parts to sign
		 */
		Vector parts = new Vector();
		WSEncryptionPart encP = new WSEncryptionPart(localName, namespace, "Content");
		parts.add(encP);

		/*
		 * Add the references to include into Signature. This can be done multiple
		 * times.
		 */
		builder.addReferencesToSign(parts, secHeader);

		/*
		 * Add the Signature now to the security header
		 */
		builder.prependToHeader(secHeader);

		/*
		 * There maybe a BST to prepend it in front of the Signature according to
		 * strict layout rules.
		 */
		builder.prependBSTElementToHeader(secHeader);

		/*
		 * Before calling computeSignature make sure all elements to sign are
		 * available in the document (SOAP Envelope)
		 */
		builder.computeSignature();

</pre>
Each new class also contains a <code>build()</code> method that is similar to the
<code>build()</code> method in the old classes. Thus, if the flexibilty is not
required you may use this method for convenience.

<h3>Each top level security element has wsu:Id or plain Id attribute</h3>
The <code>prepare()</code> method autmatically generates an Id string for each new
element and sets the wsu:Id or plain Id attribute. Which type 
of Id to use is determined by the security element. The <e>EncryptedKey</e> and <e>Signature</e> 
elements have a plain Id according to the W3C specifications, elements defined by 
the OASIS WS Security specifications contain a wsu:Id. 
<p/>
Each <code>WSSec*</code> class has a <code>getId()</code> that returns the id strig
regardless if its qualified or not.
<p/>
The security processing uses these Id to identify each top level security element to
provide additional further processing of an element, for example to encrypt a Signature or
any other top level element. Also a Signature may include each top level element. Which
parts of a message to sign and/or encrypt is controlled by the Security Policy

@since WSS4J 2.0
</body>
</html>