1 2 3 4 5 6 7Network Working Group D. Chadwick 8Request for Comments: 3876 University of Salford 9Category: Standards Track S. Mullan 10 Sun Microsystems 11 September 2004 12 13 14 Returning Matched Values with the 15 Lightweight Directory Access Protocol version 3 (LDAPv3) 16 17Status of this Memo 18 19 This document specifies an Internet standards track protocol for the 20 Internet community, and requests discussion and suggestions for 21 improvements. Please refer to the current edition of the "Internet 22 Official Protocol Standards" (STD 1) for the standardization state 23 and status of this protocol. Distribution of this memo is unlimited. 24 25Copyright Notice 26 27 Copyright (C) The Internet Society (2004). 28 29Abstract 30 31 This document describes a control for the Lightweight Directory 32 Access Protocol version 3 that is used to return a subset of 33 attribute values from an entry. Specifically, only those values that 34 match a "values return" filter. Without support for this control, a 35 client must retrieve all of an attribute's values and search for 36 specific values locally. 37 381. Introduction 39 40 When reading an attribute from an entry using the Lightweight 41 Directory Access Protocol version 3 (LDAPv3) [2], it is normally only 42 possible to read either the attribute type, or the attribute type and 43 all its values. It is not possible to selectively read just a few of 44 the attribute values. If an attribute holds many values, for 45 example, the userCertificate attribute, or the subschema publishing 46 operational attributes objectClasses and attributeTypes [3], then it 47 may be desirable for the user to be able to selectively retrieve a 48 subset of the values, specifically, those attribute values that match 49 some user defined selection criteria. Without the control specified 50 in this document, a client must read all of the attribute's values 51 and filter out the unwanted values, necessitating the client to 52 implement the matching rules. It also requires the client to 53 54 55 56 57 58Chadwick & Mullan Standards Track [Page 1] 59 60RFC 3876 Returning Matched Values with LDAPv3 September 2004 61 62 63 potentially read and process many irrelevant values, which can be 64 inefficient if the values are large or complex, or there are many 65 values stored per attribute. 66 67 This document specifies an LDAPv3 control to enable a user to return 68 only those values that matched (i.e., returned TRUE to) one or more 69 elements of a newly defined "values return" filter. This control can 70 be especially useful when used in conjunction with extensible 71 matching rules that match on one or more components of complex binary 72 attribute values. 73 74 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 75 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 76 document are to be interpreted as described in BCP 14, RFC 2119 [4]. 77 782. The valuesReturnFilter Control 79 80 The valuesReturnFilter control is either critical or non-critical as 81 determined by the user. It only has meaning for the Search 82 operation, and SHOULD only be added to the Search operation by the 83 client. If the server supports the control and it is present on a 84 Search operation, the server MUST obey the control, regardless of the 85 value of the criticality flag. 86 87 If the control is marked as critical, and either the server does not 88 support the control or the control is applied to an operation other 89 than Search, the server MUST return an unavailableCriticalExtension 90 error. If the control is not marked as critical, and either the 91 server does not support the control or the control is applied to an 92 operation other than Search, then the server MUST ignore the control. 93 94 The object identifier for this control is 1.2.826.0.1.3344810.2.3. 95 96 The controlValue is an OCTET STRING, whose value is the BER encoding 97 [6], as per Section 5.1 of RFC 2251 [2], of a value of the ASN.1 [5] 98 type ValuesReturnFilter. 99 100 ValuesReturnFilter ::= SEQUENCE OF SimpleFilterItem 101 102 SimpleFilterItem ::= CHOICE { 103 equalityMatch [3] AttributeValueAssertion, 104 substrings [4] SubstringFilter, 105 greaterOrEqual [5] AttributeValueAssertion, 106 lessOrEqual [6] AttributeValueAssertion, 107 present [7] AttributeDescription, 108 approxMatch [8] AttributeValueAssertion, 109 extensibleMatch [9] SimpleMatchingAssertion } 110 111 112 113 114Chadwick & Mullan Standards Track [Page 2] 115 116RFC 3876 Returning Matched Values with LDAPv3 September 2004 117 118 119 SimpleMatchingAssertion ::= SEQUENCE { 120 matchingRule [1] MatchingRuleId OPTIONAL, 121 type [2] AttributeDescription OPTIONAL, 122 --- at least one of the above must be present 123 matchValue [3] AssertionValue} 124 125 All the above data types have their standard meanings as defined in 126 [2]. 127 128 If the server supports this control, the server MUST make use of the 129 control as follows: 130 131 1) The Search Filter is first executed in order to determine which 132 entries satisfy the Search criteria (these are the filtered 133 entries). The control has no impact on this step. 134 135 2) If the typesOnly parameter of the Search Request is TRUE, the 136 control has no effect and the Search Request is processed as if 137 the control had not been specified. 138 139 3) If the attributes parameter of the Search Request consists of a 140 list containing only the attribute with OID "1.1" (specifying that 141 no attributes are to be returned), the control has no effect and 142 the Search Request is processed as if the control had not been 143 specified. 144 145 4) For each attribute listed in the attributes parameter of the 146 Search Request, the server MUST apply the control as follows to 147 each entry in the set of filtered entries: 148 149 i) Every attribute value that evaluates TRUE against one or more 150 elements of the ValuesReturnFilter is placed in the 151 corresponding SearchResultEntry. 152 153 ii) Every attribute value that evaluates FALSE or undefined 154 against all elements of the ValuesReturnFilter is not placed 155 in the corresponding SearchResultEntry. An attribute that has 156 no values selected is returned with an empty set of values. 157 158 Note. If the AttributeDescriptionList (see [2]) is empty or 159 comprises "*", then the control MUST be applied against every user 160 attribute. If the AttributeDescriptionList contains a "+", then the 161 control MUST be applied against every operational attribute. 162 163 164 165 166 167 168 169 170Chadwick & Mullan Standards Track [Page 3] 171 172RFC 3876 Returning Matched Values with LDAPv3 September 2004 173 174 1753. Relationship to X.500 176 177 The control is a superset of the matchedValuesOnly (MVO) boolean of 178 the X.500 Directory Access Protocol (DAP) [8] Search argument, as 179 amended in the latest version [9]. Close examination of the 180 matchedValuesOnly boolean by the LDAP Extensions (LDAPEXT) Working 181 Group revealed ambiguities and complexities in the MVO boolean that 182 could not easily be resolved. For example, it was not clear if the 183 MVO boolean governed only those attribute values that contributed to 184 the overall truth of the filter, or all of the attribute values, even 185 if the filter item containing the attribute was evaluated as false. 186 For this reason the LDAPEXT group decided to replace the MVO boolean 187 with a simple filter that removes any uncertainty as to whether an 188 attribute value has been selected or not. 189 1904. Relationship to other LDAP Controls 191 192 The purpose of this control is to select zero, one, or more attribute 193 values from each requested attribute in a filtered entry, and to 194 discard the remainder. Once the attribute values have been discarded 195 by this control, they MUST NOT be re-instated into the Search results 196 by other controls. 197 198 This control acts independently of other LDAP controls such as server 199 side sorting [13] and duplicate entries [10]. However, there might 200 be interactions between this control and other controls so that a 201 different set of Search Result Entries are returned, or the entries 202 are returned in a different order, depending upon the sequencing of 203 this control and other controls in the LDAP request. For example, 204 with server side sorting, if sorting is done first, and value return 205 filtering second, the set of Search Results may appear to be in the 206 wrong order since the value filtering may remove the attribute values 207 upon which the ordering was done. (The sorting document specifies 208 that entries without any sort key attribute values should be treated 209 as coming after all other attribute values.) Similarly with 210 duplicate entries, if duplication is performed before value 211 filtering, the set of Search Result Entries may contain identical 212 duplicate entries, each with an empty set of attribute values, 213 because the value filtering removed the attribute values that were 214 used to duplicate the results. 215 216 For these reasons, the ValuesReturnFilter control in a SearchRequest 217 SHOULD precede other controls that affect the number and ordering of 218 SearchResultEntrys. 219 220 221 222 223 224 225 226Chadwick & Mullan Standards Track [Page 4] 227 228RFC 3876 Returning Matched Values with LDAPv3 September 2004 229 230 2315. Examples 232 233 All entries are provided in an LDAP Data Interchange Format 234 (LDIF)[11]. 235 236 The string representation of the valuesReturnFilter in the examples 237 below uses the following ABNF [15] notation: 238 239 valuesReturnFilter = "(" 1*simpleFilterItem ")" 240 simpleFilterItem = "(" item ")" 241 242 where item is as defined below (adapted from RFC2254 [14]). 243 244 item = simple / present / substring / extensible 245 simple = attr filtertype value 246 filtertype = equal / approx / greater / less 247 equal = "=" 248 approx = "~=" 249 greater = ">=" 250 less = "<=" 251 extensible = attr [":" matchingrule] ":=" value 252 / ":" matchingrule ":=" value 253 present = attr "=*" 254 substring = attr "=" [initial] any [final] 255 initial = value 256 any = "*" *(value "*") 257 final = value 258 attr = AttributeDescription from Section 4.1.5 of [1] 259 matchingrule = MatchingRuleId from Section 4.1.9 of [1] 260 value = AttributeValue from Section 4.1.6 of [1] 261 262 1) The first example shows how the control can be set to return all 263 attribute values from one attribute type (e.g., telephoneNumber) 264 and a subset of values from another attribute type (e.g., mail). 265 266 The entries below represent organizationalPerson object classes 267 located somewhere beneath the distinguished name dc=ac,dc=uk. 268 269 dn: cn=Sean Mullan,ou=people,dc=sun,dc=ac,dc=uk 270 cn: Sean Mullan 271 sn: Mullan 272 objectClass: organizationalPerson 273 objectClass: person 274 objectClass: inetOrgPerson 275 mail: sean.mullan@hotmail.com 276 mail: mullan@east.sun.com 277 telephoneNumber: + 781 442 0926 278 telephoneNumber: 555-9999 279 280 281 282Chadwick & Mullan Standards Track [Page 5] 283 284RFC 3876 Returning Matched Values with LDAPv3 September 2004 285 286 287 dn: cn=David Chadwick,ou=isi,o=salford,dc=ac,dc=uk 288 cn: David Chadwick 289 sn: Chadwick 290 objectClass: organizationalPerson 291 objectClass: person 292 objectClass: inetOrgPerson 293 mail: d.w.chadwick@salford.ac.uk 294 295 An LDAP search operation is specified with a baseObject set to the DN 296 of the search base (i.e., dc=ac,dc=uk), a subtree scope, a filter set 297 to (sn=mullan), and the list of attributes to be returned set to 298 "mail,telephoneNumber" or "*". In addition, a ValuesReturnFilter 299 control is set to ((mail=*hotmail.com)(telephoneNumber=*)). 300 301 The search results returned by the server would consist of the 302 following entry: 303 304 dn: cn=Sean Mullan,ou=people,dc=sun,dc=ac,dc=uk 305 mail: sean.mullan@hotmail.com 306 telephoneNumber: + 781 442 0926 307 telephoneNumber: 555-9999 308 309 Note that the control has no effect on the values returned for the 310 "telephoneNumber" attribute (all of the values are returned), since 311 the control specified that all values should be returned. 312 313 2) The second example shows how one might retrieve a single attribute 314 type subschema definition for the "gunk" attribute with OID 315 1.2.3.4.5 from the subschema subentry. 316 317 Assume the subschema subentry is held below the root entry with DN 318 cn=subschema subentry,o=myorg and this holds an attributeTypes 319 operational attribute holding the descriptions of the 35 attributes 320 known to this server (each description is held as a single attribute 321 value of the attributeTypes attribute). 322 323 dn: cn=subschema subentry,o=myorg 324 cn: subschema subentry 325 objectClass: subschema 326 attributeTypes: ( 2.5.4.3 NAME 'cn' SUP name ) 327 attributeTypes: ( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE ) 328 attributeTypes: ( 2.5.4.0 NAME 'objectClass' EQUALITY obj 329 ectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) 330 attributeTypes: ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY gen 331 eralizedTimeMatch ORDERING generalizedTimeOrderingMatch SYN 332 TAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER- 333 MODIFICATION USAGE directoryOperation ) 334 attributeTypes: ( 2.5.21.6 NAME 'objectClasses' EQUALITY obj 335 336 337 338Chadwick & Mullan Standards Track [Page 6] 339 340RFC 3876 Returning Matched Values with LDAPv3 September 2004 341 342 343 ectIdentifierFirstComponentMatch SYNTAX 1.3. 344 6.1.4.1.1466.115.121.1.37 USAGE directoryOperation ) 345 attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMat 346 ch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3. 347 6.1.4.1.1466.115.121.1.44{64} ) 348 attributeTypes: ( 2.5.21.5 NAME 'attributeTypes' EQUALITY obj 349 ectIdentifierFirstComponentMatch SYNTAX 1.3. 350 6.1.4.1.1466.115.121.1.3 USAGE directoryOperation ) 351 352 plus another 28 - you get the idea. 353 354 The user creates an LDAP search operation with a baseObject set to 355 cn=subschema subentry,o=myorg, a scope of base, a filter set to 356 (objectClass=subschema), the list of attributes to be returned set to 357 "attributeTypes", and the ValuesReturnFilter set to 358 ((attributeTypes=1.2.3.4.5)) 359 360 The search result returned by the server would consist of the 361 following entry: 362 363 dn: cn=subschema subentry,o=myorg 364 attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMat 365 ch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3. 366 6.1.4.1.1466.115.121.1.44{64} ) 367 368 3) The final example shows how the control can be used to match on a 369 userCertificate attribute value. Note that this example requires 370 the LDAP server to support the certificateExactMatch matching rule 371 defined in [12] as the EQUALITY matching rule for userCertificate. 372 373 The entry below represents a pkiUser object class stored in the 374 directory. 375 376 dn: cn=David Chadwick,ou=people,o=University of Salford,c=gb 377 cn: David Chadwick 378 objectClass: person 379 objectClass: organizationalPerson 380 objectClass: pkiUser 381 objectClass: inetOrgPerson 382 sn: Chadwick 383 mail: d.w.chadwick@salford.ac.uk 384 userCertificate;binary: {binary representation of a certificate with 385 a serial number of 2468 issued by o=truetrust ltd,c=gb} 386 userCertificate;binary: {binary representation of certificate with a 387 serial number of 1357 issued by o=truetrust ltd,c=gb} 388 userCertificate;binary: {binary representation of certificate with a 389 serial number of 1234 issued by dc=certsRus,dc=com} 390 391 392 393 394Chadwick & Mullan Standards Track [Page 7] 395 396RFC 3876 Returning Matched Values with LDAPv3 September 2004 397 398 399 An LDAP search operation is specified with a baseObject set to 400 o=University of Salford,c=gb, a subtree scope, a filter set to 401 (sn=chadwick), and the list of attributes to be returned set to 402 "userCertificate;binary". In addition, a ValuesReturnFilter control 403 is set to ((userCertificate=1357$o=truetrust ltd,c=gb)). 404 405 The search result returned by the server would consist of the 406 following entry: 407 408 dn: cn=David Chadwick,ou=people,o=University of Salford,c=gb 409 userCertificate;binary: {binary representation of certificate with a 410 serial number of 1357 issued by o=truetrust ltd,c=gb} 411 4126. Security Considerations 413 414 This document does not primarily discuss security issues. 415 416 Note however that attribute values MUST only be returned if the 417 access controls applied by the LDAP server allow them to be returned, 418 and in this respect the effect of the ValuesReturnFilter control is 419 of no consequence. 420 421 Note that the ValuesReturnFilter control may have a positive effect 422 on the deployment of public key infrastructures. Certain PKI 423 operations, like searching for specific certificates, become more 424 scalable, and more practical when combined with X.509 certificate 425 matching rules at the server, since the control avoids the 426 downloading of potentially large numbers of irrelevant certificates 427 which would have to be processed and filtered locally (which in some 428 cases is very difficult to perform). 429 4307. IANA Considerations 431 432 The Matched Values control as an LDAP Protocol Mechanism [7] has been 433 registered as follows: 434 435 Subject: Request for LDAP Protocol Mechanism Registration 436 437 Object Identifier: 1.2.826.0.1.3344810.2.3 438 Description: Matched Values Control 439 Person & email address to contact for further information: 440 David Chadwick <d.w.chadwick@salford.ac.uk> 441 Usage: Control 442 Specification: RFC3876 443 Author/Change Controller: IESG 444 Comments: none 445 446 447 448 449 450Chadwick & Mullan Standards Track [Page 8] 451 452RFC 3876 Returning Matched Values with LDAPv3 September 2004 453 454 455 This document uses the OID 1.2.826.0.1.3344810.2.3 to identify the 456 matchedValues control described here. This OID was assigned by 457 TrueTrust Ltd, under its BSI assigned English/Welsh Registered 458 Company number [16]. 459 4608. Acknowledgements 461 462 The authors would like to thank members of the LDAPExt list for their 463 constructive comments on earlier versions of this document, and in 464 particular to Harald Alvestrand who first suggested having an 465 attribute return filter and Bruce Greenblatt who first proposed a 466 syntax for this control. 467 4689. References 469 4709.1. Normative References 471 472 [1] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 473 9, RFC 2026, October 1996. 474 475 [2] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access 476 Protocol (w3)", RFC 2251, December 1997. 477 478 [3] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight 479 Directory Access Protocol (v3): Attribute Syntax Definitions", 480 RFC 2252, December 1997. 481 482 [4] Bradner, S., "Key words for use in RFCs to Indicate Requirement 483 Levels", BCP 14, RFC 2119, March 1997. 484 485 [5] ITU-T Recommendation X.680 (1997) | ISO/IEC 8824-1:1998, 486 Information Technology - Abstract Syntax Notation One (ASN.1): 487 Specification of Basic Notation 488 489 [6] ITU-T Recommendation X.690 (1997) | ISO/IEC 8825-1,2,3:1998 490 Information technology - ASN.1 encoding rules: Specification of 491 Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and 492 Distinguished Encoding Rules (DER) 493 494 [7] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) 495 Considerations for the Lightweight Directory Access Protocol 496 (LDAP)", BCP 64, RFC 3383, September 2002. 497 498 499 500 501 502 503 504 505 506Chadwick & Mullan Standards Track [Page 9] 507 508RFC 3876 Returning Matched Values with LDAPv3 September 2004 509 510 5119.2. Informative References 512 513 [8] ITU-T Rec. X.511, "The Directory: Abstract Service Definition", 514 1993. 515 516 [9] ISO/IEC 9594 / ITU-T Rec X.511 (2001) The Directory: Abstract 517 Service Definition. 518 519 [10] Sermersheim, J., "LDAP Control for a Duplicate Entry 520 Representation of Search Results", Work in Progress, October 521 2000. 522 523 [11] Good, G., "The LDAP Data Interchange Format (LDIF) - Technical 524 Specification", RFC 2849, June 2000. 525 526 [12] Chadwick, D. and S.Legg, "Internet X.509 Public Key 527 Infrastructure - Additional LDAP Schema for PKIs", Work in 528 Progress, June 2002 529 530 [13] Howes, T., Wahl, M., and A. Anantha, "LDAP Control Extension for 531 Server Side Sorting of Search Results", RFC 2891, August 2000. 532 533 [14] Howes, T., "The String Representation of LDAP Search Filters", 534 RFC 2254, December 1997. 535 536 [15] Crocker, D. and P. Overell, "Augmented BNF for Syntax 537 Specifications: ABNF", RFC 2234, November 1997. 538 539 [16] BRITISH STANDARD BS 7453 Part 1. Procedures for UK Registration 540 for Open System Standards Part 1: Procedures for the UK Name 541 Registration Authority. 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562Chadwick & Mullan Standards Track [Page 10] 563 564RFC 3876 Returning Matched Values with LDAPv3 September 2004 565 566 56710. Authors' Addresses 568 569 David Chadwick 570 IS Institute 571 University of Salford 572 Salford M5 4WT 573 England 574 575 Phone: +44 161 295 5351 576 EMail: d.w.chadwick@salford.ac.uk 577 578 579 Sean Mullan 580 Sun Microsystems 581 One Network Drive 582 Burlington, MA 01803 583 USA 584 585 EMail: sean.mullan@sun.com 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618Chadwick & Mullan Standards Track [Page 11] 619 620RFC 3876 Returning Matched Values with LDAPv3 September 2004 621 622 62311. Full Copyright Statement 624 625 Copyright (C) The Internet Society (2004). 626 627 This document is subject to the rights, licenses and restrictions 628 contained in BCP 78, and except as set forth therein, the authors 629 retain all their rights. 630 631 This document and the information contained herein are provided on an 632 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/S HE 633 REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE 634 INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR 635 IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 636 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 637 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 638 639Intellectual Property 640 641 The IETF takes no position regarding the validity or scope of any 642 Intellectual Property Rights or other rights that might be claimed to 643 pertain to the implementation or use of the technology described in 644 this document or the extent to which any license under such rights 645 might or might not be available; nor does it represent that it has 646 made any independent effort to identify any such rights. Information 647 on the IETF's procedures with respect to rights in IETF Documents can 648 be found in BCP 78 and BCP 79. 649 650 Copies of IPR disclosures made to the IETF Secretariat and any 651 assurances of licenses to be made available, or the result of an 652 attempt made to obtain a general license or permission for the use of 653 such proprietary rights by implementers or users of this 654 specification can be obtained from the IETF on-line IPR repository at 655 http://www.ietf.org/ipr. 656 657 The IETF invites any interested party to bring to its attention any 658 copyrights, patents or patent applications, or other proprietary 659 rights that may cover technology that may be required to implement 660 this standard. Please address the information to the IETF at ietf- 661 ipr@ietf.org. 662 663Acknowledgement 664 665 Funding for the RFC Editor function is currently provided by the 666 Internet Society. 667 668 669 670 671 672 673 674Chadwick & Mullan Standards Track [Page 12] 675 676