#2594 CR28: Support CIMErrorDescription HTTP field

closed-fixed
Dave Blaschke
jsr48-client
5
2013-12-13
2013-01-15
Dave Blaschke
No

Background/Rationale:

DSP0200 1.3.1 provides the following means to deal with low level errors (errors that do not allow a CIM response message with an ERROR element to be sent):

1. HTTP status code

The HTTP status code is specified as a decimal number at the begin of the HTTP header. There is no textual information, and no information that allows to detail the same status code into multiple cases.

2. CIMError header

This is a CIM-XML specific extension header that may be added to responses as additional detail to the HTTP status code. It is intended to disambiguate errors with the same HTTP status code. Its values is currently a fixed set of tokens that are intended to be machine-processed. While these tokens are readable strings, they do not really serve well as human readable error messages.

There are multiple issues with this approach:

A number of cases related to user authentication and authorization are missing from the list of currently defined tokens for CIMError.
The list of tokens for CIMError is currently a fixed list that does not allow vendor extensions.
There is no human readable error message for such low level errors. Requiring that a client has hard wired knowledge about all the CIMError tokens and then creates such messages does not work, specifically if the set of tokens is extended over time (because of older for clients), or if it allows for vendor extensions.

At least two existing CIM server implementations have added their own extension headers to pass back such error details:

OpenPegasus added the "PGErrorDetail" extension header that contains a human readable error message. It did not add a header for a machine readable representation, and also did not extend the set of values for CIMError. It does support CIMError in addition, with the set of values defined in DSP0200.
Same for SFCB, just the header is called "SFCBErrorDetail".

This CR extends the CIMError header with new token values, provides a vendor extension concept for CIMError, and adds a CIMErrorDescription header for human readable error messages.

Requested Change:

1. Change subclause 6.3 (Extension Headers Defined for CIM Message Requests and Responses) as follows:

An HTTP response with an error status code to a CIM message request may include the following CIM extension header headers:

CIMError
CIMErrorDescription

2. Change subclause 6.3.11 (CIMError) as follows:

6.3.11 CIMError

The CIMError header may be present in any HTTP response to a CIM message request that is not a CIM message response.

It shall not be present in any CIM message response or in any CIM message request.

The CIMError header provides further CIM-specific diagnostic information if the CIM server or CIM listener encounters a fundamental error during processing of the CIM operation request and is intended to assist clients to further disambiguate errors with the same HTTP status code:
CIMError = "CIMError" ":" cim-error

cim-error = dmtf-error | extension-error

cimdmtf-error = "unsupported-protocol-version" |
"multiple-requests-unsupported" |
"unsupported-cim-version" |
"unsupported-dtd-version" |
"request-not-valid" |
"request-not-well-formed" |
"request-not-loosely-valid" |
"header-mismatch" |
"unsupported-operation" |
"authentication-failed" |
"credentials-expired" |
"userid-revoked" |
"insufficient-privileges" |
"auth-service-unavailable"

extension-error = org-id ":" local-id

org-id = 1*( ALPHA | DIGIT )

local-id = 1*( ALPHA | DIGIT | ":" | "-" )

dmtf-error includes all values defined in this specification. Future minor versions of this specification may extend the set of values.

extension-error is provided for additional implementation-defined values.

org-id shall identify the business entity owning the extension error definition. org-id shall include a copyrighted, trademarked, or otherwise unique name that is owned by that business entity or that is a registered ID assigned to that business entity by a recognized global authority. In addition, to ensure uniqueness, org-id shall not contain a colon (:).

local-id shall uniquely identify the extension error within the business entity identified by org-id.

3. Add a new subclause after subclause 6.3.11 (CIMError):
6.3.12 CIMErrorDescription

The CIMErrorDescription header may be included if the CIMError header is present in an HTTP response. The CIMErrorDescription header shall not be included if the CIMError header is not present in an HTTP response.

If included, the CIMErrorDescription header shall provide a string that is a human readable message for the situation indicated by the CIMError header. For each distinct CIMError value, there should be only one CIMErrorDescription value.

CIMErrorDescription = "CIMErrorDescription" ":" cim-error-description

This specification does not define any additional restrictions for the cim-error-description value. As a result, the rules defined in section 4.2 of RFC2616 apply: The unfolded and unescaped cim-error-description value may contain any valid UCS characters except newline (U+000A) and carriage return (U+000D); While the HTTP response is transmitted, leading and trailing whitespace characters (U+0020 and U+0009) may be stripped off and multiple adjacent whitespace characters (U+0020 and U+0009) may be replaced by one space (U+0020).

1 Attachments

Discussion

  • Dave Blaschke
    Dave Blaschke
    2013-01-15

    • priority: 5 --> 4
     
  • Dave Blaschke
    Dave Blaschke
    2013-01-15

    Lowering priority one notch below normal, this bug is dependent on DMTF
    CIM-XML changes

     
  • Dave Blaschke
    Dave Blaschke
    2013-01-15

    • summary: Implement DMTF CRCIMXML00028 --> Support CIMErrorDescription HTTP field
     
  • Dave Blaschke
    Dave Blaschke
    2013-01-16

    This change is defined in DMTF CRCIMXML00028

     
  • Dave Blaschke
    Dave Blaschke
    2013-01-24

    • summary: Support CIMErrorDescription HTTP field --> CR28: Support CIMErrorDescription HTTP field
     
  • Dave Blaschke
    Dave Blaschke
    2013-02-20

    Classic ID #3600970

     
  • Dave Blaschke
    Dave Blaschke
    2013-02-20

    • component: --> jsr48-client
     
  • Dave Blaschke
    Dave Blaschke
    2013-04-30

    • status: open --> open-remind
    • Priority: 4 --> 2
     
  • Dave Blaschke
    Dave Blaschke
    2013-04-30

    DSP0200 1.4.0a-rc1 was published yesterday, CR28 will not be applied until 1.5.0 (if at all)

     
  • Dave Blaschke
    Dave Blaschke
    2013-11-30

    • status: open-remind --> open-fixed
    • Priority: 2 --> 5
     
  • Dave Blaschke
    Dave Blaschke
    2013-11-30

    Patch sent for community review. During a 2 week period any exploiter may comment on the patch, request changes or turn it down completely (with good reason). For the time being the patch is part of the "Experimental" branch in CVS.

     
  • Dave Blaschke
    Dave Blaschke
    2013-12-12

    • status: open-fixed --> pending-fixed
     
  • Dave Blaschke
    Dave Blaschke
    2013-12-12

    The community review is completed and we received no substantial criticism. Therefore the patch has been approved and merged into the "HEAD" branch. The next release will pick it up.

     
  • Dave Blaschke
    Dave Blaschke
    2013-12-13

    The patch was picked up by release 2.2.5 and will be closed.

     
  • Dave Blaschke
    Dave Blaschke
    2013-12-13

    • status: pending-fixed --> closed-fixed