Integrating WebSphere DataPower XML Security Gateway XS40 with WebSphere Message Broker

A WebSphere DataPower XML Security Gateway XS40 can add a number of benefits to a WebSphere Message Broker environment. This article shows how the DataPower XS40 enhances a Message Broker flow with WS-Security, with security of the connection to Message Broker provided by HTTPS. The DataPower XS40 protects the SOAP messages sent to and produced by Message Broker via WS-Security encryption of the SOAP body. You can also use the WebSphere DataPower Integration Appliance XI50, which has the same functional capabilities plus additional integration features.

Peter Crocker (peter_crocker@uk.ibm.com), Senior IT Specialist, IBM 

Photo of Peter CrockerPeter Crocker works on the Software Services team at the IBM Hursley Software Lab in the UK. He specialises in WebSphere Message Broker and works as a consultant with leading customers on architecture, design, and implementation. Peter moved to this role from the Message Broker Development team, bringing a deep technical knowledge of Message Broker internals. Prior to the announcement of V6, he helped deliver the Beta program and also helped develop and deliver education to the Services teams on new V6 function. You can contact Peter at peter_crocker@uk.ibm.com.



10 October 2007

Also available in Japanese

Introduction

The following diagram illustrates the scenario described in this article:

Figure 1. The full scenario
The full scenario

The requesting application communicates to an IBM® WebSphere® DataPower® XML Security Gateway XS40 (hereafter called the DataPower appliance) using SOAP over HTTP, with the message body encrypted to the WS-Security standard. The DataPower appliance decrypts the body of the message it receives, and this content is then passed to WebSphere Message Broker (hereafter called Message Broker) over a connection secured by HTTPS. Message Broker receives the SOAP message and transforms it into a COBOL structure for the final WebSphere MQ application. The responses then flow back in a similar fashion. The initial configuration uses simple HTTP between the DataPower appliance and Message Broker. The modifications to use HTTPS are performed as a second stage of the configuration.

The components described here can be placed within an SOA design pattern in which the DataPower appliance provisions WS-Security within the demilitarized zone that protects an enterprise.

Figure 2. The scenario aligned within a demilitarized zone
The scenario aligned within a demilitarized zone

Configuration

The following sections concentrate on the configuration of DataPower and on the relevant externals that Message Broker presents to DataPower.

Configuring the DataPower appliance

Figure 3. Focusing on the DataPower configuration
Focusing on the DataPower configuration

WS-Security

WS-Security describes enhancements to SOAP messaging to provide quality of protection through message integrity, message confidentiality, and single message authentication. These mechanisms can be used to accommodate a wide variety of security models and encryption technologies.

The DataPower appliance is configured with a simple XML firewall with a static backend that connects to the Message Broker’s HTTP listener. After the main page of the XML firewall is configured,an addition must be made to the Headers page before a processing policy is associated with the XML firewall. This processing policy provides the encryption and decryption of the SOAP body using the WS-Security standard. Figure 4 below shows the main configuration of the XML firewall with the following items configured:

  • Name and summary
  • Server address and port
  • Device port
  • Request and response type set to SOAP
Figure 4. Configuration of the XML firewall
Configuration of the XML firewall

Once the header has been configured as described in the next section, the firewall policy is added.

Headers

In the firmware version, the DataPower appliance generated two connection header tags. By adding suppression for this tag, only one connection header is sent by the DataPower appliance. Figure 5 shows the Headers page with the connection header tag suppressed in the "back" direction:

Figure 5. Configuring the headers
Configuring the headers

Processing policy

The processing policy includes just two rules: the Request rule decrypts the incoming message body, and the Response rule encrypts the message body of the reply.

Following the traditions of security literature, the keys used in this article are named AliceKey and BobKey. The requesting application sends messages encrypted with the AliceKey, and the DataPower appliance encrypts the reply with the BobKey.

Request (decryption) rule

The Request rule includes a match rule property and a decrypt action as in the following figure. The matching rule property matches on all URLs.

Figure 6. The decryption rule
The decryption rule

The decrypt action is configured to decrypt the incoming message as determined from the WS-Security headers and information contained within the SOAP message. As the requesting application has encrypted the message with the AliceKey, it is used for decryption within the DataPower appliance.

Figure 7. The decryption action
The decryption action

Response (encryption) rule

The response rule performs the opposite, encrypting the messages flowing in this direction:

Figure 8. The encryption rule
The encryption rule

The encryption action is configured to encrypt the SOAP message body using WS-Security, and it uses the predefined key BobKey:

Figure 9. The encryption action
The encryption action

The private half of the BobKey is owned by the requesting application, so that it can decrypt the message sent by the DataPower appliance.

Configuring Message Broker

On receiving a decrypted SOAP/HTTP message from the DataPower appliance, a message flow running in a Message Broker instance converts the incoming message into a fixed length message in a COBOL format, which is then processed by a separate WebSphere MQ application. The message is updated and passed to a second message flow, which converts the message into a SOAP/HTTP message containing the reply:

Figure 10. Focusing on the Message Broker function
Focusing on the Message Broker function

The processing being performed is that of the Web services sample WSHOST, which is supplied with WebSphere Message Broker V6. For more information about this sample, go to the Message Broker toolkit and select Help => Samples Gallery on the Toolkit menu:

Figure 11. The two WebSphere Message Broker message flows
The two WebSphere Message Broker message flows

The first message flow processes the incoming SOAP/HTTP message after t has been decrypted by the DataPower appliance. After converting the message format and protocol, it writes an output message to a WebSphere MQ queue, which is read and processed by the WebSphere MQ application.

The second message flow receives the WebSphere MQ reply message from the WebSphere MQ application and converts the format and protocol of the input message into a SOAP/HTTP reply message. The reply message generated by the second message flow is passed to the DataPower appliance, so that it can be encrypted prior to being returned to the requesting application.

HTTP Input node properties

The input node properties show the URL on which this flow is configured to receive requests. The HTTPS box remains unchecked -- a later section enables it to complete the security.

WebSphere MQ application

The WebSphere MQ application provided with the WSHOST sample performs an MQ Get on its input queue waiting for messages from the broker. When one is received, it modifies the message and writes a reply to a queue that will be read by a message flow.

Messages

The following sections show the messages that flow within the system to and from the DataPower appliance. Figure 12 below shows the placement of these messages within the overall flow. Messages between Message Broker and the backend WebSphere MQ application are not shown.

Figure 12. Highlighting the messages described in this section
Highlighting the messages described in this section

Message sent from the requesting application to the DataPower appliance

Shown below is the HTTP body of the message sent to the DataPower appliance by the requesting application. The real content of the message in its encrypted form is highlighted (in bold) and has been truncated for readability. For the full contents of this and subsequent messages, see Downloads below.

Message 1. The message sent from the application to the DataPower appliance

Click to see code listing

Message 1. The message sent from the application to the DataPower appliance

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:c="http://www.brokersamplewshost.ibm.com"
	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Header>
		<wsse:Security
			xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
				wssecurity-secext-1.0.xsd"
			soapenv:mustUnderstand="1">
			<xenc:EncryptedKey
				xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
				<xenc:EncryptionMethod
					Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"
					xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" />
				<dsig:KeyInfo
					xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
					<wsse:SecurityTokenReference>
						<wsse:KeyIdentifier
							ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
								wss-x509-token-profile-1.0#X509v3SubjectKeyIdentifier"
							EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
								wss-soap-message-security-1.0#Base64Binary">
							8QHphchQgGO8IhB0njemHmDcLyg=
						</wsse:KeyIdentifier>
					</wsse:SecurityTokenReference>
				</dsig:KeyInfo>
				<xenc:CipherData
					xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
					<xenc:CipherValue>
						tGSKTm8BYNAfus+h57dV0T+dsiA85tcu6neZHdIJ2+fGmV2VsW+K5uTse/bVI+R . . . 
					</xenc:CipherValue>
				</xenc:CipherData>
				<xenc:ReferenceList>
					<xenc:DataReference URI="#body" />
				</xenc:ReferenceList>
			</xenc:EncryptedKey>
		</wsse:Security>
	</soapenv:Header>
	<soapenv:Body>
		<xenc:EncryptedData
			xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" Id="body"
			Type="http://www.w3.org/2001/04/xmlenc#Content">
			<xenc:EncryptionMethod
				Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc" />
			<xenc:CipherData>
				<xenc:CipherValue>
					0BOKgLugk85FMPsXPbefFamUEh+9Re4IX8FjPHrR6dQm9jAFfBYjTYAFUYDFLxB . . . 
				</xenc:CipherValue>
			</xenc:CipherData>
		</xenc:EncryptedData>
	</soapenv:Body>
</soapenv:Envelope>

Message sent from the DataPower appliance to WMB

Here is the HTTP body of the message sent by the DataPower appliance to Message Broker. The body (in bold) has been decrypted to reveal the SOAP request:

Message 2. Message sent from the DataPower appliance to Message Broker
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:c="http://www.brokersamplewshost.ibm.com"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Header>
		<wsse:Security soapenv:mustUnderstand="1"
			xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
				wssecurity-secext-1.0.xsd">
		</wsse:Security>
	</soapenv:Header>
	<soapenv:Body>
		<c:IA81CONFIN>
			<MessageId>IA81CONF</MessageId>
			<OrderNumber>ON4002</OrderNumber>
			<ItemReference>IY4003</ItemReference>
			<ItemQuantity>4</ItemQuantity>
			<CustomerNumber>CY4004</CustomerNumber>
		</c:IA81CONFIN>
	</soapenv:Body>
</soapenv:Envelope>

Message sent from Message Broker to the DataPower appliance

Here is the HTTP body of the message returned by Message Broker to the DataPower appliance. For this return trip, two additional fields, DeliveryRef and Confirm (in bold), are included at the end of the message:

Message 3. Message sent from Message Broker to the DataPower appliance
<?xml version="1.0"?>
<tns:Envelope xmlns:tns="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:NS1="http://www.brokersamplewshost.ibm.com"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<tns:Body>
		<NS1:IA81CONFOUT>
			<MessageId>IA81CONF</MessageId>
			<OrderNumber>ON4002</OrderNumber>
			<ItemReference>IY4003</ItemReference>
			<ItemQuantity>4</ItemQuantity>
			<CustomerNumber>CY4004</CustomerNumber>
				<DeliveryRef>JOHNCORP</DeliveryRef>
				<Confirm>Y</Confirm>
		</NS1:IA81CONFOUT>
	</tns:Body>
</tns:Envelope>

Message sent by the DataPower appliance to the requesting application

The HTTP body of the message returned by the DataPower appliance to the requesting application follows a similar pattern to the first message sent to the DataPower appliance. The difference is that the contents of this message is encrypted using the return key. Decrypting this message would reveal the message sent by Message Broker.

Message 4. Message sent from the DataPower appliance to the application

Click to see code listing

Message 4. Message sent from the DataPower appliance to the application

<?xml version="1.0" encoding="UTF-8"?>
<tns:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:NS1="http://www.brokersamplewshost.ibm.com"
	xmlns:tns="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Header
		xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
		<wsse:Security soapenv:mustUnderstand="1"
			xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
				wssecurity-secext-1.0.xsd">
			<xenc:EncryptedKey
				xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
				<xenc:EncryptionMethod
					Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"
					xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" />
				<dsig:KeyInfo
					xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
					<wsse:SecurityTokenReference>
						<wsse:KeyIdentifier
							ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
								wss-x509-token-profile-1.0#X509v3SubjectKeyIdentifier"
							EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
								wss-soap-message-security-1.0#Base64Binary">
							8QHphchQgGO8IhB0njemHmDcLyg=
						</wsse:KeyIdentifier>
					</wsse:SecurityTokenReference>
				</dsig:KeyInfo>
				<xenc:CipherData
					xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
					<xenc:CipherValue>
						dj+/1BlGcB+rLiazRqW+5VdBqOtGzGiJrk3kGSZ2ARhO/2eSkrUoStvBEfR . . .
					</xenc:CipherValue>
				</xenc:CipherData>
				<xenc:ReferenceList>
					<xenc:DataReference URI="#body" />
				</xenc:ReferenceList>
			</xenc:EncryptedKey>
		</wsse:Security>
	</soapenv:Header>
	<tns:Body>
		<xenc:EncryptedData Id="body"
			Type="http://www.w3.org/2001/04/xmlenc#Content"
			xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
			<xenc:EncryptionMethod
				Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc" />
			<xenc:CipherData>
				<xenc:CipherValue>
					p2g/0hah2Il1MdrrI638F9oFlmflrdTzJN5aI+tnJMRJerqs5AZebZVjX9QD7ZYaE3RHP . . .
				</xenc:CipherValue>
			</xenc:CipherData>
		</xenc:EncryptedData>
	</tns:Body>
</tns:Envelope>

Securing the connection between the DataPower appliance and Message Broker

Adding SSL support between the DataPower appliance and Message Broker completes the security of the connections between them:

Figure 13. Securing the link between the DataPower appliance and Message Broker
Securing the link between the DataPower appliance and Message Broker

SSL enabling HTTP for Message Broker

To enable SSL for Message Broker, it must first be configured and assigned a certificate. For this article, a self-signed certificate within a key store is used by the Message Broker HTTP listener process. You could also use a certificate signed by a certificate authority. The broker is then configured to use this key store.

The Java ikeyman application is used to create the key store. To create a self-signed certificate stored within this key store, select New Self-Signed Certificate. For this article the following configuration is used:

Figure 14. The self-signed certificate in ikeyman
The self-signed certificate in ikeyman

To provide the public half of this certificate to the the DataPower appliance, select Extract certificate. The following commands enable SSL, configure the key store, provide the password for this key store, and set the HTTPS port:

Listing 4. The commands to enable HTTPS in Message Broker
>mqsichangeproperties WBRK6_DEFAULT_BROKER -b httplistener -o HTTPListener 
-n enableSSLConnector -v true

>mqsichangeproperties WBRK6_DEFAULT_BROKER -b httplistener -o HTTPSConnector 
-n keystoreFile -v "c:\Program Files\IBM\WMBv6.0\MyKeystore.jks"

>mqsichangeproperties WBRK6_DEFAULT_BROKER -b httplistener -o HTTPSConnector 
-n keystorePass -v ********

>mqsichangeproperties WBRK6_DEFAULT_BROKER -b httplistener -o HTTPSConnector 
-n port -v 7083

The broker must be restarted for these changes to take effect within the HTTP listener process. You can then use the following two commands to verify the previous settings:

Listing 5. The commands report the HTTPS settings in Message Broker
>mqsireportproperties WBRK6_DEFAULT_BROKER -b httplistener -o HTTPListener -a

HTTPListener=''
uuid='HTTPListener'
enableSSLConnector='true'
traceLevel='none'
traceSize='4194304'

BIP8071I: Successful command completion.

>mqsireportproperties WBRK6_DEFAULT_BROKER -b httplistener -o HTTPSConnector -a

HTTPSConnector=''
uuid='HTTPSConnector'
keystoreFile='c:\Program Files\IBM\WMBv6.0\MyKeystore.jks'
keystorePass='********'
port='7083'

BIP8071I: Successful command completion.

Enable the message flow for SSL

With the broker restarted, you can configure the HTTP input node for HTTPS and redeploy the message flow to the broker. Figure 15 shows the properties of the HTTP Input node within the message flow, with Use HTTPS checked:

Figure 15. Properties of the HTTP node with the Use HTTPS item checked
Properties of the HTTP node with the Use HTTPS item checked

You can use the netstat -a (or equivalent) command after Message Broker is restarted and an HTTPS flow is deployed, to confirm that the HTTP listener is listening on the configured port.

Configuring client-side SSL in the DataPower appliance

You must upload a certificate of the key generated for Message Broker into the DataPower appliance, which is added as a trusted server within an SSL profile that is then used for the SSL client crypto profile. To create and associate an SSL client crypto profile, select Create on the main XML Firewall configuration page. To configure the profile upload, then add the certificate exported from ikeyman to the Trusted Servers section of the crypto profile. Select the option to authenticate and validate the certificate. With this check the DataPower appliance can be trusted to connect only to trusted servers.

Figure 16. The Trusted Server configuration
The Trusted Server configuration

You must also reconfigure the XML firewall to point to the SSL port of the HTTP listener (in this case the default value of 7083).

SSL encryption

To observe this change, an HTTP tunnel is placed between the DataPower appliance and Message Broker and used to observe messages that pass in both directions between the two components. Whilst some of the initial exchange that forms the SSL protocol passes as clear text, after the private keys are established for the session, all data is encrypted.

Message Broker Explorer

Message Broker Explorer (IS02 support pack) now includes a wizard that can configure an XML firewall within the DataPower appliance for connection with HTTP flows provisioned by Message Broker. For more information, see the first article below under "Resources."

Conclusion

This article has demonstrated how you can use a WebSphere DataPower SOA appliance to extend the function provided by WebSphere Message Broker and provide WS-Security of SOAP messages to HTTP message flows. The article also showed how to provide security between WebSphere Message Broker and the DataPower appliance using HTTPS.


Download

DescriptionNameSize
Four message files as described in articlemessages.zip4 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=260870
ArticleTitle=Integrating WebSphere DataPower XML Security Gateway XS40 with WebSphere Message Broker
publish-date=10102007