From d023222ee4b3a368fc00868f41bf1ef4d1e4e25e Mon Sep 17 00:00:00 2001
From: Pierangelo Masarati <ando@openldap.org>
Date: Sat, 1 Nov 2008 14:42:39 +0000
Subject: [PATCH] add "What Failed?" LDAP control (ITS#5784)

---
 .../draft-masarati-ldap-whatfailed-xx.txt     | 616 ++++++++++++++++++
 doc/drafts/draft-masarati-ldap-whatfailed.xml | 225 +++++++
 2 files changed, 841 insertions(+)
 create mode 100644 doc/drafts/draft-masarati-ldap-whatfailed-xx.txt
 create mode 100644 doc/drafts/draft-masarati-ldap-whatfailed.xml

diff --git a/doc/drafts/draft-masarati-ldap-whatfailed-xx.txt b/doc/drafts/draft-masarati-ldap-whatfailed-xx.txt
new file mode 100644
index 0000000000..8a0fa2a64b
--- /dev/null
+++ b/doc/drafts/draft-masarati-ldap-whatfailed-xx.txt
@@ -0,0 +1,616 @@
+
+
+
+Network Working Group                                        P. Masarati
+Internet-Draft                                     Politecnico di Milano
+Intended status: Standards Track                            October 2008
+Expires: April 4, 2009
+
+
+                      LDAP "What Failed?" Control
+                   draft-masarati-ldap-whatfailed.txt
+
+Status of this Memo
+
+   By submitting this Internet-Draft, each author represents that any
+   applicable patent or other IPR claims of which he or she is aware
+   have been or will be disclosed, and any of which he or she becomes
+   aware will be disclosed, in accordance with Section 6 of BCP 79.
+
+   Internet-Drafts are working documents of the Internet Engineering
+   Task Force (IETF), its areas, and its working groups.  Note that
+   other groups may also distribute working documents as Internet-
+   Drafts.
+
+   Internet-Drafts are draft documents valid for a maximum of six months
+   and may be updated, replaced, or obsoleted by other documents at any
+   time.  It is inappropriate to use Internet-Drafts as reference
+   material or to cite them other than as "work in progress."
+
+   The list of current Internet-Drafts can be accessed at
+   http://www.ietf.org/ietf/1id-abstracts.txt.
+
+   The list of Internet-Draft Shadow Directories can be accessed at
+   http://www.ietf.org/shadow.html.
+
+   This Internet-Draft will expire on April 4, 2009.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Masarati                  Expires April 4, 2009                 [Page 1]
+
+Internet-Draft               LDAP WHATFAILED                October 2008
+
+
+Abstract
+
+   This document describes the LDAP "What Failed?" control.  This
+   control allows DUAs to request, in response to a failed operation
+   request, the object identifier of those extensions that caused the
+   operation to fail.
+
+
+Table of Contents
+
+   1.  Background and Intended Use  . . . . . . . . . . . . . . . . .  3
+   2.  LDAP "What Failed?" Control  . . . . . . . . . . . . . . . . .  4
+     2.1.  Control Semantics  . . . . . . . . . . . . . . . . . . . .  4
+     2.2.  Control Request  . . . . . . . . . . . . . . . . . . . . .  4
+     2.3.  Control Response . . . . . . . . . . . . . . . . . . . . .  4
+   3.  Implementation Notes . . . . . . . . . . . . . . . . . . . . .  5
+   4.  Security Considerations  . . . . . . . . . . . . . . . . . . .  6
+   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  7
+     5.1.  Object Identifier Registration . . . . . . . . . . . . . .  7
+   6.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . .  8
+   7.  Normative References . . . . . . . . . . . . . . . . . . . . .  9
+   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10
+   Intellectual Property and Copyright Statements . . . . . . . . . . 11
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Masarati                  Expires April 4, 2009                 [Page 2]
+
+Internet-Draft               LDAP WHATFAILED                October 2008
+
+
+1.  Background and Intended Use
+
+   The LDAP Protocol [RFC4510] is extensible.  Extensions include
+   controls, extended requests and extensions related to other aspects
+   of the protocol, for example those described in [RFC4526], [RFC4529]
+   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 [RFC4511], 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 [RFC2119].
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Masarati                  Expires April 4, 2009                 [Page 3]
+
+Internet-Draft               LDAP WHATFAILED                October 2008
+
+
+2.  LDAP "What Failed?" Control
+
+2.1.  Control Semantics
+
+   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
+   [RFC4511], 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.
+
+2.2.  Control Request
+
+   The controlType is whatFailed-oid; the controlValue MUST be absent;
+   the criticality SHOULD be FALSE.
+
+2.3.  Control Response
+
+   The controlType is whatFailed-oid; 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 SHOULD be FALSE.
+
+
+
+
+
+
+Masarati                  Expires April 4, 2009                 [Page 4]
+
+Internet-Draft               LDAP WHATFAILED                October 2008
+
+
+3.  Implementation Notes
+
+   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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Masarati                  Expires April 4, 2009                 [Page 5]
+
+Internet-Draft               LDAP WHATFAILED                October 2008
+
+
+4.  Security Considerations
+
+   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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Masarati                  Expires April 4, 2009                 [Page 6]
+
+Internet-Draft               LDAP WHATFAILED                October 2008
+
+
+5.  IANA Considerations
+
+5.1.  Object Identifier Registration
+
+   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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Masarati                  Expires April 4, 2009                 [Page 7]
+
+Internet-Draft               LDAP WHATFAILED                October 2008
+
+
+6.  Acknowledgments
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Masarati                  Expires April 4, 2009                 [Page 8]
+
+Internet-Draft               LDAP WHATFAILED                October 2008
+
+
+7.  Normative References
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+   [RFC4510]  Zeilenga, K., "Lightweight Directory Access Protocol
+              (LDAP): Technical Specification Road Map", RFC 4510,
+              June 2006.
+
+   [RFC4511]  Sermersheim, J., "Lightweight Directory Access Protocol
+              (LDAP): The Protocol", RFC 4511, June 2006.
+
+   [RFC4526]  Zeilenga, K., "Lightweight Directory Access Protocol
+              (LDAP) Absolute True and False Filters", RFC 4526,
+              June 2006.
+
+   [RFC4529]  Zeilenga, K., "Requesting Attributes by Object Class in
+              the Lightweight Directory Access Protocol", RFC 4529,
+              June 2006.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Masarati                  Expires April 4, 2009                 [Page 9]
+
+Internet-Draft               LDAP WHATFAILED                October 2008
+
+
+Author's Address
+
+   Pierangelo Masarati
+   Politecnico di Milano
+   Dipartimento di Ingegneria Aerospaziale
+   via La Masa 34
+   Milano  20156
+   IT
+
+   Phone: +39 02 2399 8309
+   Fax:   +39 02 2399 8334
+   Email: ando@OpenLDAP.org
+   URI:   http://www.aero.polimi.it/masarati/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Masarati                  Expires April 4, 2009                [Page 10]
+
+Internet-Draft               LDAP WHATFAILED                October 2008
+
+
+Full Copyright Statement
+
+   Copyright (C) The IETF Trust (2008).
+
+   This document is subject to the rights, licenses and restrictions
+   contained in BCP 78, and except as set forth therein, the authors
+   retain all their rights.
+
+   This document and the information contained herein are provided on an
+   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
+   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
+   THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
+   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
+   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
+   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+Intellectual Property
+
+   The IETF takes no position regarding the validity or scope of any
+   Intellectual Property Rights or other rights that might be claimed to
+   pertain to the implementation or use of the technology described in
+   this document or the extent to which any license under such rights
+   might or might not be available; nor does it represent that it has
+   made any independent effort to identify any such rights.  Information
+   on the procedures with respect to rights in RFC documents can be
+   found in BCP 78 and BCP 79.
+
+   Copies of IPR disclosures made to the IETF Secretariat and any
+   assurances of licenses to be made available, or the result of an
+   attempt made to obtain a general license or permission for the use of
+   such proprietary rights by implementers or users of this
+   specification can be obtained from the IETF on-line IPR repository at
+   http://www.ietf.org/ipr.
+
+   The IETF invites any interested party to bring to its attention any
+   copyrights, patents or patent applications, or other proprietary
+   rights that may cover technology that may be required to implement
+   this standard.  Please address the information to the IETF at
+   ietf-ipr@ietf.org.
+
+
+
+
+
+
+
+
+
+
+
+Masarati                  Expires April 4, 2009                [Page 11]
+
diff --git a/doc/drafts/draft-masarati-ldap-whatfailed.xml b/doc/drafts/draft-masarati-ldap-whatfailed.xml
new file mode 100644
index 0000000000..4cab16812c
--- /dev/null
+++ b/doc/drafts/draft-masarati-ldap-whatfailed.xml
@@ -0,0 +1,225 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
+    <!ENTITY rfc2119 PUBLIC '' 
+      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
+    <!ENTITY rfc4510 PUBLIC '' 
+      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4510.xml'>
+    <!ENTITY rfc4511 PUBLIC '' 
+      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4511.xml'>
+    <!ENTITY rfc4526 PUBLIC '' 
+      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4526.xml'>
+    <!ENTITY rfc4529 PUBLIC '' 
+      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4529.xml'>
+]>
+
+<!-- $OpenLDAP$ -->
+
+<rfc category="std" ipr="full3978" docName="draft-masarati-ldap-whatfailed.txt">
+
+<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
+
+<?rfc toc="yes" ?>
+<?rfc symrefs="yes" ?>
+<?rfc sortrefs="yes"?>
+<?rfc iprnotified="no" ?>
+<?rfc strict="yes" ?>
+
+    <front>
+        <title abbrev='LDAP WHATFAILED'>LDAP "What Failed?" Control</title>
+        <author initials='P.' surname="Masarati" fullname='Pierangelo Masarati'>
+            <organization abbrev='Politecnico di Milano'>
+                Politecnico di Milano
+            </organization>
+            <address>
+                <postal>
+                    <street>Dipartimento di Ingegneria Aerospaziale</street>
+                    <street>via La Masa 34</street>
+                    <city>Milano</city>
+                    <code>20156</code>
+                    <country>IT</country>
+                </postal>
+                <phone>+39 02 2399 8309</phone>
+                <facsimile>+39 02 2399 8334</facsimile>
+                <email>ando@OpenLDAP.org</email>
+                <uri>http://www.aero.polimi.it/masarati/</uri>
+            </address>
+        </author>
+        <!--date/-->
+        <date month='October' year='2008' />
+        <abstract>
+            <t>
+This document describes the LDAP "What Failed?" control.
+This control allows DUAs to request, in response to a failed operation
+request, the object identifier of those extensions that caused
+the operation to fail.
+            </t>
+        </abstract>
+    </front>
+
+    <middle>
+        <section title="Background and Intended Use">
+            <t>
+The LDAP Protocol <xref target="RFC4510" /> is extensible.
+Extensions include controls, extended requests and extensions related
+to other aspects of the protocol, for example those described in
+<xref target="RFC4526" />, <xref target="RFC4529" /> and more.
+            </t>
+
+            <t>
+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 <xref target="RFC4511" />,
+implementations MUST NOT rely on the returned values,
+which are simply intended to be presented as are to human users.
+            </t>
+
+            <t>
+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.
+            </t>
+
+            <t>
+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.
+            </t>
+
+            <t>
+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 <xref target="RFC2119" />.
+            </t>
+        </section>
+
+        <section title='LDAP "What Failed?" Control'>
+            <section title="Control Semantics">
+                <t>
+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.
+                </t>
+
+                <t>
+The criticality of the control in the request SHOULD be FALSE.
+According to the semantics of the criticality field as indicated
+in <xref target="RFC4511" />, this ensures that in case the control
+is not recognized by the DSA, it does not cause itself an error.
+                </t>
+
+                <t>
+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.
+                </t>
+
+                <t>
+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.
+                </t>
+            </section>
+
+            <section title="Control Request">
+                <t>
+The controlType is whatFailed-oid;
+the controlValue MUST be absent;
+the criticality SHOULD be FALSE.
+                </t>
+            </section>
+
+            <section title="Control Response">
+                <figure>
+                    <preamble>
+The controlType is whatFailed-oid;
+the controlValue is:
+                    </preamble>
+                    <artwork>
+    controlValue ::= SET OF oid LDAPOID
+                    </artwork>
+                    <postamble>
+If the set of extension OID is empty, the control is omitted
+from the response.
+The criticality SHOULD be FALSE.
+                    </postamble>
+                </figure>
+            </section>
+        </section>
+
+        <section title="Implementation Notes">
+            <t>
+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.
+            </t>
+        </section>
+
+        <section title="Security Considerations">
+            <t>
+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.
+            </t>
+        </section>
+
+        <section title="IANA Considerations">
+            <section title="Object Identifier Registration">
+                <figure>
+                    <preamble>
+It is requested that IANA register upon Standards Action an LDAP
+Object Identifier for use in this technical specification.
+                    </preamble>
+                    <artwork>
+      Subject: Request for LDAP OID Registration
+      Person &amp; email address to contact for further information:
+          Pierangelo Masarati &lt;ando@OpenLDAP.org&gt;
+      Specification: (I-D)
+      Author/Change Controller: IESG
+      Comments:
+          Identifies the LDAP "What Failed?" Control request
+          and response
+                    </artwork>
+                </figure>
+            </section>
+        </section>
+
+        <section title="Acknowledgments">
+        </section>
+    </middle>
+
+    <back>
+        <references title='Normative References'>
+            &rfc2119;
+            &rfc4510;
+            &rfc4511;
+            &rfc4526;
+            &rfc4529;
+        </references>
+    </back>
+
+</rfc>
-- 
2.39.5