LDAP "What Failed?" Control

The LDAP Protocol is extensible. Extensions include controls, extended requests and extensions related to other aspects of the protocol, for example those described in , and more. Operations may fail for different reasons. The resultCode may help in determining the reason of a failure. The (optional) diagnosticsMessage fields of a LDAPResponse could also be of help. However, according to , implementations MUST NOT rely on the returned values, which are simply intended to be presented as are to human users. In case of failure related to the inability to process a control marked as critical in a request, the specific resultCode unavailableCriticalExtension is returned. In case of failure related to an unrecognized extendedReq, the generic resultCode protocolError is returned. Failures related to handling other extensions may result in other generic resultCode values. As a consequence, DUAs may be unable to exactly determine what extension, if any, caused a failure. The "What Failed?" control represents a means for the DSA to inform DUAs about what specific extensions, if any, caused an error notified by the DSA. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .

The presence of the "What Failed?" LDAP control in a LDAP request indicates that the DUA, in case of error, wishes to receive detailed information about what extension, if any, caused the error. The criticality of the control in the request SHOULD be FALSE. According to the semantics of the criticality field as indicated in , this ensures that in case the control is not recognized by the DSA, it does not cause itself an error. The presence of this control in a request does not guarantee that the DSA will return detailed information about what extensions caused an error. Considering the requirement on the criticality of the control, the DSA MAY simply choose to ignore the control. The DSA MAY hide information about failure in handling an extension to prevent disclosure of other information. The DSA MAY choose to notify an error as soon as it is detected, instead of proceed checking its ability to handle any other extension present in a request. Implementations may choose to check the validity of extensions, including controls, as soon as they are parsed. As a consequence, a critical control might result in an error before thw "What Failed?" control request is parsed. Implementations SHOULD check anyway the presence of this control, unless they detect that the remaining part of the request is malformed. Clients SHOULD NOT rely on any specific ordering of controls handling when requesting the "What Failed?" control. Servers implementing this technical specification SHOULD publish the object identifier whatFailed-oid (IANA assigned; see ) as a value of the 'supportedControl' attribute in their root DSE.

The controlType is whatFailed-oid (IANA assigned; see ); the controlValue MUST be absent; the criticality SHOULD be FALSE.

The controlType is whatFailed-oid (IANA assigned; see ); the controlValue is: controlValue ::= SET OF oid LDAPOID If the set of extension OID is empty, the control is omitted from the response. The criticality MUST be FALSE.

The "What Failed?" LDAP Control is implemented in OpenLDAP software using the temporary OID 1.3.6.1.4.1.4203.666.5.17 under OpenLDAP's experimental OID arc.

Implementations MUST take measures to prevent the disclosure of sensible information whenever this may result from disclosing what extension caused an error. This can consist in excluding the OID of specific extensions from the controlValue in the response, or in entirely omitting the control in the response.

It is requested that IANA register upon Standards Action an LDAP Object Identifier for use in this technical specification. Subject: Request for LDAP OID Registration Person & email address to contact for further information: Pierangelo Masarati <ando@OpenLDAP.org> Specification: (I-D) Author/Change Controller: IESG Comments: Identifies the LDAP "What Failed?" Control request and response