1 <?xml version="1.0" encoding="UTF-8"?>
3 <!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
4 <!ENTITY rfc2119 PUBLIC ''
5 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
6 <!ENTITY rfc4510 PUBLIC ''
7 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4510.xml'>
8 <!ENTITY rfc4511 PUBLIC ''
9 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4511.xml'>
10 <!ENTITY rfc4512 PUBLIC ''
11 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4512.xml'>
12 <!ENTITY rfc4526 PUBLIC ''
13 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4526.xml'>
14 <!ENTITY rfc4529 PUBLIC ''
15 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4529.xml'>
20 <rfc category="std" ipr="full3978" docName="draft-masarati-ldap-whatfailed.txt">
22 <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
25 <?rfc symrefs="yes" ?>
26 <?rfc sortrefs="yes"?>
27 <?rfc iprnotified="no" ?>
31 <title abbrev='LDAP WHATFAILED'>LDAP "What Failed?" Control</title>
32 <author initials='P.' surname="Masarati" fullname='Pierangelo Masarati'>
33 <organization abbrev='Politecnico di Milano'>
38 <street>Dipartimento di Ingegneria Aerospaziale</street>
39 <street>via La Masa 34</street>
44 <phone>+39 02 2399 8309</phone>
45 <facsimile>+39 02 2399 8334</facsimile>
46 <email>ando@OpenLDAP.org</email>
47 <uri>http://www.aero.polimi.it/masarati/</uri>
51 <date month='October' year='2008' />
54 This document describes the LDAP "What Failed?" control.
55 This control allows DUAs to request, in response to a failed operation
56 request, the object identifier of those extensions that caused
57 the operation to fail.
63 <section title="Background and Intended Use">
65 The LDAP Protocol <xref target="RFC4510" /> is extensible.
66 Extensions include controls, extended requests and extensions related
67 to other aspects of the protocol, for example those described in
68 <xref target="RFC4526" />, <xref target="RFC4529" /> and more.
72 Operations may fail for different reasons.
73 The resultCode may help in determining the reason of a failure.
74 The (optional) diagnosticsMessage fields of a LDAPResponse
75 could also be of help.
76 However, according to <xref target="RFC4511" />,
77 implementations MUST NOT rely on the returned values,
78 which are simply intended to be presented as are to human users.
82 In case of failure related to the inability to process a control
83 marked as critical in a request, the specific resultCode
84 unavailableCriticalExtension is returned.
85 In case of failure related to an unrecognized extendedReq, the generic
86 resultCode protocolError is returned.
87 Failures related to handling other extensions may result
88 in other generic resultCode values.
92 As a consequence, DUAs may be unable to exactly determine
93 what extension, if any, caused a failure.
94 The "What Failed?" control represents a means for the DSA to inform
95 DUAs about what specific extensions, if any, caused an error notified
100 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
101 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
102 and "OPTIONAL" in this document are to be interpreted as
103 described in <xref target="RFC2119" />.
107 <section title='LDAP "What Failed?" Control'>
108 <section title="Control Semantics">
110 The presence of the "What Failed?" LDAP control in a LDAP request
111 indicates that the DUA, in case of error, wishes to receive detailed
112 information about what extension, if any, caused the error.
116 The criticality of the control in the request SHOULD be FALSE.
117 According to the semantics of the criticality field as indicated
118 in <xref target="RFC4511" />, this ensures that in case the control
119 is not recognized by the DSA, it does not cause itself an error.
123 The presence of this control in a request does not guarantee that the DSA
124 will return detailed information about what extensions caused an error.
125 Considering the requirement on the criticality of the control,
126 the DSA MAY simply choose to ignore the control.
127 The DSA MAY hide information about failure in handling an extension
128 to prevent disclosure of other information.
129 The DSA MAY choose to notify an error as soon as it is detected,
130 instead of proceed checking its ability to handle any other extension
131 present in a request.
135 Implementations may choose to check the validity of extensions,
136 including controls, as soon as they are parsed.
137 As a consequence, a critical control might result in an error
138 before thw "What Failed?" control request is parsed.
139 Implementations SHOULD check anyway the presence of this control,
140 unless they detect that the remaining part of the request
142 Clients SHOULD NOT rely on any specific ordering of controls handling
143 when requesting the "What Failed?" control.
147 Servers implementing this technical specification SHOULD publish
148 the object identifier whatFailed-oid (IANA assigned;
149 see <xref target="iana_considerations" />) as a value
150 of the 'supportedControl' attribute <xref target="RFC4512" />
155 <section title="Control Request">
157 The controlType is whatFailed-oid (IANA assigned;
158 see <xref target="iana_considerations" />);
159 the controlValue MUST be absent;
160 the criticality SHOULD be FALSE.
164 <section title="Control Response">
167 The controlType is whatFailed-oid (IANA assigned;
168 see <xref target="iana_considerations" />);
172 controlValue ::= SET OF oid LDAPOID
175 If the set of extension OID is empty, the control is omitted
177 The criticality MUST be FALSE.
183 <section title="Implementation Notes">
185 The "What Failed?" LDAP Control is implemented in OpenLDAP software
186 using the temporary OID 1.3.6.1.4.1.4203.666.5.17 under OpenLDAP's
187 experimental OID arc.
191 <section title="Security Considerations">
193 Implementations MUST take measures to prevent the disclosure
194 of sensible information whenever this may result from disclosing
195 what extension caused an error.
196 This can consist in excluding the OID of specific extensions from
197 the controlValue in the response, or in entirely omitting the control
202 <section anchor="iana_considerations" title="IANA Considerations">
203 <section title="Object Identifier Registration">
206 It is requested that IANA register upon Standards Action an LDAP
207 Object Identifier for use in this technical specification.
210 Subject: Request for LDAP OID Registration
211 Person & email address to contact for further information:
212 Pierangelo Masarati <ando@OpenLDAP.org>
214 Author/Change Controller: IESG
216 Identifies the LDAP "What Failed?" Control request
223 <section title="Acknowledgments">
228 <references title='Normative References'>
234 <references title='Informative References'>