idnits 2.17.1 draft-ietf-ldapext-matchedval-06.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: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 510 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.) ** There are 15 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 (26 June 2002) is 7974 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) ** 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) -- Obsolete informational reference (is this intentional?): RFC 2254 (ref. '11') (Obsoleted by RFC 4510, RFC 4515) -- Obsolete informational reference (is this intentional?): RFC 2234 (ref. '12') (Obsoleted by RFC 4234) Summary: 5 errors (**), 0 flaws (~~), 4 warnings (==), 4 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: 26 December 2002 26 June 2002 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 [1]. 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. 29 30 Comments and suggestions on this document are encouraged. Comments on 31 this document should be sent to the LDAPEXT working group discussion 32 list: 33 ietf-ldapext@netscape.com 35 or directly to the authors. 37 ABSTRACT 39 This document describes a control for the Lightweight Directory 40 Access Protocol version 3 that is used to return a subset of 41 attribute values from an entry, specifically, only those values that 42 match a "values return" filter. Without support for this control, a 43 client must retrieve all of an attribute's values and search for 44 specific values locally. 46 1. Introduction 48 When reading an attribute from an entry using the Lightweight 49 Directory Access Protocol version 3 (LDAPv3) [2], it is normally only 50 possible to read either the attribute type, or the attribute type and 51 all its values. It is not possible to selectively read just a few of 52 the attribute values. If an attribute holds many values, for example, 53 the userCertificate attribute, or the subschema publishing 54 operational attributes objectClasses and attributeTypes [3], then it 55 may be desirable for the user to be able to selectively retrieve a 56 subset of the values, specifically, those attribute values that match 57 some user defined selection criteria. Without the control specified 58 in this document a client must read all of the attribute's values and 59 filter out the unwanted values, necessitating the client to implement 60 the matching rules. It also requires the client to potentially read 61 and process many irrelevant values, which can be inefficient if the 62 values are large or complex, or there are many values stored per 63 attribute. 65 This document specifies an LDAPv3 control to enable a user to return 66 only those values that matched (i.e. returned TRUE to) one or more 67 elements of a newly defined "values return" filter. This control can 68 be especially useful when used in conjunction with extensible 69 matching rules that match on one or more components of complex binary 70 attribute values. 72 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 73 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 74 document are to be interpreted as described in RFC 2119 [4]. 76 2. The valuesReturnFilter Control 78 The valuesReturnFilter control is either critical or non-critical as 79 determined by the user. It only has meaning for the Search operation, 80 and SHOULD only be added to the Search operation by the client. If 81 the server supports the control and it is present on a Search 82 operation, the server MUST obey the control regardless of the value 83 of the criticality flag. 85 If the control is marked as critical, and either the server does not 86 support the control or the control is applied to an operation other 87 than Search, then the server MUST return an 88 unavailableCriticalExtension error. If the control is not marked as 89 critical, and either the server does not support the control or the 90 control is applied to an operation other than Search, then the server 91 MUST ignore the control. 93 The object identifier for this control is 1.2.826.0.1.3344810.2.3. 95 The controlValue is an OCTET STRING, whose value is the BER encoding, 96 as per Section 5.1 of RFC 2251 [2], of a value of the type 97 ValuesReturnFilter. 99 ValuesReturnFilter ::= SEQUENCE OF SimpleFilterItem 101 SimpleFilterItem ::= CHOICE { 102 equalityMatch [3] AttributeValueAssertion, 103 substrings [4] SubstringFilter, 104 greaterOrEqual [5] AttributeValueAssertion, 105 lessOrEqual [6] AttributeValueAssertion, 106 present [7] AttributeDescription, 107 approxMatch [8] AttributeValueAssertion, 108 extensibleMatch [9] SimpleMatchingAssertion } 110 SimpleMatchingAssertion ::= SEQUENCE { 111 matchingRule [1] MatchingRuleId OPTIONAL, 112 type [2] AttributeDescription OPTIONAL, 113 --- at least one of the above must be present 114 matchValue [3] AssertionValue} 116 All the above data types have their standard meanings as defined in 117 [2]. 119 If the server supports this control, the server MUST make use of the 120 control as follows: 122 (1) The Search Filter is first executed in order to determine 123 which entries satisfy the Search criteria (these are the 124 filtered entries). The control has no impact on this step. 126 (2) If the typesOnly parameter of the Search Request is TRUE, 127 the control has no effect and the Search Request is processed as 128 if the control had not been specified. 130 (3) If the attributes parameter of the Search Request consists 131 of a list containing only the attribute with OID "1.1" 132 (specifying that no attributes are to be returned), the control 133 has no effect and the Search Request is processed as if the 134 control had not been specified. 136 (4) For each attribute listed in the attributes parameter of the 137 Search Request, the server MUST apply the control as follows to 138 each entry in the set of filtered entries: 140 i) Every attribute value that evaluates TRUE against one or 141 more elements of the ValuesReturnFilter is placed in the 142 corresponding SearchResultEntry. 143 ii) Every attribute value that evaluates FALSE or undefined 144 against all elements of the ValuesReturnFilter is not 145 placed in the corresponding SearchResultEntry. An 146 attribute that has no values selected is returned with an 147 empty set of vals. 149 Note. If the AttributeDescriptionList is empty or comprises "*" 150 then the control MUST be applied against every user attribute. 151 If the AttributeDescriptionList contains a "+" then the control 152 MUST be applied against every operational attribute. 154 3. Relationship to X.500 156 The control is a superset of the matchedValuesOnly (MVO) boolean of 157 the X.500 Directory Access Protocol (DAP) [5] Search argument, as 158 amended in the latest version [6]. Close examination of the 159 matchedValuesOnly boolean by the LDAP Extensions (LDAPEXT) Working 160 Group revealed ambiguities and complexities in the MVO boolean that 161 could not easily be resolved. For example, it was not clear if the 162 MVO boolean governed only those attribute values that contributed to 163 the overall truth of the filter, or all of the attribute values even 164 if the filter item containing the attribute evaluated to false. For 165 this reason the LDAPEXT group decided to replace the MVO boolean with 166 a simple filter that removes any uncertainty as to whether an 167 attribute value has been selected or not. 169 4. Relationship to other LDAP Controls 171 The purpose of this control is to select zero, one or more attribute 172 values from each requested attribute in a filtered entry, and to 173 discard the remainder. Once the attribute values have been discarded 174 by this control they MUST NOT be re-instated into the Search results 175 by other controls. 177 This control acts independently of other LDAP controls such as server 178 side sorting [10] and duplicate entries [7]. However, there might be 179 interactions between this control and other controls so that a 180 different set of Search Result Entries are returned, or the entries 181 are returned in a different order, depending upon the sequencing of 182 this control and other controls in the LDAP request. For example, 183 with server side sorting, if sorting is done first, and value return 184 filtering second, the set of Search Results may appear to be in the 185 wrong order since the value filtering may remove the attribute values 186 upon which the ordering was done. (The sorting document specifies 187 that entries without any sort key attribute values should be treated 188 as coming after all other attribute values.) Similarly with duplicate 189 entries, if duplication is performed before value filtering, the set 190 of Search Result Entries may contain identical duplicate entries, 191 each with an empty set of attribute values, because the value 192 filtering removed the attribute values that were used to duplicate 193 the results. 195 For these reasons the ValuesReturnFilter control in a SearchRequest 196 SHOULD precede other controls that affect the number and ordering of 197 SearchResultEntrys. 199 5. Examples 201 All entries are provided in LDAP Data Interchange Format (LDIF)[8]. 203 The string representation of the valuesReturnFilter in the examples 204 below uses the following ABNF [12] notation: 206 valuesReturnFilter = "(" 1*simpleFilterItem ")" 207 simpleFilterItem = "(" item ")" 209 where item is as defined below (adapted from RFC2254 [11]). 211 item = simple / present / substring / extensible 212 simple = attr filtertype value 213 filtertype = equal / approx / greater / less 214 equal = "=" 215 approx = "~=" 216 greater = ">=" 217 less = "<=" 218 extensible = attr [":" matchingrule] ":=" value 219 / ":" matchingrule ":=" value 220 present = attr "=*" 221 substring = attr "=" [initial] any [final] 222 initial = value 223 any = "*" *(value "*") 224 final = value 225 attr = AttributeDescription from Section 4.1.5 of [1] 226 matchingrule = MatchingRuleId from Section 4.1.9 of [1] 227 value = AttributeValue from Section 4.1.6 of [1] 229 (1) The first example shows how the control can be set to return all 230 attribute values from one attribute type (e.g. telephoneNumber) and a 231 subset of values from another attribute type (e.g. mail). 233 The entries below represent organizationalPerson object classes 234 located somewhere beneath the distinguished name dc=ac,dc=uk. 236 dn: cn=Sean Mullan,ou=people,dc=sun,dc=ac,dc=uk 237 cn: Sean Mullan 238 sn: Mullan 239 objectClass: organizationalPerson 240 objectClass: person 241 objectClass: inetOrgPerson 242 mail: sean.mullan@hotmail.com 243 mail: mullan@east.sun.com 244 telephoneNumber: + 781 442 0926 245 telephoneNumber: 555-9999 247 dn: cn=David Chadwick,ou=isi,o=salford,dc=ac,dc=uk 248 cn: David Chadwick 249 sn: Chadwick 250 objectClass: organizationalPerson 251 objectClass: person 252 objectClass: inetOrgPerson 253 mail: d.w.chadwick@salford.ac.uk 255 An LDAP search operation is specified with a baseObject set to the 256 DN of the search base (i.e. dc=ac,dc=uk), a subtree scope, a filter 257 set to (sn=mullan), and the list of attributes to be returned set to 258 "mail,telephoneNumber". In addition, a ValuesReturnFilter control is 259 set to ((mail=*hotmail.com)(telephoneNumber=*)) 261 The search results returned by the server would consist of the 262 following entry: 264 dn: cn=Sean Mullan,ou=people,dc=sun,dc=ac,dc=uk 265 mail: sean.mullan@hotmail.com 266 telephoneNumber: + 781 442 0926 267 telephoneNumber: 555-9999 269 Note that the control has no effect on the values returned for the 270 "telephoneNumber" attribute (all of the values are returned), since 271 the control specified that all values should be returned. 273 (2) The second example shows how one might retrieve a single 274 attribute type subschema definition for the "gunk" attribute with OID 275 1.2.3.4.5 from the subschema subentry 277 Assume the subschema subentry is held below the root entry with DN 278 cn=subschema subentry,o=myorg and this holds an attributeTypes 279 operational attribute holding the descriptions of the 35 attributes 280 known to this server (each description is held as a single attribute 281 value of the attributeTypes attribute). 283 dn: cn=subschema subentry,o=myorg 284 cn: subschema subentry 285 objectClass: subschema 286 attributeTypes: ( 2.5.4.3 NAME 'cn' SUP name ) 287 attributeTypes: ( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE ) 288 attributeTypes: ( 2.5.4.0 NAME 'objectClass' EQUALITY 289 objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) 290 attributeTypes: ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY 291 generalizedTimeMatch ORDERING generalizedTimeOrderingMatch 292 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER- 293 MODIFICATION USAGE directoryOperation ) 294 attributeTypes: ( 2.5.21.6 NAME 'objectClasses' EQUALITY 295 objectIdentifierFirstComponentMatch SYNTAX 296 1.3.6.1.4.1.1466.115.121.1.37 USAGE directoryOperation ) 297 attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch 298 SUBSTR caseIgnoreSubstringsMatch SYNTAX 299 1.3.6.1.4.1.1466.115.121.1.44{64} ) 300 attributeTypes: ( 2.5.21.5 NAME 'attributeTypes' EQUALITY 301 objectIdentifierFirstComponentMatch SYNTAX 302 1.3.6.1.4.1.1466.115.121.1.3 USAGE directoryOperation ) 304 plus another 28 - you get the idea. 306 The user creates an LDAP search operation with a baseObject set to 307 cn=subschema subentry,o=myorg, a scope of base, a filter set to 308 (objectClass=subschema), the list of attributes to be returned set to 309 "attributeTypes", and the ValuesReturnFilter set to 310 ((attributeTypes=1.2.3.4.5)) 312 The search result returned by the server would consist of the 313 following entry: 315 dn: cn=subschema subentry,o=myorg 316 attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch 317 SUBSTR caseIgnoreSubstringsMatch SYNTAX 318 1.3.6.1.4.1.1466.115.121.1.44{64} ) 320 (3) The final example shows how the control can be used to match on a 321 userCertificate attribute value. Note that this example requires the 322 LDAP server to support the certificateExactMatch matching rule 323 defined in [9]. 325 The entry below represent a pkiUser object class stored in the 326 directory. 328 dn: cn=David Chadwick+serialNumber=123456,ou=people,o=University 329 of Salford,c=gb 330 cn: David Chadwick 331 serialNumber: 123456 332 objectClass: person 333 objectClass: organizationalPerson 334 objectClass: pkiUser 335 objectClass: inetOrgPerson 336 sn: Chadwick 337 mail: d.w.chadwick@salford.ac.uk 338 userCertificate: {binary representation of a certificate with a 339 serial number of 2468 issued by o=truetrust ltd, c=gb} 340 userCertificate: {binary representation of certificate with a serial 341 number of 1357 issued by o=truetrust ltd, c=gb} 342 userCertificate: {binary representation of certificate with a serial 343 number of 1234 issued by dc=certs R us, dc=com} 345 An LDAP search operation is specified with a baseObject set to 346 o=University of Salford,c=gb, a subtree scope, a filter set to 347 (sn=chadwick) and the list of attributes to be returned set to 348 "userCertificate". In addition, a ValuesReturnFilter control is set 349 to (userCertificate=1357$o=truetrust ltd, c=gb) 351 The search result returned by the server would consist of the 352 following entry: 354 dn: cn=David Chadwick+serialNumber=123456,ou=people,o=University 355 of Salford,c=gb 356 userCertificate;binary: {binary representation of certificate with a 357 serial number of 1357 issued by o=truetrust ltd, c=gb} 359 6. Security Considerations 361 This document does not primarily discuss security issues. 363 Note however that attribute values MUST only be returned if the 364 access controls applied by the LDAP server allow them to be returned, 365 and in this respect the effect of the ValuesReturnFilter control is 366 of no consequence. 368 Note that the ValuesReturnFilter control may have a positive effect 369 on the deployment of public key infrastructures. Certain PKI 370 operations, like searching for specific certificates, become more 371 practical when combined with X.509 certificate matching rules at the 372 server, and more scalable, since the control avoids the downloading 373 of potentially large numbers of irrelevant certificates which would 374 have to be processed and filtered locally (which in some cases is 375 very difficult to perform). 377 7. Acknowledgements 379 The authors would like to thank members of the LDAPExt list for their 380 constructive comments on earlier versions of this document, and in 381 particular to Harald Alvestrand who first suggested having an 382 attribute return filter and Bruce Greenblatt who first proposed a 383 syntax for this control. 385 8. Copyright 387 Copyright (C) The Internet Society (date). All Rights Reserved. 389 This document and translations of it may be copied and furnished to 390 others, and derivative works that comment on or otherwise explain it 391 or assist in its implementation may be prepared, copied, published 392 and distributed, in whole or in part, without restriction of any 393 kind, provided that the above copyright notice and this paragraph are 394 included on all such copies and derivative works. However, this 395 document itself may not be modified in any way, such as by removing 396 the copyright notice or references to the Internet Society or other 397 Internet organizations, except as needed for the purpose of 398 developing Internet standards in which case the procedures for 399 copyrights defined in the Internet Standards process must be 400 followed, or as required to translate it into languages other than 401 English. 403 The limited permissions granted above are perpetual and will not be 404 revoked by the Internet Society or its successors or assigns. 406 This document and the information contained herein is provided on an 407 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 408 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 409 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 410 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 411 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 413 9. References 415 Normative 417 [1] S. Bradner. "The Internet Standards Process -- Revision 3", RFC 418 2026, October 1996. 419 [2] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access 420 Protocol (v3)", Dec. 1997, RFC 2251 421 [3] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory 422 Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, Dec 423 1997 424 [4] S.Bradner. "Key words for use in RFCs to Indicate Requirement 425 Levels", RFC 2119, March 1997. 427 Informative 429 [5] ITU-T Rec. X.511, "The Directory: Abstract Service Definition", 430 1993. 431 [6] Draft ISO/IEC 9594 / ITU-T Rec X.511 (2001) The Directory: 432 Abstract Service Definition. 433 [7] J. Sermersheim. "LDAP Control for a Duplicate Entry 434 Representation of Search Results", Internet Draft , October 2000. 436 [8] G. Good. "The LDAP Data Interchange Format (LDIF) - Technical 437 Specification". RFC 2849, June 2000. 438 [9] D. Chadwick, S.Legg. "Internet X.509 Public Key Infrastructure - 439 Additional LDAP Schema for PKIs", Internet Draft , June 2002 441 [10] T. Howes, M. Wahl, A. Anantha, "LDAP Control Extension for 442 Server Side Sorting of Search Results", RFC 2891, August 2000 443 [11] T. Howes. "The String Representation of LDAP Search Filters". 444 RFC 2254, December 1997. 445 [12] D. Crocker, Ed. "Augmented BNF for Syntax Specifications: ABNF." 446 RFC 2234. November 1997. 448 10. Authors Addresses 450 David Chadwick 451 IS Institute 452 University of Salford 453 Salford M5 4WT 454 England 456 Email: d.w.chadwick@salford.ac.uk 457 Tel: +44 161 295 5351 459 Sean Mullan 460 Sun Microsystems 461 East Point Business Park 462 Dublin 3 463 Ireland 464 Tel: +353 1 853 0655 465 Email: sean.mullan@sun.com 467 11. Changes since version 2 469 i) Revised the examples to be more appropriate 470 ii) Section on interactions with other LDAP controls added 471 iii) Removed Editor's note concerning present filter 472 iv) Tightened wording about its applicability to other operations 473 and use of criticality field 475 Changes since version 3 477 i) Mandated that at least one of type and matchingRule in 478 simpleMatchingAssertion be present 479 ii) Fixed LDIF mistakes in the examples 480 iii) Additional minor editorials only 482 Changes since version 4 484 i) corrected the ABNF for single items of valuesReturnFilter 486 Changes since version 5 488 i) added some adapted BNFL from [11] into the examples 489 (specifically the [":dn"] component was removed) 490 ii) general editorial tidying up prior to Last Call