You are on page 1of 21

Websphere DataPower Release 3.8.

1 MTOM / XOP Validation


XA/XB/XI/XM/XS

2010 IBM Corporation

Websphere DataPower Release 3.8.1 MTOM / XOP Validation

381DataPowerSecurityMTOM.ppt

Page 1 of 21

Agenda

MTOM / XOP background MTOM / XOP validation feature XML Firewall and Multi-Protocol Gateway configuration Web Services Proxy configuration Error messages

Websphere Datapower Release 3.8.1

2010 IBM Corporation

This presentation will cover the MTOM validation which is introduced in Release 3.8.1. First we will begin with some background on the MTOM and XOP specifications, and existing support for those specifications in the DataPower product. Then we will explain the feature itself, followed by a brief explanation of how to configure the feature for XML Firewalls, Multi-Protocol Gateways, and Web Services Proxies. Finally we will cover the potential error messages a user can encounter when using the feature.

381DataPowerSecurityMTOM.ppt

Page 2 of 21

MTOM and XOP Specifications

XOP: XML-binary Optimized Packaging


Establishes a mapping between XML that contains base64-encoded binary (the unoptimized form) and XML that contains a URI reference to unencoded binary content (the optimized form) Suggests using a MIME package to transport the Optimized XML and any unencoded binary attachments

MTOM: SOAP Message Transmission Optimization Mechanism


Establishes an abstract SOAP Feature for optimizing transmissions of SOAP messages with binary data Describes use of XOP with MIME as an implementation of that feature.

MTOM/XOP is a serialization optimization. The real data is base64 encoded (even if it is never actually materialized that way)

2010 IBM Corporation

MTOM and XOP are related specifications that establish a way to send binary data in an XML package. We often speak of MTOM messages, but MTOM itself relies on the XOP specification to define exactly how the XML portion of the message is constructed. MTOM pulls together the XOP specification, the use of MIME for the binary attachments, and use of SOAP (as opposed to arbitrary XML), and describes the whole as a soap feature.

The most important thing to understand about MTOM / XOP is that these specifications describe a serialization optimization. In the abstract, the data being transmitted is considered to be an XML document where the binary content is encoded as base64 text. This means, for example, that any XML Schema or WSDL documents used to describe the message will describe it in terms of this abstract textual form. The optimization applied by these specifications is to cut the encoded binary data sections out of the XML document itself and transmit them as binary attachments to the message. Because the MTOM mechanism is considered an optimization, it is up to the sender to decide whether to serialize a given section of data as a binary attachment, or as base64 text in the XML document itself. A message receiver must be prepared to accept both forms

381DataPowerSecurityMTOM.ppt

Page 3 of 21

An Example SOAP Message with base64 Binary data

<?xml version="1.0" encoding="UTF-8"?>


<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://www.w3.org/2003/05/soap-envelope"
xmlns:xop="http://www.w3.org/2004/08/xop/include"
xmlns:u="http://example.com">
<SOAP-ENV:Body>
<u:HelloWorld>VGhpcyBpcyBiaW5hcnkh</u:HelloWorld>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

2010 IBM Corporation

This is a simple example of a SOAP message containing some base64 data. The data is encoded as text, and inlined into the XML document. This is the unoptimized form, and this is the way any Schema or WSDL will describe the document.

381DataPowerSecurityMTOM.ppt

Page 4 of 21

The same Message using MTOM Optimization

--boundary Content-Type: application/xop+xml <?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://www.w3.org/2003/05/soap-envelope" xmlns:xop="http://www.w3.org/2004/08/xop/include" xmlns:u="http://example.com"> <SOAP-ENV:Body> <u:HelloWorld><xop:Include href=cid:data/></u:HelloWorld> </SOAP-ENV:Body> </SOAP-ENV:Envelope> --boundary Content-Type: application/octet-stream Content-Id: <data> This is binary!
--boundary-
2010 IBM Corporation

This is the same document optimized using MTOM. Notice that the attachment reads as clear text. This is the same content as in the previous message, but decoded. You can also notice that this document is actually quite a bit longer and more complicated than the original, unoptimized form. The notion of optimization should be understood in two ways. First, in cases where the binary data is quite large, transmitting the raw binary in attachments is more efficient because base64 encoding is not very efficient. Secondly, it is understood that in practice many senders will begin with their binary data in an decoded form, and avoiding the cost of encoding it for transmission will be an optimization of their transmission process. Similarly man servers will expect to use the binary data in an decoded form. Avoiding the overhead of decoding will optimize the server side reception process as well.

381DataPowerSecurityMTOM.ppt

Page 5 of 21

Existing MTOM Support

Datapower has support for creating and interpreting MTOM packages


Using store://dp/mtom.xsl + MTOM Policy The user can add this to their stylepolicy to translate to/from MTOM

Unless unpackaged, the root part of an MTOM message will typically fail Schema or WSDL validation
WSDL or Schema is defined in terms of the real base64 XML data The message has <xop:Include/> where the base64 text should be You cannot write a Schema (or WSDL) that will validate both Pipeline beginning at implied action Parse input as XML, attempt pipeline failed: http://0.0.0.0:10555/xop-A:7: cvc-type 3.1.2: element {http://example.com}HelloWorld of type {http://www.w3.org/2001/XMLSchema}base64Binary may not have child elements

2010 IBM Corporation

In Datapower, there is already support for creating and interpreting (or packaging and unpackaging) MTOM messages. This is done using the built-in mtom.xsl stylesheet in store, coupled with an MTOM Policy. One major complication for MTOM message processing, however, is validation. As we have already discussed, the WSDL or Schema that is used to describe a message is written in terms of the unoptimized form. As such, the message must first be unpackaged before it can be validated. When unpackaging is not performed on an MTOM optimized message, the validation action will find xop:Include elements where base64 text is expected, and validation will fail with an error similar to the one shown.

381DataPowerSecurityMTOM.ppt

Page 6 of 21

Complications of Validating of MTOM Messages

In A Firewall or Gateway, the stylepolicy must unpackage message before performing Schema or WSDL validation Inefficient to base64-encode binary data just to then validate that it is legal base64. Inefficient to unpackage the message when sending the optimized package through to the backend In Web Services Proxy, must disable body validation Built-in validation happens before the stylepolicy, so there is no opportunity to apply unpackaging policy

2010 IBM Corporation

In an XML Firewall or Multi-Protocol Gateway, requring MTOM unpackaging before the validation action is inefficient because the binary data must be encoded first, just so that the validation action can look at it and verify that it has been encoded correctly. Further, in many cases, the user is proxying the message to a backend, and the unpackaging process is unneeded, except for validation.

In a Web Service Proxy, MTOM optimization conflicts with the Proxy's built-in WSDL validation. Because the built-in validation occurs before the user's style-policy, there is no opportunity to unpackage the message before validation. Thus the user must either use a multi-protocol gateway in front of the proxy to unpackage messages, or must disable builtin body validation, and supply their own validation actions after unpackaging, in the stylepolicy.

381DataPowerSecurityMTOM.ppt

Page 7 of 21

Agenda

MTOM / XOP background MTOM / XOP validation feature XML Firewall and Multi-Protocol Gateway configuration Web Services Proxy configuration Error messages

Websphere Datapower Release 3.8.1

2010 IBM Corporation

Next on the agenda is MTOM / XOP validation feature.

381DataPowerSecurityMTOM.ppt

Page 8 of 21

MTOM / XOP Validation Feature

Accept XOP Optimized XML in a WSDL or Schema validation action


which normally validate the unoptimized form (accept both)
Allows xop:Include to appear wherever base64-encoded content
would be valid

Simple Types: xsd:anySimpleType, xsd:base64Binary, xsd:string, xsd:anyURI Any extensions or restrictions of these No Constraining Facets (pattern, length, and so on.)

Validates the xop:Include element using the built-in schema store://schemas/xop.xsd


User can override this by importing their own version of xop.xsd into their user WSDL or Schema, or by modifying the copy in store.

Does not verify existence or validity of referenced binary content


2010 IBM Corporation

To alleviate the complications discussed in the last slide, in Release 3.8.1, we have enabled validation actions to directly validate MTOM optimized messages. Simply put, this feature allows a validation action, which normally only accept the unoptimized form, to also accept XOP optimizations in place of base64 text. xop:Include elements are accepted wherever base64 text would be valid. This includes several of XML Schema's built-in simple types, and user extensions and restrictions of those types. One important exception: we do not accept XOP/MTOM validation of user defined simple types which use facets to restrict the built-in types. So, for example, we do not accept MTOM optimization of binary data with a constrained length. This is because, as noted at the bottom of this slide, the validation action does not actually verify if the referenced attachment exists, and does not retrieve its data to determine if any simple type constraints would be met. Performing such processing would re-introduce much of the overhead that this feature is intended to avoid. For users that want to use MTOM optimization with constrained simple types, unpackaging is required. The xop:Include elements are validated using a built in schema in store. As with the various SOAP schemas, users can override all or part of the built-in schema by importing their own definitions into their Schema or WSDL, or can replace the built-in schema completely in store. It is an error to replace the schema with one that does not have a definition for xop:Include.

381DataPowerSecurityMTOM.ppt

Page 9 of 21

Agenda

MTOM / XOP background MTOM / XOP validation feature XML Firewall and Multi-Protocol Gateway configuration Web Services Proxy configuration Error messages

10

Websphere Datapower Release 3.8.1

2010 IBM Corporation

Next on the agenda XML Firewall and Multi-Protocol Gateway configuration.

381DataPowerSecurityMTOM.ppt

Page 10 of 21

XML Firewall / Multi-Protocol Gateway

New option in Compile Options Policy Attached to XML Manager Like other Schema Options, option is a URL Map Can specify Schema / WSDL URLs to which the option applies Can use wildcards to specify multiple Schemas / WSDLs Off by default

2010 IBM Corporation

In an XML Firewall or Multi-Protocol Gateway, the MTOM validation feature is enabled by an option in the Compile Options Policy, which is attached to the XML Manager, which is in turn attached to the firewall or gateway. The option is specified as a URL Map, which allows you to specify the Schema or WSDL documents for which the feature should be enabled. Wildcards can be used to specify multiple documents. The option is disabled by default.

381DataPowerSecurityMTOM.ppt

Page 11 of 21

2010 IBM Corporation

This screen capture shows the option in the Compile Options Policy configuration screen.

381DataPowerSecurityMTOM.ppt

Page 12 of 21

URL Map

2010 IBM Corporation

This screen capture shows the configuration of a URL Map enabling the feature for all
WSDLs in local:///, and (somewhat redundantly) the single WSDL local:///xop-B.wsdl

381DataPowerSecurityMTOM.ppt

Page 13 of 21

Agenda

MTOM / XOP background MTOM / XOP validation feature XML Firewall and Multi-Protocol Gateway configuration Web Services Proxy configuration Error messages

14

Websphere Datapower Release 3.8.1

2010 IBM Corporation

Next on the agenda are Web Services Proxy configuration.

381DataPowerSecurityMTOM.ppt

Page 14 of 21

Web Services Proxy

New toggle in Web Services Proxy User Toggles Attached to individual wsdl/service/port/operation/and so on. On by default Additive with Compile Options Policy
If MTOM/XOP validation is enabled in either the XML Manager OR the Proxy Policy toggles then it is enabled for the WS-Proxy validation

User Toggle only applies to the built-in WSDL validation. For explicit validation actions in the stylepolicy, the user should set the Compile Options Policy in the XML Manager.

2010 IBM Corporation

In a Web Services Proxy, the built-in validation is configured to enable MTOM validation by default. This can be modified using a new toggle in the Policy tab. The toggle can be modified in any of the typical locations: wsdl document, service, port, operation, and so forth. The Policy toggle combines additively with what's specified in the Compile Options Policy of the XML Manager attached to the Proxy. If the feature is enabled in either the policy toggle or in the compile options, then the feature is enabled for the Web Services Proxy's automatic WSDL validation. For other, explicit validation actions in the user's stylepolicy, the Compile Options policy is used in the same was as with an XML Firewall or a Multi-Protocol Gateway.

381DataPowerSecurityMTOM.ppt

Page 15 of 21

2010 IBM Corporation

This screen capture shows the toggle in the Web Service Proxy Policy tab.

381DataPowerSecurityMTOM.ppt

Page 16 of 21

Agenda

MTOM / XOP background MTOM / XOP validation feature XML Firewall and Multi-Protocol Gateway configuration Web Services Proxy configuration Error messages

17

Websphere Datapower Release 3.8.1

2010 IBM Corporation

Next on the agenda are error messages.

381DataPowerSecurityMTOM.ppt

Page 17 of 21

Error Messages

MTOM/XOP optimized binary found in <element> of type <type>, but MTOM/XOP optimized binary is not allowed. This validation-time error message is issued when the input contains an XOP/MTOM optimized message, but the action was not configured to accept XOP/MTOM messages. It replaces the generic message Element <element> of type <type> may not have child elements for the specific case where the unexpected child element is xop:Include. XOP 3.2.2.b: xop:Include replacement data is not a valid value for element <element> of type <type>. This validation-time error message is issued when the input contains an xop:Include element where base64 binary data is not allowed (such as an element of type xs:date).

2010 IBM Corporation

The first error message shown is what the user will see if they send MTOM optimized input through a validation action for which the feature is not enabled. This message, in contrast to the generic error message showed in the background section of this presentation, specifically highlights that the input is MTOM optimized, but that MTOM validation was not enabled.

The second error message is what the user will see when MTOM optimization is encountered in a part of the input where base64 text not accepted. For example, if the input should contain a date, and instead contains an xop:Include element. No matter what data the xop:Include element points at, there is no way that encoding that data as base64 text will produce a valid date. The message references the section of the XOP specification that defines how an xop:Include element is replaced with base64 text.

381DataPowerSecurityMTOM.ppt

Page 18 of 21

Error Messages

XOP 3.2.2.a: xop:Include must be the sole child of <element> of type <type>. This validation-time error message is issued when the input has text or other elements before or after the xop:Include element. (which is a violation of the rules for XOP packages construction) Could not find definition of element xop:Include for validation of XOP binary-optimized XML. This compile-time error message is issued if the action was configured to accept MTOM/XOP optimized messages, but the user has modified the built-in schema in store://schemas/xop.xsd such that it no longer has a definition for xop:Include. The compiler requires the schema to have such a definition in order to compile Schemas or WSDLs with MTOM Validation.

2010 IBM Corporation

This next message is reported if the input does not conform to XOP specification section 3.2.2.a., which requires that the content of an element of simple type be replaced in its entirety. This means when xop:Include is in the input, it must be the only child of its parent element (no leading or trailing text is allowed).

Finally, the last error message is issued at compile-time if MTOM Validation is enabled, but the built-in schema in store has been incorrectly modified such that it does not define xop:Include.

381DataPowerSecurityMTOM.ppt

Page 19 of 21

Feedback

Your feedback is valuable You can help improve the quality of IBM Education Assistant content to better meet your needs by providing feedback. Did you find this module useful? Did it help you solve a problem or answer a question? Do you have suggestions for improvements?

Click to send email feedback: mailto:iea@us.ibm.com?subject=Feedback_about_381DataPowerSecurityMTOM.ppt

This module is also available in PDF format at: ../381DataPowerSecurityMTOM.pdf

20

MTOM / XOP Validation

2010 IBM Corporation

You can help improve the quality of IBM Education Assistant content by providing feedback.

381DataPowerSecurityMTOM.ppt

Page 20 of 21

Trademarks, disclaimer, and copyright information

IBM, the IBM logo, ibm.com, DataPower, and IBM are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of other IBM trademarks is available on the Web at "Copyright and trademark information" at http://www.ibm.com/legal/copytrade.shtml THE INFORMATION CONTAINED IN THIS PRESENTATION IS PROVIDED FOR INFORMATIONAL PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS PRESENTATION, IT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN ADDITION, THIS INFORMATION IS BASED ON IBMS CURRENT PRODUCT PLANS AND STRATEGY, WHICH ARE SUBJECT TO CHANGE BY IBM WITHOUT NOTICE. IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS PRESENTATION OR ANY OTHER DOCUMENTATION. NOTHING CONTAINED IN THIS PRESENTATION IS INTENDED TO, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM IBM (OR ITS SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF ANY AGREEMENT OR LICENSE GOVERNING THE USE OF IBM PRODUCTS OR SOFTWARE. Copyright International Business Machines Corporation 2010. All rights reserved.

21

2010 IBM Corporation

381DataPowerSecurityMTOM.ppt

Page 21 of 21