Introduction

This article assumes that you've read the first two installments of this series and are familiar with the healthcare reservation system and its architectural framework at the heart of this scenario.

In this scenario, remote medical offices completely delegate the function of client office visits to a centralized system that prepares the data for each service provider (medical office), encrypts the confidential information through a WebSphere DataPower XML Security Gateway XS40 box and, thus, sends it to WebSphere Enterprise Service Bus. The complete architectural picture is shown below in Figure 1.

This section provides detailed information about instrumenting WebSphere Enterprise Service Bus to:

• Recognize encrypted data: WebSphere Enterprise Service Bus has strict schema validation features that apply to data coming through its export bindings. If the format of the incoming message doesn't match the definition of the export interface, the message is discarded from WebSphere Enterprise Service Bus and an exception is raised. You must instrument WebSphere Enterprise Service Bus, as far as the encrypted data's structure, providing ad hoc data types and interfaces.
• Perform protocol switching: WebSphere Enterprise Service Bus gets these messages as SOAP/HTTP requests and then forwards them to the Java™ Message Service (JMS) topic using specific import and export bindings. The export binding describes how a client communicates with the mediation module. The import binding, instead, describes how the mediation module communicates with the defined service. Bindings guarantee transparent transport protocol switching capabilities and make it possible for the central reservation system to connect to the medical offices without any communication logic required within the application code.
  
  Figure 2. Protocol switching
  
  
  
• Make use of message selectors: According to JMS specifications, a JMS client can filter by message selectors to understand which messages it should process. Because each medical office would like to receive only the data destined to it, the JMS message should contain the serviceProviderId in the header. Starting from the 6.0.2 release, WebSphere Enterprise Service Bus provides a message element setter mediation primitive that you can use for this purpose: When the mediation module gets a request message, it inspects the incoming message format, leverages the message setter primitive to retrieve the service provider ID from the SOAP body, and stores it (through a copy action) in the output message's JMS header (see Figure 3).
  
  Figure 3. Message selectors
  
  
  

To implement the described scenario, we defined a mediation module and wired it to a SOAP/HTTP export binding and a JMS import binding.

Back to top

Mediation module

The mediation module is composed of four functional pieces:

• An export interface to get the SOAP HTTP message containing sensitive data
• A message selector to augment the JMS message header with selectors information
• An XSLT transformation that matches the import and export interfaces and, thus, shows you how it's possible to provide some mediation logic, even when the message contains encrypted data
• An import interface that sends the sensitive data to the topic as a JMS payload

Figure 4 illustrates the mediation module.

This article shows you how to build all the functional parts that the mediation module is composed of. In the following sections, you can find detailed information to complete the steps needed to do the following:

• Create a new library.
• Define data types.
• Define export and import interfaces.
• Define the mediation module.

Back to top

Create a new library

As a first step, you should create a new library in which to store both the data types and the import and export interfaces to be used within the mediation module. You do this by following these steps:

1. Select File > New > Project. A new window appears.
2. Select Library (see Figure 5).
   
   Figure 5. New project
   
   
   
3. In the window that opens, type Asynch-Library in the Library Name field, and keep the Use Default check box flagged.
4. Click Finish. The wizard takes a second to generate the library (see Figure 6).
   
   Figure 6. New library
   
   
   

Back to top

Define data types

If you looked carefully at the previous articles of this series, Part 2 in particular, you should know the format of the SOAP message coming from the central reservation system. It contains all the information concerning the calendar of the reserved slots, as displayed in Listing 1.

                
<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soapenc="http://schemas.XMLsoap.org/soap/encoding/"
 xmlns:soapenv="http://schemas.XMLsoap.org/soap/envelope/">
 <soapenv:Header/>

  -<soapenv:Body>
   -<p374:sendUpdatedAgenda xmlns:p734="http://Asynch_Library/AsynchResSystemExport">
    <xenc:EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Element"
    xmls:xenc="http://www.w3.org/2001/04/xmlenc#"/>
    <xenc:EncryptionMetod Algorithm=""http://www.w3.org/2001/04/xmlenc#triplesdes-cbc"/>

     -<dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
       <xenc:EncryptedKey Recipient="name:ASL1_cert">
       <xenc:EncryptedMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"

        -<xenc:ChiperData>
         <xenc:ChiperValue >AIWDQKgc09cBkwjXNPQ8NleT5ZMvuLqQJZUijEXsvvBzhclT
         czzDbFGTh67n9NMlpoiu)0p)xcfDATfgJuWQ+KKLN7DsErt543lkvuHTP+lllCV=OPPmhjkoik
         jRT4589JCdxzT432LLp098B00 </xenc:ChiperValue>
         </xenc:ChiperData>
         </xenc:EncryptedKey >
      </dsig:KeyInfo >
      </xenc:ChiperData>
      </xenc:EncryptedData>

  <serviceProviderId >ASL1<serviceProviderId >
 </p374:sendUpdatedAgenda >
</soapenv:Body>
</soapenv:Envelope>

As you can see in Listing 1, the sensitive data are included within an EncryptedData section. Because WebSphere Enterprise Service Bus performs schema validation on the messages coming through its export binding, it's clear that it's necessary to make WebSphere Enterprise Service Bus aware of the EncryptedData definition.

If you look carefully at the format of the message, you see that the EncryptedData element is officially defined in the W3C Standard XML encryption namespace. You can also see that as far as the KeyInfo is concerned, its definition is part of the XML digital signature namespace. For this reason, if you import from the official W3C site (see the Resources section for the URL), both the xenc-schema, including the definition of the XML encryption namespace and the xmldixencg-core schema containing the definition of the XML digital signature namespace, you should have a good chance to make WebSphere Enterprise Service Bus aware of the EncryptedData type definition.

To import these schemas:

1. In the IBM WebSphere Integration Developer console, select File > New > Other. In the window that opens, check the Show All Wizards box, then expand the XML folder, and select XML Schema, as shown in Figure 7.
   
   Figure 7. New XML schema
   
   
   
2. If a window opens asking you for the enablement of the XML development capabilities, click OK to allow the required capability (see Figure 8).
   
   Figure 8. Confirm enablement
   
   
   
3. Type xmldsig-core-schema.xsd in the File name field, select the previous created library as the schema location, and then click Finish, as shown in Figure 9.
   
   Figure 9. Create XML schema
   
   
   
4. In the schema editor that opens, cancel the whole content of the file. Then download the xenc schema from the Download section of this article. Copy the content of this schema, and paste it in the schema editor. Finally, save the file.
5. You should get an error message complaining of a duplicated attribute, PGPKeypacket, in the newly created schema. This problem is due to the fact that, as far as the 6.0.2 FP 1 release is concerned, WebSphere Enterprise Service Bus doesn't support choice elements and, thus, sees two PGPKeypackets within the same schema definition (even if the choice oppositely marks these as two alternative paths), as shown in Figure 10.
   
   Figure 10. Mediation module
   
   
   This bug has been resolved since the new 6.1 release. To solve this problem, cancel one of the two sequence elements within the choice. We decided to remove the second one. Clearly when removing one of the two sequences, the choice construct is useless, so you must remove it, too, from the schema. If you save the schema, the previous error should disappear.
6. Following the above steps, create a new XSD file, and name it xenc-schema.xsd (see Figure 11).
   
   Figure 11. XSD core schema
   
   
   In the XSD schema editor that opens, cancel the whole content of the file. Then download the xenc-schema.xsd schema from the Download section of this article. Copy the content of this schema, and paste it in the XSD schema editor. Save the file; you shouldn't get any error this time.
7. When you save the files, the wizard automatically parses the schemas and generates a new data type for each element type defined within the schema. You can easily verify this by expanding Data Types under the Asynch-Library (see Figure 12).
   
   Figure 12. Data types
   
   
   

In particular, the wizard generates an EncryptedDataType data type that, as far as WebSphere Enterprise Service Bus's schema validation is concerned, seems to be the natural counterpart for matching the sensitive data contained within the EncryptedData section. This said, creating a new export interface and using an EncryptedData object of type EncryptedDataType might let the encrypted data pass through WebSphere Enterprise Service Bus. (This isn't totally true, because a light adjustment is needed, as you'll see in the following section; but you're on the right path.)

Back to top

Define the export/import interface

Now you're ready to define the interfaces. You need an export interface for the sendUpdatedAgenda and an import interface for the publishAgenda asynchronous interaction.

1. Right-click the Asynch-Library project, and select New > Interface. Name it AsynchResSystemExport, and click the Finish button (see Figure 13).
   
   Figure 13. New export interface
   
   
   
2. In the window that appears, select the Add One Way Operation icon to add a new operation (remember the use case requires an asynchronous interaction). Name the new operation sendUpdatedAgenda, and add the following two parameters (using the Add Input icon):
   • EncryptedData of type EncryptedDataType
   • serviceProviderId as a String
   
   
   Figure 14. Export interface
   
   
   Click Save, and close the interface dialog.
3. Even if this interface definition seems at first glance to perfectly match the SOAP message's format, in reality this isn't completely true. If you open the interface definition by right-clicking it and choosing the open with the XML editor option, you see that the wizard generated with the EncryptedData element in the Asynch-Library namespace doesn't match with the EncryptedData element of the xmlenc namespace. To solve this problem, comment out the element marked in red, and replace it with the element marked in green, which is a real reference to the EncryptedData element of the xmlenc namespace, as shown in Figure 15.
   
   Figure 15. Asynchronous resource system export
   
   
   
4. After completing the above step, choose New Import Interface to add a new interface for the import binding, as shown in Figure 16.
5. Right-click the Interface folder within the Asynch-Library, and select New > Interface.
6. Select Asynch-Library from the Module list, and type AsynchResSystemImport into the Name field.
   
   Figure 16. New import interface
   
   
   
7. In the interface dialog box that opens, select the Add One Way Operation icon to add a new operation. Name the operation publishAgenda, and add a new EncryptedData parameter of type EncryptedDataType (see Figure 17).
   
   Figure 17. Publish agenda
   
   
   
8. Repeat step 5 to change the EncryptedData element definition in the Import Interface.
   
   Figure 18. Asynchronous resource system import
   
   
   
9. Save the WSDL file and close it.

   The above modifications aren't the only ones to be performed to make encrypted data correctly pass through WebSphere Enterprise Service Bus and have this data rightly copied as a JMS textual payload. If you look at the SOAP message format, you see that the KeyInfo element contains an EncryptedKey element embedding all the information, as far as the encryption algorithm used to encrypt the key and the encrypted form of the key. Being the KeyInfo defined in the xmldsig namespace, you'd expect to find the EncryptedKey element listed within the complex type definition of the KeyInfo element within the schema. However, if you open the xmldsig-core-schema.xsd file through the XML editor and look for the KeyInfo definition, you should see something like Figure 19.

   
   
   Figure 19. xmldsig-core-schema
   
   
   As you can see, there's no mention of the EncryptedKey element, but the schema assumes that any element can be added to complete the KeyInfo definition. As a consequence of this, using this schema makes WebSphere Enterprise Service Bus ignore any EncryptedKey information within an incoming SOAP message. So if no change is performed, this piece of information is missed and not copied to the JMS payload (you get a better understanding of what this means in the section dealing with the XSLT transformation). To overcome this limitation, you should perform a light change in the xmldsig-core-schema.xsd schema.
10. You should comment out the row in blue and add the row in red, as shown in Figure 20.
    
    Figure 20. xmldsig-core-schema
    
    
    
11. Moreover, because you are adding an element from a foreign namespace, this namespace must be declared in some way. So you should add the three red lines shown in Figure 21 to the namespace definition section at the beginning of the file.
    
    Figure 21. xmldsig-core-schema
    
    
    
12. If some errors appear complaining of duplicated namespace definitions, open the xenc-schema.xsd schema, and modify the import namespace, as shown in Figures 22 and 23.
    
    Figure 22. xenc-schema
    
    
    
    
    Figure 23. xenc-schema
    
    
    This should clear all the previous errors if any.

Back to top

Define the mediation module

Now you're ready to create a new mediation module and add the necessary mediation primitives.

1. Select File > New > Project. Then choose Mediation Module from the Select a wizard window.
   
   Figure 24. New mediation module
   
   
   
2. Type AsynchResSystemModule in the Module Name field, and keep the defaults as displayed in Figure 25.
   
   Figure25. Add interface
   
   
   
3. Click Next. In the Select Required Libraries window that appears, select Asynch-Library to add it to the module and, thus, allow the mediation module to use the data types and interfaces you previously defined within the library.
4. When the wizard completes the module's creation, double-click the Assembly Diagram icon to work with the assembly diagram. The Assembly Editor opens.
5. Add an import and an export component by dragging the relative icons onto the diagram. Rename them WS_Export and JMS_Import.
6. Right-click the export component and select add interface to add the AsynchResSystemExport interface to the export component (see Figure 26) and the AsynchResSystemImport interface to the import component (see Figure 27).
   
   Figure 26. Add export interface
   
   
   
   
   Figure 27. Add import interface
   
   
   
7. Select the Mediation Module component, and perform the following actions:
   1. Right-click, select the Add Interface option, and add the AsynchResSystemExport interface.
   2. Right-click, select the Add Reference option, and add the AsynchResSystemImport interface.
   3. Rename the module to Asynch_Mediation.
   Next:
   1. Select the WS_Export component, right-click, and select the Wire to Existing option.
   2. Select the JMS_Import component, right-click, and select the Wire to Existing option.
   When you've completed the above steps, your assembly diagram should look like Figure 28.
   
   Figure 28. Assembly diagram
   
   
   
8. Because the module must get a SOAP/HTTP message and convert it to a JMS payload, you should generate two bindings:
   • A Web service binding
   • A JMS message binding
9. Right-click the WS_Export component, and select the Generate Binding option.
10. From the window that appears, select Web Service Binding, and then select the SOAP/HTTP option in the Transport Selection window (see Figure 29).
    
    Figure 29. Transport selection
    
    
    
11. Right-click the JMS-Import component, and select the Generate Binding option again.
12. Select JMS Message. In the window that appears, select Publish-Subscribe as the messaging domain, then select the Use pre-configured messaging provider resources check box, and provide the topic name and the topic connection factory settings according to the configuration steps already performed in the first article of this series.
    
    Figure 30. Configure JMS import
    
    
    Remember to select the Business Object XML using JMSTextMessage option as serialization type. This way you ensure that the encrypted body of the SOAP message is passed as it is in an XML form to the topic and then can be parsed and reconstructed using some XML security standard decryption algorithm, as described in Part 2 of this series.
13. After being configured, the import and export bindings provide a mediation flow for this module. To do this, right-click the module component, and select Generate Implementation, as shown in Figure 31.
    
    Figure 31. Generate implementation
    
    
    
14. In the window that appears, select AsynchResSystemModule, and click OK (see Figure 32). A new mediation flow is generated.
    
    Figure 32. Asynchronous resource system module
    
    
    
15. Link the sendUpdateAgenda and publishAgenda operations in the Operation Connections window.
16. Add a new message setter primitive, and name it setMessageSelector.
17. Add an XSLT transformation primitive, and name it adaptInterfaces.
18. Order and wire these primitives as shown in Figure 33.
    
    Figure 33. Mediation flow
    
    
    
19. Click setMessageSelector, and in the properties window at the bottom of the page, select the Details tab.
20. Click the Add button.
21. Select Copy from the Type drop-down list. Two CustomXPath buttons appear, giving you the possibility of providing guided XPath expressions for both the Target and the Value fields.
    
    Figure 34. Message selector
    
    
    
22. Select JMSType in the Target field and serviceproviderId in the Value field. This way the messageSetter copies the serviceProviderId string that univocally identifies each service provider, from the message's body to the JMS header, thus acting as a message selector, as explained in the first article of this series.
23. Save the mediation flow, then select the adaptInterfaces XSLT transformation primitive.
24. In the Properties window at the bottom of the page, select the Details tab, then click the New button to create a new transformation.
25. In the window that appears, keep the defaults and click Finish.
    
    Figure 35. XSLT mapping
    
    
    
26. In the window that appears next, expand the tree on both sides until you reach the KeyInfo element. Expand this element, too. You should see a ds:KeyName element with an arrow on its right. The arrow is displayed as a result of the KeyInfo being defined through a Choice construct in the xmldsig schema.
    
    Figure 36. XSLT mapping
    
    
    
27. Click the arrow and scroll down until you see the EncryptedKey element, then select it on both sides. Remember that you modified the KeyInfo complex type definition to add the EncryptedKey element within the Choice; now you should have a better understanding of the reason. Without this change, in fact, you wouldn't be able to select the EncryptedKey element from the arrow, so all the key-related information, as far as the algorithm used to encrypt the key and the encrypted values, wouldn't be copied to the JMS payload (see Figure 37).
    
    Figure 37. Transformation
    
    
    
28. Select the xenc:EncryptedData element on both sides, and right-click the mouse to select the match mapping option. This way you instrument WebSphere Enterprise Service Bus to recursively copy the whole content of the incoming EncryptedData section from the incoming SOAP request's body to the JMS payload.
29. Save the transformation, and close the window.
30. Finally, save the whole mediation flow.

Back to top

Conclusion

This article described in detail how to instrument WebSphere Enterprise Service Bus to accept SOAP messages containing encrypted portions of data, perform protocol switching, and then forward these messages to a JMS topic where the service providers are registered. You've learned how to:

• Properly define an export interface to get the SOAP HTTP message containing sensitive data.
• Configure a message selector to augment the JMS message header with selectors information.
• Introduce an XSLT transformation to match the import and export interfaces and, thus, add mediation logic even when the message contains encrypted data.
• Provide an import interface to send the sensitive data to the topic as a JMS payload.

At this point, the whole scenario has been completely covered. The last installment of the series will address:

• Concerns about the client side of the application.
• Getting the JMS messages from WebSphere Enterprise Service Bus.
• Decrypting the sensitive data with the service provider's private key to reconstruct the original message that's been sent from the central reservation system and that has been encrypted through the WebSphere DataPower SOA Appliances box.

This part will be deeply covered in the fourth and final article of this series, so stay tuned!

Back to top

Download

Information about download methods

Resources

Learn

• Check out the following related IBM Redbooks®:
  • Getting Started with WebSphere Enterprise Service Bus V6
  • Patterns: Implementing an SOA using an Enterprise Service Bus
  • Connecting Enterprise Applications to WebSphere Enterprise Service Bus
  • Patterns: Integrating Enterprise Service Buses in a Service-Oriented Architecture
  
  
• Get more information about IBM WebSphere DataPower SOA Appliances.
  
  
• Learn more about IBM WebSphere Enterprise Service Bus, and visit the product page on developerWorks.
  
  
• The SOA and Web services zone on IBM developerWorks hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop Web services applications.
  
  
• Play in the IBM SOA Sandbox! Increase your SOA skills through practical, hands-on experience with the IBM SOA entry points.
  
  
• The IBM SOA Web site offers an overview of SOA and how IBM can help you get there.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  
• Browse for books on these and other technical topics at the Safari bookstore.
  
  
• Check out a quick Web services on demand demo.
  
  
• Get an RSS feed for this series. (Find out more about RSS.)
  
  

Get products and technologies

• Download XENC Schema, and XMLDSIG CORE Schema.
  
  
• Innovate your next development project with IBM trial software, available for download or on DVD.
  
  

Discuss

• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  

About the authors

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Mediation module
• Create a new library
• Define data types
• Define the export/import interface
• Define the mediation module
• Conclusion
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

Rational Tester for SOA Quality is an automated web services testing and SOA testing tool that supports Web services SOAP, HTTP(S), JMS, WS-Security, UDDI, and RESTful standards.

---

• Try: The no-charge Rational Service Tester for SOA Quality helps quality assurance professionals validate web service based SOA application..
• Article: See the whats new with Rational Service Tester for SOA Quality, and its Generic Service Client, which provides a single client to interact with any SOA service type.
• Tutorial: Get hands-on experience with this Transport for SOAP feature tutorial using Rational Tester for SOA Quality.
• Buy: Rational Service Tester for SOA Quality

Dig deeper into SOA and Web services on developerWorks

Discover knowledge paths

Skill-building guides for Linux, open source, cloud, Java, business analytics, and more.

Special offers