idnits 2.17.1 draft-ietf-ldapext-matchedval-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 406 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 2 instances of lines with control characters in the document. == There are 6 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The "Author's Address" (or "Authors' Addresses") section title is misspelled. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (1 July 2000) is 8699 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: 'ID/standard' on line 56 == Missing Reference: '8' is mentioned on line 93, but not defined == Missing Reference: '9' is mentioned on line 94, but not defined ** Obsolete normative reference: RFC 1777 (ref. '1') (Obsoleted by RFC 3494) ** Obsolete normative reference: RFC 2251 (ref. '2') (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) ** Obsolete normative reference: RFC 2252 (ref. '3') (Obsoleted by RFC 4510, RFC 4512, RFC 4517, RFC 4523) -- Possible downref: Non-RFC (?) normative reference: ref. '4' -- Possible downref: Non-RFC (?) normative reference: ref. '6' -- Possible downref: Non-RFC (?) normative reference: ref. '7' Summary: 7 errors (**), 0 flaws (~~), 5 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet-Draft David Chadwick 2 LDAPExt WG University of Salford 3 Intended Category: Standards Track Sean Mullan 4 Sun Microsystems 5 Expires: 1 January 2001 1 July 2000 7 Returning Matched Values with LDAPv3 8 10 STATUS OF THIS MEMO 12 This document is an Internet-Draft and is in full conformance with 13 all the provisions of Section 10 of RFC2026. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that other 17 groups may also distribute working documents as Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six months 20 and may be updated, replaced, or obsoleted by other documents at any 21 time. It is inappropriate to use Internet-Drafts as reference 22 material or to cite them other than as "work in progress." 24 The list of current Internet-Drafts can be accessed at 25 http://www.ietf.org/ietf/1id-abstracts.txt. 27 The list of Internet-Draft Shadow Directories can be accessed at 28 http://www.ietf.org/shadow.html. 30 This Internet-Draft expires on 1 January 2001. Comments and 31 suggestions on this document are encouraged. Comments on this 32 document should be sent to the LDAPExt working group discussion list: 33 ietf-ldapext@netscape.com 34 or directly to the authors. 36 ABSTRACT 38 This document describes a control for the Lightweight Directory 39 Access Protocol v3 that is used to return a subset of attribute 40 values from an entry, specifically, only those values that match a 41 "values return" filter. Without support for this control, a client 42 must retrieve all of an attribute's values and search for specific 43 values locally. 45 1. Introduction 47 When reading an attribute from an entry using LDAP v2 [1] or LDAPv3 48 [2], it is normally only possible to read either the attribute type, 49 or the attribute type and all its values. It is not possible to 50 selectively read just a few of the attribute values. If an attribute 51 holds many values, for example, the userCertificate attribute, or the 52 subschema publishing operational attributes objectClasses and 53 attributeTypes [3], then it may be desirable for the user to be able 54 to selectively retrieve a subset of the values, specifically, those 55 attribute values that match some user defined selection criteria. 56 Without the control specified in this [ID/standard] a client must 57 read all of the attribute's values and filter out the unwanted 58 values, necessitating the client to implement the matching rules. It 59 also requires the client to potentially read and process many 60 irrelevant values, which can be inefficient if the values are large 61 or complex, or there are many values stored per attribute. 63 This Internet Draft specifies an LDAPv3 control to enable a user to 64 return only those values that matched (i.e. returned TRUE to) one or 65 more elements of a newly defined "values return" filter. This control 66 can be especially useful when used in conjunction with extensible 67 matching rules that match on one or more components of complex binary 68 attribute values. 70 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 71 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 72 document are to be interpreted as described in RFC 2119 [5]. 74 2. The valuesReturnFilter Control 76 The valuesReturnFilter control MAY be critical or non-critical as 77 determined by the user. It is only applicable to the Search 78 operation, and SHALL be ignored by the server if it is present on any 79 other LDAP operation (even if marked critical on such operations). 81 The object identifier for this control is 1.2.826.0.1.3344810.2.3 83 The controlValue is 85 ValuesReturnFilter ::= SEQUENCE OF SimpleFilterItem 87 SimpleFilterItem ::= CHOICE { 88 equalityMatch [3] AttributeValueAssertion, 89 substrings [4] SubstringFilter, 90 greaterOrEqual [5] AttributeValueAssertion, 91 lessOrEqual [6] AttributeValueAssertion, 92 present [7] AttributeDescription, 93 approxMatch [8] AttributeValueAssertion, 94 extensibleMatch [9] SimpleMatchingAssertion } 96 SimpleMatchingAssertion ::= SEQUENCE { 97 matchingRule [1] MatchingRuleId OPTIONAL, 98 type [2] AttributeDescription OPTIONAL, 99 matchValue [3] AssertionValue} 101 All the above data types have their standard meanings as defined in 102 [2]. 104 If the server supports this control, the server MUST make use of the 105 control as follows: 107 (1) The Search Filter is first executed in order to determine 108 which entries satisfy the Search criteria. The control has no 109 impact on this step. 111 (2) If the typesOnly parameter of the Search Request is TRUE, 112 the control has no effect and the Search Request SHOULD be 113 processed as if the control had not been specified. 115 (3) If the attributes parameter of the Search Request consists 116 of a list containing only the attribute with OID "1.1" 117 (specifying that no attributes are to be returned), the control 118 has no effect and the Search Request SHOULD be processed as if 119 the control had not been specified. 121 (4) For each attribute listed in the attributes parameter of the 122 Search Request, the server MUST apply the control as follows: 124 i) Every attribute value that evaluates TRUE against one or 125 more elements of the ValuesReturnFilter is placed in the 126 SearchResultEntry. 127 ii) Every attribute value that evaluates FALSE or undefined 128 against all elements of the ValuesReturnFilter is not 129 placed in the SearchResultEntry. An attribute that has no 130 values selected is returned with an empty set of vals. 132 Editor's Note. There is possibly a more efficient but slightly more 133 complex way of achieving the value filtering. An alternative is to 134 remove the 'present' SimpleFilterItem (which obviously evaluates true 135 for every attribute value of the 'present' attribute description), 136 and to say that any attribute whose type is not mentioned in the 137 ValuesReturnFilter is not filtered and has all its attribute values 138 returned. Comments please. 140 3. Relationship to X.500 142 The control is a superset of the matchedValuesOnly boolean of the 143 X.500 DAP [4] Search argument, as amended in the latest version [6]. 144 Close examination of the matchedValuesOnly boolean by the LDAPExt 145 group revealed ambiguities and complexities in the MVO boolean that 146 could not easily be resolved. For example, are only those attribute 147 values that contributed to the overall truth of the filter governed 148 by the MVO boolean, or all values of attributes in the filter 149 governed by the MVO boolean, even if the filter item containing the 150 attribute evaluated to false. For this reason the LDAP group decided 151 to replace the MVO boolean with a simple filter that removes any 152 uncertainty as to whether an attribute value has been selected or 153 not. 155 4. Examples 157 (1) The first example simply shows how the control can be used to 158 selectively read a subset of attribute values. 160 The entry below represents a groupOfNames object class containing 161 several members from different organizations. 163 cn: Cross Organizational Standards Body 164 member: cn=joe,o=acme 165 member: cn=alice,o=acme 166 member: cn=bob,o=foo 167 member: cn=sue,o=bar 169 An LDAP search operation is specified with a baseObject set to the 170 DN of the entry, a baseObject scope, a filter set to 171 "member=*o=acme", and the list of attributes to be returned set to 172 "member". In addition, a ValuesReturnFilter control is set to 173 "member=*o=acme". 175 The search results returned by the server would consist of the 176 following entry: 178 cn: Cross Organizational Standards Body 179 member: cn=joe, o=acme 180 member: cn=alice, o=acme 182 (2) The second example shows how the control can be set to match on 183 attributes that are (mail) and are not (telephoneNumber) part of the 184 search filter. It also shows how a user can filter some attribute 185 values (mail) and not others (telephoneNumber). 187 The entries below represent inetOrgPerson [7] object classes located 188 below some distinguished name in the directory. 190 cn: Sean Mullan 191 mail: sean.mullan@sun.com 192 mail: mullan@east.sun.com 193 telephoneNumber: +1 781 442 0926 194 telephoneNumber: 555-9999 196 cn: David Chadwick 197 mail: d.w.chadwick@salford.ac.uk 199 An LDAP search operation is specified with a baseObject set to the 200 DN of the entry, a subtree scope, a filter set to 201 "(|(mail=sean.mullan@sun.com)(mail=d.w.chadwick@salford.ac.uk))", and 202 the list of attributes to be returned set to "mail telephoneNumber". 203 In addition, a ValuesReturnFilter control is set to 204 "mail=sean.mullan@sun.com, mail=d.w.chadwick@salford.ac.uk, 205 telephoneNumber=*" 207 The search results returned by the server would consist of the 208 following entries: 210 cn: Sean Mullan 211 mail: sean.mullan@sun.com 212 telephoneNumber: +1 781 442 0926 213 telephoneNumber: 555-9999 215 cn: David Chadwick 216 mail: d.w.chadwick@salford.ac.uk 218 Note that the control has no effect on the values returned for the 219 "telephoneNumber" attribute (all of the values are returned), since 220 the control specified that all values should be returned. 222 (3) The third example shows how one might retrieve a single attribute 223 type schema definition for the "gunk" attribute with OID 1.2.3.4.5 225 Assume the subschema subentry is held somewhere below the root entry 226 with RDN "subschema subentry", and this holds an attributeTypes 227 operational attribute holding the descriptions of the 35 attributes 228 known to this server (each description is held as a single attribute 229 value of the attributeTypes attribute). 231 cn: subschema subentry 232 objectClass: subschema 233 attributeTypes: ( 2.5.4.3 NAME 'cn' SUP name ) 234 attributeTypes: ( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE ) 235 attributeTypes: ( 2.5.4.0 NAME 'objectClass' EQUALITY 236 objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) 237 attributeTypes: ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY 238 generalizedTimeMatch ORDERING generalizedTimeOrderingMatch 239 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER- 240 MODIFICATION USAGE directoryOperation ) 241 attributeTypes: ( 2.5.21.6 NAME 'objectClasses' EQUALITY 242 objectIdentifierFirstComponentMatch SYNTAX 243 1.3.6.1.4.1.1466.115.121.1.37 USAGE directoryOperation ) 244 attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch 245 SUBSTR caseIgnoreSubstringsMatch SYNTAX 246 1.3.6.1.4.1.1466.115.121.1.44{64} ) 247 attributeTypes: ( 2.5.21.5 NAME 'attributeTypes' EQUALITY 248 objectIdentifierFirstComponentMatch SYNTAX 249 1.3.6.1.4.1.1466.115.121.1.3 USAGE directoryOperation ) 251 plus another 28 - you get the idea. 253 The user creates an LDAP search operation with a baseObject set to 254 root, a subtree scope, a filter set to "objectClass=subschema", the 255 list of attributes to be returned set to "attributeTypes", and the 256 ValuesReturnFilter set to "attributeTypes=1.2.3.4.5" 258 The search result returned by the server would consist of the 259 following entry: 261 cn: subschema subentry 262 attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch 263 SUBSTR caseIgnoreSubstringsMatch SYNTAX 264 1.3.6.1.4.1.1466.115.121.1.44{64} ) 266 (4) The final example shows how the control can be set to match on 267 attributes that are not part of the search filter. For example, 268 searching for all entries that have an email address in the 269 sun.com domain, and returning the telephone number for any attribute 270 values that start with "555". 272 The entries below represent inetOrgPerson [7] object classes located 273 below some distinguished name in the directory. 275 cn: Sean Mullan 276 mail: sean.mullan@sun.com 277 mail: mullan@east.sun.com 278 telephoneNumber: +1 781 442 0926 279 telephoneNumber: 555-9999 281 cn: David Chadwick 282 mail: d.w.chadwick@salford.ac.uk 284 An LDAP search operation is specified with a baseObject set to the 285 DN of the entry, a subtree scope, a filter set to "mail=*sun.com", 286 and the list of attributes to be returned set to "telephoneNumber". 287 In addition, a ValuesReturnFilter control is set to 288 "telephoneNumber=555*" 290 The search results returned by the server would consist of the 291 following entry: 293 cn: Sean Mullan 294 telephoneNumber: 555-9999 296 5. Security Considerations 298 This Internet Draft does not discuss security issues at all. 300 Note that attribute values MUST only be returned if the access 301 controls applied by the LDAP server allow them to be returned, and in 302 this respect the effect of the ValuesReturnFilter control is of no 303 consequence. 305 Note that the ValuesReturnFilter control may have a positive effect 306 on the deployment of public key infrastructures. Certain PKI 307 operations, like searching for specific certificates, become more 308 practical (when combined with X.509 certificate matching rules at the 309 server) and more scalable, since the control avoids the downloading 310 of potentially large numbers of irrelevant certificates which would 311 have to be processed and filtered locally (which in some cases is 312 very difficult to perform). 314 6. Acknowledgements 316 The authors would like to thank members of the LDAPExt list for their 317 constructive comments on earlier versions of this draft, and in 318 particular to Harald Alvestrand who first suggested having an 319 attribute return filter and Bruce Greenblatt who first proposed a 320 syntax for this control. 322 7. Copyright 324 Copyright (C) The Internet Society (date). All Rights Reserved. 326 This document and translations of it may be copied and furnished to 327 others, and derivative works that comment on or otherwise explain it 328 or assist in its implementation may be prepared, copied, published 329 and distributed, in whole or in part, without restriction of any 330 kind, provided that the above copyright notice and this paragraph are 331 included on all such copies and derivative works. However, this 332 document itself may not be modified in any way, such as by removing 333 the copyright notice or references to the Internet Society or other 334 Internet organizations, except as needed for the purpose of 335 developing Internet standards in which case the procedures for 336 copyrights defined in the Internet Standards process must be 337 followed, or as required to translate it into languages other than 338 English. 340 The limited permissions granted above are perpetual and will not be 341 revoked by the Internet Society or its successors or assigns. 343 This document and the information contained herein is provided on an 344 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 345 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 346 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 347 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 348 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 350 8. References 352 [1] Yeong, W., Howes, T., and Kille, S. "Lightweight Directory Access 353 Protocol", RFC 1777, March 1995. 354 [2] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access 355 Protocol (v3)", Dec. 1997, RFC 2251 356 [3] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory 357 Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, Dec 358 1997 359 [4] ITU-T Rec. X.511, "The Directory: Abstract Service Definition", 360 1993. 361 [5] S.Bradner. "Key words for use in RFCs to Indicate Requirement 362 Levels", RFC 2119, March 1997. 363 [6] ISO/IEC 9594 / ITU-T Rec X.511 (2000) The Directory: Abstract 364 Service Definition. 365 [7] M. Smith. "Definition of the inetOrgPerson LDAP Object Class", 366 Internet Draft , April 1999. 368 9. Authors Addresses 370 David Chadwick 371 IS Institute 372 University of Salford 373 Salford M5 4WT 374 England 376 Email: d.w.chadwick@salford.ac.uk 378 Sean Mullan 379 Sun Microsystems 380 East Point Business Park 381 Dublin 3 382 Ireland 383 Tel: +353 1 853 0655 384 Email: sean.mullan@sun.com 385 1