idnits 2.17.1 draft-ietf-ldapext-matchedval-07.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 549 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 19 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 (8 September 2002) is 7873 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) -- Possible downref: Non-RFC (?) normative reference: ref. '14' -- Possible downref: Non-RFC (?) normative reference: ref. '15' -- Possible downref: Non-RFC (?) normative reference: ref. '16' -- 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: 4 errors (**), 0 flaws (~~), 3 warnings (==), 7 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: 8 March 2003 8 September 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. 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 [15], as per Section 5.1 of RFC 2251 [2], of a value of the ASN.1 97 [14] type 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" or "*". In addition, a ValuesReturnFilter 259 control is 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 obj 289 ectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) 290 attributeTypes: ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY gen 291 eralizedTimeMatch ORDERING generalizedTimeOrderingMatch SYN 292 TAX 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 obj 295 ectIdentifierFirstComponentMatch SYNTAX 1.3. 296 6.1.4.1.1466.115.121.1.37 USAGE directoryOperation ) 297 attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMat 298 ch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3. 299 6.1.4.1.1466.115.121.1.44{64} ) 300 attributeTypes: ( 2.5.21.5 NAME 'attributeTypes' EQUALITY obj 301 ectIdentifierFirstComponentMatch SYNTAX 1.3. 302 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 caseIgnoreMat 317 ch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3. 318 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] as the EQUALITY matching rule for userCertificate. 325 The entry below represent a pkiUser object class stored in the 326 directory. 328 dn: cn=David Chadwick,ou=people,o=University of Salford,c=gb 329 cn: David Chadwick 330 objectClass: person 331 objectClass: organizationalPerson 332 objectClass: pkiUser 333 objectClass: inetOrgPerson 334 sn: Chadwick 335 mail: d.w.chadwick@salford.ac.uk 336 userCertificate;binary: {binary representation of a certificate with 337 a serial number of 2468 issued by o=truetrust ltd,c=gb} 338 userCertificate;binary: {binary representation of certificate with a 339 serial number of 1357 issued by o=truetrust ltd,c=gb} 340 userCertificate;binary: {binary representation of certificate with a 341 serial number of 1234 issued by dc=certsRus,dc=com} 343 An LDAP search operation is specified with a baseObject set to 344 o=University of Salford,c=gb, a subtree scope, a filter set to 345 (sn=chadwick) and the list of attributes to be returned set to 346 "userCertificate;binary". In addition, a ValuesReturnFilter control 347 is set to ((userCertificate=1357$o=truetrust ltd,c=gb)). 349 The search result returned by the server would consist of the 350 following entry: 352 dn: cn=David Chadwick,ou=people,o=University of Salford,c=gb 353 userCertificate;binary: {binary representation of certificate with a 354 serial number of 1357 issued by o=truetrust ltd,c=gb} 356 6. Security Considerations 358 This document does not primarily discuss security issues. 360 Note however that attribute values MUST only be returned if the 361 access controls applied by the LDAP server allow them to be returned, 362 and in this respect the effect of the ValuesReturnFilter control is 363 of no consequence. 365 Note that the ValuesReturnFilter control may have a positive effect 366 on the deployment of public key infrastructures. Certain PKI 367 operations, like searching for specific certificates, become more 368 practical when combined with X.509 certificate matching rules at the 369 server, and more scalable, since the control avoids the downloading 370 of potentially large numbers of irrelevant certificates which would 371 have to be processed and filtered locally (which in some cases is 372 very difficult to perform). 374 7. IANA Considerations 376 Registrigration of the Matched Values control as an LDAP Protocol 377 Mechanism [16] is requested: 379 Subject: Request for LDAP Protocol Mechanism Registration 381 Object Identifier: 1.2.826.0.1.3344810.2.3 382 Description: Matched Values Control 383 Person & email address to contact for further information: 384 David Chadwick 385 Usage: Control 386 Specification: RFCxxxx 387 Author/Change Controller: IESG 388 Comments: none 390 This document uses the OID 1.2.826.0.1.3344810.2.3 to identify the 391 matchedValues control described here. This OID was assigned by 392 TrueTrust Ltd, under its BSI assigned English/Welsh Registered 393 Company number [13]. 395 8. Acknowledgements 397 The authors would like to thank members of the LDAPExt list for their 398 constructive comments on earlier versions of this document, and in 399 particular to Harald Alvestrand who first suggested having an 400 attribute return filter and Bruce Greenblatt who first proposed a 401 syntax for this control. 403 9. Copyright 405 Copyright (C) The Internet Society (date). All Rights Reserved. 407 This document and translations of it may be copied and furnished to 408 others, and derivative works that comment on or otherwise explain it 409 or assist in its implementation may be prepared, copied, published 410 and distributed, in whole or in part, without restriction of any 411 kind, provided that the above copyright notice and this paragraph are 412 included on all such copies and derivative works. However, this 413 document itself may not be modified in any way, such as by removing 414 the copyright notice or references to the Internet Society or other 415 Internet organizations, except as needed for the purpose of 416 developing Internet standards in which case the procedures for 417 copyrights defined in the Internet Standards process must be 418 followed, or as required to translate it into languages other than 419 English. 421 The limited permissions granted above are perpetual and will not be 422 revoked by the Internet Society or its successors or assigns. 424 This document and the information contained herein is provided on an 425 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 426 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 427 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 428 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 429 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 431 10. References 433 Normative 435 [1] S. Bradner. "The Internet Standards Process -- Revision 3", RFC 436 2026, October 1996. 437 [2] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access 438 Protocol (v3)", Dec. 1997, RFC 2251 439 [3] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory 440 Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, Dec 441 1997 442 [4] S.Bradner. "Key words for use in RFCs to Indicate Requirement 443 Levels", RFC 2119, March 1997. 444 [14] ITU-T Recommendation X.680 (1997) | ISO/IEC 8824-1:1998, 445 Information Technology - Abstract Syntax Notation One (ASN.1): 446 Specification of Basic Notation 447 [15] ITU-T Recommendation X.690 (1997) | ISO/IEC 8825-1,2,3:1998 448 Information technology - ASN.1 encoding rules: Specification of Basic 449 Encoding Rules (BER), Canonical Encoding Rules (CER) and 450 Distinguished Encoding Rules (DER) 451 [16] K. Zeilenga. "IANA Considerations for LDAP" , August 2002 454 Informative 456 [5] ITU-T Rec. X.511, "The Directory: Abstract Service Definition", 457 1993. 458 [6] Draft ISO/IEC 9594 / ITU-T Rec X.511 (2001) The Directory: 459 Abstract Service Definition. 460 [7] J. Sermersheim. "LDAP Control for a Duplicate Entry 461 Representation of Search Results", Internet Draft , October 2000. 463 [8] G. Good. "The LDAP Data Interchange Format (LDIF) - Technical 464 Specification". RFC 2849, June 2000. 465 [9] D. Chadwick, S.Legg. "Internet X.509 Public Key Infrastructure - 466 Additional LDAP Schema for PKIs", Internet Draft , June 2002 468 [10] T. Howes, M. Wahl, A. Anantha, "LDAP Control Extension for 469 Server Side Sorting of Search Results", RFC 2891, August 2000 470 [11] T. Howes. "The String Representation of LDAP Search Filters". 471 RFC 2254, December 1997. 472 [12] D. Crocker, Ed. "Augmented BNF for Syntax Specifications: ABNF." 473 RFC 2234. November 1997. 474 [13] BRITISH STANDARD BS 7453 Part 1. Procedures for UK Registration 475 for Open System Standards Part 1: Procedures for the UK Name 476 Registration Authority. 478 11. Authors Addresses 480 David Chadwick 481 IS Institute 482 University of Salford 483 Salford M5 4WT 484 England 486 Email: d.w.chadwick@salford.ac.uk 487 Tel: +44 161 295 5351 489 Sean Mullan 490 Sun Microsystems 491 East Point Business Park 492 Dublin 3 493 Ireland 494 Tel: +353 1 853 0655 495 Email: sean.mullan@sun.com 497 12. Changes since version 2 499 i) Revised the examples to be more appropriate 500 ii) Section on interactions with other LDAP controls added 501 iii) Removed Editor's note concerning present filter 502 iv) Tightened wording about its applicability to other operations 503 and use of criticality field 505 Changes since version 3 507 i) Mandated that at least one of type and matchingRule in 508 simpleMatchingAssertion be present 509 ii) Fixed LDIF mistakes in the examples 510 iii) Additional minor editorials only 512 Changes since version 4 514 i) corrected the ABNF for single items of valuesReturnFilter 516 Changes since version 5 518 i) added some adapted BNFL from [11] into the examples 519 (specifically the [":dn"] component was removed) 520 ii) general editorial tidying up prior to Last Call 522 Changes since version 6 524 i) First example had all attributes (*) added to it 525 ii) References to ASN.1 standards added 526 iii) Syntax error in third example corrected 527 iv) IANA considerations section added