git.sur5r.net Git - openldap/blob - doc/drafts/draft-masarati-ldap-whatfailed.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2
   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 rfc4526 PUBLIC ''
  11       'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4526.xml'>
  12     <!ENTITY rfc4529 PUBLIC ''
  13       'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4529.xml'>
  14 ]>
  15
  16 <!-- $OpenLDAP$ -->
  17
  18 <rfc category="std" ipr="full3978" docName="draft-masarati-ldap-whatfailed.txt">
  19
  20 <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
  21
  22 <?rfc toc="yes" ?>
  23 <?rfc symrefs="yes" ?>
  24 <?rfc sortrefs="yes"?>
  25 <?rfc iprnotified="no" ?>
  26 <?rfc strict="yes" ?>
  27
  28     <front>
  29         <title abbrev='LDAP WHATFAILED'>LDAP "What Failed?" Control</title>
  30         <author initials='P.' surname="Masarati" fullname='Pierangelo Masarati'>
  31             <organization abbrev='Politecnico di Milano'>
  32                 Politecnico di Milano
  33             </organization>
  34             <address>
  35                 <postal>
  36                     <street>Dipartimento di Ingegneria Aerospaziale</street>
  37                     <street>via La Masa 34</street>
  38                     <city>Milano</city>
  39                     <code>20156</code>
  40                     <country>IT</country>
  41                 </postal>
  42                 <phone>+39 02 2399 8309</phone>
  43                 <facsimile>+39 02 2399 8334</facsimile>
  44                 <email>ando@OpenLDAP.org</email>
  45                 <uri>http://www.aero.polimi.it/masarati/</uri>
  46             </address>
  47         </author>
  48         <!--date/-->
  49         <date month='October' year='2008' />
  50         <abstract>
  51             <t>
  52 This document describes the LDAP "What Failed?" control.
  53 This control allows DUAs to request, in response to a failed operation
  54 request, the object identifier of those extensions that caused
  55 the operation to fail.
  56             </t>
  57         </abstract>
  58     </front>
  59
  60     <middle>
  61         <section title="Background and Intended Use">
  62             <t>
  63 The LDAP Protocol <xref target="RFC4510" /> is extensible.
  64 Extensions include controls, extended requests and extensions related
  65 to other aspects of the protocol, for example those described in
  66 <xref target="RFC4526" />, <xref target="RFC4529" /> and more.
  67             </t>
  68
  69             <t>
  70 Operations may fail for different reasons.
  71 The resultCode may help in determining the reason of a failure.
  72 The (optional) diagnosticsMessage fields of a LDAPResponse
  73 could also be of help.
  74 However, according to <xref target="RFC4511" />,
  75 implementations MUST NOT rely on the returned values,
  76 which are simply intended to be presented as are to human users.
  77             </t>
  78
  79             <t>
  80 In case of failure related to the inability to process a control
  81 marked as critical in a request, the specific resultCode
  82 unavailableCriticalExtension is returned.
  83 In case of failure related to an unrecognized extendedReq, the generic
  84 resultCode protocolError is returned.
  85 Failures related to handling other extensions may result
  86 in other generic resultCode values.
  87             </t>
  88
  89             <t>
  90 As a consequence, DUAs may be unable to exactly determine
  91 what extension, if any, caused a failure.
  92 The "What Failed?" control represents a means for the DSA to inform
  93 DUAs about what specific extensions, if any, caused an error notified
  94 by the DSA.
  95             </t>
  96
  97             <t>
  98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
  99 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
 100 and "OPTIONAL" in this document are to be interpreted as
 101 described in <xref target="RFC2119" />.
 102             </t>
 103         </section>
 104
 105         <section title='LDAP "What Failed?" Control'>
 106             <section title="Control Semantics">
 107                 <t>
 108 The presence of the "What Failed?" LDAP control in a LDAP request
 109 indicates that the DUA, in case of error, wishes to receive detailed
 110 information about what extension, if any, caused the error.
 111                 </t>
 112
 113                 <t>
 114 The criticality of the control in the request SHOULD be FALSE.
 115 According to the semantics of the criticality field as indicated
 116 in <xref target="RFC4511" />, this ensures that in case the control
 117 is not recognized by the DSA, it does not cause itself an error.
 118                 </t>
 119
 120                 <t>
 121 The presence of this control in a request does not guarantee that the DSA
 122 will return detailed information about what extensions caused an error.
 123 Considering the requirement on the criticality of the control,
 124 the DSA MAY simply choose to ignore the control.
 125 The DSA MAY hide information about failure in handling an extension
 126 to prevent disclosure of other information.
 127 The DSA MAY choose to notify an error as soon as it is detected,
 128 instead of proceed checking its ability to handle any other extension
 129 present in a request.
 130                 </t>
 131
 132                 <t>
 133 Implementations may choose to check the validity of extensions,
 134 including controls, as soon as they are parsed.
 135 As a consequence, a critical control might result in an error
 136 before thw "What Failed?" control request is parsed.
 137 Implementations SHOULD check anyway the presence of this control,
 138 unless they detect that the remaining part of the request
 139 is malformed.
 140 Clients SHOULD NOT rely on any specific ordering of controls handling
 141 when requesting the "What Failed?" control.
 142                 </t>
 143             </section>
 144
 145             <section title="Control Request">
 146                 <t>
 147 The controlType is whatFailed-oid;
 148 the controlValue MUST be absent;
 149 the criticality SHOULD be FALSE.
 150                 </t>
 151             </section>
 152
 153             <section title="Control Response">
 154                 <figure>
 155                     <preamble>
 156 The controlType is whatFailed-oid;
 157 the controlValue is:
 158                     </preamble>
 159                     <artwork>
 160     controlValue ::= SET OF oid LDAPOID
 161                     </artwork>
 162                     <postamble>
 163 If the set of extension OID is empty, the control is omitted
 164 from the response.
 165 The criticality MUST be FALSE.
 166                     </postamble>
 167                 </figure>
 168             </section>
 169         </section>
 170
 171         <section title="Implementation Notes">
 172             <t>
 173 The "What Failed?" LDAP Control is implemented in OpenLDAP software
 174 using the temporary OID 1.3.6.1.4.1.4203.666.5.17 under OpenLDAP's
 175 experimental OID arc.
 176             </t>
 177         </section>
 178
 179         <section title="Security Considerations">
 180             <t>
 181 Implementations MUST take measures to prevent the disclosure
 182 of sensible information whenever this may result from disclosing
 183 what extension caused an error.
 184 This can consist in excluding the OID of specific extensions from
 185 the controlValue in the response, or in entirely omitting the control
 186 in the response.
 187             </t>
 188         </section>
 189
 190         <section title="IANA Considerations">
 191             <section title="Object Identifier Registration">
 192                 <figure>
 193                     <preamble>
 194 It is requested that IANA register upon Standards Action an LDAP
 195 Object Identifier for use in this technical specification.
 196                     </preamble>
 197                     <artwork>
 198       Subject: Request for LDAP OID Registration
 199       Person &amp; email address to contact for further information:
 200           Pierangelo Masarati &lt;ando@OpenLDAP.org&gt;
 201       Specification: (I-D)
 202       Author/Change Controller: IESG
 203       Comments:
 204           Identifies the LDAP "What Failed?" Control request
 205           and response
 206                     </artwork>
 207                 </figure>
 208             </section>
 209         </section>
 210
 211         <section title="Acknowledgments">
 212         </section>
 213     </middle>
 214
 215     <back>
 216         <references title='Normative References'>
 217             &rfc2119;
 218             &rfc4510;
 219             &rfc4511;
 220         </references>
 221         <references title='Informative References'>
 222             &rfc4526;
 223             &rfc4529;
 224         </references>
 225     </back>
 226
 227 </rfc>