From: Kurt Zeilenga Date: Mon, 18 Dec 2000 20:10:07 +0000 (+0000) Subject: Strip ^M X-Git-Tag: LDBM_PRE_GIANT_RWLOCK~1625 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=c19462d44e8cddebe1cc550a44d66c2c7b1b03b3;p=openldap Strip ^M --- diff --git a/doc/drafts/draft-ietf-ldapext-matchedval-xx.txt b/doc/drafts/draft-ietf-ldapext-matchedval-xx.txt index d35e2ff666..7d0c790b58 100644 --- a/doc/drafts/draft-ietf-ldapext-matchedval-xx.txt +++ b/doc/drafts/draft-ietf-ldapext-matchedval-xx.txt @@ -1,405 +1,405 @@ -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 - - - -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 , 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 - +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 + + + +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 , 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 +