src/org/apache/ws/security/policy/parser/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>Parser for Web Services Security Policy Language</title>
 <!--

   @(#)Parser for Web Services Security Policy Language

 /*
  * Copyright 2004,2005 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">

 This parser shows how to use the generic Policy implementation to read, process,
 and decide on policies. The generic Policy implementation provides the framework
 to read, normalize, merge, and intersect policies. The generic implementation
 follows the specifications laid down in the document
 <a href="http://www-128.ibm.com/developerworks/webservices/library/specification/ws-polfram/">
 <i>Web Services Policy Framework</i></a>.
 <p/>
 The <i>Parser for Web Services Security Policy Language</i> uses the generic policy
 implementation to read, normalize, and merge Web Service Sercurity policy files. The
 parser then parses and processes the specific Web Services Security Policy assertions.
 The document <a href="http://www-128.ibm.com/developerworks/library/specification/ws-secpol/">
 <i>Web Services Security Policy Language</i></a> defines the specific Web Service
 Security Policy assertions.
 <p/>
 This is an example and the parser provides a skeleton for further development. Currently
 the processing methods of all assertions return <code>true</code>, that is every assertion
 is accepted.

 <h3>Prerequisties</h3>
 To be able to run the generic Policy implementation and the associated examples you
 need several additonal Jar files from the current Axis2 development because some
 examples use the StAX API and the OM XML datamodell implemented in Axis2. Currently
 you need

 <ul>
   <li>Axis2-0.94.jar</li>
   <li>axis2-wsdl-0.94.jar</li>
   <li>axis2-common-0.94.jar</li>
   <li>wsdl4j-1.5.1.jar</li>
   <li>stax-api-1.0.jar</li>
   <li>stax-1.1.2.jar</li>
 </ul>

 In addition you also need the ubiquitous log4j, junit and commons-logging jars. At least
 this is the enviroment I currently use. For the Axis2 files you may use the according
 *SNAPSHOT.jar files as well.

 <h3>How does it work</h3>
 The main class is <code>WSSpolicyProcessorFull</code>. At first it populates the top level
 token with all security policy tokens/assertions known at the top level. All
 tokens/assertions are pre-initialized in the <code>SecurityPolicy</code> class file. We always
 use copies of the pre-initialized token structures. During setup the parser initializes
 the top level tokens with the objects that contain the processing methods for the
 tokens.
 <p/>
 There are two types of security policy tokens: <i>simple</i> tokens and <i>complex</i> tokens.
 Simple tokens stand for themself and do not contains subtokens or assertions. Simple
 tokens switch on properties of define a specific behaviour. Complex token contain other
 tokens and assertions. At the top level we only have complex tokens (refer to the <code>
 setup</code> method).
 <p/>
 When the parser finds a security policy assertion (<code>PrimitiveAssertion</code>) it starts
 a policy transaction (<code>startPolicyTransaction</code>). The start policy transaction
 checks if the current token contains this assertion as a child assertin. If the parser finds the
 assertion it sets up the parser context and calls the assertion's processing function. The
 processing functions use the following naming pattern: use the token's name and prepend
 this name with the string <i>do</i>. For example: the processing method of the <i>X509Token</i>
 has the name <code>doX509Token</code>. Each processing function of a complex token
 initializes its child tokens on the first call of the processing function (lazy initialization).
 <p/>
 If all children of an assertion/token are processed the policy transaction is either committed or aborted
 depending on the outcome of the processing of the child tokens. During commit transaction
 the information gathered during the processing of the child tokens can be check, validated,
 and mixed with other data. These functions are not implemented in this example. If a transaction
 has to be aborted you can perform some cleanup.
 <p/>
 All policies are parsed recursively. If a policy containes alternatives the first alternative
 that matches or can be processed is chosen.

 <h3>Missing stuff</h3>
 As noted before this is an example and provides some ideas how to implement a security
 policy parser. Not all top level tokens are implemented as processors (all assertions/tokens are
 pre-initialized in SecurityPolicy). The following processors are currently missing:

 <ul>
   <li>IssuedToken</li>
   <li>KerberosToken</li>
   <li>SpnegoContextToken</li>
   <li>SecurityContextToken</li>
   <li>SecureConversationToken</li>
   <li>SamlTokenAssertion</li>
   <li>RelTokenAssertion</li>
 </ul>

 <!-- Put @see and @since tags down here. -->
 @since  Parser for Web Services Security Policy Language 1.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>Parser for Web Services Security Policy Language</title>
	<!--

	@(#)Parser for Web Services Security Policy Language

	/*
	* Copyright 2004,2005 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">

	This parser shows how to use the generic Policy implementation to read, process,
	and decide on policies. The generic Policy implementation provides the framework
	to read, normalize, merge, and intersect policies. The generic implementation
	follows the specifications laid down in the document
	<a href="http://www-128.ibm.com/developerworks/webservices/library/specification/ws-polfram/">
	<i>Web Services Policy Framework</i></a>.
	<p/>
	The <i>Parser for Web Services Security Policy Language</i> uses the generic policy
	implementation to read, normalize, and merge Web Service Sercurity policy files. The
	parser then parses and processes the specific Web Services Security Policy assertions.
	The document <a href="http://www-128.ibm.com/developerworks/library/specification/ws-secpol/">
	<i>Web Services Security Policy Language</i></a> defines the specific Web Service
	Security Policy assertions.
	<p/>
	This is an example and the parser provides a skeleton for further development. Currently
	the processing methods of all assertions return <code>true</code>, that is every assertion
	is accepted.

	<h3>Prerequisties</h3>
	To be able to run the generic Policy implementation and the associated examples you
	need several additonal Jar files from the current Axis2 development because some
	examples use the StAX API and the OM XML datamodell implemented in Axis2. Currently
	you need

	<ul>
	<li>Axis2-0.94.jar</li>
	<li>axis2-wsdl-0.94.jar</li>
	<li>axis2-common-0.94.jar</li>
	<li>wsdl4j-1.5.1.jar</li>
	<li>stax-api-1.0.jar</li>
	<li>stax-1.1.2.jar</li>
	</ul>

	In addition you also need the ubiquitous log4j, junit and commons-logging jars. At least
	this is the enviroment I currently use. For the Axis2 files you may use the according
	*SNAPSHOT.jar files as well.

	<h3>How does it work</h3>
	The main class is <code>WSSpolicyProcessorFull</code>. At first it populates the top level
	token with all security policy tokens/assertions known at the top level. All
	tokens/assertions are pre-initialized in the <code>SecurityPolicy</code> class file. We always
	use copies of the pre-initialized token structures. During setup the parser initializes
	the top level tokens with the objects that contain the processing methods for the
	tokens.
	<p/>
	There are two types of security policy tokens: <i>simple</i> tokens and <i>complex</i> tokens.
	Simple tokens stand for themself and do not contains subtokens or assertions. Simple
	tokens switch on properties of define a specific behaviour. Complex token contain other
	tokens and assertions. At the top level we only have complex tokens (refer to the <code>
	setup</code> method).
	<p/>
	When the parser finds a security policy assertion (<code>PrimitiveAssertion</code>) it starts
	a policy transaction (<code>startPolicyTransaction</code>). The start policy transaction
	checks if the current token contains this assertion as a child assertin. If the parser finds the
	assertion it sets up the parser context and calls the assertion's processing function. The
	processing functions use the following naming pattern: use the token's name and prepend
	this name with the string <i>do</i>. For example: the processing method of the <i>X509Token</i>
	has the name <code>doX509Token</code>. Each processing function of a complex token
	initializes its child tokens on the first call of the processing function (lazy initialization).
	<p/>
	If all children of an assertion/token are processed the policy transaction is either committed or aborted
	depending on the outcome of the processing of the child tokens. During commit transaction
	the information gathered during the processing of the child tokens can be check, validated,
	and mixed with other data. These functions are not implemented in this example. If a transaction
	has to be aborted you can perform some cleanup.
	<p/>
	All policies are parsed recursively. If a policy containes alternatives the first alternative
	that matches or can be processed is chosen.

	<h3>Missing stuff</h3>
	As noted before this is an example and provides some ideas how to implement a security
	policy parser. Not all top level tokens are implemented as processors (all assertions/tokens are
	pre-initialized in SecurityPolicy). The following processors are currently missing:

	<ul>
	<li>IssuedToken</li>
	<li>KerberosToken</li>
	<li>SpnegoContextToken</li>
	<li>SecurityContextToken</li>
	<li>SecureConversationToken</li>
	<li>SamlTokenAssertion</li>
	<li>RelTokenAssertion</li>
	</ul>

	<!-- Put @see and @since tags down here. -->
	@since Parser for Web Services Security Policy Language 1.0
	</body>
	</html>