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.
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:
2. Change subclause 6.3.11 (CIMError) as follows:
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" |
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):
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).