--- /dev/null
+
+
+
+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]
+\f
+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]
+\f
+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]
+\f
+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]
+\f
+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]
+\f
+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]
+\f
+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]
+\f
+Internet-Draft LDAP WHATFAILED October 2008
+
+
+6. Acknowledgments
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Masarati Expires April 4, 2009 [Page 8]
+\f
+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]
+\f
+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]
+\f
+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]
+\f
--- /dev/null
+<?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 & 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
+ </artwork>
+ </figure>
+ </section>
+ </section>
+
+ <section title="Acknowledgments">
+ </section>
+ </middle>
+
+ <back>
+ <references title='Normative References'>
+ &rfc2119;
+ &rfc4510;
+ &rfc4511;
+ &rfc4526;
+ &rfc4529;
+ </references>
+ </back>
+
+</rfc>
projects / openldap / commitdiff