-Internet-Draft David Chadwick\r
-LDAPExt WG University of Salford \r
-Intended Category: Standards Track Sean Mullan\r
- Sun Microsystems\r
-Expires: 1 January 2001 1 July 2000\r
-\r
-\r
-Returning Matched Values with LDAPv3\r
-<draft-ietf-ldapext-matchedval-02.txt>\r
-\r
-\r
-STATUS OF THIS MEMO\r
-\r
-This document is an Internet-Draft and is in full conformance with \r
-all the provisions of Section 10 of RFC2026.\r
-\r
-Internet-Drafts are working documents of the Internet Engineering \r
-Task Force (IETF), its areas, and its working groups. Note that other\r
-groups may also distribute working documents as Internet-Drafts.\r
-\r
-Internet-Drafts are draft documents valid for a maximum of six months\r
-and may be updated, replaced, or obsoleted by other documents at any\r
-time. It is inappropriate to use Internet-Drafts as reference \r
-material or to cite them other than as "work in progress."\r
-\r
-The list of current Internet-Drafts can be accessed at\r
-http://www.ietf.org/ietf/1id-abstracts.txt.\r
-\r
-The list of Internet-Draft Shadow Directories can be accessed at\r
-http://www.ietf.org/shadow.html.\r
-\r
-This Internet-Draft expires on 1 January 2001. Comments and \r
-suggestions on this document are encouraged. Comments on this \r
-document should be sent to the LDAPExt working group discussion list:\r
- ietf-ldapext@netscape.com\r
-or directly to the authors.\r
-\r
-\r
-ABSTRACT\r
-\r
-This document describes a control for the Lightweight Directory \r
-Access Protocol v3 that is used to return a subset of attribute \r
-values from an entry, specifically, only those values that match a \r
-"values return" filter. Without support for this control, a client \r
-must retrieve all of an attribute's values and search for specific \r
-values locally.\r
-\r
-\r
-1. Introduction\r
-\r
-When reading an attribute from an entry using LDAP v2 [1] or LDAPv3 \r
-[2], it is normally only possible to read either the attribute type, \r
-or the attribute type and all its values. It is not possible to \r
-selectively read just a few of the attribute values. If an attribute \r
-holds many values, for example, the userCertificate attribute, or the \r
-subschema publishing operational attributes objectClasses and \r
-attributeTypes [3], then it may be desirable for the user to be able \r
-to selectively retrieve a subset of the values, specifically, those \r
-attribute values that match some user defined selection criteria. \r
-Without the control specified in this [ID/standard] a client must \r
-read all of the attribute's values and filter out the unwanted \r
-values, necessitating the client to implement the matching rules. It \r
-also requires the client to potentially read and process many \r
-irrelevant values, which can be inefficient if the values are large \r
-or complex, or there are many values stored per attribute.\r
-\r
-This Internet Draft specifies an LDAPv3 control to enable a user to \r
-return only those values that matched (i.e. returned TRUE to) one or \r
-more elements of a newly defined "values return" filter. This control \r
-can be especially useful when used in conjunction with extensible \r
-matching rules that match on one or more components of complex binary \r
-attribute values.\r
-\r
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", \r
-"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this \r
-document are to be interpreted as described in RFC 2119 [5].\r
-\r
-\r
-2. The valuesReturnFilter Control\r
-\r
-The valuesReturnFilter control MAY be critical or non-critical as \r
-determined by the user. It is only applicable to the Search \r
-operation, and SHALL be ignored by the server if it is present on any \r
-other LDAP operation (even if marked critical on such operations).\r
-\r
-The object identifier for this control is 1.2.826.0.1.3344810.2.3\r
-\r
-\r
-The controlValue is \r
-\r
- ValuesReturnFilter ::= SEQUENCE OF SimpleFilterItem\r
-\r
- SimpleFilterItem ::= CHOICE {\r
- equalityMatch [3] AttributeValueAssertion,\r
- substrings [4] SubstringFilter,\r
- greaterOrEqual [5] AttributeValueAssertion,\r
- lessOrEqual [6] AttributeValueAssertion,\r
- present [7] AttributeDescription,\r
- approxMatch [8] AttributeValueAssertion,\r
- extensibleMatch [9] SimpleMatchingAssertion }\r
-\r
- SimpleMatchingAssertion ::= SEQUENCE {\r
- matchingRule [1] MatchingRuleId OPTIONAL,\r
- type [2] AttributeDescription OPTIONAL,\r
- matchValue [3] AssertionValue}\r
-\r
-All the above data types have their standard meanings as defined in \r
-[2].\r
-\r
-If the server supports this control, the server MUST make use of the \r
-control as follows:\r
-\r
-(1) The Search Filter is first executed in order to determine \r
-which entries satisfy the Search criteria. The control has no \r
-impact on this step.\r
-\r
-(2) If the typesOnly parameter of the Search Request is TRUE, \r
-the control has no effect and the Search Request SHOULD be \r
-processed as if the control had not been specified.\r
-\r
-(3) If the attributes parameter of the Search Request consists \r
-of a list containing only the attribute with OID "1.1" \r
-(specifying that no attributes are to be returned), the control \r
-has no effect and the Search Request SHOULD be processed as if \r
-the control had not been specified.\r
-\r
-(4) For each attribute listed in the attributes parameter of the \r
-Search Request, the server MUST apply the control as follows:\r
-\r
-i) Every attribute value that evaluates TRUE against one or \r
-more elements of the ValuesReturnFilter is placed in the \r
-SearchResultEntry.\r
-ii) Every attribute value that evaluates FALSE or undefined \r
-against all elements of the ValuesReturnFilter is not \r
-placed in the SearchResultEntry. An attribute that has no \r
-values selected is returned with an empty set of vals.\r
-\r
-Editor's Note. There is possibly a more efficient but slightly more \r
-complex way of achieving the value filtering. An alternative is to \r
-remove the 'present' SimpleFilterItem (which obviously evaluates true \r
-for every attribute value of the 'present' attribute description), \r
-and to say that any attribute whose type is not mentioned in the \r
-ValuesReturnFilter is not filtered and has all its attribute values \r
-returned. Comments please.\r
-\r
-\r
-3. Relationship to X.500\r
-\r
-The control is a superset of the matchedValuesOnly boolean of the \r
-X.500 DAP [4] Search argument, as amended in the latest version [6].\r
-Close examination of the matchedValuesOnly boolean by the LDAPExt \r
-group revealed ambiguities and complexities in the MVO boolean that \r
-could not easily be resolved. For example, are only those attribute \r
-values that contributed to the overall truth of the filter governed \r
-by the MVO boolean, or all values of attributes in the filter \r
-governed by the MVO boolean, even if the filter item containing the \r
-attribute evaluated to false. For this reason the LDAP group decided \r
-to replace the MVO boolean with a simple filter that removes any \r
-uncertainty as to whether an attribute value has been selected or \r
-not. \r
-\r
-\r
-4. Examples\r
-\r
-(1) The first example simply shows how the control can be used to \r
-selectively read a subset of attribute values. \r
-\r
-The entry below represents a groupOfNames object class containing \r
-several members from different organizations.\r
-\r
-cn: Cross Organizational Standards Body\r
-member: cn=joe,o=acme\r
-member: cn=alice,o=acme\r
-member: cn=bob,o=foo\r
-member: cn=sue,o=bar\r
-\r
-An LDAP search operation is specified with a baseObject set to the\r
-DN of the entry, a baseObject scope, a filter set to \r
-"member=*o=acme", and the list of attributes to be returned set to \r
-"member". In addition, a ValuesReturnFilter control is set to \r
-"member=*o=acme".\r
-\r
-The search results returned by the server would consist of the \r
-following entry:\r
-\r
-cn: Cross Organizational Standards Body\r
-member: cn=joe, o=acme\r
-member: cn=alice, o=acme\r
-\r
-\r
-(2) The second example shows how the control can be set to match on \r
-attributes that are (mail) and are not (telephoneNumber) part of the \r
-search filter. It also shows how a user can filter some attribute \r
-values (mail) and not others (telephoneNumber).\r
-\r
-The entries below represent inetOrgPerson [7] object classes located\r
-below some distinguished name in the directory.\r
-\r
-cn: Sean Mullan\r
-mail: sean.mullan@sun.com\r
-mail: mullan@east.sun.com\r
-telephoneNumber: +1 781 442 0926\r
-telephoneNumber: 555-9999\r
-\r
-cn: David Chadwick\r
-mail: d.w.chadwick@salford.ac.uk\r
-\r
-An LDAP search operation is specified with a baseObject set to the\r
-DN of the entry, a subtree scope, a filter set to \r
-"(|(mail=sean.mullan@sun.com)(mail=d.w.chadwick@salford.ac.uk))", and \r
-the list of attributes to be returned set to "mail telephoneNumber". \r
-In addition, a ValuesReturnFilter control is set to \r
-"mail=sean.mullan@sun.com, mail=d.w.chadwick@salford.ac.uk, \r
-telephoneNumber=*"\r
-\r
-The search results returned by the server would consist of the \r
-following entries:\r
-\r
-cn: Sean Mullan\r
-mail: sean.mullan@sun.com\r
-telephoneNumber: +1 781 442 0926\r
-telephoneNumber: 555-9999\r
-\r
-cn: David Chadwick\r
-mail: d.w.chadwick@salford.ac.uk\r
-\r
-Note that the control has no effect on the values returned for the \r
-"telephoneNumber" attribute (all of the values are returned), since \r
-the control specified that all values should be returned.\r
-\r
-(3) The third example shows how one might retrieve a single attribute \r
-type schema definition for the "gunk" attribute with OID 1.2.3.4.5\r
-\r
-Assume the subschema subentry is held somewhere below the root entry \r
-with RDN "subschema subentry", and this holds an attributeTypes \r
-operational attribute holding the descriptions of the 35 attributes \r
-known to this server (each description is held as a single attribute \r
-value of the attributeTypes attribute). \r
-\r
-cn: subschema subentry\r
-objectClass: subschema\r
-attributeTypes: ( 2.5.4.3 NAME 'cn' SUP name )\r
-attributeTypes: ( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE )\r
-attributeTypes: ( 2.5.4.0 NAME 'objectClass' EQUALITY \r
-objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )\r
-attributeTypes: ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY \r
-generalizedTimeMatch ORDERING generalizedTimeOrderingMatch\r
-SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER-\r
-MODIFICATION USAGE directoryOperation )\r
-attributeTypes: ( 2.5.21.6 NAME 'objectClasses' EQUALITY \r
-objectIdentifierFirstComponentMatch SYNTAX \r
-1.3.6.1.4.1.1466.115.121.1.37 USAGE directoryOperation )\r
-attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch \r
-SUBSTR caseIgnoreSubstringsMatch SYNTAX \r
-1.3.6.1.4.1.1466.115.121.1.44{64} )\r
-attributeTypes: ( 2.5.21.5 NAME 'attributeTypes' EQUALITY \r
-objectIdentifierFirstComponentMatch SYNTAX \r
-1.3.6.1.4.1.1466.115.121.1.3 USAGE directoryOperation )\r
-\r
-plus another 28 - you get the idea.\r
-\r
-\r
-The user creates an LDAP search operation with a baseObject set to \r
-root, a subtree scope, a filter set to "objectClass=subschema", the \r
-list of attributes to be returned set to "attributeTypes", and the \r
-ValuesReturnFilter set to "attributeTypes=1.2.3.4.5"\r
-\r
-The search result returned by the server would consist of the \r
-following entry:\r
-\r
-cn: subschema subentry\r
-attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch \r
-SUBSTR caseIgnoreSubstringsMatch SYNTAX \r
-1.3.6.1.4.1.1466.115.121.1.44{64} )\r
-\r
-(4) The final example shows how the control can be set to match on \r
-attributes that are not part of the search filter. For example, \r
-searching for all entries that have an email address in the\r
-sun.com domain, and returning the telephone number for any attribute\r
-values that start with "555". \r
-\r
-The entries below represent inetOrgPerson [7] object classes located\r
-below some distinguished name in the directory.\r
-\r
-cn: Sean Mullan\r
-mail: sean.mullan@sun.com\r
-mail: mullan@east.sun.com\r
-telephoneNumber: +1 781 442 0926\r
-telephoneNumber: 555-9999\r
-\r
-cn: David Chadwick\r
-mail: d.w.chadwick@salford.ac.uk\r
-\r
-An LDAP search operation is specified with a baseObject set to the\r
-DN of the entry, a subtree scope, a filter set to "mail=*sun.com", \r
-and the list of attributes to be returned set to "telephoneNumber". \r
-In addition, a ValuesReturnFilter control is set to\r
-"telephoneNumber=555*"\r
-\r
-The search results returned by the server would consist of the \r
-following entry:\r
-\r
-cn: Sean Mullan\r
-telephoneNumber: 555-9999\r
-\r
-\r
-5. Security Considerations\r
-\r
-This Internet Draft does not discuss security issues at all. \r
-\r
-Note that attribute values MUST only be returned if the access \r
-controls applied by the LDAP server allow them to be returned, and in \r
-this respect the effect of the ValuesReturnFilter control is of no \r
-consequence.\r
-\r
-Note that the ValuesReturnFilter control may have a positive effect \r
-on the deployment of public key infrastructures. Certain PKI \r
-operations, like searching for specific certificates, become more \r
-practical (when combined with X.509 certificate matching rules at the \r
-server) and more scalable, since the control avoids the downloading \r
-of potentially large numbers of irrelevant certificates which would \r
-have to be processed and filtered locally (which in some cases is \r
-very difficult to perform).\r
-\r
-\r
-6. Acknowledgements\r
-\r
-The authors would like to thank members of the LDAPExt list for their \r
-constructive comments on earlier versions of this draft, and in \r
-particular to Harald Alvestrand who first suggested having an \r
-attribute return filter and Bruce Greenblatt who first proposed a \r
-syntax for this control.\r
-\r
-7. Copyright\r
-\r
-Copyright (C) The Internet Society (date). All Rights Reserved.\r
-\r
-This document and translations of it may be copied and furnished to \r
-others, and derivative works that comment on or otherwise explain it \r
-or assist in its implementation may be prepared, copied, published \r
-and distributed, in whole or in part, without restriction of any \r
-kind, provided that the above copyright notice and this paragraph are \r
-included on all such copies and derivative works. However, this \r
-document itself may not be modified in any way, such as by removing \r
-the copyright notice or references to the Internet Society or other \r
-Internet organizations, except as needed for the purpose of \r
-developing Internet standards in which case the procedures for \r
-copyrights defined in the Internet Standards process must be \r
-followed, or as required to translate it into languages other than \r
-English.\r
-\r
-The limited permissions granted above are perpetual and will not be \r
-revoked by the Internet Society or its successors or assigns.\r
-\r
-This document and the information contained herein is provided on an \r
-"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING \r
-TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING \r
-BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION \r
-HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF \r
-MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.\r
-\r
-\r
-8. References\r
-\r
-[1] Yeong, W., Howes, T., and Kille, S. "Lightweight Directory Access \r
-Protocol", RFC 1777, March 1995.\r
-[2] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access \r
-Protocol (v3)", Dec. 1997, RFC 2251\r
-[3] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory \r
-Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, Dec \r
-1997\r
-[4] ITU-T Rec. X.511, "The Directory: Abstract Service Definition", \r
-1993.\r
-[5] S.Bradner. "Key words for use in RFCs to Indicate Requirement \r
-Levels", RFC 2119, March 1997.\r
-[6] ISO/IEC 9594 / ITU-T Rec X.511 (2000) The Directory: Abstract \r
-Service Definition.\r
-[7] M. Smith. "Definition of the inetOrgPerson LDAP Object Class", \r
-Internet Draft <draft-smith-ldap-inetorgperson-03.txt>, April 1999.\r
-\r
-\r
-9. Authors Addresses\r
-\r
-David Chadwick\r
-IS Institute\r
-University of Salford\r
-Salford M5 4WT \r
-England\r
-\r
-Email: d.w.chadwick@salford.ac.uk\r
-\r
-\r
-Sean Mullan \r
-Sun Microsystems\r
-East Point Business Park\r
-Dublin 3\r
-Ireland\r
-Tel: +353 1 853 0655\r
-Email: sean.mullan@sun.com\r
-\r
-Internet-Draft Returning Matched Values with LDAPv3 1 July 2000\r
-\r
-\r
-1\r
-\r
+Internet-Draft David Chadwick
+LDAPExt WG University of Salford
+Intended Category: Standards Track Sean Mullan
+ Sun Microsystems
+Expires: 1 January 2001 1 July 2000
+
+
+Returning Matched Values with LDAPv3
+<draft-ietf-ldapext-matchedval-02.txt>
+
+
+STATUS OF THIS MEMO
+
+This document is an Internet-Draft and is in full conformance with
+all the provisions of Section 10 of RFC2026.
+
+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 expires on 1 January 2001. Comments and
+suggestions on this document are encouraged. Comments on this
+document should be sent to the LDAPExt working group discussion list:
+ ietf-ldapext@netscape.com
+or directly to the authors.
+
+
+ABSTRACT
+
+This document describes a control for the Lightweight Directory
+Access Protocol v3 that is used to return a subset of attribute
+values from an entry, specifically, only those values that match a
+"values return" filter. Without support for this control, a client
+must retrieve all of an attribute's values and search for specific
+values locally.
+
+
+1. Introduction
+
+When reading an attribute from an entry using LDAP v2 [1] or LDAPv3
+[2], it is normally only possible to read either the attribute type,
+or the attribute type and all its values. It is not possible to
+selectively read just a few of the attribute values. If an attribute
+holds many values, for example, the userCertificate attribute, or the
+subschema publishing operational attributes objectClasses and
+attributeTypes [3], then it may be desirable for the user to be able
+to selectively retrieve a subset of the values, specifically, those
+attribute values that match some user defined selection criteria.
+Without the control specified in this [ID/standard] a client must
+read all of the attribute's values and filter out the unwanted
+values, necessitating the client to implement the matching rules. It
+also requires the client to potentially read and process many
+irrelevant values, which can be inefficient if the values are large
+or complex, or there are many values stored per attribute.
+
+This Internet Draft specifies an LDAPv3 control to enable a user to
+return only those values that matched (i.e. returned TRUE to) one or
+more elements of a newly defined "values return" filter. This control
+can be especially useful when used in conjunction with extensible
+matching rules that match on one or more components of complex binary
+attribute values.
+
+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 RFC 2119 [5].
+
+
+2. The valuesReturnFilter Control
+
+The valuesReturnFilter control MAY be critical or non-critical as
+determined by the user. It is only applicable to the Search
+operation, and SHALL be ignored by the server if it is present on any
+other LDAP operation (even if marked critical on such operations).
+
+The object identifier for this control is 1.2.826.0.1.3344810.2.3
+
+
+The controlValue is
+
+ ValuesReturnFilter ::= SEQUENCE OF SimpleFilterItem
+
+ SimpleFilterItem ::= CHOICE {
+ equalityMatch [3] AttributeValueAssertion,
+ substrings [4] SubstringFilter,
+ greaterOrEqual [5] AttributeValueAssertion,
+ lessOrEqual [6] AttributeValueAssertion,
+ present [7] AttributeDescription,
+ approxMatch [8] AttributeValueAssertion,
+ extensibleMatch [9] SimpleMatchingAssertion }
+
+ SimpleMatchingAssertion ::= SEQUENCE {
+ matchingRule [1] MatchingRuleId OPTIONAL,
+ type [2] AttributeDescription OPTIONAL,
+ matchValue [3] AssertionValue}
+
+All the above data types have their standard meanings as defined in
+[2].
+
+If the server supports this control, the server MUST make use of the
+control as follows:
+
+(1) The Search Filter is first executed in order to determine
+which entries satisfy the Search criteria. The control has no
+impact on this step.
+
+(2) If the typesOnly parameter of the Search Request is TRUE,
+the control has no effect and the Search Request SHOULD be
+processed as if the control had not been specified.
+
+(3) If the attributes parameter of the Search Request consists
+of a list containing only the attribute with OID "1.1"
+(specifying that no attributes are to be returned), the control
+has no effect and the Search Request SHOULD be processed as if
+the control had not been specified.
+
+(4) For each attribute listed in the attributes parameter of the
+Search Request, the server MUST apply the control as follows:
+
+i) Every attribute value that evaluates TRUE against one or
+more elements of the ValuesReturnFilter is placed in the
+SearchResultEntry.
+ii) Every attribute value that evaluates FALSE or undefined
+against all elements of the ValuesReturnFilter is not
+placed in the SearchResultEntry. An attribute that has no
+values selected is returned with an empty set of vals.
+
+Editor's Note. There is possibly a more efficient but slightly more
+complex way of achieving the value filtering. An alternative is to
+remove the 'present' SimpleFilterItem (which obviously evaluates true
+for every attribute value of the 'present' attribute description),
+and to say that any attribute whose type is not mentioned in the
+ValuesReturnFilter is not filtered and has all its attribute values
+returned. Comments please.
+
+
+3. Relationship to X.500
+
+The control is a superset of the matchedValuesOnly boolean of the
+X.500 DAP [4] Search argument, as amended in the latest version [6].
+Close examination of the matchedValuesOnly boolean by the LDAPExt
+group revealed ambiguities and complexities in the MVO boolean that
+could not easily be resolved. For example, are only those attribute
+values that contributed to the overall truth of the filter governed
+by the MVO boolean, or all values of attributes in the filter
+governed by the MVO boolean, even if the filter item containing the
+attribute evaluated to false. For this reason the LDAP group decided
+to replace the MVO boolean with a simple filter that removes any
+uncertainty as to whether an attribute value has been selected or
+not.
+
+
+4. Examples
+
+(1) The first example simply shows how the control can be used to
+selectively read a subset of attribute values.
+
+The entry below represents a groupOfNames object class containing
+several members from different organizations.
+
+cn: Cross Organizational Standards Body
+member: cn=joe,o=acme
+member: cn=alice,o=acme
+member: cn=bob,o=foo
+member: cn=sue,o=bar
+
+An LDAP search operation is specified with a baseObject set to the
+DN of the entry, a baseObject scope, a filter set to
+"member=*o=acme", and the list of attributes to be returned set to
+"member". In addition, a ValuesReturnFilter control is set to
+"member=*o=acme".
+
+The search results returned by the server would consist of the
+following entry:
+
+cn: Cross Organizational Standards Body
+member: cn=joe, o=acme
+member: cn=alice, o=acme
+
+
+(2) The second example shows how the control can be set to match on
+attributes that are (mail) and are not (telephoneNumber) part of the
+search filter. It also shows how a user can filter some attribute
+values (mail) and not others (telephoneNumber).
+
+The entries below represent inetOrgPerson [7] object classes located
+below some distinguished name in the directory.
+
+cn: Sean Mullan
+mail: sean.mullan@sun.com
+mail: mullan@east.sun.com
+telephoneNumber: +1 781 442 0926
+telephoneNumber: 555-9999
+
+cn: David Chadwick
+mail: d.w.chadwick@salford.ac.uk
+
+An LDAP search operation is specified with a baseObject set to the
+DN of the entry, a subtree scope, a filter set to
+"(|(mail=sean.mullan@sun.com)(mail=d.w.chadwick@salford.ac.uk))", and
+the list of attributes to be returned set to "mail telephoneNumber".
+In addition, a ValuesReturnFilter control is set to
+"mail=sean.mullan@sun.com, mail=d.w.chadwick@salford.ac.uk,
+telephoneNumber=*"
+
+The search results returned by the server would consist of the
+following entries:
+
+cn: Sean Mullan
+mail: sean.mullan@sun.com
+telephoneNumber: +1 781 442 0926
+telephoneNumber: 555-9999
+
+cn: David Chadwick
+mail: d.w.chadwick@salford.ac.uk
+
+Note that the control has no effect on the values returned for the
+"telephoneNumber" attribute (all of the values are returned), since
+the control specified that all values should be returned.
+
+(3) The third example shows how one might retrieve a single attribute
+type schema definition for the "gunk" attribute with OID 1.2.3.4.5
+
+Assume the subschema subentry is held somewhere below the root entry
+with RDN "subschema subentry", and this holds an attributeTypes
+operational attribute holding the descriptions of the 35 attributes
+known to this server (each description is held as a single attribute
+value of the attributeTypes attribute).
+
+cn: subschema subentry
+objectClass: subschema
+attributeTypes: ( 2.5.4.3 NAME 'cn' SUP name )
+attributeTypes: ( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE )
+attributeTypes: ( 2.5.4.0 NAME 'objectClass' EQUALITY
+objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
+attributeTypes: ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY
+generalizedTimeMatch ORDERING generalizedTimeOrderingMatch
+SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER-
+MODIFICATION USAGE directoryOperation )
+attributeTypes: ( 2.5.21.6 NAME 'objectClasses' EQUALITY
+objectIdentifierFirstComponentMatch SYNTAX
+1.3.6.1.4.1.1466.115.121.1.37 USAGE directoryOperation )
+attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch
+SUBSTR caseIgnoreSubstringsMatch SYNTAX
+1.3.6.1.4.1.1466.115.121.1.44{64} )
+attributeTypes: ( 2.5.21.5 NAME 'attributeTypes' EQUALITY
+objectIdentifierFirstComponentMatch SYNTAX
+1.3.6.1.4.1.1466.115.121.1.3 USAGE directoryOperation )
+
+plus another 28 - you get the idea.
+
+
+The user creates an LDAP search operation with a baseObject set to
+root, a subtree scope, a filter set to "objectClass=subschema", the
+list of attributes to be returned set to "attributeTypes", and the
+ValuesReturnFilter set to "attributeTypes=1.2.3.4.5"
+
+The search result returned by the server would consist of the
+following entry:
+
+cn: subschema subentry
+attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch
+SUBSTR caseIgnoreSubstringsMatch SYNTAX
+1.3.6.1.4.1.1466.115.121.1.44{64} )
+
+(4) The final example shows how the control can be set to match on
+attributes that are not part of the search filter. For example,
+searching for all entries that have an email address in the
+sun.com domain, and returning the telephone number for any attribute
+values that start with "555".
+
+The entries below represent inetOrgPerson [7] object classes located
+below some distinguished name in the directory.
+
+cn: Sean Mullan
+mail: sean.mullan@sun.com
+mail: mullan@east.sun.com
+telephoneNumber: +1 781 442 0926
+telephoneNumber: 555-9999
+
+cn: David Chadwick
+mail: d.w.chadwick@salford.ac.uk
+
+An LDAP search operation is specified with a baseObject set to the
+DN of the entry, a subtree scope, a filter set to "mail=*sun.com",
+and the list of attributes to be returned set to "telephoneNumber".
+In addition, a ValuesReturnFilter control is set to
+"telephoneNumber=555*"
+
+The search results returned by the server would consist of the
+following entry:
+
+cn: Sean Mullan
+telephoneNumber: 555-9999
+
+
+5. Security Considerations
+
+This Internet Draft does not discuss security issues at all.
+
+Note that attribute values MUST only be returned if the access
+controls applied by the LDAP server allow them to be returned, and in
+this respect the effect of the ValuesReturnFilter control is of no
+consequence.
+
+Note that the ValuesReturnFilter control may have a positive effect
+on the deployment of public key infrastructures. Certain PKI
+operations, like searching for specific certificates, become more
+practical (when combined with X.509 certificate matching rules at the
+server) and more scalable, since the control avoids the downloading
+of potentially large numbers of irrelevant certificates which would
+have to be processed and filtered locally (which in some cases is
+very difficult to perform).
+
+
+6. Acknowledgements
+
+The authors would like to thank members of the LDAPExt list for their
+constructive comments on earlier versions of this draft, and in
+particular to Harald Alvestrand who first suggested having an
+attribute return filter and Bruce Greenblatt who first proposed a
+syntax for this control.
+
+7. Copyright
+
+Copyright (C) The Internet Society (date). All Rights Reserved.
+
+This document and translations of it may be copied and furnished to
+others, and derivative works that comment on or otherwise explain it
+or assist in its implementation may be prepared, copied, published
+and distributed, in whole or in part, without restriction of any
+kind, provided that the above copyright notice and this paragraph are
+included on all such copies and derivative works. However, this
+document itself may not be modified in any way, such as by removing
+the copyright notice or references to the Internet Society or other
+Internet organizations, except as needed for the purpose of
+developing Internet standards in which case the procedures for
+copyrights defined in the Internet Standards process must be
+followed, or as required to translate it into languages other than
+English.
+
+The limited permissions granted above are perpetual and will not be
+revoked by the Internet Society or its successors or assigns.
+
+This document and the information contained herein is provided on an
+"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+TASK FORCE DISCLAIMS 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.
+
+
+8. References
+
+[1] Yeong, W., Howes, T., and Kille, S. "Lightweight Directory Access
+Protocol", RFC 1777, March 1995.
+[2] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
+Protocol (v3)", Dec. 1997, RFC 2251
+[3] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory
+Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, Dec
+1997
+[4] ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
+1993.
+[5] S.Bradner. "Key words for use in RFCs to Indicate Requirement
+Levels", RFC 2119, March 1997.
+[6] ISO/IEC 9594 / ITU-T Rec X.511 (2000) The Directory: Abstract
+Service Definition.
+[7] M. Smith. "Definition of the inetOrgPerson LDAP Object Class",
+Internet Draft <draft-smith-ldap-inetorgperson-03.txt>, April 1999.
+
+
+9. Authors Addresses
+
+David Chadwick
+IS Institute
+University of Salford
+Salford M5 4WT
+England
+
+Email: d.w.chadwick@salford.ac.uk
+
+
+Sean Mullan
+Sun Microsystems
+East Point Business Park
+Dublin 3
+Ireland
+Tel: +353 1 853 0655
+Email: sean.mullan@sun.com
+
+Internet-Draft Returning Matched Values with LDAPv3 1 July 2000
+
+
+1
+
projects / openldap / commitdiff