Re: [wss] ISSUE 190: text for SOAP MustUnderstand issue

[Christopher B Ferris <chrisfer@us.ibm.com>]

<decloak/>

SOAP1.1 may have been somewhat ambiguous as regards the intent behind
soap:mustUnderstand attribute, but SOAP1.2 is quite clear on the 
matter[1].
        "A SOAP header block is said to be understood by a SOAP node if 
        the software at that SOAP node has been written to fully conform 
to 
        and implement the semantics specified for the XML expanded name 
        of the outer-most element information item of that header block."

IMO, it isn't a balance that must be struck. All it requires is that 
the specification for the header block define the implied semantics. 

The SOAP mustUnderstand attribute with a value of true does not 
mean "ignore at your own peril", it is an integral part of the 
SOAP protocol. 

Section 2.4 of the SOAP1.2 spec continues:

        "Mandatory SOAP header blocks are presumed to somehow modify the 
semantics of other 
        SOAP header blocks or SOAP body elements. Therefore, for every 
mandatory SOAP header 
        block targeted to a node, that node MUST either process the header 
block or not process the 
        SOAP message at all, and instead generate a fault (see 2.6 
Processing SOAP Messages 
        and 5.4 SOAP Fault). Tagging SOAP header blocks as mandatory thus 
assures that such 
        modifications will not be silently (and, presumably, erroneously) 
ignored by a SOAP node 
        to which the header block is targeted."

The understanding of a SOAP header block labeled as mandatory, by means
of a SOAP mustUnderstand attribute, is not important only to the SOAP
node processing the message, it may have consequences for the sender of
that message as well. That's why the SOAP spec requires that a
MustUnderstand fault be generated, so that both the sender and receiver
are protected from unintended consequences.

One last point. It is not always possible to "return a fault". 
A SOAP fault is said to be "generated", which is distinct from
returning a message containing that fault to the sender of the
message that caused the fault to be generated. The important
point is that the generation of a fault terminates all subsequent
processing of the message beyond that which is necessary to 
handle the fault (e.g backing out uncommitted processing results
and possibly creating a SOAP Fault message to transmit the
fault to the sender).

I would suggest the following refinement to your proposal:

        Conforming implementations are said to "understand" a
        <wsse:Security> element if they are able to process the 
        <wsse:Security> element and all of its descendant elements, 
        including any elements or attributes defined by profiles 
        or extensions.

        If a <wsse:Security> header block is marked as mandatory by
        means of a SOAP mustUnderstand attribute, and also contains 
        extension elements or attributes that are not recognized 
        by the SOAP node to which the <wsse:Security> header block is
        targetted, a conforming implementation MUST generate a 
        SOAP MustUnderstand fault. 

The tricky part becomes what to do with non-mandatory <wsse:Security>
header blocks when they contain unrecognized extension elements or 
attributes. There are two possibilities, ignore the unrecognized
content but process the <wsse:Security> header block as if they were
not present, or discontinue processing the <wsse:Security> header
block entirely (e.g. ignore it altogether). 

SOAP header blocks that are not marked as mandatory with a SOAP 
mustUnderstand attribute carry the semantic that they MAY be safely 
ignored if not understood. From the SOAP1.2 specification section
2.6:

        "4.     ... A SOAP node MAY also choose to process non-mandatory 
SOAP 
        header blocks targeted at it."

Given this, and to be consistent with SOAP, I would suggest that 
the implementation be given the option of "ignoring unrecognized
extensions at its peril" or ignoring the header block altogether.

Suggested prose:

        If a <wsse:Security> header block is not marked as mandatory
        by means of a SOAP mustUnderstand attribute, and also contains
        extension elements or attributes that are not recognized by the
        SOAP node to which the <wsse:Security> header block is targetted,
        a conforming implementation MAY choose not to process the 
        <wsse:Security> header block.

[1] http://www.w3.org/TR/soap12-part1/#muprocessing

<cloak/>

Cheers,

Christopher Ferris
STSM, Emerging e-business Industry Architecture
email: chrisfer@us.ibm.com
phone: +1 508 234 3624

"Reid, Irving" <irving.reid@hp.com> wrote on 10/29/2003 06:44:31 PM:

> 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 -