idnits 2.17.1 draft-ietf-ldapext-matchedval-04.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 469 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 (16 October 2000) is 8593 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. '4' -- Possible downref: Non-RFC (?) normative reference: ref. '6' -- Possible downref: Non-RFC (?) normative reference: ref. '7' -- Possible downref: Non-RFC (?) normative reference: ref. '9' ** Obsolete normative reference: RFC 2254 (ref. '11') (Obsoleted by RFC 4510, RFC 4515) Summary: 7 errors (**), 0 flaws (~~), 3 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: 15 April 2001 16 October 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 [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 This Internet-Draft expires on 15 April 2001. 32 Comments and suggestions on this document are encouraged. Comments on 33 this document should be sent to the LDAPEXT working group discussion 34 list: 35 ietf-ldapext@netscape.com 37 or directly to the authors. 39 ABSTRACT 41 This document describes a control for the Lightweight Directory 42 Access Protocol v3 that is used to return a subset of attribute 43 values from an entry, specifically, only those values that match a 44 "values return" filter. Without support for this control, a client 45 must retrieve all of an attribute's values and search for specific 46 values locally. 48 1. Introduction 50 When reading an attribute from an entry using LDAPv3 [2], it is 51 normally only possible to read either the attribute type, or the 52 attribute type and all its values. It is not possible to selectively 53 read just a few of the attribute values. If an attribute holds many 54 values, for example, the userCertificate attribute, or the subschema 55 publishing operational attributes objectClasses and attributeTypes 56 [3], then it may be desirable for the user to be able to selectively 57 retrieve a subset of the values, specifically, those attribute values 58 that match some user defined selection criteria. Without the control 59 specified in this [ID/standard/document] a client must read all of 60 the attribute's values and filter out the unwanted values, 61 necessitating the client to implement the matching rules. It also 62 requires the client to potentially read and process many irrelevant 63 values, which can be inefficient if the values are large or complex, 64 or there are many values stored per attribute. 66 This [ID/Standard/document] specifies an LDAPv3 control to enable a 67 user to return only those values that matched (i.e. returned TRUE to) 68 one or more elements of a newly defined "values return" filter. This 69 control can be especially useful when used in conjunction with 70 extensible matching rules that match on one or more components of 71 complex binary attribute values. 73 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 74 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 75 document are to be interpreted as described in RFC 2119 [5]. 77 2. The valuesReturnFilter Control 79 The valuesReturnFilter control MAY be critical or non-critical as 80 determined by the user. It only has meaning for the Search operation, 81 and SHOULD only be added to the Search operation by the client. If 82 the server supports the control and it is present on a Search 83 operation, the server MUST obey the control regardless of the value 84 of the criticality flag. 86 If the control is marked as critical, and either the server does not 87 support the control or the control is applied to an operation other 88 than Search, then the server MUST return an 89 unavailableCriticalExtension error. If the control is not marked as 90 critical, and either the server does not support the control or the 91 control is applied to an operation other than Search, then the server 92 MUST ignore the control. 94 The object identifier for this control is 1.2.826.0.1.3344810.2.3 96 The controlValue is an OCTET STRING, whose value is the BER encoding 97 of a value of the 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 SHOULD be 128 processed as 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 SHOULD be processed as if 134 the 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 attribute. 152 3. Relationship to X.500 154 The control is a superset of the matchedValuesOnly (MVO) boolean of 155 the X.500 DAP [4] Search argument, as amended in the latest version 156 [6]. Close examination of the matchedValuesOnly boolean by the 157 LDAPEXT group revealed ambiguities and complexities in the MVO 158 boolean that could not easily be resolved. For example, it was not 159 clear if the MVO boolean governed only those attribute values that 160 contributed to the overall truth of the filter, or all of the 161 attribute values even if the filter item containing the attribute 162 evaluated to false. For this reason the LDAPEXT group decided to 163 replace the MVO boolean with a simple filter that removes any 164 uncertainty as to whether an attribute value has been selected or 165 not. 167 4. Relationship to other LDAP Controls 169 The purpose of this control is to select zero, one or more attribute 170 values from each requested attribute in a filtered entry, and to 171 discard the remainder. Once the attribute values have been discarded 172 by this control they MUST NOT be re-instated into the Search results 173 by other controls. 175 This control acts independently of other LDAP controls such as server 176 side sorting [10] and duplicate entries [7]. However, there might be 177 interactions between this control and other controls so that a 178 different set of Search Result Entries are returned, or the entries 179 are returned in a different order, depending upon the sequencing of 180 this control and other controls in the LDAP request. For example, 181 with server side sorting, if sorting is done first, and value return 182 filtering second, the set of Search Results may appear to be in the 183 wrong order since the value filtering may remove the attribute values 184 upon which the ordering was done. (The sorting document specifies 185 that entries without any sort key attribute values should be treated 186 as coming after all other attribute values.) Similarly with duplicate 187 entries, if duplication is performed before value filtering, the set 188 of Search Result Entries may contain identical duplicate entries, 189 each with an empty set of attribute values, because the value 190 filtering removed the attribute values that were used to duplicate 191 the results. 193 For these reasons it is recommended that the ValuesReturnFilter 194 control in a SearchRequest SHOULD precede other controls that affect 195 the number and ordering of SearchResultEntrys. 197 5. Examples 199 All entries are provided in LDIF format [8]. 201 The string representation of the valuesReturnFilter in the examples 202 below uses the notation defined in RFC 2254 [11]. 204 (1) The first example shows how the control can be set to return all 205 attribute values from one attribute type (e.g. telephoneNumber) and a 206 subset of values from another attribute type (e.g. mail). 208 The entries below represent organizationalPerson object classes 209 located somewhere beneath the distinguished name dc=ac, dc=uk. 211 dn: cn=Sean Mullan, ou=people, dc=sun, dc=ac, dc=uk 212 cn: Sean Mullan 213 sn: Mullan 214 objectClass: organizationalPerson 215 objectClass: person 216 objectClass: inetOrgPerson 217 mail: sean.mullan@hotmail.com 218 mail: mullan@east.sun.com 219 telephoneNumber: + 781 442 0926 220 telephoneNumber: 555-9999 222 dn: cn=David Chadwick, ou=isi, o=salford, dc=ac, dc=uk 223 cn: David Chadwick 224 sn: Chadwick 225 objectClass: organizationalPerson 226 objectClass: person 227 objectClass: inetOrgPerson 228 mail: d.w.chadwick@salford.ac.uk 230 An LDAP search operation is specified with a baseObject set to the 231 DN of the search base (i.e. dc=ac, dc=uk), a subtree scope, a filter 232 set to (sn=mullan), and the list of attributes to be returned set to 233 "mail, telephoneNumber". In addition, a ValuesReturnFilter control is 234 set to ((mail=*hotmail.com)(telephoneNumber=*)) 236 The search results returned by the server would consist of the 237 following entry: 239 dn: cn=Sean Mullan, ou=people, dc=sun, dc=ac, dc=uk 240 mail: sean.mullan@hotmail.com 241 telephoneNumber: + 781 442 0926 242 telephoneNumber: 555-9999 244 Note that the control has no effect on the values returned for the 245 "telephoneNumber" attribute (all of the values are returned), since 246 the control specified that all values should be returned. 248 (2) The second example shows how one might retrieve a single 249 attribute type subschema definition for the "gunk" attribute with OID 250 1.2.3.4.5 from the subschema subentry 252 Assume the subschema subentry is held below the root entry with DN 253 cn=subschema subentry, o=myorg and this holds an attributeTypes 254 operational attribute holding the descriptions of the 35 attributes 255 known to this server (each description is held as a single attribute 256 value of the attributeTypes attribute). 258 dn: cn=subschema subentry, o=myorg 259 cn: subschema subentry 260 objectClass: subschema 261 attributeTypes: ( 2.5.4.3 NAME 'cn' SUP name ) 262 attributeTypes: ( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE ) 263 attributeTypes: ( 2.5.4.0 NAME 'objectClass' EQUALITY 264 objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) 265 attributeTypes: ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY 266 generalizedTimeMatch ORDERING generalizedTimeOrderingMatch 267 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER- 268 MODIFICATION USAGE directoryOperation ) 269 attributeTypes: ( 2.5.21.6 NAME 'objectClasses' EQUALITY 270 objectIdentifierFirstComponentMatch SYNTAX 271 1.3.6.1.4.1.1466.115.121.1.37 USAGE directoryOperation ) 272 attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch 273 SUBSTR caseIgnoreSubstringsMatch SYNTAX 274 1.3.6.1.4.1.1466.115.121.1.44{64} ) 275 attributeTypes: ( 2.5.21.5 NAME 'attributeTypes' EQUALITY 276 objectIdentifierFirstComponentMatch SYNTAX 277 1.3.6.1.4.1.1466.115.121.1.3 USAGE directoryOperation ) 279 plus another 28 - you get the idea. 281 The user creates an LDAP search operation with a baseObject set to 282 cn=subschema subentry, o=myorg, a scope of base, a filter set to 283 (objectClass=subschema), the list of attributes to be returned set to 284 "attributeTypes", and the ValuesReturnFilter set to 285 (attributeTypes=1.2.3.4.5) 287 The search result returned by the server would consist of the 288 following entry: 290 dn: cn=subschema subentry, o=myorg 291 attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch 292 SUBSTR caseIgnoreSubstringsMatch SYNTAX 293 1.3.6.1.4.1.1466.115.121.1.44{64} ) 295 (3) The final example shows how the control can be used to match on a 296 userCertificate attribute value with a particular key usage bit set 297 (in this case the key encipherment bit). Note that this example 298 requires the LDAP server to support the certificateMatch matching 299 rule defined in [9] and extensible matching. 301 The entry below represent a pkiUser object class stored in the 302 directory. 304 dn: cn=David Chadwick + serialNumber=123456, ou=people, o=University 305 of Salford, c=gb 306 cn: David Chadwick + serialNumber=123456 307 objectClass: person 308 objectClass: organizationalPerson 309 objectClass: pkiUser 310 objectClass: inetOrgPerson 311 sn: Chadwick 312 mail: d.w.chadwick@salford.ac.uk 313 userCertificate: {binary representation of certificate including key 314 usage bit of digitalSignature (0)} 315 userCertificate: {binary representation of certificate including key 316 usage bit of nonRepudiation (1)} 317 userCertificate: {binary representation of certificate including key 318 usage bit of key encipherment (2)} 319 userCertificate: {binary representation of certificate including key 320 usage bit of data encipherment (3)} 322 An LDAP search operation is specified with a baseObject set to 323 o=University of Salford, c=gb, a subtree scope, a filter set to 324 (sn=chadwick) and the list of attributes to be returned set to 325 "userCertificate;binary". In addition, a ValuesReturnFilter control 326 is set to (userCertificate:2.5.13.35:=USE'001'B) 328 The search result returned by the server would consist of the 329 following entry: 331 dn: cn=David Chadwick + serialNumber=123456, ou=people, o=University 332 of Salford, c=gb 333 userCertificate;binary: {binary representation of certificate with 334 key usage bit of key encipherment (2)} 336 6. Security Considerations 338 This [ID/standard/document] does not primarily discuss security 339 issues. 341 Note however that attribute values MUST only be returned if the 342 access controls applied by the LDAP server allow them to be returned, 343 and in this respect the effect of the ValuesReturnFilter control is 344 of no consequence. 346 Note that the ValuesReturnFilter control may have a positive effect 347 on the deployment of public key infrastructures. Certain PKI 348 operations, like searching for specific certificates, become more 349 practical when combined with X.509 certificate matching rules at the 350 server, and more scalable, since the control avoids the downloading 351 of potentially large numbers of irrelevant certificates which would 352 have to be processed and filtered locally (which in some cases is 353 very difficult to perform). 355 7. Acknowledgements 357 The authors would like to thank members of the LDAPExt list for their 358 constructive comments on earlier versions of this 359 [ID/standard/document], and in particular to Harald Alvestrand who 360 first suggested having an attribute return filter and Bruce 361 Greenblatt who first proposed a syntax for this control. 363 8. Copyright 365 Copyright (C) The Internet Society (date). All Rights Reserved. 367 This document and translations of it may be copied and furnished to 368 others, and derivative works that comment on or otherwise explain it 369 or assist in its implementation may be prepared, copied, published 370 and distributed, in whole or in part, without restriction of any 371 kind, provided that the above copyright notice and this paragraph are 372 included on all such copies and derivative works. However, this 373 document itself may not be modified in any way, such as by removing 374 the copyright notice or references to the Internet Society or other 375 Internet organizations, except as needed for the purpose of 376 developing Internet standards in which case the procedures for 377 copyrights defined in the Internet Standards process must be 378 followed, or as required to translate it into languages other than 379 English. 381 The limited permissions granted above are perpetual and will not be 382 revoked by the Internet Society or its successors or assigns. 384 This document and the information contained herein is provided on an 385 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 386 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 387 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 388 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 389 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 391 9. References 393 [1] S. Bradner. "The Internet Standards Process -- Revision 3", RFC 394 2026, October 1996. 395 [2] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access 396 Protocol (v3)", Dec. 1997, RFC 2251 397 [3] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory 398 Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, Dec 399 1997 400 [4] ITU-T Rec. X.511, "The Directory: Abstract Service Definition", 401 1993. 402 [5] S.Bradner. "Key words for use in RFCs to Indicate Requirement 403 Levels", RFC 2119, March 1997. 404 [6] Draft ISO/IEC 9594 / ITU-T Rec X.511 (2001) The Directory: 405 Abstract Service Definition. 406 [7] J. Sermersheim. "LDAP Control for a Duplicate Entry 407 Representation of Search Results", Internet Draft , July 2000. 409 [8] G. Good. "The LDAP Data Interchange Format (LDIF) - Technical 410 Specification". RFC 2849, June 2000. 411 [9] D. Chadwick, S.Legg. "Internet X.509 Public Key Infrastructure - 412 Additional LDAP Schema for PKIs and PMIs", Internet Draft , September 2000 414 [10] T. Howes, M. Wahl, A. Anantha, "LDAP Control Extension for 415 Server Side Sorting of Search Results", RFC 2891, August 2000 416 [11] T. Howes. "The String Representation of LDAP Search Filters". 417 RFC 2254, December 1997. 419 10. Authors Addresses 421 David Chadwick 422 IS Institute 423 University of Salford 424 Salford M5 4WT 425 England 427 Email: d.w.chadwick@salford.ac.uk 428 Tel: +44 161 295 5351 430 Sean Mullan 431 Sun Microsystems 432 East Point Business Park 433 Dublin 3 434 Ireland 435 Tel: +353 1 853 0655 436 Email: sean.mullan@sun.com 438 11. Changes since version 2 440 i) Revised the examples to be more appropriate 441 ii) Section on interactions with other LDAP controls added 442 iii) Removed Editor's note concerning present filter 443 iv) Tightened wording about its applicability to other operations 444 and use of criticality field 446 Changes since version 3 448 i) Mandated that at least one of type and matchingRule in 449 simpleMatchingAssertion be present 450 ii) Fixed LDIF mistakes in the examples 451 iii) Additional minor editorials only