IBM Lotus Expeditor is a framework that includes client, server, and tooling and that provides an integrated environment for enterprise applications. IBM Lotus Expeditor Client is built on eRCP and adds J2EE and IBM’s own enterprise application components to eRCP. IBM Lotus Expeditor Server interacts with Lotus Expeditor Client and is well integrated with IBM server software, thus providing a good entry point for building Service-Oriented Architecture (SOA) solutions on Lotus Expeditor. Lotus Expeditor also provides a toolkit to help you if you are not familiar with OSGi Alliance, but know J2EE so that you can quickly and easily build applications for Lotus Expeditor.

Lotus Expeditor follows JSR-172 to provide basic Web services support, and it also implements some other specifications to provide more support for Web services. One of them is the WS-Security implementation, which enables Web services to exchange data securely. Lotus Expeditor supports a subset of the Minimalist Profile (MProf) security profile of WS-Security from OASIS. IBM Lotus Expeditor Toolkit helps you set up the WS-Security-related settings easily, so that you do not have to deal with the complicated XML tags in WS-Security. To work with more advanced operations in WS-Security, though, you need a basic understanding of WS-Security.

To get the most from this article, you should be familiar with XML, Java, Web services, and OSGi framework, and you should have a basic knowledge of encryption and digital signature algorithms as well as plug-in development using Eclipse 3.x technology.

Before completing the steps in this article, you must have IBM Rational Application Developer for WebSphere Software 7.0 with Lotus Expeditor Toolkit V6.1 and Lotus Expeditor installed. Eclipse 3.2 is not sufficient to do this because the GUI editor for Web services security does not run in Eclipse 3.2.

Introduction to WS-Security

WS-Security is an open standard published by OASIS. The goal of this specification is to enable applications to conduct secure SOAP message exchanges. This specification does not invent any new security protocols; instead, it provides a flexible set of mechanisms to use the existing security protocols in Web services. To understand WS-Security, you need to know XML Encryption and XML Signature first.

XML Encryption

XML Encryption is an open specification published by the World Wide Web Consortium (W3C). It defines a set of XML tags and specifies how to use them with existing encryption algorithms to encrypt an XML document. The best way to understand this quickly is through example. Assume that you have your credit card information in an XML document; see listing 1.

<?xml version='1.0'?>
  <PaymentInfo xmlns='http://example.org/payment'>
    <Name>Eric Johnson</Name>
    <CreditCard Limit='10,000' Currency='USD'>
      <Number>4033 0309 2377 5438</Number>
      <Issuer>My Bank</Issuer>
      <Expiration>08/12</Expiration>
    </CreditCard>
 </PaymentInfo>

You don't want others to know the information in the CreditCard element, so you use XML Encryption to encrypt this element as shown in listing 2.

<?xml version='1.0'?>
  <PaymentInfo xmlns='http://example.org/paymentv2'>
    <Name>Eric Johnson</Name>
<EncryptedData xmlns='http://www.w3.org/2001/04/xmlenc#'
        Type='http://www.w3.org/2001/04/xmlenc#Element'/>
     <EncryptionMethod Algorithm='http://www.w3.org/2001/04/xmlenc#tripledes-cbc'/>
     <ds:KeyInfo xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
       <ds:KeyName>Eric Johnson</ds:KeyName>
     </ds:KeyInfo>
     <CipherData><CipherValue>ABCDEFG</CipherValue></CipherData>
</EncryptedData>  
</PaymentInfo>

Note these points:

• As you can see, the CreditCard element is encrypted by XML Encryption. EncryptedData includes the EncryptionMethod, which indicates the encryption algorithm being used.
• KeyInfo gives the receiver information about how to obtain the key.
• CipherData is the encrypted content of the CreditCard element.

XML Encryption is more complex than this example indicates, but the example illustrates its concept so that you can understand this article.

XML Signature

Like XML Encryption, XML Signature is an open specification published by the W3C. It defines a set of XML tags and specifies how to use them with existing signature algorithms to sign an XML document. Listing 3 shows a simple example.

<Signature Id="SampleSignature"
 xmlns="http://www.w3.org/2000/09/xmldsig#"> 
      <SignedInfo> 
      <CanonicalizationMethod
 Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/> 
      <SignatureMethod
 Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1"/> 
      <Reference
 URI="http://www.w3.org/TR/xml-stylesheet/"> 
        <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/> 
        <DigestValue>dadavpoqjepgqpoj3fj99eq9j8nk=</DigestValue> 
      </Reference> 
    </SignedInfo> 
      <SignatureValue>DOADJVOJOEUYYQM</SignatureValue> 
      <KeyInfo> 
       <KeyValue>
         <DSAKeyValue> 
           <A>...</A><D>...</D><G>...
           </G><R>...</R> 
         </DSAKeyValue> 
       </KeyValue> 
      </KeyInfo> 
    </Signature>

The entire signature is represented by a signature element. CanonicalizationMethod is the algorithm used to canonicalize the SignedInfo before the signature is calculated. SignatureMethod indicates the algorithm used to sign this data object. The URI attribute in Reference includes the reference to the resource, which in this case is http://www.w3.org/TR/xml-stylesheet/. DigestMethod is the algorithm used to digest the data object, and DigestValue is the value after the content is digested. SignatureValue is the value after the signature process is done. The KeyInfo element gives the receiver information to get the key of the signature.

The XML Signature process is more complicated than XML Encryption. Follow these detailed steps to generate an XML signature against any data object:

• Reference generation.
  For each data object being signed, do the following:
  
  1. Apply the Transforms as determined by the application, to the data object. This step is optional, and we do not have this in our example.
  2. Calculate the digest value over the data object.
  3. Create a Reference element, including the ID of the data objects (optional), the transform elements (optional), the digest algorithm, and the DigestValue.
• Signature generation.
  For each data object being signed, do the following:
  
  1. Create the SignedInfo element with SignatureMethod, CanonicalizationMethod, and References.
  2. Canonicalize and then calculate the SignatureValue over SignedInfo based on algorithms specified in SignedInfo.
  3. Construct the Signature element that includes SignedInfo, Object (not included in this example), KeyInfo (if necessary), and SignatureValue. Again, XML Signature is more complex than the example indicates, but the example illustrates its concept.

WS-Security

WS-Security is built on XML Encryption and on XML Signature to provide a security solution for Web services. This specification provides three main mechanisms:

• The ability to send a security token as part of a message
• Message integrity
• Message confidentiality

WS-Security uses XML Encryption to provide message confidentiality and XML Signature to provide message integrity along with security tokens to construct security solutions for Web services. To date, WS-Security is the most well-known security specification for Web services, and Lotus Expeditor implements this specification to provide secured Web services.

Listing 4 shows an example of a Web services request SOAP message generated by Lotus Expeditor.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
- <soapenv:Header>
- <w:Security xmlns:w="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-secext-1.0.xsd" 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
soapenv:mustUnderstand="1">
  <w:BinarySecurityToken xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-
  200401-wss-wssecurity-utility-1.0.xsd" 
  EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-
  message-security-1.0#Base64Binary" 
  ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-
  profile-1.0#X509" 
  u:Id="x509bst__8924027784298412302_1171243809506">…
  </w:BinarySecurityToken> 
- <e:EncryptedKey xmlns:e="http://www.w3.org/2001/04/xmlenc#">
  <e:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5" />
- <d:KeyInfo xmlns:d="http://www.w3.org/2000/09/xmldsig#">
….
</d:KeyInfo>
- <e:CipherData>
  <e:CipherValue>…</e:CipherValue> 
  </e:CipherData>
- <e:ReferenceList>
  <e:DataReference URI="#wss_encryption_id_378629557415344846_1171243810598" />
  </e:ReferenceList>
  </e:EncryptedKey>
- <d:Signature xmlns:d="http://www.w3.org/2000/09/xmldsig#">
- <d:SignedInfo xmlns:d="http://www.w3.org/2000/09/xmldsig#" 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:w="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
......
<d:Reference URI="#wss_signature_id_1528272557003819498_1171243809516">
……
  </d:SignedInfo>
  <d:SignatureValue>…</d:SignatureValue> 
- <d:KeyInfo>
- <w:SecurityTokenReference>
  <w:Reference URI="#x509bst__8924027784298412302_1171243809506" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509" /> 
  </w:SecurityTokenReference>
  </d:KeyInfo>
  </d:Signature>
  </w:Security>
  </soapenv:Header>
- <soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" 
u:Id="wss_signature_id_1528272557003819498_1171243809516">
- <e:EncryptedData xmlns:e="http://www.w3.org/2001/04/xmlenc#" 
Id="wss_encryption_id_378629557415344846_1171243810598" 
Type="http://www.w3.org/2001/04/xmlenc#Content">
	…..
  </e:EncryptedData>
  </soapenv:Body>
  </soapenv:Envelope>

As you can see, WS-Security uses XML Encryption to encrypt the message and XML Signature to sign the message. The major difference between WS-Security and XML Encryption/XML Signature is that WS-Security has security tokens in it. WS-Security defines two kinds of security tokens. One is Username Token, which looks like this:

<wsse:UsernameToken wsu:Id="...">
<wsse:Username>...</wsse:Username>
</wsse:UsernameToken>

The Username Token is used to claim the identity through Username. This is a very simple, but sometimes useful approach.

WS-Security also defines the Binary Security Token. The security token in the preceding code contains a Binary Security Token, which is often used to carry a digital certificate. In this case, it carries an X.509 certificate. This Binary Security Token also has an wsu:Id attribute, which is later used in the w:SecurityTokenReference of the XML Signature element to provide key information. This referencing mechanism is also an important part of WS-Security.

Back to top

Creating a Mobile Web Services Provider project with WS-Security enabled

Next, we show you how to use Rational Application Developer 7.0 with Lotus Expeditor Toolkit to create a WS-Security-enabled Web Services Provider project.

1. In Rational Application Developer, switch to the Plug-in Development perspective by selecting Window - Open Perspective - Plug-in Development.
2. Open the New Project wizard by choosing File - New - Project.
3. In the New Project wizard, select Client Services Project, and then click Next.
4. In the Client Services Project wizard, enter WSSProvider in the Project name field, and then click Next as shown in figure 1.
   
   
   Figure 1. Create a Client Services Project
   
   
   
5. In the next window, do not change any default settings. Then click Finish.
6. Create an interface WSSService, and add a method getResult() in it; see listing 5.
   
   
   Listing 5. The WSSService interface
   

   package wssprovider; public interface WSSService { public String getResult(); }

   
   
7. Create a class WSSServiceImpl that implements WSSService as shown in listing 6.
   
   
   Listing 6. The implementation of WSSService
   

   package wssprovider; public class WSSServiceImpl implements WSSService { public String getResult() { return "This is WSSServiceImpl"; } }

   
   
8. Open the New Project wizard as you did in step 2. This time, select Mobile Web Services Provider, and then click Next.
9. Select WSSServiceImpl.java in the Java file field, choose wssprovider.WSSService as the interface you want to expose, and select the Configure Security option. Click Next, and then click Yes when the message dialog box appears. See figure 2.
   
   
   Figure 2. Create Mobile Web Services Provider
   
   
   
10. Click Next in the Data Type Marshalling panel because there are no custom data types.
11. In the Web Services Security settings panel (see figure 3), enter the following:
    
    • In the Web Services Name field, enter WSSServiceService.
    • In the Web Services Port field, enter WSSService.
    • Select the Use template configuration option, and in the Client field enter "Lotus Expeditor 6.1.x and WED 6.0" In the Security template field, select Signing and encryption.
    • Click Finish.
    
    
    Figure 3. Web Services Security settings
    
    
    In the Client type field, you selected Lotus Expeditor 6.1.x and WED 6.0 because you plan to run the provider in Lotus Expeditor runtime. If you plan run the provider in IBM WebSphere Application Server, select the WebSphere Application Server that matches your version in the drop-down list.
12. After you create the provider, open the wssecurity.xml file generated by Lotus Expeditor Toolkit. You see the Web Services security settings editor shown in figure 4.
    
    
    Figure 4. Web Services Security Extensions settings page
    
    
    

The Web Services Security Extensions tab defines the security policies to be applied, and the Web Services Security Binding tab defines how to apply these policies. We discuss this later after we complete our Web Services project.

Back to top

Creating a Mobile Web Services consumer project with WS-Security enabled

In this section, we show you how to create a WS-Security enabled Web Services consumer project with Rational Application Developer 7.0 and Lotus Expeditor Toolkit.

1. Repeat steps 2-5 in "Creating a Mobile Web Services provider project with WS-Security enabled," and change the project name to WSSConsumer.
2. Choose File - New - Other to open the New Project wizard.
3. Select Client Services - Mobile Web Services - Mobile Web Services Client, and click Next.
4. Enter the following information in the fields as shown in figure 5:
   
   • In the Source folder field, select /WSSConsumer/src.
   • In the Package field, enter wssconsumer.
   • In the WSDL location field, select Settings/JYHSU/IBM/rationalsdp7.0/workspace/WSSProvider/WSSServiceImpl.wsdl.
   • Select the Configure Security option.
   • Click Next.
   
   
   Figure 5. Creating the Mobile Web Services Client
   
   
   
5. In Web Services Security settings, enter the following information:
   
   • In the Web Services Name field, select WSSServiceService from the drop-down list.
   • In the Web Services Port field, select WSSService from the drop-down list.
   • Select the Use template configuration option.
   • In the Client type field, select Lotus Expeditor 6.1.x and WED 6.0 from the drop-down list.
   • In the Security template field, select Signing and encryption from the drop-down list.
6. Click Finish.

You see the Web Services security settings editor similar to the one you see in the provider project. Here we briefly explain the use of some fields in the Web Services Extension and Web Services Binding tabs.

Web Services Extension tab

The Web Services Extension tab is the editor of ibm-webservices-ext.xmi. It is not recommended that you edit the XMI file directly; instead, use this editor to edit it. Note, though, that this editor is not available if you are using Eclipse.

There are two parts in this file: Request and Response. The Request Generator in the client side and the Response Consumer in the provider side define how the outbound SOAP message looks in the client side and how the server consumes the SOAP message. In contrast, the Request Generator in the provider side defines how the inbound SOAP message looks in the client side, and the Response Consumer in the client side defines how the client consumes this SOAP message.

All settings in Web Services Extension and Web Services Binding are automatically generated by Lotus Expeditor Toolkit by default. Your application works if you don’t change anything. Here we tell you what some important fields do, so that you know how to change them if you don't like the default settings.

There are not many things in the default-generated Extension file. The most important thing here is to define the parts in the SOAP message to be signed and encrypted as well as whether or not you want to add a timestamp in the message. These are defined in the Integrity, Confidentiality, and Add Timestamp fields. If you expand the Integrity field and choose to edit the existing integrity, you see the dialog box shown in figure 6.

This means that the SOAP body and timestamp element are signed. You can add and remove the parts you want to sign in this SOAP message by clicking Add or Remove and choosing the Parts Keyword. The Confidentiality field is similar to this, and the Add Timestamp field is very straightforward, so we do not cover them in this article.

Web Services Binding tab

The Web Services Binding tab is the editor of ibm-webservices-bnd.xmi. While Web Services Extension defines what the SOAP message looks like, Web Services Bindings defines how to protect each part. You can choose the security algorithms, keystores, and keys that you want to use in the SOAP message.

To explain this, it's better to start from the Signing Information in Request Generator of the client side because most fields are either directly or indirectly referenced by this field. First, expand Security Request Generator Binding, and then expand Signing Information. Click Edit on gen_dsig to see the settings shown in figure 7.

Figure 7 defines the canonicalization algorithm and signature algorithm used in the XML Signature process. You can change the algorithm by selecting available algorithms in the drop-down list. The Key information element defines the reference to the element that defines how to construct the KeyInfo element in XML Signature. Now, click OK to close this dialog box and to go back to the Web Services Binding tab, and then expand Key Information and click Edit on gen_dsigkeyinfo to get to the dialog box shown in figure 8.

Here you define how to construct the KeyInfo element. You have gen_klocator to define where to acquire the key and gen_dsigtgen to define how to construct the security token including the key. We don't suggest that you change settings in this dialog box because they are complicated and you may make a mistake if you don't take care; also, people do not change them very often. We open this dialog box to show you the other two important setting fields, gen_klocator and gen_dsigtgen, that are being referenced. Now click OK to close this dialog box and to go back to the Web Services Binding tab. Then, expand Key Locator and choose Edit on gen_klocator as shown in figure 9.

Key Locator defines where you can acquire the key. By default, Lotus Expeditor uses the key from the built-in keystore that is generated when the Web services project is created. You can replace it with your own keystore if you want.

Now click OK to close this dialog box and to go back to the Web Services Binding tab. Then expand Token Generator and click Edit on gen_dsigtgen to get to the dialog box shown in figure 10.

Here you generate an X.509 certificate token and use the key from the default keystore. Again, you can change the keystore if you want.

Now click OK to close this dialog box and to go back to the Web Services Binding tab. Then expand Part References and click Edit on int_body. You can change the digest and transform algorithms in this dialog box by choosing them from the drop-down list.

The encryption settings are very similar and easier than the signature settings, so we do not cover those details here.

Back to top

Deploy and run the provider and consumer to Lotus Expeditor Client

In this section, we show you how to deploy and how to run the WS-Security enabled Web services provider and consumer in the test runtime provided by Lotus Expeditor Toolkit.

1. Choose Run - Run to open the Run wizard.
2. Select Client Services, and then click the New icon at the top left of the screen. See figure 12.
   
   Figure 12. Run configuration
   
   
   
3. In the New_configuration dialog box, select the Plug-ins tab. You see that all plug-ins are selected by default. Deselect Workspace Plug-ins to uncheck all plug-ins that are in your workspace, and then check WSSConsumer and WSSProvider as shown in figure 13.
   
   Figure 13. Plug-ins tab
   
   
   
4. Click the Add Required Plug-ins button, and then click Apply.
5. Select the Arguments tab and change –Dcom.ibm.pvc.webcontainer.port=0 to 8777 as shown in figure 14. Then click Run.
   
   Figure 14. Arguments tab
   
   
   
6. In the Console tab, enter ss and find the bundle numbers of WSSConsumer, WSSProvider, com.ibm.pvc.webcontainer, and org.eclipse.equinox.http. See figure 15.
   
   Figure 15. The runtime console
   
   
   The ID of com.ibm.pvc.webcontainer is shown in figure 16.
   
   Figure 16. ID of com.ibm.pvc.webcontainer
   
   
   
7. Start the bundle com.ibm.pvc.webcontainer and org.eclipse.equinox.http by entering start xx in the console where xx is the bundle ID of the bundle. For example, to start webcontainer here, enter start 207.
8. Start WSSProvider.
9. Open your browser, and connect to http://localhost:8777/ws/pid/WSSServiceImpl to see if the service is correctly deployed. If so, you see the WSDL of this Web service.
10. Start WSSConsumer to see the response message. From the log shown in figure 17, you can see that the request and response SOAP message are really secured.
    
    Figure 17. The log after running the sample application
    
    
    

You can check the log to see which SOAP message is being sent. We suggest that you print the log to the console to make sure that the messages being transferred are secured. If you use the default setting, you do not see the log in the console.

Back to top

Conclusion

This article briefly introduced the WS-Security specification, which is the Web service security standard that Lotus Expeditor supports. Then we showed how to create, deploy, and run secured Web services using Lotus Expeditor Toolkit with Rational Application Developer 7. We also showed how to tune the security settings through the GUI editor.

Resources

Learn

• Read the developerWorks Lotus article, "Using the Personal Wizards plug-in in IBM Lotus Expeditor."
  
  
• Read the developerWorks Lotus article, "Migrating J2EE projects to IBM Lotus Expeditor V6.1."
  
  
• Read the developerWorks Lotus article, "End-to-end integration with pervasive messaging and IBM Lotus Expeditor micro broker."
  
  
• Read the developerWorks Lotus article, "Building an offline application in IBM Lotus Expeditor."
  
  
• Read the developerWorks Lotus article, "Developing and deploying rich client applications on desktops and mobile devices using IBM Lotus Expeditor V6.1."
  
  
• Read the developerWorks Lotus article, "Migrating Eclipse RCP applications to IBM Lotus Expeditor."
  
  
• Read the developerWorks Lotus article, "Creating collaborative components for IBM Lotus Expeditor Property Broker."
  
  
• Read the developerWorks Lotus article, "Developing an OSGi service as a Web service in IBM Lotus Expeditor."
  
  
• Read the developerWorks Lotus article, "Building and deploying a simple Web Services Resource in IBM Lotus Expeditor."
  
  
• Read the IBM Redbooks publication, Building Composite Applications in Lotus Expeditor V6.1.
  
  
• Read the developerWorks Lotus Expeditor page.
  
  
• Refer to the IBM Lotus Expeditor Education Assistant.
  
  
• Refer to the IBM Lotus Expeditor documentation.
  
  

Get products and technologies

• Download a trial version of the IBM Lotus Expeditor V6.1 Toolkit.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Participate in the developerWorks Lotus team blog.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction to WS-Security
• Creating a Mobile Web Services Provider project with WS-Security enabled
• Creating a Mobile Web Services consumer project with WS-Security enabled
• Deploy and run the provider and consumer to Lotus Expeditor Client
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Lotus Expeditor toolkit
• Webcast: A Smart Approach to Core Banking Renovation in a Tough Economic Climate
• Briefing: Smarter collaboration with IBM Lotus solutions
• Buy: Lotus Expeditor toolkit

My developerWorks community

Dig deeper into Lotus on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers