[security-services] Status code clarifications/cleanup

[Scott Cantor <cantor.2@osu.edu>]

This is kind of a mixed bag of suggested text and some schema changes to
clean up the document during last call. None of this should hold
anything up this week. Item (1) is the only substantive change.

1) Removal of StatusCodeEnumType

I've realized that if we define the base set of four status codes in the
schema, as an enumeration of QNames, the schema then mandates that the
namespace prefix of "samlp" appear inside the status code value. A
restriction derivation of QName seems to be lexical instead of logical,
essentially. I think this is weird, but it seems to be a consequence of
the poor handling of QNames in XML because they were tacked on
afterward.

It should be legal for any namespace prefix to be used as long as it
maps to the correct namespace URI (the SAML protocol namespace in this
case), so my suggestion is to remove the eumeration from the schema and
then collapse the StatusCode schema definition to:

<complexType name="StatusCodeType">
	<sequence>
		<element ref="samlp:StatusCode" minOccurs="0"/>
	</sequence>
	<attribute name="Value" type="QName" use="required"/>
</complexType>

StatusCodeEnumType, SubStatusCodeType, and the SubStatusCode element can
then be deleted along with corresponding cleanup of the element
descriptions in the document. In 3.4.3.1 where it defines the codes, it
could say something like:

"The following top-level status code values are defined:"

Then underneath those:

"The following second-level status codes are referenced at various
places in the specification. Additional subcodes may be defined in
future versions of the SAML specification."

The disadvantage to this is that it moves the validation/checking of the
four mandatory Status Codes out of the schema and into the SAML
implementation, but personally I think lexically validating the samlp
prefix in the QNames is even worse.

If there's a better way to create an enumeration of QNames that doesn't
suffer from this drawback, I guess that would be the alternative to
this, but I haven't found one.

---------------

2) Change Sender/Receiver to Requester/Responder

This is a suggestion of Simon Godik's that got lost somewhere, but it
was a good one, IMHO. The latter terminology is more consistent with the
usage and the other documents, so I think the four top-level codes
should be Success, VersionMismatch, Requester, and Responder.

---------------

3) Clarifying section on namespace of status codes in the document

I suggest adding a section after the current section 1.2.1 (Time Values)
as follows:

1.2.2 Status Code Values

All status code values defined in this document are QNames associated
with the SAML protocol namespace [SAMLP] and MUST be prefixed
approprately when they appear in SAML messages. SAML extensions and
applications are free to define more specific status codes in other
namespaces.

---------------

4) Additional cleanup of document

The following changes should clean up the specification of what codes
are defined and how they're used, especially subcodes. I use the changed
terminology from Simon from suggestion (2) above.

Section 3.3.4, change line 1116 to:

SHOULD respond with a top-level StatusCode value of Responder and a
second-level value of ResourceNotRecognized.

Section 4.3, change line 1374 to:

Incompatible protocol versions MUST result in reporting a top-level
StatusCode value of VersionMismatch, and MAY result in reporting one of
the following second-level values:

If I missed any spots, similar text can be used as above.

-- Scott