Added: webservices/wss4j/trunk/src/site/xdoc/package.xml URL: http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/site/xdoc/package.xml?rev=1076594&view=auto ============================================================================== --- webservices/wss4j/trunk/src/site/xdoc/package.xml (added) +++ webservices/wss4j/trunk/src/site/xdoc/package.xml Thu Mar 3 11:48:46 2011 @@ -0,0 +1,648 @@ +<?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/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> + <!-- define the service, use the WSDoAllSender security handler in request flow --> + <service name="Ping1"> + <requestFlow> + <handler type="java:org.apache.ws.axis.security.WSDoAllSender" > + <parameter name="action" value="UsernameToken"/> + <parameter name="user" value="werner"/> + <parameter name="passwordType" value="PasswordText" /> + <parameter name="passwordCallbackClass" + value="org.apache.ws.axis.oasis.PWCallback1Out"/> + </handler> + </requestFlow> + </service> +</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> +<?xml version="1.0" encoding="UTF-8"?> +<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"; + xmlns:xsd="http://www.w3.org/2001/XMLSchema"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> + <soapenv:Header> + <wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"; + soapenv:mustUnderstand="true"> + <wsse:UsernameToken> + <wsse:Username>werner</wsse:Username> + <wsse:Password Type="wsse:PasswordText">security</wsse:Password> + </wsse:UsernameToken> + </wsse:Security> + </soapenv:Header> + <soapenv:Body> + <Ping xmlns="http://xmlsoap.org/Ping"> + <text>Scenario 1 text</text> + <ticket xmlns:ns1="http://xmlsoap.org/Ping"; + xsi:type="ns1:ticketType">scenario1</ticket> + </Ping> + </soapenv:Body> +</soapenv:Envelope> +</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 < 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> + <requestFlow> + <handler type="java:org.apache.ws.axis.security.WSDoAllReceiver"> + <parameter name="passwordCallbackClass" + value="org.apache.ws.axis.oasis.PWCallback"/> + <parameter name="action" value="UsernameToken"/> + </handler> + </requestFlow> +</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> + <requestFlow> + <handler type="java:org.apache.ws.axis.security.WSDoAllSender" > + <parameter name="action" value="UsernameToken Encrypt"/> + <parameter name="user" value="werner"/> + <parameter name="passwordCallbackClass" + value="org.apache.ws.axis.oasis.PWCallback"/> + <parameter name="passwordType" value="PasswordText" /> + <parameter name="addUTElement" value="Nonce Created" /> + <parameter name="encryptionPropFile" value="crypto.properties" /> + <parameter name="encryptionKeyIdentifier" value="X509KeyIdentifier" /> + <parameter name="encryptionUser" + value="16c73ab6-b892-458f-abf5-2f875f74882e" /> + <parameter name="encryptionParts" + value="{Element}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd}UsernameToken"; /> + </handler> + </requestFlow> +</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> + <requestFlow> + <handler type="java:org.apache.ws.axis.security.WSDoAllReceiver"> + <parameter name="passwordCallbackClass" + value="org.apache.ws.axis.oasis.PWCallback"/> + <parameter name="action" value="UsernameToken Encrypt"/> + <parameter name="decryptionPropFile" value="crypto.properties" /> + </handler> + </requestFlow> +</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> +<requestFlow> + <handler type="java:org.apache.ws.axis.security.WSDoAllSender" > + <parameter name="user" value="16c73ab6-b892-458f-abf5-2f875f74882e"/> + <parameter name="passwordCallbackClass" + value="org.apache.ws.axis.oasis.PWCallback"/> + <parameter name="action" value="Signature Encrypt"/> + <parameter name="signaturePropFile" value="crypto.properties" /> + </handler> +</requestFlow> +</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> +<requestFlow> + <handler type="java:org.apache.ws.axis.security.WSDoAllReceiver"> + <parameter name="passwordCallbackClass" + value="org.apache.ws.axis.oasis.PWCallback"/> + <parameter name="action" value="Signature Encrypt"/> + <parameter name="signaturePropFile" value="crypto.properties" /> + </handler> + </requestFlow> +</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> + <requestFlow> + <handler type="java:org.apache.ws.axis.security.WSDoAllSender" > + <parameter name="action" value="Signature NoSerialization"/> + <parameter name="user" value="firstUser"/> + <parameter name="passwordCallbackClass" + value="org.apache.ws.axis.oasis.PWCallback"/> + <parameter name="signaturePropFile" value="crypto.properties" /> + <parameter name="signatureParts" value="{}{http://xmlsoap.org/Ping}ticket"; /> + </handler> + <handler type="java:org.apache.ws.axis.security.WSDoAllSender" > + <parameter name="action" value="Signature"/> + <parameter name="user" value="anotherUser"/> + <parameter name="passwordCallbackClass" + value="org.apache.ws.axis.oasis.PWCallback"/> + <parameter name="signaturePropFile" value="crypto.properties" /> + </handler> + </requestFlow> +</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> + <requestFlow> + <handler type="java:org.apache.ws.axis.security.WSDoAllReceiver"> + <parameter name="passwordCallbackClass" + value="org.apache.ws.axis.oasis.PWCallback"/> + <parameter name="action" value="Signature Signature"/> + <parameter name="signaturePropFile" value="crypto.properties" /> + </handler> + </requestFlow> +</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 < results.size(); i++) { + WSHandlerResult hResult = (WSHandlerResult)results.get(i); + String actor = hResult.getActor(); + Vector hResults = hResult.getResults(); + for (int j = 0; j < 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> \ No newline at end of file
Added: webservices/wss4j/trunk/src/site/xdoc/rampart.xml URL: http://svn.apache.org/viewvc/webservices/wss4j/trunk/src/site/xdoc/rampart.xml?rev=1076594&view=auto ============================================================================== --- webservices/wss4j/trunk/src/site/xdoc/rampart.xml (added) +++ webservices/wss4j/trunk/src/site/xdoc/rampart.xml Thu Mar 3 11:48:46 2011 @@ -0,0 +1,7 @@ + <subsection name="Rampart: WS-Security Implementation module for Axis2"> + <p style="margin-left: 40px;">Please refer to the + <a href="http://ws.apache.org/axis2/modules/rampart/1_2/security-module.html";> + Rampart configuration guide</a> for configuration information.<br/> + </p> + <br/> + </subsection> \ No newline at end of file
