trunk/src/org/apache/ws/security/message/package.html - ws-wss4j - Git at Google

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