ISSUE 190: text for SOAP MustUnderstand issue

["Reid, Irving" <irving.reid@hp.com>]

This message relates to Issue 190, raised by the W3C XMLP working group.

In WSS-SOAPMessageSecurity-17-082703-merged.pdf, lines 455-457, the draft reads:

455 The optional mustUnderstand SOAP attribute on Security header (sic) simply means you are aware of
456 the Web Services Security: SOAP Message Security specification, and there are no implied
457 semantics.



The background is that SOAP allows header elements to contain a "MustUnderstand" attribute, and if MustUnderstand="1" (or "true") then the recipient of the message MUST return a fault if it does not understand said header element. Unfortunately, it's not clear what "understand" means in this context.

We need to strike a balance between the extremes of:

 o MustUnderstand just means "ignore at your own peril"; a recipient can completely ignore the content, but if that leads to problems they have no one to blame but themselves. In the real world, this is what it really comes down to. We don't have a protocol for sending Big Foam Cluebats across the network to people who ignore MustUnderstand elements.

 o MustUnderstand means that a recipient must be able to fully process every optional sub-element and possible extension of the MustUnderstand header element. This is clearly too strict a constraint.


The problem is further complicated by the fact that elements within wsse:Security may be extensions defined in other specifications, so we can't clearly specify where people need to look to determine how to "understand" them.


I think the balance looks very much like the text we already have in the spec (WSS-SOAPMessageSecurity-17-082703-merged.pdf) in the "Message Security Model" section:

237 Where the specification requires that an element be "processed" it means that the element type
238 MUST be recognized to the extent that an appropriate error is returned if the element is not
239 supported..

and also immediately above the text in question:

450 All compliant implementations MUST declare which profiles they support and MUST be able to
451 process a <wsse:Security> element including any sub-elements which may be defined by that
452 profile.


Now, there is also an open issue (189) complaining about this text, since we don't provide a way for implementations to "declare" which profiles they support and therefore this MUST is unimplementable/unenforceable.

Perhaps we could replace lines 450-452 and 455-457 with the following, and move lines 453-454 to the end of the section:


Conforming implementations MUST be able to process the <wsse:Security> element and all sub-elements, including any elements defined by profiles or extensions supported by that implementation. If the <wsse:Security> header has a SOAP mustUnderstand="true" attribute and the implementation cannot process all sub-element and extensions, the implementation MUST return an appropriate SOAP fault. If the <wsse:Security> header does not have a mustUnderstand="true" attribute, the implementation SHOULD return a fault if it cannot process all sub-elements and extensions.


(I struggled a bit with the semantics of this - one option would be to try and effectively override mustUnderstand by saying that conforming implementations MUST process or fault, independent of mustUnderstand; I changed my mind on that because SOAP listeners without Soap Message Security implementations can legally ignore <wsse:Security mustUnderstand="false"> headers, so why can't conforming implementations?)


I think this says what we mean, modulo the above and the fact that the current specification isn't always clear about what it means to "process" the contents of a <wsse:Security> header. Speak up if you think I'm off track with the semantics, or if you have better wording.

 - irving -