| <?xml version="1.0" encoding="ISO-8859-1"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You 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. |
| --> |
| <document> |
| <body> |
| <section name="Axis1 Deployment Tutorial"> |
| <p> |
| WSS4J 1.5.x 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="Prerequisites"><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> |
